From 27e04ea2ecf7a35ca0000fe7f3c76720e295a61a Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:32:08 +0800 Subject: [PATCH] fix(javascript): share source-map admission and path resolution (#12161) * fix(source-map): share bounded structural inspection with local analysis Refs #12135 * fix(javascript): retain relative URL traversal and decline unusable map paths * fix(javascript): retain source content beyond coordinate admission --- .../javascript-application-workflows.md | 6 + .../javascript/JavaScriptArtifactAnalysis.ts | 158 ++--- src/artifacts/ReleaseExposureReader.test.ts | 28 + .../javascriptApplicationGraph.fixture.ts | 8 +- .../javascript/javascriptSourceMapPaths.ts | 75 ++- .../javascriptStaticAnalysisHelpers.ts | 15 +- .../javascript/javascriptSyntheticUrlRoot.ts | 32 + src/domain/sourceMapContents.ts | 15 - src/domain/sourceMapEnvelope.test.ts | 110 ++-- src/domain/sourceMapEnvelope.ts | 130 +--- src/domain/sourceMapFormat.ts | 588 ++++++++++++------ .../createRequireFilenameBase.test.ts | 35 ++ .../applications/sourceMapPrefixCli.test.ts | 117 ++++ .../filesystem/sourceToBundlePaths.test.ts | 4 +- .../process/sourceMapUncHosts.test.ts | 4 +- 15 files changed, 794 insertions(+), 531 deletions(-) create mode 100644 src/domain/javascript/javascriptSyntheticUrlRoot.ts delete mode 100644 src/domain/sourceMapContents.ts diff --git a/docs/guides/javascript/javascript-application-workflows.md b/docs/guides/javascript/javascript-application-workflows.md index e1968273b3..b5c0044f88 100644 --- a/docs/guides/javascript/javascript-application-workflows.md +++ b/docs/guides/javascript/javascript-application-workflows.md @@ -441,6 +441,12 @@ never forces a mapping. Unicode-equivalent spellings are candidate evidence only because distinct filesystem paths can preserve those spellings as separate files; multiple canonical-equivalent candidates remain unknown. +Source-map declarations and embedded source digests remain available when the +declared reference cannot produce a matching path. For example, a relative +reference that leaves the inventoried artifact or a pathname that decodes to a +NUL byte has an unresolved path. The raw declaration still identifies the +source-map observation. + Each historical source file is classified as `unchanged`, `modified`, `removed`, `split`, `merged`, `duplicated`, or `unknown`. Multiple equally scored path mappings form a static split inference. Multiple current file diff --git a/src/application/javascript/JavaScriptArtifactAnalysis.ts b/src/application/javascript/JavaScriptArtifactAnalysis.ts index c21647b73f..37e0304657 100644 --- a/src/application/javascript/JavaScriptArtifactAnalysis.ts +++ b/src/application/javascript/JavaScriptArtifactAnalysis.ts @@ -5,14 +5,11 @@ import { setImmediate } from "node:timers/promises"; import type { JavaScriptPackageType } from "../../domain/javascript/javascriptSourceParser.js"; -import { resolveJavaScriptSourceMapReferences } from "../../domain/javascript/javascriptSourceMapPaths.js"; -import { hasValidSourceMapContents } from "../../domain/sourceMapContents.js"; +import { resolveJavaScriptSourceMapReference } from "../../domain/javascript/javascriptSourceMapPaths.js"; import { - inspectSourceMapEnvelope, - sourceMapJsonText, - sourceMapMappingsSchema, -} from "../../domain/sourceMapEnvelope.js"; -import type { SourceMapLeaf } from "../../domain/sourceMapEnvelope.js"; + inspectLocalSourceMapDeclarations, + type LocalSourceMapDeclaration, +} from "../../domain/sourceMapFormat.js"; import type { JavaScriptStaticAnalysis } from "../../domain/javascript/javascriptStaticAnalysisTypes.js"; import type { JavaScriptArtifactFile, @@ -120,7 +117,7 @@ export const analyzeAndAdoptJavaScriptArtifactFiles = async ( analysisStarted = true; if (file.kind !== "javascript" || !file.text.included) { assertJavaScriptAnalysisActive(signal); - analyzeArtifactMetadata(file, state); + analyzeArtifactMetadata(file, state, signal); assertJavaScriptAnalysisActive(signal); continue; } @@ -392,6 +389,7 @@ const finalizeArtifactAnalysis = ( const analyzeArtifactMetadata = ( file: JavaScriptArtifactFile, state: MutableArtifactAnalysis, + signal: AbortSignal | undefined, ): void => { addStructuredObservations(file, state); if (file.kind === "html" && file.text.included) { @@ -401,7 +399,8 @@ const analyzeArtifactMetadata = ( if (html.inlineScripts !== null) state.htmlInlineScripts.push(html.inlineScripts); } - if (file.kind === "source-map") state.sourceMaps.push(parseSourceMap(file)); + if (file.kind === "source-map") + state.sourceMaps.push(parseSourceMap(file, signal)); state.files.push({ file, javascript: null, semantic: null }); }; @@ -601,118 +600,33 @@ const parseHtmlScripts = ( const parseSourceMap = ( file: JavaScriptArtifactFile, + signal: AbortSignal | undefined, ): JavaScriptSourceMapObservation => { if (!file.text.included) return unavailableSourceMap(file); - let value: unknown; - try { - value = JSON.parse(sourceMapJsonText(file.text.value)); - } catch (cause: unknown) { - void cause; - return invalidSourceMap(file, "Source map is not valid JSON."); - } - const envelope = inspectSourceMapEnvelope(value); - if (envelope.status === "invalid") - return invalidSourceMap(file, envelope.reason); - const observation = collectSourceMapOriginals(file, envelope.leaves); - if (envelope.status === "included") return observation; - const envelopeLimitations = [ - ...envelope.invalid_sections.map( + const observed = inspectLocalSourceMapDeclarations(file.text.value, { + check: () => assertJavaScriptAnalysisActive(signal), + }); + const sources = collectSourceMapOriginals(file, observed.declarations); + const limitations = [ + ...observed.limitations, + ...observed.invalid_sections.map( ({ section_path, reason }) => `Indexed source-map section at [${section_path.join(",")}]: ${reason}`, ), - ...envelope.external_sections.map( + ...observed.external_sections.map( ({ url }) => `External source-map section URL is not fetched: ${url}`, ), ]; - const limitation = [ - ...(observation.status === "invalid" ? [observation.limitation] : []), - ...envelopeLimitations, - ].join("; "); - return { - ...observation, - status: "invalid", - limitation, - ...(envelope.external_sections.length === 0 - ? {} - : { external_sections: envelope.external_sections }), - ...(envelope.invalid_sections.length === 0 - ? {} - : { invalid_sections: envelope.invalid_sections }), - }; -}; - -const collectSourceMapOriginals = ( - file: JavaScriptArtifactFile, - leaves: readonly SourceMapLeaf[], -): JavaScriptSourceMapObservation => { - const sources: JavaScriptSourceMapOriginal[] = []; - const limitations: string[] = []; - let declarationIndex = 0; - for (const { map, section_path } of leaves) { - const location = - section_path.length === 0 - ? "" - : ` in section [${section_path.join(",")}]`; - const names = map.sources; - if (!Array.isArray(names)) { - limitations.push(`Source map has no sources array${location}.`); - continue; - } - const contents = map.sourcesContent; - if (!hasValidSourceMapContents(contents)) - limitations.push( - `Source map sourcesContent must be an array of strings or null entries${location}.`, - ); - if (map.sourceRoot != null && typeof map.sourceRoot !== "string") { - limitations.push( - `Source map sourceRoot must be a string or null${location}.`, - ); - continue; - } - const root = typeof map.sourceRoot === "string" ? map.sourceRoot : null; - const sourceDeclarations: { - readonly index: number; - readonly name: string | null; - }[] = []; - for (const [index, raw] of names.entries()) { - if (raw !== null && typeof raw !== "string") { - limitations.push( - `Source map contains a non-string source name at index ${String(index)}${location}.`, - ); - continue; - } - sourceDeclarations.push({ index, name: raw }); - } - const references = resolveJavaScriptSourceMapReferences( - sourceDeclarations.map(({ name }) => name), - root, - file.path, - ); - for (const [index, reference] of references.entries()) { - const declaration = sourceDeclarations[index]; - if (declaration === undefined) continue; - const rawContent = Array.isArray(contents) - ? contents[declaration.index] - : undefined; - const content = typeof rawContent === "string" ? rawContent : null; - sources.push({ - source_index: declaration.index, - declaration_index: declarationIndex++, - reference, - content, - content_sha256: content === null ? null : sha256Hex(content), - section_path, - }); - } - if (!sourceMapMappingsSchema.safeParse(map.mappings).success) - limitations.push(`Source map has no mappings string${location}.`); - } if (limitations.length > 0) - return invalidSourceMap( - file, - [...new Set(limitations)].join("; "), - sources, - ); + return { + ...invalidSourceMap(file, [...new Set(limitations)].join("; "), sources), + ...(observed.external_sections.length === 0 + ? {} + : { external_sections: observed.external_sections }), + ...(observed.invalid_sections.length === 0 + ? {} + : { invalid_sections: observed.invalid_sections }), + }; return { path: file.path, sha256: file.sha256, @@ -722,6 +636,26 @@ const collectSourceMapOriginals = ( }; }; +const collectSourceMapOriginals = ( + file: JavaScriptArtifactFile, + declarations: readonly LocalSourceMapDeclaration[], +): JavaScriptSourceMapOriginal[] => + declarations.map( + ( + { sectionPath, sourceIndex, source, root, content }, + declaration_index, + ) => { + return { + source_index: sourceIndex, + declaration_index, + reference: resolveJavaScriptSourceMapReference(source, root, file.path), + content, + content_sha256: content === null ? null : sha256Hex(content), + section_path: sectionPath, + }; + }, + ); + /** Name the HTML file and lines whose inline JavaScript was not analyzed. */ export const htmlInlineScriptLimitation = ({ path, diff --git a/src/artifacts/ReleaseExposureReader.test.ts b/src/artifacts/ReleaseExposureReader.test.ts index 0ce79dc177..ec1854ffba 100644 --- a/src/artifacts/ReleaseExposureReader.test.ts +++ b/src/artifacts/ReleaseExposureReader.test.ts @@ -1,3 +1,4 @@ +import { WEB_SOURCE_MAP_LIMITS } from "../domain/sourceMapLimits.js"; import { writeMinimalElfHeader } from "../../tests/fixtures/nativeHeaders.js"; import { createHash } from "node:crypto"; import { Readable } from "node:stream"; @@ -647,6 +648,33 @@ describe("ReleaseExposureReader member reads", () => { }); }); +it("keeps observed embedded sources when generated coordinates exceed their budget", async () => { + const root = await createTestTempDirectory("rea-release-exposure-offset-"); + const map = { + version: 3, + sections: [ + { + offset: { line: WEB_SOURCE_MAP_LIMITS.decodedRows - 1, column: 0 }, + map: { + version: 3, + sources: ["src/app.ts"], + sourcesContent: ["export {};"], + mappings: ";", + }, + }, + ], + }; + await writeFile(join(root, "app.js.map"), JSON.stringify(map)); + const scanned = await inspect(root); + expect(scanned.source_maps).toMatchObject({ + embedded: 1, + unparsed: 1, + without_sources: 0, + embedded_paths: [join(root, "app.js.map")], + }); + expect(sourceMapSourcesStatus(scanned)).toBe("exposed"); +}); + describe("ReleaseExposureReader limits", () => { it("counts sourcesContent nested past the old depth-8 walker", async () => { const root = await createTestTempDirectory("rea-release-exposure-depth-"); diff --git a/src/domain/javascript/javascriptApplicationGraph.fixture.ts b/src/domain/javascript/javascriptApplicationGraph.fixture.ts index 792fb0ba7f..e8fc30f52a 100644 --- a/src/domain/javascript/javascriptApplicationGraph.fixture.ts +++ b/src/domain/javascript/javascriptApplicationGraph.fixture.ts @@ -6,7 +6,7 @@ import { } from "./javascriptApplicationGraph.js"; import type { ApplicationNode } from "./javascriptApplicationGraphSchemas.js"; import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js"; -import { resolveJavaScriptSourceMapReferences } from "./javascriptSourceMapPaths.js"; +import { resolveJavaScriptSourceMapReference } from "./javascriptSourceMapPaths.js"; export const APPLICATION_GRAPH_DIGESTS = { package: "1".repeat(64), @@ -28,11 +28,11 @@ export const sourceMapReference = ( sourceRoot: string | null, mapPath: string, ) => { - const reference = resolveJavaScriptSourceMapReferences( - [sourceName], + const reference = resolveJavaScriptSourceMapReference( + sourceName, sourceRoot, mapPath, - )[0]; + ); if (reference == null) throw new TypeError("Expected a source-map reference"); return reference; }; diff --git a/src/domain/javascript/javascriptSourceMapPaths.ts b/src/domain/javascript/javascriptSourceMapPaths.ts index 7402dd4f54..e49b7e456a 100644 --- a/src/domain/javascript/javascriptSourceMapPaths.ts +++ b/src/domain/javascript/javascriptSourceMapPaths.ts @@ -3,6 +3,8 @@ import { domainToASCII, fileURLToPath, pathToFileURL } from "node:url"; import { z } from "zod"; +import { createSyntheticUrlRoot } from "./javascriptSyntheticUrlRoot.js"; + /** Map-scoped source declaration and its path interpretation for matching. */ export const javascriptSourceMapReferenceSchema = z.strictObject({ source_name: z.string(), @@ -25,24 +27,22 @@ export type JavaScriptSourceMapReference = z.infer< typeof javascriptSourceMapReferenceSchema >; -/** Interpret declarations together once at their source-map ingestion boundary. */ -export const resolveJavaScriptSourceMapReferences = ( - sourceNames: readonly (string | null)[], +/** Interpret a declaration once at the source-map ingestion boundary. */ +export const resolveJavaScriptSourceMapReference = ( + sourceName: string | null, sourceRoot: string | null, mapPath: string, -): (JavaScriptSourceMapReference | null)[] => { - return sourceNames.map((sourceName) => { - if (sourceName === null) return null; - return { - source_name: sourceName, - source_root: sourceRoot, - map_path: mapPath, - resolution: resolveJavaScriptSourceMapPath( - sourceMapReference(sourceName, sourceRoot), - mapPath, - ), - }; - }); +): JavaScriptSourceMapReference | null => { + if (sourceName === null) return null; + return { + source_name: sourceName, + source_root: sourceRoot, + map_path: mapPath, + resolution: resolveJavaScriptSourceMapPath( + sourceMapReference(sourceName, sourceRoot), + mapPath, + ), + }; }; /** Resolve one source declaration with ECMA-426's WHATWG URL parsing rule. */ @@ -80,12 +80,20 @@ const resolveJavaScriptSourceMapPath = ( ): JavaScriptSourceMapReference["resolution"] => { const portable = source.replaceAll("\\", "/"); const windowsPath = /^[a-z]:\//iu.test(portable) || source.startsWith("\\\\"); - // Preserve parent traversal rather than letting URL resolution clamp at '/'. - const anchor = `/${"source/".repeat(portable.split("/").length + 1)}`; - const directory = posix.join(anchor, posix.dirname(mapPath)); - const base = pathToFileURL(`${directory}/`, { windows: false }); + const declaredText = windowsPath + ? source + : (source.split(/[?#]/u, 1)[0] ?? ""); + // The URL parser can discard a literal NUL at the edge of the input. + if (declaredText.includes("\0")) return nulPath(); + const anchor = createSyntheticUrlRoot(source); + const mapDirectory = posix.dirname(mapPath); + const resolve = (root: string): URL | null => + URL.parse( + source, + pathToFileURL(`${posix.join(root, mapDirectory)}/`, { windows: false }), + ); const absolute = windowsPath ? windowsFileUrl(source) : URL.parse(source); - const resolved = windowsPath ? absolute : URL.parse(source, base); + const resolved = windowsPath ? absolute : resolve(anchor.root); if (resolved === null) return { kind: "unresolved", @@ -116,15 +124,15 @@ const resolveJavaScriptSourceMapPath = ( ? !portable.startsWith("/") : absolute.href !== resolved.href; const path = decodedUrlPath(resolved); - if (path === null) - return { - kind: "unresolved", - reason: - "Source reference has malformed URL encoding or an invalid file URL.", - }; + if (path === null) return invalidDecodedPath(); + if (path.includes("\0")) return nulPath(); const value = relative - ? posix.relative(anchor, path) + ? anchor.relativePath(path, (root) => { + const alternate = resolve(root); + return alternate === null ? null : decodedUrlPath(alternate); + }) : path.replace(/^\/+/, ""); + if (value === null) return invalidDecodedPath(); if (value === "" || value === ".." || value.startsWith("../")) return { kind: "unresolved", @@ -133,6 +141,17 @@ const resolveJavaScriptSourceMapPath = ( return { path: value, kind: relative ? "artifact-relative" : "suffix" }; }; +const invalidDecodedPath = (): JavaScriptSourceMapReference["resolution"] => ({ + kind: "unresolved", + reason: "Source reference has malformed URL encoding or an invalid file URL.", +}); + +const nulPath = (): JavaScriptSourceMapReference["resolution"] => ({ + kind: "unresolved", + reason: + "Source reference contains a NUL byte and cannot name a filesystem path.", +}); + // Reject URL delimiters/escapes before IDNA can truncate or decode the host. const unusableHost = /[\0\t\n\r #/:<>?@[\\\]^|%]/u; diff --git a/src/domain/javascript/javascriptStaticAnalysisHelpers.ts b/src/domain/javascript/javascriptStaticAnalysisHelpers.ts index 1682cac794..ad3a3433b5 100644 --- a/src/domain/javascript/javascriptStaticAnalysisHelpers.ts +++ b/src/domain/javascript/javascriptStaticAnalysisHelpers.ts @@ -22,6 +22,7 @@ import { compositeKey, } from "../unicodeCodePointOrder.js"; import { unexaminedJavaScriptStaticCoverage } from "./javascriptStaticCoverage.js"; +import { createSyntheticUrlRoot } from "./javascriptSyntheticUrlRoot.js"; /** Explicit result for source text that Babel cannot parse. */ export const failedJavaScriptStaticAnalysis = (): JavaScriptStaticAnalysis => ({ @@ -367,15 +368,19 @@ export const staticSourceRelativeUrlPath = ( /%(?:2e|2f|5c)/iu.test(value.split(/[?#]/u, 1)[0] ?? "") ) return undefined; - // A sufficiently deep inert anchor preserves any leading parent segments - // without using this host's cwd or inventing the application's directory. - const directory = `/${"source/".repeat(value.split("/").length + 1)}`; + const anchor = createSyntheticUrlRoot(value); + const resolve = (root: string): URL => + new URL(value, `file://${root}entry.js`); try { - const resolved = new URL(value, `file://${directory}entry.js`); + const resolved = resolve(anchor.root); const path = fileURLToPath(resolved, { windows: false }); if (value.startsWith("/")) return { path, directory: resolved.pathname.endsWith("/") }; - const relative = posix.relative(directory, path) || "."; + const relativePath = anchor.relativePath(path, (root) => + fileURLToPath(resolve(root), { windows: false }), + ); + if (relativePath === null) return undefined; + const relative = relativePath || "."; // Keep the established explicit source-directory observation spelling. return { path: diff --git a/src/domain/javascript/javascriptSyntheticUrlRoot.ts b/src/domain/javascript/javascriptSyntheticUrlRoot.ts new file mode 100644 index 0000000000..7190bc6e6c --- /dev/null +++ b/src/domain/javascript/javascriptSyntheticUrlRoot.ts @@ -0,0 +1,32 @@ +import { posix } from "node:path"; + +/** + * Set a file URL base far enough below "/" that the URL parser does not + * discard parent segments. Project the result against two distinct roots: + * "../source/a.js" can appear to stay below a root made of "source" segments + * only because its descent spells that root's name. The longer parent prefix + * from the two projections preserves the actual traversal. + */ +export const createSyntheticUrlRoot = (reference: string) => { + const depth = reference.split(/[\\/]/u).length + 1; + const root = `/${"source/".repeat(depth)}`; + return { + root, + relativePath( + resolvedPath: string, + resolveAlternative: (root: string) => string | null, + ): string | null { + const alternativeRoot = `/${"anchor/".repeat(depth)}`; + const alternativePath = resolveAlternative(alternativeRoot); + if (alternativePath === null) return null; + const primary = posix.relative(root, resolvedPath); + const alternative = posix.relative(alternativeRoot, alternativePath); + return parentPrefixLength(alternative) > parentPrefixLength(primary) + ? alternative + : primary; + }, + }; +}; + +const parentPrefixLength = (path: string): number => + /^(?:\.\.\/)*(?:\.\.$)?/u.exec(path)?.[0].length ?? 0; diff --git a/src/domain/sourceMapContents.ts b/src/domain/sourceMapContents.ts deleted file mode 100644 index c6a621f1aa..0000000000 --- a/src/domain/sourceMapContents.ts +++ /dev/null @@ -1,15 +0,0 @@ -/** - * Validate optional source-map content against its source inventory. - * - * ECMA-426 DecodeSourceMapSources reads a content slot only while its index is - * within `sourcesContent`, so a shorter array leaves trailing sources without - * content and a longer array contributes no extra sources. Only the entry types - * are checked here. - */ -export const hasValidSourceMapContents = (contents: unknown): boolean => - contents === undefined || - contents === null || - (Array.isArray(contents) && - contents.every( - (content: unknown) => content === null || typeof content === "string", - )); diff --git a/src/domain/sourceMapEnvelope.test.ts b/src/domain/sourceMapEnvelope.test.ts index cc15b00377..ebee1d4f80 100644 --- a/src/domain/sourceMapEnvelope.test.ts +++ b/src/domain/sourceMapEnvelope.test.ts @@ -1,6 +1,10 @@ import { describe, expect, it } from "vitest"; -import { inspectSourceMapEnvelope } from "./sourceMapEnvelope.js"; +import { inspectLocalSourceMapDeclarations } from "./sourceMapFormat.js"; +import { selectedSourceMapLimits } from "./sourceMapLimits.js"; + +const inspect = (root: unknown) => + inspectLocalSourceMapDeclarations(JSON.stringify(root)); const leaf = { version: 3, @@ -10,7 +14,7 @@ const leaf = { }; describe("source-map envelope walk", () => { - it("collects indexed section leaves without interpreting generated offsets", () => { + it("retains ordered declarations under nested section offsets", () => { const root = { version: 3, sections: [ @@ -36,19 +40,19 @@ describe("source-map envelope walk", () => { }, ], }; - const result = inspectSourceMapEnvelope(root); - expect(result.status).toBe("included"); - if (result.status !== "included") throw new Error("Expected embedded maps"); - expect(result.leaves.map(({ map }) => map.sources)).toEqual([ - ["b.ts"], - ["c.ts"], - ["d.ts"], + const result = inspect(root); + expect(result.limitations).toEqual([]); + expect(result.invalid_sections).toEqual([]); + expect(result.declarations.map(({ source }) => source)).toEqual([ + "b.ts", + "c.ts", + "d.ts", ]); }); it("retains external sections in canonical path order and embedded leaves", () => { const url = "https://app.test/maps/part.map"; - const result = inspectSourceMapEnvelope({ + const result = inspect({ version: 3, sections: [ { @@ -68,11 +72,11 @@ describe("source-map envelope walk", () => { }, ], }); - expect(result).toEqual({ - status: "unsupported", - leaves: [ - { section_path: [0, 1], map: leaf }, - { section_path: [2], map: { ...leaf, sources: ["after.ts"] } }, + expect(result).toMatchObject({ + limitations: [], + declarations: [ + { sectionPath: [0, 1], source: "app.ts" }, + { sectionPath: [2], source: "after.ts" }, ], external_sections: [ { section_path: [0, 0], url: `${url}/nested` }, @@ -84,7 +88,7 @@ describe("source-map envelope walk", () => { it("retains valid leaves and URLs when a sibling section is malformed", () => { const url = "https://app.test/maps/part.map"; - const result = inspectSourceMapEnvelope({ + const result = inspect({ version: 3, sections: [ { @@ -99,11 +103,11 @@ describe("source-map envelope walk", () => { }, ], }); - expect(result).toEqual({ - status: "malformed", - leaves: [ - { section_path: [0], map: { ...leaf, sources: ["before.ts"] } }, - { section_path: [3], map: { ...leaf, sources: ["after.ts"] } }, + expect(result).toMatchObject({ + limitations: [], + declarations: [ + { sectionPath: [0], source: "before.ts" }, + { sectionPath: [3], source: "after.ts" }, ], external_sections: [{ section_path: [1], url }], invalid_sections: [ @@ -120,8 +124,7 @@ describe("source-map envelope walk", () => { version: 3, sections: [{ offset: { line: 0, column: 0 } }], }; - expect(inspectSourceMapEnvelope(missing)).toMatchObject({ - status: "malformed", + expect(inspect(missing)).toMatchObject({ invalid_sections: [ { section_path: [0], @@ -137,15 +140,15 @@ describe("source-map envelope walk", () => { describe("malformed source-map envelope facts", () => { it("marks a present non-array sections member malformed at the map path", () => { expect( - inspectSourceMapEnvelope({ + inspect({ version: 3, sections: null, sources: ["must-not-be-read.ts"], mappings: "AAAA", }), ).toEqual({ - status: "malformed", - leaves: [], + declarations: [], + limitations: [], external_sections: [], invalid_sections: [ { @@ -157,24 +160,28 @@ describe("malformed source-map envelope facts", () => { }); it("rejects non-version-3 roots and nested maps", () => { - expect(inspectSourceMapEnvelope({ version: 3 })).toMatchObject({ - status: "included", - leaves: [{ section_path: [], map: {} }], + expect(inspect({ version: 3 })).toMatchObject({ + declarations: [], + limitations: ["Source map has no sources array."], }); - expect(inspectSourceMapEnvelope(null)).toMatchObject({ status: "invalid" }); - expect(inspectSourceMapEnvelope([{ version: 3 }])).toMatchObject({ - status: "invalid", + expect(inspect(null)).toMatchObject({ + declarations: [], + limitations: ["Source map is not a version 3 map."], + }); + expect(inspect([{ version: 3 }])).toMatchObject({ + declarations: [], + limitations: ["Source map is not a version 3 map."], + }); + expect(inspect({ version: 2, mappings: "AAAA" })).toMatchObject({ + declarations: [], + limitations: ["Source map is not a version 3 map."], + }); + expect(inspect({ mappings: "AAAA" })).toMatchObject({ + declarations: [], + limitations: ["Source map is not a version 3 map."], }); expect( - inspectSourceMapEnvelope({ version: 2, mappings: "AAAA" }), - ).toMatchObject({ - status: "invalid", - }); - expect(inspectSourceMapEnvelope({ mappings: "AAAA" })).toMatchObject({ - status: "invalid", - }); - expect( - inspectSourceMapEnvelope({ + inspect({ version: 3, sections: [ { @@ -184,7 +191,6 @@ describe("malformed source-map envelope facts", () => { ], }), ).toMatchObject({ - status: "malformed", invalid_sections: [ { section_path: [0], @@ -194,3 +200,23 @@ describe("malformed source-map envelope facts", () => { }); }); }); + +it("does not traverse more local sections than the format reader admits", () => { + const observed = inspectLocalSourceMapDeclarations( + JSON.stringify({ + version: 3, + sections: [ + { offset: { line: 0, column: 0 }, map: leaf }, + { offset: { line: 1, column: 0 }, map: leaf }, + ], + }), + { limits: selectedSourceMapLimits({ decoded_records: 1 }) }, + ); + expect(observed.declarations).toEqual([]); + expect(observed.invalid_sections).toEqual([ + { + section_path: [], + reason: "Local source-map inspection exceeded decoded_records (1).", + }, + ]); +}); diff --git a/src/domain/sourceMapEnvelope.ts b/src/domain/sourceMapEnvelope.ts index fa37a823a8..56866afcc1 100644 --- a/src/domain/sourceMapEnvelope.ts +++ b/src/domain/sourceMapEnvelope.ts @@ -1,4 +1,3 @@ -import { z } from "zod"; import { isRecord } from "../kernel/isRecord.js"; /** Artifact source declarations do not require generated-position decoding. */ @@ -14,11 +13,6 @@ export interface InvalidSourceMapSection { readonly reason: string; } -export interface SourceMapLeaf { - readonly section_path: readonly number[]; - readonly map: Readonly>; -} - export type SourceMapSection = | { readonly kind: "embedded"; readonly map: SourceMapRecord } | { readonly kind: "external"; readonly url: string } @@ -29,18 +23,6 @@ export type SourceMapSectionList = | { readonly kind: "indexed"; readonly sections: readonly unknown[] } | { readonly kind: "invalid"; readonly reason: string }; -export type SourceMapEnvelope = - | { readonly status: "invalid"; readonly reason: string } - | { - readonly status: "included" | "unsupported" | "malformed"; - readonly leaves: readonly SourceMapLeaf[]; - readonly external_sections: readonly ExternalSourceMapSection[]; - readonly invalid_sections: readonly InvalidSourceMapSection[]; - }; - -/** ECMA-426 requires a string mapping payload on every regular map leaf. */ -export const sourceMapMappingsSchema = z.string(); - /** * Return the JSON parsing view of retained source-map text. ECMA-426 permits * HTTP responses to start with `)]}'`; the first line is transport framing. @@ -101,115 +83,5 @@ export const classifySourceMapSections = ( }; /** Whether a parsed value has the version-3 map shape. */ -const isVersion3Map = (value: unknown): value is SourceMapRecord => +export const isVersion3Map = (value: unknown): value is SourceMapRecord => isRecord(value) && value.version === 3; - -/** - * Collect valid embedded leaves and retain external or malformed section - * facts. A map with neither `mappings` nor `sections` is a leaf; callers - * decide whether that leaf has valid declarations and mappings. - */ -interface SectionPath { - readonly parent: SectionPath | null; - readonly index: number; -} - -const materializeSectionPath = (path: SectionPath | null): number[] => { - const result: number[] = []; - for (let current = path; current !== null; current = current.parent) - result.push(current.index); - return result.reverse(); -}; - -const compareSectionPaths = ( - left: readonly number[], - right: readonly number[], -): number => { - for (let index = 0; index < Math.min(left.length, right.length); index += 1) { - const leftIndex = left[index] ?? 0; - const rightIndex = right[index] ?? 0; - if (leftIndex !== rightIndex) return leftIndex - rightIndex; - } - return left.length - right.length; -}; - -/** Walk embedded maps while retaining unsupported and malformed section facts. */ -export const inspectSourceMapEnvelope = (root: unknown): SourceMapEnvelope => { - if (!isVersion3Map(root)) - return { status: "invalid", reason: "Source map is not a version 3 map." }; - const leaves: SourceMapLeaf[] = []; - const externalSections: { - readonly path: SectionPath; - readonly url: string; - }[] = []; - const invalidSections: { - readonly path: SectionPath | null; - readonly reason: string; - }[] = []; - const pending: { - readonly map: SourceMapRecord; - readonly path: SectionPath | null; - }[] = [{ map: root, path: null }]; - while (pending.length > 0) { - const current = pending.pop(); - if (current === undefined) break; - const map = current.map; - const sectionList = classifySourceMapSections(map); - if (sectionList.kind === "invalid") { - invalidSections.push({ path: current.path, reason: sectionList.reason }); - continue; - } - if (sectionList.kind === "indexed") { - const children: { - readonly map: SourceMapRecord; - readonly path: SectionPath; - }[] = []; - for (let index = 0; index < sectionList.sections.length; index += 1) { - const section = sectionList.sections[index]; - const path = { parent: current.path, index }; - const classification = classifySourceMapSection(section); - if (classification.kind === "external") - externalSections.push({ path, url: classification.url }); - else if (classification.kind === "invalid") - invalidSections.push({ path, reason: classification.reason }); - else children.push({ map: classification.map, path }); - } - for (let index = children.length - 1; index >= 0; index -= 1) { - const child = children[index]; - if (child !== undefined) pending.push(child); - } - } else - leaves.push({ - section_path: materializeSectionPath(current.path), - map, - }); - } - const external = externalSections - .map(({ path, url }) => ({ - section_path: materializeSectionPath(path), - url, - })) - .sort((left, right) => - compareSectionPaths(left.section_path, right.section_path), - ); - const invalid = invalidSections - .map(({ path, reason }) => ({ - section_path: materializeSectionPath(path), - reason, - })) - .sort((left, right) => - compareSectionPaths(left.section_path, right.section_path), - ); - const status = - invalid.length > 0 - ? "malformed" - : external.length > 0 - ? "unsupported" - : "included"; - return { - status, - leaves, - external_sections: external, - invalid_sections: invalid, - }; -}; diff --git a/src/domain/sourceMapFormat.ts b/src/domain/sourceMapFormat.ts index 88b35724fc..801523ef93 100644 --- a/src/domain/sourceMapFormat.ts +++ b/src/domain/sourceMapFormat.ts @@ -8,6 +8,7 @@ import { import { malformedInput, ParseFailureError, + type ParseFailure, type ParseFailureKind, unsupportedInput, } from "./parseFailure.js"; @@ -15,19 +16,28 @@ import { classifySourceMapSection, classifySourceMapSections, sourceMapJsonText, - sourceMapMappingsSchema, + isVersion3Map, +} from "./sourceMapEnvelope.js"; +import type { + ExternalSourceMapSection, + InvalidSourceMapSection, } from "./sourceMapEnvelope.js"; -import type { SourceMapSection } from "./sourceMapEnvelope.js"; import type { EncodedSourceMapXInput } from "@jridgewell/trace-mapping"; +const sourceNameSchema = z.string().nullable(); +const sourceRootSchema = sourceNameSchema.optional(); +// A missing slot leaves that declaration without content. Extra slots +// contribute no extra sources (ECMA-426 DecodeSourceMapSources). +const sourceContentsSchema = z.array(sourceNameSchema).nullable().optional(); + const leafSchema = z.object({ version: z.literal(3), file: z.string().nullable().optional(), - sourceRoot: z.string().nullable().optional(), - sources: z.array(z.string().nullable()), - sourcesContent: z.array(z.string().nullable()).nullable().optional(), + sourceRoot: sourceRootSchema, + sources: z.array(sourceNameSchema), + sourcesContent: sourceContentsSchema, names: z.array(z.string()).default([]), - mappings: sourceMapMappingsSchema.regex(/^[A-Za-z0-9+/,;]*$/u), + mappings: z.string().regex(/^[A-Za-z0-9+/,;]*$/u), ignoreList: z.array(z.int().min(0)).optional(), x_google_ignoreList: z.array(z.int().min(0)).optional(), }); @@ -36,22 +46,31 @@ const mapHeaderSchema = z.object({ file: z.string().nullable().optional(), sections: z.unknown().optional(), }); -const sectionSchema = z.object({ +const sectionOffsetSchema = z.object({ offset: z.object({ - line: z.int().min(0).max(Number.MAX_SAFE_INTEGER), - column: z.int().min(0).max(Number.MAX_SAFE_INTEGER), + line: z.int().min(0), + column: z.int().min(0), }), - map: z.unknown().optional(), - url: z.unknown().optional(), }); -type Offset = { readonly line: number; readonly column: number }; +type Offset = z.output["offset"]; +type RawMap = Readonly>; interface PendingMap { - readonly value: unknown; + readonly value: RawMap; readonly path: readonly number[]; - readonly offset: Offset; + readonly offset: Offset | null; readonly stop: Offset | null; } +interface PartialStructure { + readonly invalid: (path: readonly number[], failure: ParseFailure) => void; + readonly external: (section: ExternalSourceMapSection) => void; + readonly leaf: ( + node: PendingMap, + failure: ParseFailure, + unpositionedMap?: z.output, + ) => void; +} + /** Aggregate structural work shared by maps in one selected inspection. */ export interface SourceMapStructureBudget { records: number; @@ -118,12 +137,7 @@ const parseStructure = ( }; /** Raw declaration identity, separate from flattened engine URL identity. */ -export interface SourceMapSourceDeclaration { - readonly sectionPath: readonly number[]; - readonly sourceIndex: number; - readonly source: string | null; - readonly root: string | null; - readonly content: string | null; +export interface SourceMapSourceDeclaration extends LocalSourceMapDeclaration { readonly ignored: boolean; } @@ -189,73 +203,117 @@ const consumeRecords = ( budget.records += count; }; +/** Keep format failures as partial facts only when the selected reader supports them. */ +const recoverStructure = ( + read: () => Value, + path: readonly number[], + partial: PartialStructure | undefined, +): Value | null => { + try { + return read(); + } catch (failure) { + if (partial === undefined || !isSourceMapFailure(failure)) throw failure; + partial.invalid(path, failure.failure); + return null; + } +}; + const addSections = ({ node, pending, rawSections, budget, options, + partial, }: { readonly node: PendingMap; readonly pending: PendingMap[]; readonly rawSections: readonly unknown[]; - readonly budget: { records: number }; + readonly budget: SourceMapStructureBudget; readonly options: SourceMapStructureOptions; + readonly partial: PartialStructure | undefined; }): void => { const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS; options.check?.(); - consumeRecords(budget, limits, rawSections.length); - const sections = parseStructure(z.array(sectionSchema), rawSections); - const embeddedMaps: Extract< - SourceMapSection, - { readonly kind: "embedded" } - >["map"][] = []; - for (const [index, section] of sections.entries()) { + if ( + recoverStructure( + () => consumeRecords(budget, limits, rawSections.length), + node.path, + partial, + ) === null + ) + return; + const offsets = rawSections.map((section, index) => { if ((index & 255) === 0) options.check?.(); - const previous = sections[index - 1]; - if (previous !== undefined && compare(section.offset, previous.offset) < 0) - throw malformedInput( + return recoverStructure( + () => parseStructure(sectionOffsetSchema, section).offset, + [...node.path, index], + partial, + ); + }); + const maps: (RawMap | null)[] = []; + let previous: Offset | null = null; + for (const [index, section] of rawSections.entries()) { + if ((index & 255) === 0) options.check?.(); + const path = [...node.path, index]; + const offset = offsets[index] ?? null; + if (offset !== null && previous !== null && compare(offset, previous) < 0) { + const failure = malformedInput( SOURCE_MAP_FORMAT, "Indexed section offsets must be in nondecreasing order.", ); + if (partial === undefined) throw failure; + partial.invalid(path, failure.failure); + offsets[index] = null; + } + if (offset !== null) previous = offset; + const classification = classifySourceMapSection(section); - if (classification.kind === "external") - throw unsupportedInput( - SOURCE_MAP_FORMAT, - `External source-map section URL is not fetched: ${classification.url}`, + if (classification.kind === "external") { + if (partial === undefined) + throw unsupportedInput( + SOURCE_MAP_FORMAT, + `External source-map section URL is not fetched: ${classification.url}`, + ); + partial.external({ section_path: path, url: classification.url }); + } else if (classification.kind === "invalid") { + if (partial === undefined) + throw malformedInput( + SOURCE_MAP_FORMAT, + `${classification.reason} Section path: ${JSON.stringify(path)}.`, + ); + partial.invalid( + path, + malformedInput(SOURCE_MAP_FORMAT, classification.reason).failure, ); - if (classification.kind === "invalid") - throw malformedInput( - SOURCE_MAP_FORMAT, - `${classification.reason} Section path: ${JSON.stringify([...node.path, index])}.`, - ); - embeddedMaps.push(classification.map); + } + maps.push(classification.kind === "embedded" ? classification.map : null); } - for (let index = sections.length - 1; index >= 0; index -= 1) { - const section = sections[index]; - if (section === undefined) continue; - const map = embeddedMaps[index]; - if (map === undefined) - throw malformedInput( - SOURCE_MAP_FORMAT, - "Validated indexed section map is unavailable.", - ); - const next = sections[index + 1]; - const nextOffset = - next === undefined ? null : addOffset(node.offset, next.offset, limits); + + // Validate section syntax and ownership before applying generated-row limits. + let nextOffset: Offset | null = null; + for (let index = maps.length - 1; index >= 0; index -= 1) { + if ((index & 255) === 0) options.check?.(); + const path = [...node.path, index]; + const declared = offsets[index]; + const base = node.offset; + const offset = + declared == null || base === null + ? null + : recoverStructure( + () => addOffset(base, declared, limits), + path, + partial, + ); const stop = nextOffset === null ? node.stop : node.stop === null || compare(nextOffset, node.stop) < 0 ? nextOffset : node.stop; - const offset = addOffset(node.offset, section.offset, limits); - pending.push({ - value: map, - path: [...node.path, index], - offset, - stop, - }); + const map = maps[index]; + if (map != null) pending.push({ value: map, path, offset, stop }); + nextOffset = offset; } }; @@ -329,53 +387,132 @@ const inspectMappingLayout = ( return { lines, segments }; }; -const inspectLeaf = ( - node: PendingMap, - budget: { records: number }, +const admitLeafFields = ( + value: RawMap, + budget: SourceMapStructureBudget, options: SourceMapStructureOptions, -): z.output => { +): void => { const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS; options.check?.(); consumeRecords(budget, limits, 1); - if ( - typeof node.value !== "object" || - node.value === null || - Array.isArray(node.value) - ) - return parseStructure(leafSchema, node.value); - const rawMap = node.value as Readonly>; - const rawSources = rawMap.sources; - const rawNames = rawMap.names; - const rawContents = rawMap.sourcesContent; - consumeRecords( - budget, - limits, - Array.isArray(rawSources) ? rawSources.length : 0, - ); - consumeRecords(budget, limits, Array.isArray(rawNames) ? rawNames.length : 0); - consumeRecords( - budget, - limits, - Array.isArray(rawContents) ? rawContents.length : 0, - ); + for (const field of ["sources", "names", "sourcesContent"] as const) { + const raw = value[field]; + if (Array.isArray(raw)) consumeRecords(budget, limits, raw.length); + } options.check?.(); - const leaf = parseStructure(leafSchema, node.value); - const layout = inspectMappingLayout(leaf.mappings, limits, options.check); - consumeRecords(budget, limits, layout.segments + layout.lines); - if ( - layout.segments > limits.decodedSegments || - node.offset.line + layout.lines > limits.decodedRows - ) - throw sourceMapLimitFailure( - `Source-map layout exceeds decoder admission.`, - layout.segments > limits.decodedSegments - ? "decoded_segments" - : "decoded_rows", - layout.segments > limits.decodedSegments - ? limits.decodedSegments - : limits.decodedRows, - ); - return leaf; +}; + +const inspectLeaf = ( + value: RawMap, + budget: SourceMapStructureBudget, + options: SourceMapStructureOptions, +): { map: z.output; lines: number } => { + const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS; + const map = parseStructure(leafSchema, value); + const { lines, segments } = inspectMappingLayout( + map.mappings, + limits, + options.check, + ); + consumeRecords(budget, limits, segments + lines); + return { map, lines }; +}; + +/** Shared bounded walk. Only position-based consumers require offsets for every leaf. */ +const walkSourceMapStructure = ( + value: RawMap, + options: SourceMapStructureOptions, + leaf: (node: PendingMap, map: z.output) => void, + partial?: PartialStructure, +): void => { + const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS; + const pending: PendingMap[] = [ + { value, path: [], offset: { line: 0, column: 0 }, stop: null }, + ]; + const budget = options.budget ?? { records: 0 }; + while (pending.length > 0) { + options.check?.(); + const node = pending.pop(); + if (node === undefined) break; + if (node.path.length > limits.sectionDepth) { + const failure = sourceMapLimitFailure( + "Indexed source-map nesting exceeds decoder admission.", + "section_depth", + limits.sectionDepth, + ); + if (partial === undefined) throw failure; + partial.invalid(node.path, failure.failure); + continue; + } + const sections = classifySourceMapSections(node.value); + if (sections.kind === "invalid") { + const failure = malformedInput(SOURCE_MAP_FORMAT, sections.reason); + if (partial === undefined) throw failure; + partial.invalid(node.path, failure.failure); + } else if (sections.kind === "indexed") { + addSections({ + node, + pending, + rawSections: sections.sections, + budget, + options, + partial, + }); + } else { + if ( + recoverStructure( + () => admitLeafFields(node.value, budget, options), + node.path, + partial, + ) === null + ) + continue; + let admitted: ReturnType; + try { + admitted = inspectLeaf(node.value, budget, options); + } catch (failure) { + if (partial === undefined || !isSourceMapFailure(failure)) + throw failure; + partial.leaf(node, failure.failure); + continue; + } + // A valid leaf can exceed the positioned row allowance without losing + // its bounded source declarations. + if ( + node.offset !== null && + node.offset.line + admitted.lines > limits.decodedRows + ) { + const failure = sourceMapLimitFailure( + "Source-map layout exceeds decoder admission.", + "decoded_rows", + limits.decodedRows, + ); + if (partial === undefined) throw failure; + partial.leaf(node, failure.failure, admitted.map); + continue; + } + leaf(node, admitted.map); + } + } +}; + +const observeSourceDeclarations = ( + path: readonly number[], + map: z.output, + observe: (declaration: SourceMapSourceDeclaration) => void, +): void => { + const ignoredSources = new Set( + map.ignoreList ?? map.x_google_ignoreList ?? [], + ); + for (const [sourceIndex, source] of map.sources.entries()) + observe({ + sectionPath: path, + sourceIndex, + source, + root: map.sourceRoot ?? null, + content: map.sourcesContent?.[sourceIndex] ?? null, + ignored: ignoredSources.has(sourceIndex), + }); }; /** Validate structure before allocation, retaining raw declarations and section boundaries. */ @@ -398,60 +535,26 @@ export const inspectSourceMapValue = ( readonly declarations: readonly SourceMapSourceDeclaration[]; readonly leaves: readonly SourceMapLeaf[]; } => { - const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS; options.check?.(); const root = parseStructure(mapHeaderSchema, value); const declarations: SourceMapSourceDeclaration[] = []; const leaves: SourceMapLeaf[] = []; - const pending: PendingMap[] = [ - { value, path: [], offset: { line: 0, column: 0 }, stop: null }, - ]; - const budget = options.budget ?? { records: 0 }; - while (pending.length > 0) { - options.check?.(); - const node = pending.pop(); - if (node === undefined) break; - if (node.path.length > limits.sectionDepth) - throw sourceMapLimitFailure( - `Indexed source-map nesting exceeds decoder admission.`, - "section_depth", - limits.sectionDepth, - ); - const sections = classifySourceMapSections(node.value); - if (sections.kind === "invalid") - throw malformedInput(SOURCE_MAP_FORMAT, sections.reason); - if (sections.kind === "indexed") { - addSections({ - node, - pending, - rawSections: sections.sections, - budget, - options, - }); - continue; - } - const leaf = inspectLeaf(node, budget, options); + if (!isVersion3Map(value)) + throw new TypeError("Validated source map is unavailable"); + walkSourceMapStructure(value, options, (node, leaf) => { + if (node.offset === null) + throw new TypeError("Validated source-map offset is unavailable"); leaves.push({ map: leaf, codecMap: codecLeaf(leaf), offset: node.offset, stop: node.stop, }); - if (options.profile !== "browser-collection") { - const ignoredSources = new Set( - leaf.ignoreList ?? leaf.x_google_ignoreList ?? [], + if (options.profile !== "browser-collection") + observeSourceDeclarations(node.path, leaf, (declaration) => + declarations.push(declaration), ); - for (const [sourceIndex, source] of leaf.sources.entries()) - declarations.push({ - sectionPath: node.path, - sourceIndex, - source, - root: leaf.sourceRoot ?? null, - content: leaf.sourcesContent?.[sourceIndex] ?? null, - ignored: ignoredSources.has(sourceIndex), - }); - } - } + }); return { format: root.sections === undefined ? "regular" : "indexed", reportedFile: root.file ?? null, @@ -460,46 +563,144 @@ export const inspectSourceMapValue = ( }; }; -/** - * Leaf maps reachable within the decoder's section depth and record budgets. - * Deeper or excess sections are dropped rather than expanded, so a map the - * decoder refused for its limits cannot allocate past them here. - */ -const boundedSourceMapLeaves = ( - root: unknown, - options: Pick, -): Record[] => { - const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS; - const leaves: Record[] = []; - if ( - typeof root !== "object" || - root === null || - Array.isArray(root) || - (root as { version?: unknown }).version !== 3 - ) - return leaves; - const pending: { map: unknown; depth: number }[] = [{ map: root, depth: 0 }]; - let records = 0; - while (pending.length > 0) { - options.check?.(); - const current = pending.pop(); - if (current === undefined) break; - const sections = classifySourceMapSections(current.map); - if (sections.kind === "invalid") continue; - if (sections.kind === "regular") { - leaves.push(current.map as Record); +export interface LocalSourceMapDeclaration { + readonly sectionPath: readonly number[]; + readonly sourceIndex: number; + readonly source: string | null; + readonly root: string | null; + readonly content: string | null; +} + +const localFailureDetail = (failure: ParseFailure): string => + failure.kind === "limit" + ? `Local source-map inspection exceeded ${failure.limit.name} (${String(failure.limit.maximum)}).` + : failure.detail; + +const recoverSourceDeclarations = ( + node: PendingMap, + failure: ParseFailure, + declarations: LocalSourceMapDeclaration[], + limitations: string[], +): void => { + const map = node.value; + const start = limitations.length; + const location = + node.path.length === 0 ? "" : ` in section [${node.path.join(",")}]`; + const names = map.sources; + if (!Array.isArray(names)) { + limitations.push(`Source map has no sources array${location}.`); + return; + } + const contents = sourceContentsSchema.safeParse(map.sourcesContent); + if (!contents.success) + limitations.push( + `Source map sourcesContent must be an array of strings or null entries${location}.`, + ); + const root = sourceRootSchema.safeParse(map.sourceRoot); + if (!root.success) { + limitations.push( + `Source map sourceRoot must be a string or null${location}.`, + ); + return; + } + for (const [sourceIndex, value] of names.entries()) { + const source = sourceNameSchema.safeParse(value); + if (!source.success) { + limitations.push( + `Source map contains a non-string source name at index ${String(sourceIndex)}${location}.`, + ); continue; } - if (current.depth >= limits.sectionDepth) continue; - records += sections.sections.length; - if (records > limits.decodedRecords) break; - for (let index = sections.sections.length - 1; index >= 0; index -= 1) { - const section = classifySourceMapSection(sections.sections[index]); - if (section.kind === "embedded") - pending.push({ map: section.map, depth: current.depth + 1 }); - } + const content = Array.isArray(map.sourcesContent) + ? sourceNameSchema.safeParse(map.sourcesContent[sourceIndex]) + : undefined; + declarations.push({ + sectionPath: node.path, + sourceIndex, + source: source.data, + root: root.data ?? null, + content: content?.success ? content.data : null, + }); } - return leaves; + if (typeof map.mappings !== "string") + limitations.push(`Source map has no mappings string${location}.`); + if (limitations.length === start) + limitations.push( + `Source map structure is invalid${location}: ${localFailureDetail(failure)}`, + ); +}; + +interface LocalSourceMapFacts { + readonly declarations: readonly LocalSourceMapDeclaration[]; + readonly limitations: readonly string[]; + readonly external_sections: readonly ExternalSourceMapSection[]; + readonly invalid_sections: readonly InvalidSourceMapSection[]; +} + +/** Read only local source declarations. Missing or invalid generated coordinates stay unresolved. */ +export const inspectLocalSourceMapDeclarations = ( + text: string, + options: Pick = {}, +): LocalSourceMapFacts => { + const declarations: LocalSourceMapDeclaration[] = []; + const limitations: string[] = []; + const external: ExternalSourceMapSection[] = []; + const invalid: InvalidSourceMapSection[] = []; + const unreadable = (limitation: string): LocalSourceMapFacts => ({ + declarations, + limitations: [limitation], + external_sections: external, + invalid_sections: invalid, + }); + options.check?.(); + let value: unknown; + try { + value = JSON.parse(sourceMapJsonText(text)); + } catch (cause) { + if (!(cause instanceof SyntaxError)) throw cause; + return unreadable("Source map is not valid JSON."); + } + if (!isVersion3Map(value)) + return unreadable("Source map is not a version 3 map."); + + const root = mapHeaderSchema.safeParse(value); + if (!root.success) + limitations.push("Source map reported file must be a string or null."); + walkSourceMapStructure( + value, + options, + (node, map) => + observeSourceDeclarations(node.path, map, (declaration) => + declarations.push(declaration), + ), + { + invalid: (path, failure) => + invalid.push({ + section_path: path, + reason: localFailureDetail(failure), + }), + external: (section) => external.push(section), + leaf: (node, failure) => + recoverSourceDeclarations(node, failure, declarations, limitations), + }, + ); + const comparePaths = ( + left: { section_path: readonly number[] }, + right: { section_path: readonly number[] }, + ): number => { + for (const [index, segment] of left.section_path.entries()) { + const other = right.section_path[index]; + if (other === undefined) return 1; + if (segment !== other) return segment - other; + } + return left.section_path.length - right.section_path.length; + }; + return { + declarations, + limitations, + external_sections: external.sort(comparePaths), + invalid_sections: invalid.sort(comparePaths), + }; }; /** Recover observed source content without treating incomplete maps as absent. */ @@ -543,17 +744,20 @@ export const inspectSourceMapSourceContent = ( }; } catch (failure) { if (!isSourceMapFailure(failure)) throw failure; - const budget = { records: 0 }; let embedded = false; - for (const leaf of boundedSourceMapLeaves(value, options)) { - try { - const inspected = inspectSourceMapValue(leaf, { ...options, budget }); - embedded ||= hasContent(inspected); - } catch (cause) { - if (!isSourceMapFailure(cause)) throw cause; - // An unresolved leaf cannot discard content observed in valid siblings. - } - } + const observe = (leaf: z.output): void => { + embedded ||= leaf.sources.some( + (_source, index) => (leaf.sourcesContent?.[index]?.length ?? 0) > 0, + ); + }; + if (isVersion3Map(value)) + walkSourceMapStructure(value, options, (_node, leaf) => observe(leaf), { + invalid: () => {}, + external: () => {}, + leaf: (_node, _failure, unpositionedMap) => { + if (unpositionedMap !== undefined) observe(unpositionedMap); + }, + }); return { embedded, complete: false, failure }; } }; diff --git a/tests/acceptance/applications/createRequireFilenameBase.test.ts b/tests/acceptance/applications/createRequireFilenameBase.test.ts index 4958564ab4..0d985228f0 100644 --- a/tests/acceptance/applications/createRequireFilenameBase.test.ts +++ b/tests/acceptance/applications/createRequireFilenameBase.test.ts @@ -50,3 +50,38 @@ console.log(JSON.stringify([nested("./dep.cjs"), current("./dep.cjs")]));`, ); }, ); + +cliTest.for(["CLI", "stdio MCP"] as const)( + "retains a parent in a createRequire filename that re-enters a same-named directory through %s", + async (surface, { cli }) => { + const root = await createTestTempDirectory("rea-create-require-parent-"); + await writeFixtureFiles(root, { + "app/main.mjs": `import { createRequire } from "node:module"; +const sibling = createRequire(new URL("../source/anchor.cjs", import.meta.url)); +console.log(JSON.stringify(sibling("./dep.cjs")));`, + "app/dep.cjs": 'module.exports = "app";', + "source/dep.cjs": 'module.exports = "source";', + }); + + expect(await runNodeJsonControl(root, "app/main.mjs")).toBe("source"); + const { graph } = await analyzeJavaScriptDirectory(surface, cli, root); + expect( + graph.edges + .filter( + ({ relation, properties }) => + relation === "imports" && + properties.specifier === "./dep.cjs" && + properties.kind === "require", + ) + .map(({ properties }) => ({ + resolution_base_path: properties.resolution_base_path, + resolved_path: properties.resolved_path, + })), + ).toEqual([ + { + resolution_base_path: "../source/anchor.cjs", + resolved_path: "source/dep.cjs", + }, + ]); + }, +); diff --git a/tests/acceptance/applications/sourceMapPrefixCli.test.ts b/tests/acceptance/applications/sourceMapPrefixCli.test.ts index 4d7adfe1a3..2a2523deb2 100644 --- a/tests/acceptance/applications/sourceMapPrefixCli.test.ts +++ b/tests/acceptance/applications/sourceMapPrefixCli.test.ts @@ -242,3 +242,120 @@ cliTest.for(["CLI", "stdio MCP"] as const)( } }, ); + +cliTest.for(["CLI", "stdio MCP"] as const)( + "keeps source declarations whose paths cannot be projected into the artifact through %s", + async (surface, { cli }) => { + const root = await createTestTempDirectory( + "rea-source-map-path-projection-", + ); + const original = "export const answer = 42;"; + const cases = [ + { source: "bad%00.ts", reason: /NUL byte/u }, + { source: "bad\0.ts", reason: /NUL byte/u }, + { source: "trailing.ts\0", reason: /NUL byte/u }, + { source: "file:///bad%00.ts", reason: /NUL byte/u }, + { source: "https://example.test/bad%00.ts", reason: /NUL byte/u }, + { source: "C:\\bad\0.ts", reason: /NUL byte/u }, + { source: "../../source/a.ts", reason: /outside/u }, + { source: "../../%73ource/a.ts", reason: /outside/u }, + { source: "../../anchor/a.ts", reason: /outside/u }, + { source: "../source/a.ts", path: "source/a.ts" }, + { source: "literal%2500.ts", path: "maps/literal%00.ts" }, + ]; + const mapPath = "maps/bundle.js.map"; + const mapText = JSON.stringify({ + version: 3, + sources: cases.map(({ source }) => source), + sourcesContent: cases.map(() => original), + names: [], + mappings: "", + }); + await writeFixtureFiles(root, { [mapPath]: mapText }); + const { graph } = await analyzeJavaScriptDirectory(surface, cli, root); + const originals = graph.nodes.filter( + ({ identity }) => identity.strategy === "source-map-original", + ); + expect(originals).toHaveLength(cases.length); + const sourceDigest = createHash("sha256").update(original).digest("hex"); + const mapDigest = createHash("sha256").update(mapText).digest("hex"); + for (const { source, reason, path } of cases) { + const node = originals.find( + ({ identity }) => + identity.strategy === "source-map-original" && + identity.original_source === source, + ); + expect(node?.identity).toMatchObject({ + source_sha256: sourceDigest, + source_map_sha256: mapDigest, + }); + expect(node?.observations[0]?.source_map_reference).toEqual({ + source_name: source, + source_root: null, + map_path: mapPath, + resolution: reason + ? { kind: "unresolved", reason: expect.stringMatching(reason) } + : { kind: "artifact-relative", path }, + }); + } + expect(graph.coverage.status).toBe("complete"); + }, +); + +cliTest.for(["CLI", "stdio MCP"] as const)( + "keeps local originals but reports incomplete source maps with malformed mappings or offsets through %s", + async (surface, { cli }) => { + const root = await createTestTempDirectory("rea-malformed-source-map-"); + const leaf = { + version: 3, + sources: ["original.ts"], + sourcesContent: ["export const answer = 42;"], + names: [], + mappings: "AAAA", + }; + const maps = { + "valid.js.map": leaf, + "bad-mapping.js.map": { ...leaf, mappings: "!" }, + "bad-offset.js.map": { + version: 3, + sections: [{ offset: { line: -1, column: 0 }, map: leaf }], + }, + }; + await writeFixtureFiles( + root, + Object.fromEntries( + Object.entries(maps).map(([path, map]) => [path, JSON.stringify(map)]), + ), + ); + + const { graph } = await analyzeJavaScriptDirectory(surface, cli, root); + expect(graph.coverage.status).toBe("partial"); + for (const path of Object.keys(maps)) + expect(graph.nodes).toContainEqual( + expect.objectContaining({ + kind: "source-module", + observations: expect.arrayContaining([ + expect.objectContaining({ + source_map_reference: expect.objectContaining({ + map_path: path, + source_name: "original.ts", + }), + properties: expect.objectContaining({ content_available: true }), + }), + ]), + }), + ); + + const unknownPaths = graph.nodes + .filter((node) => node.kind === "unknown") + .flatMap((node) => node.observations) + .filter( + ({ properties }) => properties.operation === "parse-local-source-map", + ) + .map(({ properties }) => properties.path); + expect(unknownPaths.toSorted()).toEqual([ + "bad-mapping.js.map", + "bad-offset.js.map", + ]); + }, +); diff --git a/tests/boundary/filesystem/sourceToBundlePaths.test.ts b/tests/boundary/filesystem/sourceToBundlePaths.test.ts index 4ceb6aff2e..5284b2af7c 100644 --- a/tests/boundary/filesystem/sourceToBundlePaths.test.ts +++ b/tests/boundary/filesystem/sourceToBundlePaths.test.ts @@ -10,7 +10,7 @@ import { parseApplicationGraphEvidence } from "../../../src/application/javascri import { findApplicationFeatureSeeds } from "../../../src/domain/javascript/javascriptFeatureSeed.js"; import { compareSourceToBundle } from "../../../src/domain/javascript/sourceToBundleComparison.js"; import { - resolveJavaScriptSourceMapReferences, + resolveJavaScriptSourceMapReference, resolveJavaScriptSourceMapUrl, } from "../../../src/domain/javascript/javascriptSourceMapPaths.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -935,7 +935,7 @@ it.each([ "checks encoded source-map separators in the parsed pathname of $source", ({ source, expected }) => { expect( - resolveJavaScriptSourceMapReferences([source], null, "ordinary.js.map")[0] + resolveJavaScriptSourceMapReference(source, null, "ordinary.js.map") ?.resolution, ).toEqual({ kind: "suffix", path: expected }); }, diff --git a/tests/boundary/process/sourceMapUncHosts.test.ts b/tests/boundary/process/sourceMapUncHosts.test.ts index 6fb0b88ec9..30fad2611c 100644 --- a/tests/boundary/process/sourceMapUncHosts.test.ts +++ b/tests/boundary/process/sourceMapUncHosts.test.ts @@ -73,11 +73,11 @@ processTest( const result = await processes.run(process.execPath, [ "--input-type=module", "--eval", - `import { resolveJavaScriptSourceMapReferences } from "./dist/domain/javascript/javascriptSourceMapPaths.js"; + `import { resolveJavaScriptSourceMapReference } from "./dist/domain/javascript/javascriptSourceMapPaths.js"; const inputs = JSON.parse(process.argv[1]); const references = inputs.map(({ name, source, root }) => { console.error("Resolving", name); - return resolveJavaScriptSourceMapReferences([source], root, "maps/main.js.map")[0]; + return resolveJavaScriptSourceMapReference(source, root, "maps/main.js.map"); }); console.log(JSON.stringify(references));`, JSON.stringify(inputs),