reverseport 0.0.0-stage → 1.2.0

package/dist/javascript/sourceMaps/SourceMapDecoder.js

@@ -0,0 +1,135 @@
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
+import { err, ok } from "../../domain/result.js";
+import { javaScriptRuntime } from "../../domain/runtimeVersion.js";
+import { WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
+import { sourceMapCodecInputSchema, sourceMapCodecReplySchema, } from "./SourceMapCodecProtocol.js";
+import { SOURCE_MAP_CODEC_MEMORY_LIMIT_BYTES, SourceMapCleanupFailure, runSourceMapCommand, } from "./SourceMapCommand.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { jsonParts } from "../../domain/jsonSerialization.js";
+const OPERATION = "trace_web_source_location";
+/** Integrate the pinned upstream codec through an independently bounded owned process. */
+export class SourceMapDecoder {
+    dependencies;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup;
+    constructor(dependencies = {}) {
+        this.dependencies = dependencies;
+    }
+    /** Return complete point evidence after process and private-root cleanup. */
+    trace(input, options) {
+        if (this.#closing)
+            return Promise.resolve(err(new ProviderCleanupError("source-map-decoder", [], { reason: "Provider is closing" }, { operation: OPERATION })));
+        const operation = this.#tail.then(() => this.#closing
+            ? err(new ProviderCleanupError("source-map-decoder", [], { reason: "Provider is closing" }, { operation: OPERATION }))
+            : this.#trace(input, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #trace(input, options) {
+        const cleanupFailure = await this.#retryCleanup();
+        if (cleanupFailure !== undefined)
+            return err(cleanupFailure);
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const request = sourceMapCodecInputSchema.safeParse({
+            text: input.text,
+            url: input.url,
+            position: input.position,
+        });
+        if (!request.success)
+            return err(new AnalysisInputError(OPERATION, { cause: request.error }));
+        const capacityFailure = () => new ArtifactOperationError(OPERATION, "limit", undefined, `${input.path}: Source-map input exceeds the 4 MiB map or 32 MiB encoded request budget.`);
+        if (Buffer.byteLength(input.text) > WEB_SOURCE_MAP_LIMITS.mapBytes)
+            return err(capacityFailure());
+        const encoded = [];
+        let encodedBytes = 0;
+        for (const part of jsonParts(request.data)) {
+            const bytes = Buffer.byteLength(part);
+            if (bytes > WEB_SOURCE_MAP_LIMITS.outputBytes - encodedBytes)
+                return err(capacityFailure());
+            encoded.push(part);
+            encodedBytes += bytes;
+        }
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const serialized = encoded.join("");
+        const response = await runSourceMapCommand(serialized, input.path, options, this.dependencies);
+        if (!response.ok) {
+            if (response.error instanceof SourceMapCleanupFailure)
+                this.#pendingCleanup = response.error.cleanupOwner;
+            return response;
+        }
+        let value;
+        try {
+            value = JSON.parse(response.value);
+        }
+        catch (cause) {
+            return err(new AnalysisOutputError(OPERATION, `Malformed codec JSON reply: ${cause instanceof Error ? cause.message : String(cause)}`));
+        }
+        const reply = sourceMapCodecReplySchema.safeParse(value);
+        if (!reply.success)
+            return err(new AnalysisOutputError(OPERATION, `Malformed codec reply: ${reply.error.message}`));
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        if (reply.data.state === "failure")
+            return codecFailure(input.path, reply.data.reason, reply.data.message);
+        const runtimeFailure = codecRuntimeFailure(reply.data.report.runtime);
+        return runtimeFailure === undefined
+            ? ok(reply.data.report)
+            : err(new AnalysisOutputError(OPERATION, runtimeFailure));
+    }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retryCleanup();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    async #retryCleanup() {
+        const pending = this.#pendingCleanup;
+        if (pending === undefined)
+            return undefined;
+        const failure = await pending.close(null);
+        if (failure !== undefined)
+            return failure;
+        this.#pendingCleanup = undefined;
+        return undefined;
+    }
+}
+/**
+ * The codec runs on this process's executable. Only a V8 report carries a heap
+ * limit; a Bun report must name the process limit its launcher enforced.
+ */
+const codecRuntimeFailure = (runtime) => {
+    if (runtime.id !==
+        (javaScriptRuntime(process.versions).id === "bun" ? "bun" : "node-v8"))
+        return `Codec reported runtime ${runtime.id}, not the runtime that launched it.`;
+    if (runtime.id === "node-v8" &&
+        runtime.v8_heap_limit_bytes > 256 * 1024 * 1024)
+        return "Codec reported a V8 heap limit exceeding its independent process budget.";
+    if (runtime.id === "bun" &&
+        runtime.process_memory_limit_bytes !== SOURCE_MAP_CODEC_MEMORY_LIMIT_BYTES)
+        return "Codec reported a process memory limit other than the one its launcher enforced.";
+    return undefined;
+};
+const codecFailure = (path, reason, detail) => err(reason === "limit"
+    ? new ArtifactOperationError(OPERATION, "limit", undefined, `${path}: ${detail}`)
+    : reason === "unsupported"
+        ? new AnalysisCapabilityUnavailableError("source-map-decoder", OPERATION, "unsupported_source_map_profile", { userMessage: `${path}: ${detail}` })
+        : new AnalysisInputError(OPERATION, undefined, [
+            {
+                path: ["source_map", "path"],
+                reason: "invalid_format",
+                message: `${path}: ${detail}`,
+            },
+        ]));

package/dist/javascript/sourceMaps/SourceMapFormat.js

@@ -0,0 +1,238 @@
+import { z } from "zod";
+import { WEB_SOURCE_MAP_LIMITS } from "../../domain/webSourceLocation.js";
+import { hasValidSourceMapContents } from "../../domain/sourceMapContents.js";
+import { sourceMapJsonText } from "../../domain/sourceMapEnvelope.js";
+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(),
+    names: z.array(z.string()).default([]),
+    mappings: z.string().regex(/^[A-Za-z0-9+/,;]*$/u),
+    ignoreList: z.array(z.number().int().min(0)).optional(),
+    x_google_ignoreList: z.array(z.number().int().min(0)).optional(),
+});
+const mapHeaderSchema = z.object({
+    version: z.literal(3),
+    file: z.string().nullable().optional(),
+    sections: z.unknown().optional(),
+});
+const sectionSchema = z.object({
+    offset: z.object({
+        line: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+        column: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    }),
+    map: z.unknown().optional(),
+    url: z.string().optional(),
+});
+const indexedSchema = z.object({
+    version: z.literal(3),
+    sections: z.array(sectionSchema),
+});
+/** A decoder-profile failure with an actionable producer constraint. */
+export class SourceMapFormatFailure extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+const codecLeaf = (map) => ({
+    version: 3,
+    ...(map.file === undefined ? {} : { file: map.file }),
+    ...(typeof map.sourceRoot === "string" ? { sourceRoot: map.sourceRoot } : {}),
+    sources: map.sources,
+    ...(map.sourcesContent == null ? {} : { sourcesContent: map.sourcesContent }),
+    names: map.names,
+    mappings: map.mappings,
+    ...(map.ignoreList === undefined ? {} : { ignoreList: map.ignoreList }),
+    ...(map.x_google_ignoreList === undefined
+        ? {}
+        : { x_google_ignoreList: map.x_google_ignoreList }),
+});
+const compare = (a, b) => a.line - b.line || a.column - b.column;
+const addOffset = (base, offset) => {
+    const result = {
+        line: base.line + offset.line,
+        column: offset.column + (offset.line === 0 ? base.column : 0),
+    };
+    if (!Number.isSafeInteger(result.line) ||
+        !Number.isSafeInteger(result.column) ||
+        result.line >= WEB_SOURCE_MAP_LIMITS.decodedRows)
+        throw new SourceMapFormatFailure("limit", "Indexed offset exceeds the 262144 generated-row decoder budget.");
+    return result;
+};
+const consumeRecords = (budget, count) => {
+    if (count > WEB_SOURCE_MAP_LIMITS.decodedRecords - budget.records)
+        throw new SourceMapFormatFailure("limit", `Source-map structure exceeds the ${WEB_SOURCE_MAP_LIMITS.decodedRecords}-record decoder budget.`);
+    budget.records += count;
+};
+const addSections = (node, pending, budget, options) => {
+    options.check?.();
+    const header = mapHeaderSchema.parse(node.value);
+    if (!Array.isArray(header.sections))
+        throw new SourceMapFormatFailure("format", "Indexed source-map sections must be an array.");
+    consumeRecords(budget, header.sections.length);
+    const sections = indexedSchema.parse(node.value).sections;
+    for (const [index, section] of sections.entries()) {
+        if ((index & 255) === 0)
+            options.check?.();
+        const previous = sections[index - 1];
+        if (previous !== undefined && compare(section.offset, previous.offset) <= 0)
+            throw new SourceMapFormatFailure("format", "Indexed section offsets must be strictly increasing.");
+        if (section.url !== undefined)
+            throw new SourceMapFormatFailure("unsupported", `External source-map section URL is not fetched: ${section.url}`);
+        if (section.map === undefined)
+            throw new SourceMapFormatFailure("format", "Indexed section requires an embedded map.");
+    }
+    for (let index = sections.length - 1; index >= 0; index -= 1) {
+        const section = sections[index];
+        if (section === undefined)
+            continue;
+        const next = sections[index + 1];
+        const nextOffset = next === undefined ? null : addOffset(node.offset, next.offset);
+        const stop = nextOffset === null
+            ? node.stop
+            : node.stop === null || compare(nextOffset, node.stop) < 0
+                ? nextOffset
+                : node.stop;
+        const offset = addOffset(node.offset, section.offset);
+        if (node.stop !== null && compare(offset, node.stop) >= 0)
+            throw new SourceMapFormatFailure("format", "Nested source-map section overlaps its enclosing boundary.");
+        pending.push({
+            value: section.map,
+            path: [...node.path, index],
+            offset,
+            stop,
+        });
+    }
+};
+const inspectMappingLayout = (mappings, check) => {
+    let lines = 1;
+    let segments = 0;
+    let components = 0;
+    let inSegment = false;
+    let continued = false;
+    let digits = 0;
+    const finish = () => {
+        if (continued)
+            throw new SourceMapFormatFailure("format", "Source-map VLQ ends with an unfinished continuation.");
+        if (inSegment && ![1, 4, 5].includes(components))
+            throw new SourceMapFormatFailure("format", "Source-map segment requires one, four or five VLQ components.");
+    };
+    let index = 0;
+    for (const character of mappings) {
+        if ((index++ & 0x3fff) === 0)
+            check?.();
+        if (character === "," || character === ";") {
+            finish();
+            inSegment = false;
+            components = 0;
+            if (character === ";")
+                lines += 1;
+        }
+        else {
+            digits += 1;
+            if ((digits === 7 && !/[A-Dg-j]/u.test(character)) ||
+                (digits > 7 && character !== "A" && character !== "g"))
+                throw new SourceMapFormatFailure("format", "Source-map VLQ exceeds the format's 32-bit quantity representation.");
+            if (!inSegment)
+                segments += 1;
+            inSegment = true;
+            continued = /[g-z0-9+/]/u.test(character);
+            if (!continued) {
+                components += 1;
+                digits = 0;
+            }
+        }
+        if (segments > WEB_SOURCE_MAP_LIMITS.decodedSegments ||
+            lines > WEB_SOURCE_MAP_LIMITS.decodedRows)
+            throw new SourceMapFormatFailure("limit", "Source-map layout exceeds the 262144 segment/generated-row decoder budget.");
+    }
+    finish();
+    return { lines, segments };
+};
+const inspectLeaf = (node, budget, options) => {
+    options.check?.();
+    consumeRecords(budget, 1);
+    if (typeof node.value !== "object" ||
+        node.value === null ||
+        Array.isArray(node.value))
+        return leafSchema.parse(node.value);
+    const rawMap = node.value;
+    const rawSources = rawMap.sources;
+    const rawNames = rawMap.names;
+    const rawContents = rawMap.sourcesContent;
+    consumeRecords(budget, Array.isArray(rawSources) ? rawSources.length : 0);
+    consumeRecords(budget, Array.isArray(rawNames) ? rawNames.length : 0);
+    consumeRecords(budget, Array.isArray(rawContents) ? rawContents.length : 0);
+    options.check?.();
+    if (options.profile === "browser-collection" && !Array.isArray(rawNames))
+        throw new SourceMapFormatFailure("format", "Source-map leaf requires a names array.");
+    if (options.profile === "browser-collection" &&
+        !hasValidSourceMapContents(Array.isArray(rawSources) ? rawSources.length : 0, rawContents))
+        throw new SourceMapFormatFailure("format", "Source-map sourcesContent must align with its source declarations.");
+    options.check?.();
+    const leaf = leafSchema.parse(node.value);
+    const layout = inspectMappingLayout(leaf.mappings, options.check);
+    consumeRecords(budget, layout.segments + layout.lines);
+    if (layout.segments > WEB_SOURCE_MAP_LIMITS.decodedSegments ||
+        node.offset.line + layout.lines > WEB_SOURCE_MAP_LIMITS.decodedRows)
+        throw new SourceMapFormatFailure("limit", "Source-map layout exceeds the 262144 segment/generated-row decoder budget.");
+    return leaf;
+};
+/** Validate structure before allocation, retaining raw declarations and section boundaries. */
+export const inspectSourceMap = (text) => {
+    const jsonText = sourceMapJsonText(text);
+    const value = JSON.parse(jsonText);
+    return inspectSourceMapValue(value);
+};
+/** Return validated leaves when a consumer needs decoded rows after preflight. */
+export const inspectSourceMapValue = (value, options = {}) => {
+    options.check?.();
+    const root = mapHeaderSchema.parse(value);
+    const declarations = [];
+    const leaves = [];
+    const pending = [
+        { 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 > WEB_SOURCE_MAP_LIMITS.sectionDepth)
+            throw new SourceMapFormatFailure("limit", "Indexed source-map nesting exceeds the 64-level decoder stack budget.");
+        if (mapHeaderSchema.parse(node.value).sections !== undefined) {
+            addSections(node, pending, budget, options);
+            continue;
+        }
+        const leaf = inspectLeaf(node, budget, options);
+        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 ?? []);
+            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,
+        declarations,
+        leaves,
+    };
+};

package/dist/javascript/sourceMaps/TraceSourceMap.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { getHeapStatistics } from "node:v8";
+import { AnyMap, TraceMap, decodedMappings, } from "@jridgewell/trace-mapping";
+import { z } from "zod";
+import { javaScriptRuntime } from "../../domain/runtimeVersion.js";
+import { javaScriptWorkerMemoryLimitBytes } from "../../process/JavaScriptWorkerMemoryLimit.js";
+import { webSourceOffset } from "../../domain/webSourcePosition.js";
+import { webSourceMapReportSchema, WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
+import { inspectSourceMap, SourceMapFormatFailure, } from "./SourceMapFormat.js";
+import { decodeValidatedSourceMapLeaves, isBeforeSourceMapLeafStop, } from "./DecodedSourceMap.js";
+/** Decode with the pinned upstream codec; preserve every equal-position candidate. */
+export const traceSourceMap = (text, url, position) => {
+    const inspected = inspectSourceMap(text);
+    const decodedLeaves = decodeValidatedSourceMapLeaves(inspected.leaves, url);
+    for (const { leaf, rows } of decodedLeaves)
+        for (const [line, row] of rows.entries())
+            for (const segment of row)
+                if (!isBeforeSourceMapLeafStop(leaf, line, segment[0]))
+                    throw new SourceMapFormatFailure("format", "Embedded source-map mappings overlap the following section boundary.");
+    let map;
+    if (inspected.format === "regular") {
+        const decoded = decodedLeaves[0];
+        if (decoded === undefined)
+            throw new SourceMapFormatFailure("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);
+    let bytes = 0;
+    const matches = [];
+    for (const segment of segments) {
+        const match = originalMatch(segment, map, inspected.declarations);
+        bytes += Buffer.byteLength(JSON.stringify(match)) + 1;
+        if (bytes > WEB_SOURCE_MAP_LIMITS.outputBytes)
+            throw new SourceMapFormatFailure("limit", "Complete source-map point evidence exceeds the 32 MiB output budget; no partial evidence was returned.");
+        matches.push(match);
+    }
+    const metadata = createRequire(import.meta.url)("@jridgewell/trace-mapping/package.json");
+    const version = z
+        .object({ version: z.string().min(1) })
+        .parse(metadata).version;
+    const runtime = javaScriptRuntime(process.versions);
+    return webSourceMapReportSchema.parse({
+        source_map_sha256: createHash("sha256").update(text).digest("hex"),
+        url_context: url,
+        engine: { id: "jridgewell-trace-mapping", version },
+        // Bun reports V8-shaped heap statistics but ignores the codec's heap flags.
+        // Its launcher applies the same runtime policy, and the parent verifies it.
+        runtime: runtime.id === "node"
+            ? {
+                id: "node-v8",
+                version: process.version,
+                v8_heap_limit_bytes: getHeapStatistics().heap_size_limit,
+            }
+            : {
+                id: "bun",
+                version: runtime.version,
+                node_compatibility_version: runtime.nodeCompatibilityVersion,
+                v8_heap_limit_bytes: null,
+                process_memory_limit_bytes: javaScriptWorkerMemoryLimitBytes(WEB_SOURCE_MAP_LIMITS.codecHeapMiB),
+            },
+        format: inspected.format,
+        reported_file: inspected.reportedFile,
+        lookup: {
+            requested: position,
+            matched_generated_position: matched,
+            semantics: "greatest generated position <= requested, across lines; all equal-position segments",
+            location_units: "one-based lines; zero-based UTF-16 columns",
+        },
+        matches,
+        diagnostics: [],
+    });
+};
+const validateFlattenedRows = (inspected, rows, map) => {
+    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 new SourceMapFormatFailure("format", "Decoded mapping has invalid component count, position, source index or name index.");
+        }
+};
+const greatestPosition = (rows, position) => {
+    for (let line = Math.min(position.line - 1, rows.length - 1); line >= 0; line -= 1) {
+        let column;
+        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 };
+    }
+    return null;
+};
+const originalMatch = (segment, map, declarations) => {
+    if (segment.length === 1)
+        return { state: "generated-only" };
+    const declaration = declarations[segment[1]];
+    if (declaration === undefined)
+        throw new SourceMapFormatFailure("format", "Mapping references an absent source declaration.");
+    const original = { line: segment[2] + 1, column: segment[3] };
+    const offset = declaration.content === null
+        ? undefined
+        : webSourceOffset(declaration.content, original);
+    return {
+        state: "mapped",
+        flattened_source_index: segment[1],
+        section_path: [...declaration.sectionPath],
+        source_index: declaration.sourceIndex,
+        reported_source: declaration.source,
+        reported_source_root: declaration.root,
+        resolved_url: declaration.source === null
+            ? null
+            : (map.resolvedSources[segment[1]] ?? null),
+        ignored: declaration.ignored,
+        content: declaration.content === null
+            ? { state: "unavailable", reason: "sourcesContent-not-retained" }
+            : {
+                state: "embedded",
+                text: declaration.content,
+                utf8_sha256: createHash("sha256")
+                    .update(declaration.content)
+                    .digest("hex"),
+                utf8_bytes: Buffer.byteLength(declaration.content),
+                representation: "UTF-8 encoding of decoded sourcesContent text",
+            },
+        original_position: {
+            ...original,
+            offset: offset ?? null,
+            content_position: declaration.content === null
+                ? "content-unavailable"
+                : offset === undefined
+                    ? "outside-embedded-text"
+                    : "verified-in-embedded-text",
+        },
+        name: segment.length === 5 ? (map.names[segment[4]] ?? null) : null,
+    };
+};