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
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 03:32:08 +00:00
1 parent 261c6d06d1
commit 27e04ea2ec
15 files changed
+794 -531

No files matched your search

@@ -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
@@ -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,
@@ -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-");
@@ -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;
};
@@ -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;
@@ -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:
@@ -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;
-15
View File
@@ -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",
));
+68 -42
View File
@@ -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).",
},
]);
});
+1 -129
View File
@@ -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<Record<string, unknown>>;
}
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,
};
};
+396 -192
View File
@@ -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<typeof sectionOffsetSchema>["offset"];
type RawMap = Readonly<Record<string, unknown>>;
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<typeof leafSchema>,
) => void;
}
/** Aggregate structural work shared by maps in one selected inspection. */
export interface SourceMapStructureBudget {
records: number;
@@ -118,12 +137,7 @@ const parseStructure = <Schema extends z.ZodType>(
};
/** 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 = <Value>(
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<typeof leafSchema> => {
): 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<Record<string, unknown>>;
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<typeof leafSchema>; 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<typeof leafSchema>) => 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<typeof inspectLeaf>;
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<typeof leafSchema>,
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<SourceMapStructureOptions, "limits" | "check">,
): Record<string, unknown>[] => {
const limits = options.limits ?? WEB_SOURCE_MAP_LIMITS;
const leaves: Record<string, unknown>[] = [];
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<string, unknown>);
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<SourceMapStructureOptions, "limits" | "check"> = {},
): 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<typeof leafSchema>): 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 };
}
};
@@ -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",
},
]);
},
);
@@ -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",
]);
},
);
@@ -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 });
},
@@ -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),