@specific.dev/spectest 0.80.0 → 0.81.1

package/dist/coverage.d.ts

@@ -53,6 +53,9 @@ export interface CoverageCaptureContext {
     }>;
     /** Write one report file (name relative to the directory). */
     writeReport(name: string, content: string): Promise<void>;
+    /** Read one file out of the container (`docker cp`). `null` when it
+     *  does not exist. Absent on a context that has no container. */
+    readContainerFile?(containerPath: string): Promise<Buffer | null>;
     /** Aborts when the per-service capture budget runs out. */
     signal: AbortSignal;
 }
@@ -137,7 +140,16 @@ export declare const NODE_COVERAGE_HOOK: string;
  *
  * What ships is the V8 documents themselves, compacted
  * ({@link compactV8Document}): the app's own scripts that ran, and each
- * script's source map once per branch. Nothing is converted in the VM.
+ * script's source map once per branch. A map comes from Node's own
+ * `source-map-cache` when Node found one through the script's
+ * `sourceMappingURL` (it caches maps under NODE_V8_COVERAGE with or
+ * without `--enable-source-maps`), else from `<script>.map` next to the
+ * script, read out of the container once
+ * ({@link resolveSourceMapsFromContainer}). The second way is the one to
+ * build a short-lived bundled process in: a map Node finds is serialized
+ * whole into every exit dump — 12 MB per invocation for a bundled CLI,
+ * inside the test's own time — and parsed again by the harness; a map
+ * with no comment costs nothing there. Nothing is converted in the VM.
  * A dump is a **delta** by construction: V8 resets its counters at every
  * `takeCoverage()`, so a live server's dump after a test is that test's
  * own execution, and the boot dump (everything loaded) lands in the
@@ -201,13 +213,69 @@ export interface PrepareV8Stats {
     scripts: number;
     bytesIn: number;
     bytesOut: number;
+    /** Source maps read out of the container this capture. */
+    mapsFromContainer: number;
 }
+/** One `source-map-cache` entry in the shape Node writes: the map (its
+ *  `sourcesContent` dropped), the generated script's line lengths, and
+ *  the map's own URL. */
+export interface SourceMapEntry {
+    url: string | null;
+    data: Record<string, unknown>;
+    lineLengths: number[];
+}
+/** Finds the source maps of the scripts a dump carries no map for, in
+ *  one go. A script absent from the result has none. */
+export type SourceMapResolver = (scriptUrls: string[]) => Promise<Map<string, SourceMapEntry>>;
+/**
+ * The probe {@link resolveSourceMapsFromContainer} runs in the container:
+ * one `sh` loop over every script path, printing `<path>\t<ref>` — the
+ * last `sourceMappingURL` value in the file, else `<path>.map` when that
+ * file exists, else `-`; `!` for a script that is not there. One exec per
+ * capture per service, whatever the number of scripts: a Next.js server
+ * loads hundreds of chunk scripts with no map, and a `docker cp` per
+ * script (the first cut) took a capture past its budget on a busy host.
+ */
+export declare function sourceMapProbeCommand(scriptPaths: string[]): string;
+/** The length of every line of `text`, the way Node computes it for
+ *  `source-map-cache`: split on `\n` (and U+2028/2029), `\r` kept, the
+ *  last line included. Lengths in UTF-16 units, which is what V8's byte
+ *  offsets count in. */
+export declare function lineLengthsOf(text: string): number[];
+/**
+ * The source maps of `scriptUrls`, read out of the container. One probe
+ * exec ({@link sourceMapProbeCommand}) finds, per script, the map a
+ * `sourceMappingURL` comment names or `<script>.map` next to it; only a
+ * script that has one is then read (`docker cp`, the script for its line
+ * lengths and the map file, or the inline `data:` map decoded). A map's
+ * `sourcesContent` is dropped. Scripts that are not `file://` URLs, have
+ * no map, or whose map is not there or not JSON are absent from the
+ * result. The caller remembers every outcome, so this runs once per
+ * script per branch.
+ *
+ * With no comment the map next to the script is the shape to build a
+ * short-lived bundled process in: Node caches a map it finds through a
+ * comment into every dump it writes under NODE_V8_COVERAGE, flag or no
+ * flag, and a bundled CLI's map is tens of MB per exit; a map it does not
+ * find costs nothing there.
+ */
+export declare function resolveSourceMapsFromContainer(ctx: CoverageCaptureContext, scriptUrls: string[]): Promise<Map<string, SourceMapEntry>>;
+/**
+ * Give every kept script of a compacted document a `source-map-cache`
+ * entry it lacks: a stub when the map shipped earlier on this branch,
+ * else the map `resolve` finds (asked once for all such scripts; shipped
+ * whole, with its hash, and remembered), else nothing — and that outcome
+ * is remembered too, so a script with no map is looked up once per
+ * branch. Returns how many maps `resolve` supplied.
+ */
+export declare function attachSourceMaps(doc: Record<string, unknown>, resolve: SourceMapResolver, shipped?: Map<string, string>, missing?: Set<string>): Promise<number>;
 /**
  * Compact, in place, every `coverage-*.json` in `dir` that no earlier
- * capture shipped, and mark it shipped. A dump mid-write (not yet valid
- * JSON) is left for the next capture.
+ * capture shipped, attach the maps the dump lacks through `resolve`
+ * ({@link attachSourceMaps}), and mark it shipped. A dump mid-write (not
+ * yet valid JSON) is left for the next capture.
  */
-export declare function prepareV8Reports(dir: string): Promise<PrepareV8Stats>;
+export declare function prepareV8Reports(dir: string, resolve?: SourceMapResolver): Promise<PrepareV8Stats>;
 /**
  * Coverage for the frontend a service serves. The code runs in the guest
  * browser — spectest's own process — so no report can be written by the

package/dist/coverage.js

@@ -184,7 +184,16 @@ if (process.env.NODE_V8_COVERAGE && require("node:worker_threads").isMainThread)
  *
  * What ships is the V8 documents themselves, compacted
  * ({@link compactV8Document}): the app's own scripts that ran, and each
- * script's source map once per branch. Nothing is converted in the VM.
+ * script's source map once per branch. A map comes from Node's own
+ * `source-map-cache` when Node found one through the script's
+ * `sourceMappingURL` (it caches maps under NODE_V8_COVERAGE with or
+ * without `--enable-source-maps`), else from `<script>.map` next to the
+ * script, read out of the container once
+ * ({@link resolveSourceMapsFromContainer}). The second way is the one to
+ * build a short-lived bundled process in: a map Node finds is serialized
+ * whole into every exit dump — 12 MB per invocation for a bundled CLI,
+ * inside the test's own time — and parsed again by the harness; a map
+ * with no comment costs nothing there. Nothing is converted in the VM.
  * A dump is a **delta** by construction: V8 resets its counters at every
  * `takeCoverage()`, so a live server's dump after a test is that test's
  * own execution, and the boot dump (everything loaded) lands in the
@@ -225,14 +234,15 @@ export function node() {
             await removeShippedV8Reports(ctx.reportDir);
             const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
             const t1 = performance.now();
-            const stats = await prepareV8Reports(ctx.reportDir);
+            const stats = await prepareV8Reports(ctx.reportDir, (urls) => resolveSourceMapsFromContainer(ctx, urls));
             if (stats.dumps === 0) {
                 await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
                 SHIPPED_V8_REPORTS.add((await import("node:path")).join(ctx.reportDir, NODE_COVERAGE_EMPTY_REPORT));
             }
             const t2 = performance.now();
             console.log(`[coverage] node/${ctx.service}: ${live} live process(es) dumped in ${Math.round(t1 - t0)} ms; ` +
-                `${stats.dumps} dump(s), ${stats.scripts} script(s), ${stats.bytesIn} → ${stats.bytesOut} bytes compacted in ${Math.round(t2 - t1)} ms`);
+                `${stats.dumps} dump(s), ${stats.scripts} script(s), ${stats.bytesIn} → ${stats.bytesOut} bytes compacted in ${Math.round(t2 - t1)} ms; ` +
+                `${stats.mapsFromContainer} map(s) read from the container`);
         },
     };
 }
@@ -300,10 +310,15 @@ const SHIPPED_V8_REPORTS = new Set();
  *  of the same script carries a stub that refers to the hash instead of
  *  the map again. */
 const SHIPPED_SOURCE_MAPS = new Map();
+/** Scripts looked up in the container and found to have no source map
+ *  (no `sourceMappingURL`, or a map file that is not there). Module
+ *  memory, forks with the environment: one lookup per script per branch. */
+const NO_SOURCE_MAP = new Set();
 /** Forget the branch memory (tests). */
 export function resetNodeCoverageMemory() {
     SHIPPED_V8_REPORTS.clear();
     SHIPPED_SOURCE_MAPS.clear();
+    NO_SOURCE_MAP.clear();
 }
 /** Remove from `dir` the reports an earlier capture shipped. */
 export async function removeShippedV8Reports(dir) {
@@ -366,9 +381,7 @@ export function compactV8Document(doc, shipped) {
                 const { sourcesContent: _dropped, ...data } = e.data;
                 e.data = data;
             }
-            delete e[SOURCE_MAP_HASH_KEY];
-            delete e[SOURCE_MAP_REF_KEY];
-            const hash = "sha256:" + createHash("sha256").update(JSON.stringify(e)).digest("hex");
+            const hash = sourceMapEntryHash(e);
             if (shipped?.get(url) === hash) {
                 slim[url] = { [SOURCE_MAP_REF_KEY]: hash };
             }
@@ -384,15 +397,223 @@ export function compactV8Document(doc, shipped) {
     }
     return out;
 }
+/** Shell-quote one argument for `sh -c`. */
+function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The probe {@link resolveSourceMapsFromContainer} runs in the container:
+ * one `sh` loop over every script path, printing `<path>\t<ref>` — the
+ * last `sourceMappingURL` value in the file, else `<path>.map` when that
+ * file exists, else `-`; `!` for a script that is not there. One exec per
+ * capture per service, whatever the number of scripts: a Next.js server
+ * loads hundreds of chunk scripts with no map, and a `docker cp` per
+ * script (the first cut) took a capture past its budget on a busy host.
+ */
+export function sourceMapProbeCommand(scriptPaths) {
+    const script = 'for f in "$@"; do ' +
+        'if [ -f "$f" ]; then ' +
+        "ref=$(grep -o 'sourceMappingURL=[^[:space:]]*' -- \"$f\" 2>/dev/null | tail -n 1 | cut -c18-); " +
+        'if [ -n "$ref" ]; then printf \'%s\\t%s\\n\' "$f" "$ref"; ' +
+        'elif [ -f "$f.map" ]; then printf \'%s\\t%s.map\\n\' "$f" "$f"; ' +
+        'else printf \'%s\\t-\\n\' "$f"; fi; ' +
+        'else printf \'%s\\t!\\n\' "$f"; fi; ' +
+        "done";
+    return `sh -c ${shQuote(script)} sh ${scriptPaths.map(shQuote).join(" ")}`;
+}
+/** The length of every line of `text`, the way Node computes it for
+ *  `source-map-cache`: split on `\n` (and U+2028/2029), `\r` kept, the
+ *  last line included. Lengths in UTF-16 units, which is what V8's byte
+ *  offsets count in. */
+export function lineLengthsOf(text) {
+    const out = [];
+    let len = 0;
+    for (let i = 0; i < text.length; i++, len++) {
+        const c = text.charCodeAt(i);
+        if (c === 0x0a || c === 0x2028 || c === 0x2029) {
+            out.push(len);
+            len = -1;
+        }
+    }
+    out.push(len);
+    return out;
+}
+/**
+ * The source maps of `scriptUrls`, read out of the container. One probe
+ * exec ({@link sourceMapProbeCommand}) finds, per script, the map a
+ * `sourceMappingURL` comment names or `<script>.map` next to it; only a
+ * script that has one is then read (`docker cp`, the script for its line
+ * lengths and the map file, or the inline `data:` map decoded). A map's
+ * `sourcesContent` is dropped. Scripts that are not `file://` URLs, have
+ * no map, or whose map is not there or not JSON are absent from the
+ * result. The caller remembers every outcome, so this runs once per
+ * script per branch.
+ *
+ * With no comment the map next to the script is the shape to build a
+ * short-lived bundled process in: Node caches a map it finds through a
+ * comment into every dump it writes under NODE_V8_COVERAGE, flag or no
+ * flag, and a bundled CLI's map is tens of MB per exit; a map it does not
+ * find costs nothing there.
+ */
+export async function resolveSourceMapsFromContainer(ctx, scriptUrls) {
+    const out = new Map();
+    if (!ctx.readContainerFile)
+        return out;
+    const { fileURLToPath, pathToFileURL } = await import("node:url");
+    const path = await import("node:path");
+    const byPath = new Map();
+    for (const url of scriptUrls) {
+        if (!url.startsWith("file://"))
+            continue;
+        try {
+            byPath.set(fileURLToPath(url), url);
+        }
+        catch {
+            // not a path
+        }
+    }
+    if (byPath.size === 0)
+        return out;
+    let probe;
+    try {
+        probe = (await ctx.exec(sourceMapProbeCommand([...byPath.keys()]))).stdout;
+    }
+    catch {
+        return out; // no shell, no grep: no maps from this container
+    }
+    for (const line of probe.split("\n")) {
+        const tab = line.indexOf("\t");
+        if (tab < 0)
+            continue;
+        const scriptPath = line.slice(0, tab);
+        const ref = line.slice(tab + 1).trim();
+        const url = byPath.get(scriptPath);
+        if (!url || ref === "-" || ref === "!" || ref === "")
+            continue;
+        let mapText;
+        let mapUrl;
+        if (ref.startsWith("data:")) {
+            const comma = ref.indexOf(",");
+            if (comma < 0)
+                continue;
+            const head = ref.slice(5, comma);
+            const body = ref.slice(comma + 1);
+            try {
+                mapText = /;base64$/i.test(head) ? Buffer.from(body, "base64").toString("utf8") : decodeURIComponent(body);
+            }
+            catch {
+                continue;
+            }
+            mapUrl = null;
+        }
+        else {
+            let mapPath;
+            if (ref.startsWith("file://")) {
+                try {
+                    mapPath = fileURLToPath(ref);
+                }
+                catch {
+                    continue;
+                }
+            }
+            else if (/^[a-z]+:/i.test(ref)) {
+                continue; // an http(s) map is not in the container
+            }
+            else {
+                let rel = ref;
+                try {
+                    rel = decodeURIComponent(ref);
+                }
+                catch {
+                    // keep as written
+                }
+                mapPath = path.resolve(path.dirname(scriptPath), rel);
+            }
+            const map = await ctx.readContainerFile(mapPath);
+            if (!map)
+                continue;
+            mapText = map.toString("utf8");
+            mapUrl = pathToFileURL(mapPath).href;
+        }
+        let data;
+        try {
+            data = JSON.parse(mapText);
+        }
+        catch {
+            continue;
+        }
+        if (!data || typeof data !== "object" || !("mappings" in data))
+            continue;
+        const script = await ctx.readContainerFile(scriptPath);
+        if (!script)
+            continue;
+        const { sourcesContent: _dropped, ...slim } = data;
+        out.set(url, { url: mapUrl, data: slim, lineLengths: lineLengthsOf(script.toString("utf8")) });
+    }
+    return out;
+}
+/** The content hash of a map entry, over its JSON with the spectest
+ *  keys removed. */
+function sourceMapEntryHash(entry) {
+    const e = { ...entry };
+    delete e[SOURCE_MAP_HASH_KEY];
+    delete e[SOURCE_MAP_REF_KEY];
+    return "sha256:" + createHash("sha256").update(JSON.stringify(e)).digest("hex");
+}
+/**
+ * Give every kept script of a compacted document a `source-map-cache`
+ * entry it lacks: a stub when the map shipped earlier on this branch,
+ * else the map `resolve` finds (asked once for all such scripts; shipped
+ * whole, with its hash, and remembered), else nothing — and that outcome
+ * is remembered too, so a script with no map is looked up once per
+ * branch. Returns how many maps `resolve` supplied.
+ */
+export async function attachSourceMaps(doc, resolve, shipped = SHIPPED_SOURCE_MAPS, missing = NO_SOURCE_MAP) {
+    const result = Array.isArray(doc.result) ? doc.result : [];
+    const cache = (doc["source-map-cache"] ?? {});
+    const unknown = [];
+    for (const s of result) {
+        const url = s.url;
+        if (typeof url !== "string" || url in cache)
+            continue;
+        const prior = shipped.get(url);
+        if (prior) {
+            cache[url] = { [SOURCE_MAP_REF_KEY]: prior };
+            continue;
+        }
+        if (missing.has(url) || unknown.includes(url))
+            continue;
+        unknown.push(url);
+    }
+    let found = 0;
+    if (unknown.length > 0) {
+        const entries = await resolve(unknown);
+        for (const url of unknown) {
+            const entry = entries.get(url);
+            if (!entry) {
+                missing.add(url);
+                continue;
+            }
+            const hash = sourceMapEntryHash(entry);
+            cache[url] = { ...entry, [SOURCE_MAP_HASH_KEY]: hash };
+            shipped.set(url, hash);
+            found++;
+        }
+    }
+    if (Object.keys(cache).length > 0)
+        doc["source-map-cache"] = cache;
+    return found;
+}
 /**
  * Compact, in place, every `coverage-*.json` in `dir` that no earlier
- * capture shipped, and mark it shipped. A dump mid-write (not yet valid
- * JSON) is left for the next capture.
+ * capture shipped, attach the maps the dump lacks through `resolve`
+ * ({@link attachSourceMaps}), and mark it shipped. A dump mid-write (not
+ * yet valid JSON) is left for the next capture.
  */
-export async function prepareV8Reports(dir) {
+export async function prepareV8Reports(dir, resolve) {
     const fs = await import("node:fs/promises");
     const path = await import("node:path");
-    const stats = { dumps: 0, scripts: 0, bytesIn: 0, bytesOut: 0 };
+    const stats = { dumps: 0, scripts: 0, bytesIn: 0, bytesOut: 0, mapsFromContainer: 0 };
     let names;
     try {
         names = await fs.readdir(dir);
@@ -417,7 +638,10 @@ export async function prepareV8Reports(dir) {
         }
         if (!Array.isArray(doc.result))
             continue;
-        const out = JSON.stringify(compactV8Document(doc, SHIPPED_SOURCE_MAPS));
+        const compact = compactV8Document(doc, SHIPPED_SOURCE_MAPS);
+        if (resolve)
+            stats.mapsFromContainer += await attachSourceMaps(compact, resolve);
+        const out = JSON.stringify(compact);
         const tmp = path.join(dir, `.${name}.compact`);
         await fs.writeFile(tmp, out);
         await fs.rename(tmp, file);

package/dist/daemon.js

@@ -40,7 +40,7 @@ import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
-import { cpus } from "node:os";
+import { cpus, tmpdir } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import { bindInstrumentationScope, createInstrumentationScope, runInstrumented, runUninstrumented, } from "./harness/instrumentation-scope.js";
@@ -3392,6 +3392,24 @@ function coverageCaptureContext(svc, signal, written) {
             await fs.rename(tmp, file);
             written.add(path.relative(reportDir, file));
         },
+        async readContainerFile(containerPath) {
+            // `docker cp` rather than `exec cat`: a source map can be tens of
+            // MB, and the exec path buffers stdout as a string. The copy lands
+            // in the VM's tmp, never in the coverage directory (it would ship).
+            const tmp = path.join(tmpdir(), `spectest-cov-${svc.name}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+            try {
+                const r = await docker(["cp", `${svc.name}:${containerPath}`, tmp], COVERAGE_CAPTURE_TIMEOUT_MS);
+                if (r.code !== 0)
+                    return null;
+                return await fs.readFile(tmp);
+            }
+            catch {
+                return null;
+            }
+            finally {
+                await fs.rm(tmp, { force: true, recursive: true }).catch(() => { });
+            }
+        },
     };
 }
 /** Run one service's adapters in order under one budget. Returns the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.80.0",
+  "version": "0.81.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/coverage.test.ts

@@ -12,6 +12,10 @@ import {
   SOURCE_MAP_REF_KEY,
   applyCoverageAdapters,
   appendEnvFlag,
+  attachSourceMaps,
+  lineLengthsOf,
+  resolveSourceMapsFromContainer,
+  sourceMapProbeCommand,
   browser,
   command,
   coverageReportsMode,
@@ -187,15 +191,125 @@ function fakeCtx(dir: string, signal = new AbortController().signal): CoverageCa
     service: "api",
     reportDir: dir,
     signal,
-    async exec() {
-      throw new Error("no container");
+    // The probe runs through a real shell; the "container" paths are
+    // this directory's own.
+    async exec(command: string) {
+      return new Promise((resolve, reject) => {
+        const p = spawn("sh", ["-c", command], { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        p.stdout!.on("data", (b: Buffer) => (stdout += b));
+        p.stderr!.on("data", (b: Buffer) => (stderr += b));
+        p.on("exit", (code) => (code === 0 ? resolve({ stdout, stderr }) : reject(new Error(stderr || `exit ${code}`))));
+      });
     },
     async writeReport(name, content) {
       await fs.writeFile(path.join(dir, name), content);
     },
+    async readContainerFile(p) {
+      return fs.readFile(p).catch(() => null);
+    },
   };
 }
 
+describe("source maps by reference", () => {
+  test("lineLengthsOf matches Node's shape: \\n splits, \\r stays, last line counted", () => {
+    expect(lineLengthsOf("ab\ncde\r\n\nf")).toEqual([2, 4, 0, 1]);
+    expect(lineLengthsOf("")).toEqual([0]);
+    expect(lineLengthsOf("x\n")).toEqual([1, 0]);
+  });
+  test("the probe: one exec, one line per script — the last comment's ref, the .map next to it, or none", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covprobe-"));
+    await fs.writeFile(path.join(dir, "a.js"), "x\n//# sourceMappingURL=old.map\ny\n//# sourceMappingURL=maps/a.map\n");
+    await fs.writeFile(path.join(dir, "b.js"), "x();\n");
+    await fs.writeFile(path.join(dir, "b.js.map"), "{}");
+    await fs.writeFile(path.join(dir, "it's.js"), "x();\n");
+    const r = await fakeCtx(dir).exec(
+      sourceMapProbeCommand([path.join(dir, "a.js"), path.join(dir, "b.js"), path.join(dir, "it's.js"), path.join(dir, "gone.js")]),
+    );
+    expect(r.stdout).toBe(
+      `${path.join(dir, "a.js")}\tmaps/a.map\n` +
+        `${path.join(dir, "b.js")}\t${path.join(dir, "b.js.map")}\n` +
+        `${path.join(dir, "it's.js")}\t-\n` +
+        `${path.join(dir, "gone.js")}\t!\n`,
+    );
+  });
+  test("resolves the map a comment names, drops sourcesContent, computes line lengths", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covmap-"));
+    await fs.mkdir(path.join(dir, "maps"));
+    await fs.writeFile(path.join(dir, "cli.js"), "const a = 1;\nconsole.log(a);\n//# sourceMappingURL=maps/cli.map\n");
+    await fs.writeFile(
+      path.join(dir, "maps", "cli.map"),
+      JSON.stringify({ version: 3, sources: ["../src/cli.ts"], mappings: "AAAA;AACA", names: [], sourcesContent: ["x"] }),
+    );
+    const url = `file://${path.join(dir, "cli.js")}`;
+    const out = await resolveSourceMapsFromContainer(fakeCtx(dir), [url, "node:fs"]);
+    expect([...out.keys()]).toEqual([url]);
+    const entry = out.get(url)!;
+    expect(entry.url).toBe(`file://${path.join(dir, "maps", "cli.map")}`);
+    expect(entry.data).toEqual({ version: 3, sources: ["../src/cli.ts"], mappings: "AAAA;AACA", names: [] });
+    expect(entry.lineLengths).toEqual([12, 15, 33, 0]);
+  });
+  test("with no comment, <script>.map next to the script is the map; inline data: maps decode; the rest is absent", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covmap-"));
+    await fs.writeFile(path.join(dir, "cli.js"), "x();\n");
+    await fs.writeFile(path.join(dir, "cli.js.map"), JSON.stringify({ version: 3, sources: ["cli.ts"], mappings: "AAAA" }));
+    const map = JSON.stringify({ version: 3, sources: ["a.ts"], mappings: "AAAA" });
+    await fs.writeFile(
+      path.join(dir, "inline.js"),
+      `x();\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(map).toString("base64")}\n`,
+    );
+    await fs.writeFile(path.join(dir, "bare.js"), "x();\n");
+    await fs.writeFile(path.join(dir, "gone.js"), "x();\n//# sourceMappingURL=gone.js.map\n");
+    await fs.writeFile(path.join(dir, "http.js"), "x();\n//# sourceMappingURL=https://cdn.test/x.map\n");
+    await fs.writeFile(path.join(dir, "notjson.js"), "x();\n");
+    await fs.writeFile(path.join(dir, "notjson.js.map"), "nope");
+    const u = (n: string) => `file://${path.join(dir, n)}`;
+    const out = await resolveSourceMapsFromContainer(fakeCtx(dir), [
+      u("cli.js"), u("inline.js"), u("bare.js"), u("gone.js"), u("http.js"), u("notjson.js"), u("missing.js"),
+    ]);
+    expect([...out.keys()].sort()).toEqual([u("cli.js"), u("inline.js")].sort());
+    expect(out.get(u("cli.js"))!.url).toBe(`file://${path.join(dir, "cli.js.map")}`);
+    expect(out.get(u("cli.js"))!.data).toEqual({ version: 3, sources: ["cli.ts"], mappings: "AAAA" });
+    expect(out.get(u("inline.js"))!.url).toBeNull();
+    expect(out.get(u("inline.js"))!.data).toEqual({ version: 3, sources: ["a.ts"], mappings: "AAAA" });
+    const noRead = { ...fakeCtx(dir), readContainerFile: undefined };
+    expect((await resolveSourceMapsFromContainer(noRead, [u("cli.js")])).size).toBe(0);
+  });
+  test("attachSourceMaps: one batched lookup, a map once, a stub after, a missing map looked up once", async () => {
+    const calls: string[][] = [];
+    const entry = { url: null, data: { version: 3, sources: ["a.ts"], mappings: "AAAA" }, lineLengths: [4] };
+    const resolve = async (urls: string[]) => {
+      calls.push(urls);
+      return new Map(urls.filter((u) => u.endsWith("/a.js")).map((u) => [u, entry]));
+    };
+    const shipped = new Map<string, string>();
+    const missing = new Set<string>();
+    const dump = () => ({
+      result: [
+        { url: "file:///app/a.js", ...ran },
+        { url: "file:///app/b.js", ...ran },
+      ],
+    });
+    const first = dump() as Record<string, unknown>;
+    expect(await attachSourceMaps(first, resolve, shipped, missing)).toBe(1);
+    const c1 = first["source-map-cache"] as Record<string, Record<string, unknown>>;
+    expect(c1["file:///app/a.js"][SOURCE_MAP_HASH_KEY]).toMatch(/^sha256:/);
+    expect(c1["file:///app/a.js"].lineLengths).toEqual([4]);
+    expect("file:///app/b.js" in c1).toBe(false);
+    expect(calls).toEqual([["file:///app/a.js", "file:///app/b.js"]]);
+    const second = dump() as Record<string, unknown>;
+    expect(await attachSourceMaps(second, resolve, shipped, missing)).toBe(0);
+    const c2 = second["source-map-cache"] as Record<string, Record<string, unknown>>;
+    expect(c2["file:///app/a.js"]).toEqual({ [SOURCE_MAP_REF_KEY]: c1["file:///app/a.js"][SOURCE_MAP_HASH_KEY] });
+    expect(calls.length).toBe(1); // b.js is not asked again
+    // A dump that carries its own entry is left alone.
+    const own = { ...dump(), "source-map-cache": { "file:///app/b.js": { data: { mappings: "" }, lineLengths: [1] } } } as Record<string, unknown>;
+    expect(await attachSourceMaps(own, resolve, shipped, missing)).toBe(0);
+    expect(calls.length).toBe(1);
+  });
+});
+
 describe("browserCoverage", () => {
   test("writes an empty lcov when nothing ran for the service", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
@@ -391,6 +505,44 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     }
   });
 
+  test("a CLI built with an external map and no comment gets its map from the file next to the script, once per branch", async () => {
+    // Node caches a map it finds through a sourceMappingURL comment into
+    // every dump under NODE_V8_COVERAGE, flag or no flag (checked: the
+    // entry then carries Node's resolved `sources` and `sourceRoot`).
+    // Without the comment the dump has no map and the adapter reads
+    // `cli.js.map` from the container.
+    resetNodeCoverageMemory();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const hook = path.join(dir, "coverage-hook.cjs");
+    await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(dir, "cli.js"), "function used() { return 1 }\nused();\n");
+    await fs.writeFile(path.join(dir, "cli.js.map"), JSON.stringify({ version: 3, sources: ["cli.ts"], mappings: "AAAA;AACA", sourcesContent: ["src"] }));
+    const url = `file://${path.join(dir, "cli.js")}`;
+    for (let i = 0; i < 2; i++) {
+      const cli = spawn("node", [path.join(dir, "cli.js")], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
+        stdio: "ignore",
+      });
+      expect(await new Promise<number | null>((r) => cli.on("exit", r))).toBe(0);
+      await node().capture!(fakeCtx(dir));
+      const [name] = (await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT);
+      const doc = JSON.parse(await fs.readFile(path.join(dir, name!), "utf8")) as {
+        result: { url: string }[];
+        "source-map-cache": Record<string, Record<string, unknown>>;
+      };
+      expect(doc.result.map((x) => x.url)).toEqual([url]);
+      const entry = doc["source-map-cache"][url]!;
+      if (i === 0) {
+        expect(entry[SOURCE_MAP_HASH_KEY]).toMatch(/^sha256:/);
+        expect(entry.data).toEqual({ version: 3, sources: ["cli.ts"], mappings: "AAAA;AACA" });
+        expect(entry.lineLengths).toEqual([28, 7, 0]);
+      } else {
+        expect(Object.keys(entry)).toEqual([SOURCE_MAP_REF_KEY]);
+      }
+    }
+    resetNodeCoverageMemory();
+  });
+
   test("no process and no dump: an empty report is written, once", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
     await node().capture!(fakeCtx(dir));

package/src/coverage.ts

@@ -90,6 +90,9 @@ export interface CoverageCaptureContext {
   exec(command: string): Promise<{ stdout: string; stderr: string }>;
   /** Write one report file (name relative to the directory). */
   writeReport(name: string, content: string): Promise<void>;
+  /** Read one file out of the container (`docker cp`). `null` when it
+   *  does not exist. Absent on a context that has no container. */
+  readContainerFile?(containerPath: string): Promise<Buffer | null>;
   /** Aborts when the per-service capture budget runs out. */
   signal: AbortSignal;
 }
@@ -284,7 +287,16 @@ if (process.env.NODE_V8_COVERAGE && require("node:worker_threads").isMainThread)
  *
  * What ships is the V8 documents themselves, compacted
  * ({@link compactV8Document}): the app's own scripts that ran, and each
- * script's source map once per branch. Nothing is converted in the VM.
+ * script's source map once per branch. A map comes from Node's own
+ * `source-map-cache` when Node found one through the script's
+ * `sourceMappingURL` (it caches maps under NODE_V8_COVERAGE with or
+ * without `--enable-source-maps`), else from `<script>.map` next to the
+ * script, read out of the container once
+ * ({@link resolveSourceMapsFromContainer}). The second way is the one to
+ * build a short-lived bundled process in: a map Node finds is serialized
+ * whole into every exit dump — 12 MB per invocation for a bundled CLI,
+ * inside the test's own time — and parsed again by the harness; a map
+ * with no comment costs nothing there. Nothing is converted in the VM.
  * A dump is a **delta** by construction: V8 resets its counters at every
  * `takeCoverage()`, so a live server's dump after a test is that test's
  * own execution, and the boot dump (everything loaded) lands in the
@@ -325,7 +337,7 @@ export function node(): CoverageAdapter {
       await removeShippedV8Reports(ctx.reportDir);
       const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
       const t1 = performance.now();
-      const stats = await prepareV8Reports(ctx.reportDir);
+      const stats = await prepareV8Reports(ctx.reportDir, (urls) => resolveSourceMapsFromContainer(ctx, urls));
       if (stats.dumps === 0) {
         await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
         SHIPPED_V8_REPORTS.add((await import("node:path")).join(ctx.reportDir, NODE_COVERAGE_EMPTY_REPORT));
@@ -333,7 +345,8 @@ export function node(): CoverageAdapter {
       const t2 = performance.now();
       console.log(
         `[coverage] node/${ctx.service}: ${live} live process(es) dumped in ${Math.round(t1 - t0)} ms; ` +
-          `${stats.dumps} dump(s), ${stats.scripts} script(s), ${stats.bytesIn} → ${stats.bytesOut} bytes compacted in ${Math.round(t2 - t1)} ms`,
+          `${stats.dumps} dump(s), ${stats.scripts} script(s), ${stats.bytesIn} → ${stats.bytesOut} bytes compacted in ${Math.round(t2 - t1)} ms; ` +
+          `${stats.mapsFromContainer} map(s) read from the container`,
       );
     },
   };
@@ -401,10 +414,16 @@ const SHIPPED_V8_REPORTS = new Set<string>();
  *  the map again. */
 const SHIPPED_SOURCE_MAPS = new Map<string, string>();
 
+/** Scripts looked up in the container and found to have no source map
+ *  (no `sourceMappingURL`, or a map file that is not there). Module
+ *  memory, forks with the environment: one lookup per script per branch. */
+const NO_SOURCE_MAP = new Set<string>();
+
 /** Forget the branch memory (tests). */
 export function resetNodeCoverageMemory(): void {
   SHIPPED_V8_REPORTS.clear();
   SHIPPED_SOURCE_MAPS.clear();
+  NO_SOURCE_MAP.clear();
 }
 
 /** Remove from `dir` the reports an earlier capture shipped. */
@@ -485,9 +504,7 @@ export function compactV8Document(
         const { sourcesContent: _dropped, ...data } = e.data as Record<string, unknown>;
         e.data = data;
       }
-      delete e[SOURCE_MAP_HASH_KEY];
-      delete e[SOURCE_MAP_REF_KEY];
-      const hash = "sha256:" + createHash("sha256").update(JSON.stringify(e)).digest("hex");
+      const hash = sourceMapEntryHash(e);
       if (shipped?.get(url) === hash) {
         slim[url] = { [SOURCE_MAP_REF_KEY]: hash };
       } else {
@@ -507,17 +524,234 @@ export interface PrepareV8Stats {
   scripts: number;
   bytesIn: number;
   bytesOut: number;
+  /** Source maps read out of the container this capture. */
+  mapsFromContainer: number;
+}
+
+/** One `source-map-cache` entry in the shape Node writes: the map (its
+ *  `sourcesContent` dropped), the generated script's line lengths, and
+ *  the map's own URL. */
+export interface SourceMapEntry {
+  url: string | null;
+  data: Record<string, unknown>;
+  lineLengths: number[];
+}
+
+/** Finds the source maps of the scripts a dump carries no map for, in
+ *  one go. A script absent from the result has none. */
+export type SourceMapResolver = (scriptUrls: string[]) => Promise<Map<string, SourceMapEntry>>;
+
+/** Shell-quote one argument for `sh -c`. */
+function shQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The probe {@link resolveSourceMapsFromContainer} runs in the container:
+ * one `sh` loop over every script path, printing `<path>\t<ref>` — the
+ * last `sourceMappingURL` value in the file, else `<path>.map` when that
+ * file exists, else `-`; `!` for a script that is not there. One exec per
+ * capture per service, whatever the number of scripts: a Next.js server
+ * loads hundreds of chunk scripts with no map, and a `docker cp` per
+ * script (the first cut) took a capture past its budget on a busy host.
+ */
+export function sourceMapProbeCommand(scriptPaths: string[]): string {
+  const script =
+    'for f in "$@"; do ' +
+    'if [ -f "$f" ]; then ' +
+    "ref=$(grep -o 'sourceMappingURL=[^[:space:]]*' -- \"$f\" 2>/dev/null | tail -n 1 | cut -c18-); " +
+    'if [ -n "$ref" ]; then printf \'%s\\t%s\\n\' "$f" "$ref"; ' +
+    'elif [ -f "$f.map" ]; then printf \'%s\\t%s.map\\n\' "$f" "$f"; ' +
+    'else printf \'%s\\t-\\n\' "$f"; fi; ' +
+    'else printf \'%s\\t!\\n\' "$f"; fi; ' +
+    "done";
+  return `sh -c ${shQuote(script)} sh ${scriptPaths.map(shQuote).join(" ")}`;
+}
+
+/** The length of every line of `text`, the way Node computes it for
+ *  `source-map-cache`: split on `\n` (and U+2028/2029), `\r` kept, the
+ *  last line included. Lengths in UTF-16 units, which is what V8's byte
+ *  offsets count in. */
+export function lineLengthsOf(text: string): number[] {
+  const out: number[] = [];
+  let len = 0;
+  for (let i = 0; i < text.length; i++, len++) {
+    const c = text.charCodeAt(i);
+    if (c === 0x0a || c === 0x2028 || c === 0x2029) {
+      out.push(len);
+      len = -1;
+    }
+  }
+  out.push(len);
+  return out;
+}
+
+/**
+ * The source maps of `scriptUrls`, read out of the container. One probe
+ * exec ({@link sourceMapProbeCommand}) finds, per script, the map a
+ * `sourceMappingURL` comment names or `<script>.map` next to it; only a
+ * script that has one is then read (`docker cp`, the script for its line
+ * lengths and the map file, or the inline `data:` map decoded). A map's
+ * `sourcesContent` is dropped. Scripts that are not `file://` URLs, have
+ * no map, or whose map is not there or not JSON are absent from the
+ * result. The caller remembers every outcome, so this runs once per
+ * script per branch.
+ *
+ * With no comment the map next to the script is the shape to build a
+ * short-lived bundled process in: Node caches a map it finds through a
+ * comment into every dump it writes under NODE_V8_COVERAGE, flag or no
+ * flag, and a bundled CLI's map is tens of MB per exit; a map it does not
+ * find costs nothing there.
+ */
+export async function resolveSourceMapsFromContainer(
+  ctx: CoverageCaptureContext,
+  scriptUrls: string[],
+): Promise<Map<string, SourceMapEntry>> {
+  const out = new Map<string, SourceMapEntry>();
+  if (!ctx.readContainerFile) return out;
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+  const path = await import("node:path");
+  const byPath = new Map<string, string>();
+  for (const url of scriptUrls) {
+    if (!url.startsWith("file://")) continue;
+    try {
+      byPath.set(fileURLToPath(url), url);
+    } catch {
+      // not a path
+    }
+  }
+  if (byPath.size === 0) return out;
+  let probe: string;
+  try {
+    probe = (await ctx.exec(sourceMapProbeCommand([...byPath.keys()]))).stdout;
+  } catch {
+    return out; // no shell, no grep: no maps from this container
+  }
+  for (const line of probe.split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab < 0) continue;
+    const scriptPath = line.slice(0, tab);
+    const ref = line.slice(tab + 1).trim();
+    const url = byPath.get(scriptPath);
+    if (!url || ref === "-" || ref === "!" || ref === "") continue;
+    let mapText: string;
+    let mapUrl: string | null;
+    if (ref.startsWith("data:")) {
+      const comma = ref.indexOf(",");
+      if (comma < 0) continue;
+      const head = ref.slice(5, comma);
+      const body = ref.slice(comma + 1);
+      try {
+        mapText = /;base64$/i.test(head) ? Buffer.from(body, "base64").toString("utf8") : decodeURIComponent(body);
+      } catch {
+        continue;
+      }
+      mapUrl = null;
+    } else {
+      let mapPath: string;
+      if (ref.startsWith("file://")) {
+        try {
+          mapPath = fileURLToPath(ref);
+        } catch {
+          continue;
+        }
+      } else if (/^[a-z]+:/i.test(ref)) {
+        continue; // an http(s) map is not in the container
+      } else {
+        let rel = ref;
+        try {
+          rel = decodeURIComponent(ref);
+        } catch {
+          // keep as written
+        }
+        mapPath = path.resolve(path.dirname(scriptPath), rel);
+      }
+      const map = await ctx.readContainerFile(mapPath);
+      if (!map) continue;
+      mapText = map.toString("utf8");
+      mapUrl = pathToFileURL(mapPath).href;
+    }
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(mapText) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (!data || typeof data !== "object" || !("mappings" in data)) continue;
+    const script = await ctx.readContainerFile(scriptPath);
+    if (!script) continue;
+    const { sourcesContent: _dropped, ...slim } = data;
+    out.set(url, { url: mapUrl, data: slim, lineLengths: lineLengthsOf(script.toString("utf8")) });
+  }
+  return out;
+}
+
+/** The content hash of a map entry, over its JSON with the spectest
+ *  keys removed. */
+function sourceMapEntryHash(entry: Record<string, unknown>): string {
+  const e = { ...entry };
+  delete e[SOURCE_MAP_HASH_KEY];
+  delete e[SOURCE_MAP_REF_KEY];
+  return "sha256:" + createHash("sha256").update(JSON.stringify(e)).digest("hex");
+}
+
+/**
+ * Give every kept script of a compacted document a `source-map-cache`
+ * entry it lacks: a stub when the map shipped earlier on this branch,
+ * else the map `resolve` finds (asked once for all such scripts; shipped
+ * whole, with its hash, and remembered), else nothing — and that outcome
+ * is remembered too, so a script with no map is looked up once per
+ * branch. Returns how many maps `resolve` supplied.
+ */
+export async function attachSourceMaps(
+  doc: Record<string, unknown>,
+  resolve: SourceMapResolver,
+  shipped: Map<string, string> = SHIPPED_SOURCE_MAPS,
+  missing: Set<string> = NO_SOURCE_MAP,
+): Promise<number> {
+  const result = Array.isArray(doc.result) ? (doc.result as V8Script[]) : [];
+  const cache = ((doc["source-map-cache"] as Record<string, unknown> | undefined) ?? {}) as Record<string, unknown>;
+  const unknown: string[] = [];
+  for (const s of result) {
+    const url = s.url;
+    if (typeof url !== "string" || url in cache) continue;
+    const prior = shipped.get(url);
+    if (prior) {
+      cache[url] = { [SOURCE_MAP_REF_KEY]: prior };
+      continue;
+    }
+    if (missing.has(url) || unknown.includes(url)) continue;
+    unknown.push(url);
+  }
+  let found = 0;
+  if (unknown.length > 0) {
+    const entries = await resolve(unknown);
+    for (const url of unknown) {
+      const entry = entries.get(url);
+      if (!entry) {
+        missing.add(url);
+        continue;
+      }
+      const hash = sourceMapEntryHash(entry as unknown as Record<string, unknown>);
+      cache[url] = { ...entry, [SOURCE_MAP_HASH_KEY]: hash };
+      shipped.set(url, hash);
+      found++;
+    }
+  }
+  if (Object.keys(cache).length > 0) doc["source-map-cache"] = cache;
+  return found;
 }
 
 /**
  * Compact, in place, every `coverage-*.json` in `dir` that no earlier
- * capture shipped, and mark it shipped. A dump mid-write (not yet valid
- * JSON) is left for the next capture.
+ * capture shipped, attach the maps the dump lacks through `resolve`
+ * ({@link attachSourceMaps}), and mark it shipped. A dump mid-write (not
+ * yet valid JSON) is left for the next capture.
  */
-export async function prepareV8Reports(dir: string): Promise<PrepareV8Stats> {
+export async function prepareV8Reports(dir: string, resolve?: SourceMapResolver): Promise<PrepareV8Stats> {
   const fs = await import("node:fs/promises");
   const path = await import("node:path");
-  const stats: PrepareV8Stats = { dumps: 0, scripts: 0, bytesIn: 0, bytesOut: 0 };
+  const stats: PrepareV8Stats = { dumps: 0, scripts: 0, bytesIn: 0, bytesOut: 0, mapsFromContainer: 0 };
   let names: string[];
   try {
     names = await fs.readdir(dir);
@@ -537,7 +771,9 @@ export async function prepareV8Reports(dir: string): Promise<PrepareV8Stats> {
       continue; // a dump mid-write, or not ours; the read path judges it
     }
     if (!Array.isArray(doc.result)) continue;
-    const out = JSON.stringify(compactV8Document(doc, SHIPPED_SOURCE_MAPS));
+    const compact = compactV8Document(doc, SHIPPED_SOURCE_MAPS);
+    if (resolve) stats.mapsFromContainer += await attachSourceMaps(compact, resolve);
+    const out = JSON.stringify(compact);
     const tmp = path.join(dir, `.${name}.compact`);
     await fs.writeFile(tmp, out);
     await fs.rename(tmp, file);

package/src/daemon.ts

@@ -90,7 +90,7 @@ import {
 import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import type { WrapperDiagnostic } from "./harness/wrapper-rules.js";
-import { cpus } from "node:os";
+import { cpus, tmpdir } from "node:os";
 import { APP_DIR, WORKSPACE, resolveExistingProjectPath, resolveProjectPath } from "./project-files.js";
 import { installFetchWrapper, isTransportError } from "./harness/fetch.js";
 import {
@@ -4052,6 +4052,21 @@ function coverageCaptureContext(
       await fs.rename(tmp, file);
       written.add(path.relative(reportDir, file));
     },
+    async readContainerFile(containerPath: string) {
+      // `docker cp` rather than `exec cat`: a source map can be tens of
+      // MB, and the exec path buffers stdout as a string. The copy lands
+      // in the VM's tmp, never in the coverage directory (it would ship).
+      const tmp = path.join(tmpdir(), `spectest-cov-${svc.name}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      try {
+        const r = await docker(["cp", `${svc.name}:${containerPath}`, tmp], COVERAGE_CAPTURE_TIMEOUT_MS);
+        if (r.code !== 0) return null;
+        return await fs.readFile(tmp);
+      } catch {
+        return null;
+      } finally {
+        await fs.rm(tmp, { force: true, recursive: true }).catch(() => {});
+      }
+    },
   };
 }