Scarab Diagnostic Suite 현장 테스트 #012: Next.js 소스 맵 출처 경계 (Source Map Provenance

이 현장 테스트는 Next.js를 대상으로 진행되었습니다.

해당 이슈는 Next.js #94450이었습니다:

https://github.com/vercel/next.js/issues/94450

보고된 문제는 React Compiler와 Turbopack이 관여될 때 발생하는 프로덕션 브라우저 소스 맵 (source maps) 관련 문제였습니다.

가시적인 증상은 최종 브라우저 소스 맵이 원래의 클라이언트 소스 콘텐츠를 보존하는 대신, 변환된 컴파일러 출력물 (transformed compiler output)을 노출할 수 있다는 점이었습니다.

이는 소스 맵이 단순한 디버깅용 부가 기능이 아니기 때문에 중요합니다. 소스 맵은 출처 산물 (provenance artifacts)입니다. 소스 맵은 브라우저 출력이 어떤 소스에서 왔는지를 개발자에게 알려줍니다.

만약 소스 맵이 특정 소스 파일을 나타낸다고 주장하지만, 그 sourcesContent가 원래 파일 콘텐츠 대신 컴파일러로 변환된 출력물을 포함하고 있다면, 해당 디버깅 산물은 보존해야 할 소스 진실 (source truth)로부터 벗어난 것입니다.

유효한 진단 경계는 다음과 같습니다:

원본 클라이언트 소스 → 변환 소스 맵 (transform source map) → Turbopack 소스 맵 합성 (source-map composition) → 최종 브라우저 청크 맵 (final browser chunk map)

중요한 증거는 Babel/React Compiler 변환 자체는 sourcesContent가 여전히 원래의 클라이언트 파일을 나타내는 소스 맵을 생성할 수 있다는 점이었습니다.

따라서 손실의 원인은 단순히 다음과 같은 것이 아니었습니다:

React Compiler가 코드를 변경했다

더 날카로운 문제는 다음과 같았습니다:

브라우저 소스 맵 합성 경로가 최종 산물에 이르기까지 원래의 소스 권위 (source authority)를 보존하지 못했다

이로 인해 수정 방향 (repair lane)이 훨씬 좁아졌습니다.

로컬 수정 후보는 두 부분으로 구성됩니다:

1. Babel 로더 변환 맵 (Babel loader transform map)에서 원래의 로더 입력 소스를 보존합니다.
2. 유입되는 변환 맵에서 출처가 누락된 경우, 원본 경로로부터 누락된 소스 맵 파일 출처 (source-map file provenance)를 채워 넣습니다. 이를 통해 Turbopack이 합성 과정에서 변환 맵을 생성된 중간 파일과 다시 매칭할 수 있는 충분한 식별 정보 (identity information)를 갖도록 합니다.

목표는 소스 맵 동작을 광범위하게 재작성하는 것이 아닙니다. 사후에 최종 브라우저 맵을 패치하는 것도 아닙니다. 변환 맵이 브라우저 산물로 합성되는 시점에 소스 권위 (source authority)를 보존하는 것입니다.

원본 소스 마커 (original source marker)를 가진 React Compiler 클라이언트 컴포넌트를 중심으로 회귀 테스트 피스처 (regression fixture)가 추가되었습니다.

이 테스트는 프로덕션 브라우저 소스 맵 (production browser source map)이 원래의 클라이언트 소스 콘텐츠를 유지하며, React Compiler 런타임 출력과 같은 컴파일러에 의해 변환된 마커를 노출하지 않음을 확인합니다.

집중적인 브라우저 소스 맵 증명, 관련 Turbopack 소스 맵 유틸리티 테스트, 수정된 파일의 Rust 포매팅 (formatting)

Scarab의 역할은 수리(repair)가 시작되기 전에 그러한 경계(boundary)를 식별하는 것입니다.

일단 경계가 명확해지면, 수리 범위는 증상이 시사하는 것보다 훨씬 작아질 수 있기 때문입니다.