diff --git a/docs/guides/web/web-source-location.md b/docs/guides/web/web-source-location.md index efd3b9a74a..f98e59b6b7 100644 --- a/docs/guides/web/web-source-location.md +++ b/docs/guides/web/web-source-location.md @@ -48,6 +48,11 @@ It includes generated-only mappings. This follows with one-based lines in REA's public contract. A point result does not establish coverage of a source range, execution or UI causality. +Adjacent indexed sections may contribute mappings at the same generated +position. Those candidates are retained together, with their own section, +source, name and embedded-content identities. A mapping strictly after the +following section's start remains an invalid overlap. + Mapped entries preserve the raw source name/root, section path, section-local source index and flattened index. Duplicate URLs remain distinct, including entries with different embedded contents. Missing source names retain a null @@ -66,15 +71,15 @@ selected file identities. The adapter uses the locked upstream [`@jridgewell/trace-mapping` 0.3.31](https://github.com/jridgewell/trace-mapping) without modifying its code. It validates map/VLQ structure before allocation, -normalizes nested indexed offsets before upstream flattening, checks section -boundaries and indexes, and retains raw declaration identity. It supports regular +normalizes nested indexed offsets, decodes and validates each leaf's mappings, +and traces those validated rows directly, retaining raw declaration identity. It supports regular maps and inline indexed sections. Numeric `version: 3` is required on the root and every embedded map, including indexed ancestors. Invalid embedded headers report their section path and cannot produce descendant mapping facts. This uses the rejection option for version errors allowed by -[ECMA-426](https://tc39.es/ecma426/#sec-decodeindexsourcemap). -Equal section starts are allowed when earlier sections contribute no mappings; -actual decoded mappings must stay before the next section boundary. +[ECMA-426](https://tc39.es/ecma426/#sec-DecodeIndexSourceMap). +Equal section starts and mappings at the next section's start are allowed; +decoded mappings strictly past the next or an enclosing section boundary are rejected. External section URLs return an actionable unsupported-profile error. This is a defined decoder profile, not a claim to implement every current source-map extension. @@ -241,9 +246,10 @@ the failed bundle request retains those items with the captured page in partial Evidence and marks bundle analysis `not_performed`. This is distinct from the local source-map decoder's failure semantics above. An enclosing column offset contributes only when the nested section starts on -that enclosing section's first generated line. Parent boundaries still clip +that enclosing section's first generated line. Parent boundaries still constrain preceding browser mappings when a nested section starts with a gap or has no -child leaves. Raw map text, original source identities and the dedicated decoder +child leaves: mappings at the boundary are retained, and mappings past it are rejected. +Raw map text, original source identities and the dedicated decoder profile are preserved. Browser `original_module_edges` carry a `declaration_index` joining each edge to @@ -254,7 +260,7 @@ of the original source it maps to. Browser collection defaults to 64 MiB of map responses per inspection and preflights indexed sections, sources, names, generated rows and mapping segments -against a 262144-record decode budget before upstream flattening. Indexed maps +against a 262144-record decode budget before decoding validated leaf mappings. Indexed maps default to 64 nested levels. These structural limits bound decoded object growth while preserving large embedded `sourcesContent` strings within the response-byte budget. It also bounds the expanded inline evidence to 32 MiB diff --git a/src/domain/decodedSourceMap.ts b/src/domain/decodedSourceMap.ts index 677c988e0e..98724a165e 100644 --- a/src/domain/decodedSourceMap.ts +++ b/src/domain/decodedSourceMap.ts @@ -6,8 +6,8 @@ import { type SourceMapLeaf, } from "./sourceMapFormat.js"; -/** Determine whether a leaf-local mapping falls before its enclosing boundary. */ -const isBeforeSourceMapLeafStop = ( +/** ECMA-426 permits equal-position mappings at a following section's start. */ +const isWithinSourceMapLeafStop = ( leaf: SourceMapLeaf, line: number, column: number, @@ -17,7 +17,7 @@ const isBeforeSourceMapLeafStop = ( const generatedColumn = column + (line === 0 ? leaf.offset.column : 0); return ( generatedLine < leaf.stop.line || - (generatedLine === leaf.stop.line && generatedColumn < leaf.stop.column) + (generatedLine === leaf.stop.line && generatedColumn <= leaf.stop.column) ); }; @@ -41,7 +41,7 @@ export const decodeValidatedSourceMapLeaves = ( const generatedLine = leaf.offset.line + line; const generatedColumn = segment[0] + (line === 0 ? leaf.offset.column : 0); - if (!isBeforeSourceMapLeafStop(leaf, line, segment[0])) + if (!isWithinSourceMapLeafStop(leaf, line, segment[0])) throw sourceMapSectionOverlap( "Embedded source-map mappings overlap the following section boundary.", ); diff --git a/src/javascript/sourceMaps/TraceSourceMap.test.ts b/src/javascript/sourceMaps/TraceSourceMap.test.ts index 724c8f0ad3..75d9976740 100644 --- a/src/javascript/sourceMaps/TraceSourceMap.test.ts +++ b/src/javascript/sourceMaps/TraceSourceMap.test.ts @@ -220,6 +220,109 @@ describe("upstream source-map point evidence", () => { }); }); +describe("source-map section-boundary candidates", () => { + it.each([ + { mappings: "AAAAA", column: 0, nested: false }, + { mappings: "AAAAA,KAAAA", column: 5, nested: false }, + { mappings: "AAAAA;AAAAA", column: 0, nested: true }, + ])( + "retains all section-boundary candidates ($mappings, nested=$nested)", + ({ mappings, column, nested }) => { + const first = { + ...leaf, + sources: ["same.ts"], + sourcesContent: ["first"], + names: ["firstName"], + mappings, + }; + const second = { + ...leaf, + sources: ["same.ts"], + sourcesContent: ["second"], + names: ["secondName"], + mappings: "AAAAA", + }; + const line = nested ? 1 : 0; + const report = trace( + { + version: 3, + sections: [ + { offset: { line: 0, column: 0 }, map: first }, + { + offset: { line, column }, + map: nested + ? { + version: 3, + sections: [ + { + offset: { line: 0, column: 0 }, + map: second, + }, + ], + } + : second, + }, + ], + }, + { line: line + 1, column }, + ); + expect(report.lookup.matched_generated_position).toEqual({ + line: line + 1, + column, + }); + expect(report.matches).toMatchObject([ + { + flattened_source_index: 0, + section_path: [0], + source_index: 0, + content: { text: "first" }, + name: "firstName", + }, + { + flattened_source_index: 1, + section_path: nested ? [1, 0] : [1], + source_index: 0, + content: { text: "second" }, + name: "secondName", + }, + ]); + expect(report.matches).toHaveLength(2); + }, + ); + it.each([false, true])( + "keeps a generated-only section-boundary candidate (first=%s)", + (generatedOnlyFirst) => { + const generated = { version: 3, sources: [], names: [], mappings: "A" }; + const first = generatedOnlyFirst ? generated : leaf; + const second = generatedOnlyFirst ? leaf : generated; + const report = trace( + { + version: 3, + sections: [ + { + offset: { line: 0, column: 0 }, + map: { ...first, mappings: `K${first.mappings.slice(1)}` }, + }, + { offset: { line: 0, column: 5 }, map: second }, + ], + }, + { line: 1, column: 5 }, + ); + const mapped = { + state: "mapped", + flattened_source_index: 0, + section_path: [generatedOnlyFirst ? 1 : 0], + source_index: 0, + }; + const generatedOnly = { state: "generated-only" }; + expect(report.matches).toMatchObject( + generatedOnlyFirst ? [generatedOnly, mapped] : [mapped, generatedOnly], + ); + expect(report.matches).toHaveLength(2); + }, + ); +}); + describe("source-map layout admission", () => { it.each(["AAAAC", "g", "!", "AA", "D"])( "rejects malformed VLQ/components/indexes: %s", diff --git a/src/javascript/sourceMaps/TraceSourceMap.ts b/src/javascript/sourceMaps/TraceSourceMap.ts index 32dfd61c68..e072d845f0 100644 --- a/src/javascript/sourceMaps/TraceSourceMap.ts +++ b/src/javascript/sourceMaps/TraceSourceMap.ts @@ -1,17 +1,11 @@ import { malformedInput } from "../../domain/parseFailure.js"; import { WEB_SOURCE_MAP_LIMITS, - sourceMapLimitRecovery, type SourceMapLimits, } from "../../domain/sourceMapLimits.js"; import { createRequire } from "node:module"; import { getHeapStatistics } from "node:v8"; -import { - AnyMap, - TraceMap, - decodedMappings, - type SourceMapSegment, -} from "@jridgewell/trace-mapping"; +import type { TraceMap, SourceMapSegment } from "@jridgewell/trace-mapping"; import { z } from "zod"; import { javaScriptRuntime } from "../../domain/runtimeVersion.js"; import { javaScriptWorkerMemoryLimitBytes } from "../../process/JavaScriptWorkerMemoryLimit.js"; @@ -40,51 +34,34 @@ export const traceSourceMap = ( ): WebSourceMapReport => { const inspected = inspectSourceMap(text, { limits }); const decodedLeaves = decodeValidatedSourceMapLeaves(inspected.leaves, url); - let map: TraceMap; - if (inspected.format === "regular") { - const decoded = decodedLeaves[0]; - if (decoded === undefined) - throw malformedInput( - SOURCE_MAP_FORMAT, - "Regular source map has no validated leaf.", - ); - map = decoded.map; - } else { - map = new AnyMap( - { - version: 3, - sections: decodedLeaves.map(({ leaf, map: sectionMap }) => ({ - offset: leaf.offset, - map: sectionMap, - })), - }, - url, - ); - } - const rows = - inspected.format === "regular" - ? (decodedLeaves[0]?.rows ?? []) - : decodedMappings(map); - validateFlattenedRows(inspected, rows, map); - const matched = greatestPosition(rows, position); - const segments = - matched === null - ? [] - : (rows[matched.line - 1] ?? []).filter( - (segment) => segment[0] === matched.column, - ); + const matched = greatestPosition(decodedLeaves, position); let bytes = 0; const matches: WebSourceMapReport["matches"] = []; - for (const segment of segments) { - const match = originalMatch(segment, map, url, inspected.declarations); - bytes += Buffer.byteLength(JSON.stringify(match)) + 1; - if (bytes > limits.outputBytes) - throw sourceMapLimitFailure( - `Complete source-map point evidence exceeds output admission; no partial evidence was returned.`, - "output_bytes", - limits.outputBytes, - ); - matches.push(match); + let sourceBase = 0; + for (const { leaf, map, rows } of decodedLeaves) { + if (matched !== null) { + const line = matched.line - leaf.offset.line - 1; + const column = matched.column - (line === 0 ? leaf.offset.column : 0); + for (const segment of rows[line] ?? []) { + if (segment[0] !== column) continue; + const match = originalMatch( + segment, + map, + url, + inspected.declarations, + sourceBase, + ); + bytes += Buffer.byteLength(JSON.stringify(match)) + 1; + if (bytes > limits.outputBytes) + throw sourceMapLimitFailure( + `Complete source-map point evidence exceeds output admission; no partial evidence was returned.`, + "output_bytes", + limits.outputBytes, + ); + matches.push(match); + } + } + sourceBase += leaf.map.sources.length; } const metadata: unknown = createRequire(import.meta.url)( "@jridgewell/trace-mapping/package.json", @@ -129,49 +106,45 @@ export const traceSourceMap = ( }); }; -const validateFlattenedRows = ( - inspected: ReturnType, - rows: ReturnType, - map: ReturnType, -): void => { - for (const row of rows) - for (const segment of row) { - if ( - (segment.length !== 1 && segment[1] >= inspected.declarations.length) || - (segment.length === 5 && segment[4] >= map.names.length) - ) - throw malformedInput( - SOURCE_MAP_FORMAT, - "Decoded mapping has invalid component count, position, source index or name index.", - ); - } -}; - +/** Compare validated leaf positions without a second, clipping flatten operation. */ const greatestPosition = ( - rows: ReturnType, + leaves: ReturnType, position: WebSourcePosition, ): WebSourcePosition | null => { - for ( - let line = Math.min(position.line - 1, rows.length - 1); - line >= 0; - line -= 1 - ) { - let column: number | undefined; - for (const segment of rows[line] ?? []) - if (line < position.line - 1 || segment[0] <= position.column) - column = segment[0]; - if (column !== undefined) return { line: line + 1, column }; + let matched: WebSourcePosition | null = null; + for (const { leaf, rows } of leaves) { + const localLine = position.line - leaf.offset.line - 1; + for (let line = Math.min(localLine, rows.length - 1); line >= 0; line--) { + let column: number | undefined; + for (const segment of rows[line] ?? []) { + const absoluteColumn = + segment[0] + (line === 0 ? leaf.offset.column : 0); + if (line < localLine || absoluteColumn <= position.column) + column = absoluteColumn; + } + if (column === undefined) continue; + const absoluteLine = leaf.offset.line + line + 1; + if ( + matched === null || + absoluteLine > matched.line || + (absoluteLine === matched.line && column > matched.column) + ) + matched = { line: absoluteLine, column }; + break; + } } - return null; + return matched; }; const originalMatch = ( segment: Readonly, map: TraceMap, mapUrl: string, declarations: readonly SourceMapSourceDeclaration[], + sourceBase: number, ): WebSourceMapReport["matches"][number] => { if (segment.length === 1) return { state: "generated-only" }; - const declaration = declarations[segment[1]]; + const sourceIndex = sourceBase + segment[1]; + const declaration = declarations[sourceIndex]; if (declaration === undefined) throw malformedInput( SOURCE_MAP_FORMAT, @@ -184,7 +157,7 @@ const originalMatch = ( : webSourceOffset(declaration.content, original); return { state: "mapped", - flattened_source_index: segment[1], + flattened_source_index: sourceIndex, section_path: [...declaration.sectionPath], source_index: declaration.sourceIndex, reported_source: declaration.source, diff --git a/tests/acceptance/webSourceLocationCli.test.ts b/tests/acceptance/webSourceLocationCli.test.ts index 748c228b68..f4d8d54b2b 100644 --- a/tests/acceptance/webSourceLocationCli.test.ts +++ b/tests/acceptance/webSourceLocationCli.test.ts @@ -470,7 +470,7 @@ cliTest( ); cliTest( - "traces empty equal-offset sections while rejecting decreasing offsets and represented overlaps", + "traces equal-offset sections and shared boundary mappings while rejecting decreasing offsets and overlaps", { tags: ["long-running"] }, async ({ cli }) => { const root = await createTestTempDirectory("rea-empty-indexed-map-"); @@ -486,11 +486,32 @@ cliTest( version: 3, sections: [{ offset: { line: 0, column: 0 }, map: empty }], }; + const boundaryLeaf = { + version: 3, + sources: ["earlier.ts"], + sourcesContent: ["earlier"], + names: ["earlierName"], + mappings: "AAAAA,CAAAA", + }; for (const [index, sample] of [ { first: empty, firstColumn: 0, nextColumn: 0, succeeds: true }, { first: nestedEmpty, firstColumn: 0, nextColumn: 0, succeeds: true }, { first: empty, firstColumn: 0, nextColumn: 1, succeeds: true }, - { first: leaf, firstColumn: 0, nextColumn: 0, succeeds: false }, + { + first: leaf, + firstColumn: 0, + nextColumn: 0, + succeeds: true, + shared: true, + }, + { + first: boundaryLeaf, + firstColumn: 0, + nextColumn: 1, + succeeds: true, + shared: true, + }, + { first: boundaryLeaf, firstColumn: 0, nextColumn: 0, succeeds: false }, { first: empty, firstColumn: 1, nextColumn: 0, succeeds: false }, ].entries()) { const path = join(root, `empty-${index}.map`); @@ -537,6 +558,19 @@ cliTest( }, }, matches: [ + ...("shared" in sample + ? [ + { + state: "mapped", + section_path: [0], + flattened_source_index: 0, + content: { + text: sample.first === leaf ? "original" : "earlier", + }, + name: sample.first === leaf ? null : "earlierName", + }, + ] + : []), { state: "mapped", section_path: [1], @@ -545,6 +579,10 @@ cliTest( ], }, }); + const matches = ( + result.json as { normalized_result: { matches: unknown[] } } + ).normalized_result.matches; + expect(matches).toHaveLength("shared" in sample ? 2 : 1); expect(response.isError, JSON.stringify(response)).not.toBe(true); expect(response.structuredContent).toEqual(result.json); } else { diff --git a/tests/boundary/browser/webSourceMapNestedCoordinates.test.ts b/tests/boundary/browser/webSourceMapNestedCoordinates.test.ts index 23eb03ae15..d59d5252a2 100644 --- a/tests/boundary/browser/webSourceMapNestedCoordinates.test.ts +++ b/tests/boundary/browser/webSourceMapNestedCoordinates.test.ts @@ -17,11 +17,11 @@ const input = analyzeWebBundleInputSchema.parse({ fetch_source_maps: true, }); -const leaf = (source: string, mappings = "AAAA") => ({ +const leaf = (source: string, mappings = "AAAA", names: string[] = []) => ({ version: 3, sources: [source], sourcesContent: ["export const value = 1;"], - names: [], + names, mappings, }); @@ -134,7 +134,7 @@ it.each([ }); }); -it("treats the next section start as an exclusive end for the previous section", async () => { +it("accepts mappings at the next section start and rejects mappings beyond it", async () => { const fetchSiblings = (firstMappings: string) => fetchMap( JSON.stringify( @@ -157,7 +157,54 @@ it("treats the next section start as an exclusive end for the previous section", }, ], }); - expect(await fetchSiblings("AAAA,UAAA")).toMatchObject({ + const text = JSON.stringify( + indexed( + section(0, 0, { + ...leaf("same.ts", "AAAAA,UAAAA", ["first"]), + sourcesContent: ["export const first = 1;"], + }), + section(0, 10, { + ...leaf("same.ts", "AAAAA", ["second"]), + sourcesContent: ["export const second = 2;"], + }), + ), + ); + expect(await fetchMap(text)).toMatchObject({ + status: "included", + items: [ + { + artifact: { + sha256: createHash("sha256").update(text).digest("hex"), + bytes: Buffer.byteLength(text), + }, + original_sources: [ + { source: `${origin}/same.ts`, declaration_index: 0 }, + { source: `${origin}/same.ts`, declaration_index: 1 }, + ], + mappings: [ + { + generated_line: 1, + generated_column: 0, + declaration_index: 0, + name: "first", + }, + { + generated_line: 1, + generated_column: 10, + declaration_index: 0, + name: "first", + }, + { + generated_line: 1, + generated_column: 10, + declaration_index: 1, + name: "second", + }, + ], + }, + ], + }); + expect(await fetchSiblings("AAAA,UAAA,CAAA")).toMatchObject({ status: "unavailable", items: [ {