@specific.dev/spectest 0.80.0 → 0.81.0

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 resolveSourceMapFromContainer}). 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,53 @@ 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 map of a script the dump carries no map for.
+ *  `null` when there is none. */
+export type SourceMapResolver = (scriptUrl: string) => Promise<SourceMapEntry | null>;
+/** 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 last `sourceMappingURL` comment of a script, or `null`. */
+export declare function sourceMappingUrlOf(script: string): string | null;
+/**
+ * The source map of `scriptUrl`, read out of the container: the script
+ * itself (for its `sourceMappingURL` and its line lengths), then the map
+ * — inline as a `data:` URL, a file the comment names, or, with no
+ * comment, `<script>.map` next to it. `null` when the script is not a
+ * `file://` URL, cannot be read, or the map is not there or not JSON; a
+ * map's `sourcesContent` is dropped.
+ * One read per script per branch: the caller remembers the outcome.
+ */
+export declare function resolveSourceMapFromContainer(ctx: CoverageCaptureContext, scriptUrl: string): Promise<SourceMapEntry | null>;
+/**
+ * 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 (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 resolveSourceMapFromContainer}). 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, (url) => resolveSourceMapFromContainer(ctx, url));
             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,169 @@ export function compactV8Document(doc, shipped) {
     }
     return out;
 }
+/** 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 last `sourceMappingURL` comment of a script, or `null`. */
+export function sourceMappingUrlOf(script) {
+    const re = /\/\/[#@]\s*sourceMappingURL=(\S+)/g;
+    let last = null;
+    let m;
+    while ((m = re.exec(script)) !== null)
+        last = m[1];
+    return last;
+}
+/**
+ * The source map of `scriptUrl`, read out of the container: the script
+ * itself (for its `sourceMappingURL` and its line lengths), then the map
+ * — inline as a `data:` URL, a file the comment names, or, with no
+ * comment, `<script>.map` next to it. `null` when the script is not a
+ * `file://` URL, cannot be read, or the map is not there or not JSON; a
+ * map's `sourcesContent` is dropped.
+ * One read per script per branch: the caller remembers the outcome.
+ */
+export async function resolveSourceMapFromContainer(ctx, scriptUrl) {
+    if (!ctx.readContainerFile || !scriptUrl.startsWith("file://"))
+        return null;
+    const { fileURLToPath, pathToFileURL } = await import("node:url");
+    const path = await import("node:path");
+    let scriptPath;
+    try {
+        scriptPath = fileURLToPath(scriptUrl);
+    }
+    catch {
+        return null;
+    }
+    const script = await ctx.readContainerFile(scriptPath);
+    if (!script)
+        return null;
+    const text = script.toString("utf8");
+    // No comment: the map next to the script, by convention (`x.js.map`).
+    // That 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 and
+    // is read here once per branch.
+    const ref = sourceMappingUrlOf(text) ?? `${path.basename(scriptPath)}.map`;
+    let mapText;
+    let mapUrl;
+    if (ref.startsWith("data:")) {
+        const comma = ref.indexOf(",");
+        if (comma < 0)
+            return null;
+        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 {
+            return null;
+        }
+        mapUrl = null;
+    }
+    else {
+        let mapPath;
+        if (ref.startsWith("file://")) {
+            try {
+                mapPath = fileURLToPath(ref);
+            }
+            catch {
+                return null;
+            }
+        }
+        else if (/^[a-z]+:/i.test(ref)) {
+            return null; // an http(s) map is not in the container
+        }
+        else {
+            mapPath = path.resolve(path.dirname(scriptPath), decodeURIComponent(ref));
+        }
+        const map = await ctx.readContainerFile(mapPath);
+        if (!map)
+            return null;
+        mapText = map.toString("utf8");
+        mapUrl = pathToFileURL(mapPath).href;
+    }
+    let data;
+    try {
+        data = JSON.parse(mapText);
+    }
+    catch {
+        return null;
+    }
+    if (!data || typeof data !== "object" || !("mappings" in data))
+        return null;
+    const { sourcesContent: _dropped, ...slim } = data;
+    return { url: mapUrl, data: slim, lineLengths: lineLengthsOf(text) };
+}
+/** 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 (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"] ?? {});
+    let found = 0;
+    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))
+            continue;
+        const entry = await resolve(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 +584,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.0",
   "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,
+  resolveSourceMapFromContainer,
+  sourceMappingUrlOf,
   browser,
   command,
   coverageReportsMode,
@@ -193,9 +197,99 @@ function fakeCtx(dir: string, signal = new AbortController().signal): CoverageCa
     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("sourceMappingUrlOf takes the last comment", () => {
+    expect(sourceMappingUrlOf("a\n//# sourceMappingURL=a.js.map\nb\n//# sourceMappingURL=b.js.map\n")).toBe("b.js.map");
+    expect(sourceMappingUrlOf("//@ sourceMappingURL=old.map")).toBe("old.map");
+    expect(sourceMappingUrlOf("no map here")).toBeNull();
+  });
+  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 entry = await resolveSourceMapFromContainer(fakeCtx(dir), `file://${path.join(dir, "cli.js")}`);
+    expect(entry).not.toBeNull();
+    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", 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 entry = await resolveSourceMapFromContainer(fakeCtx(dir), `file://${path.join(dir, "cli.js")}`);
+    expect(entry!.url).toBe(`file://${path.join(dir, "cli.js.map")}`);
+    expect(entry!.data).toEqual({ version: 3, sources: ["cli.ts"], mappings: "AAAA" });
+  });
+  test("resolves an inline data: URL map; no map, no file, or a foreign URL is null", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covmap-"));
+    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`,
+    );
+    const inline = await resolveSourceMapFromContainer(fakeCtx(dir), `file://${path.join(dir, "inline.js")}`);
+    expect(inline!.url).toBeNull();
+    expect(inline!.data).toEqual({ version: 3, sources: ["a.ts"], mappings: "AAAA" });
+    await fs.writeFile(path.join(dir, "bare.js"), "x();\n");
+    expect(await resolveSourceMapFromContainer(fakeCtx(dir), `file://${path.join(dir, "bare.js")}`)).toBeNull();
+    await fs.writeFile(path.join(dir, "gone.js"), "x();\n//# sourceMappingURL=gone.js.map\n");
+    expect(await resolveSourceMapFromContainer(fakeCtx(dir), `file://${path.join(dir, "gone.js")}`)).toBeNull();
+    await fs.writeFile(path.join(dir, "http.js"), "x();\n//# sourceMappingURL=https://cdn.test/x.map\n");
+    expect(await resolveSourceMapFromContainer(fakeCtx(dir), `file://${path.join(dir, "http.js")}`)).toBeNull();
+    expect(await resolveSourceMapFromContainer(fakeCtx(dir), "node:fs")).toBeNull();
+    const noRead = { ...fakeCtx(dir), readContainerFile: undefined };
+    expect(await resolveSourceMapFromContainer(noRead, `file://${path.join(dir, "inline.js")}`)).toBeNull();
+  });
+  test("attachSourceMaps: 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 (url: string) => {
+      calls.push(url);
+      return url.endsWith("/a.js") ? entry : null;
+    };
+    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(2); // 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(2);
+  });
+});
+
 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 +485,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 resolveSourceMapFromContainer}). 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, (url) => resolveSourceMapFromContainer(ctx, url));
       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,183 @@ 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 map of a script the dump carries no map for.
+ *  `null` when there is none. */
+export type SourceMapResolver = (scriptUrl: string) => Promise<SourceMapEntry | null>;
+
+/** 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 last `sourceMappingURL` comment of a script, or `null`. */
+export function sourceMappingUrlOf(script: string): string | null {
+  const re = /\/\/[#@]\s*sourceMappingURL=(\S+)/g;
+  let last: string | null = null;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(script)) !== null) last = m[1]!;
+  return last;
+}
+
+/**
+ * The source map of `scriptUrl`, read out of the container: the script
+ * itself (for its `sourceMappingURL` and its line lengths), then the map
+ * — inline as a `data:` URL, a file the comment names, or, with no
+ * comment, `<script>.map` next to it. `null` when the script is not a
+ * `file://` URL, cannot be read, or the map is not there or not JSON; a
+ * map's `sourcesContent` is dropped.
+ * One read per script per branch: the caller remembers the outcome.
+ */
+export async function resolveSourceMapFromContainer(
+  ctx: CoverageCaptureContext,
+  scriptUrl: string,
+): Promise<SourceMapEntry | null> {
+  if (!ctx.readContainerFile || !scriptUrl.startsWith("file://")) return null;
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+  const path = await import("node:path");
+  let scriptPath: string;
+  try {
+    scriptPath = fileURLToPath(scriptUrl);
+  } catch {
+    return null;
+  }
+  const script = await ctx.readContainerFile(scriptPath);
+  if (!script) return null;
+  const text = script.toString("utf8");
+  // No comment: the map next to the script, by convention (`x.js.map`).
+  // That 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 and
+  // is read here once per branch.
+  const ref = sourceMappingUrlOf(text) ?? `${path.basename(scriptPath)}.map`;
+  let mapText: string;
+  let mapUrl: string | null;
+  if (ref.startsWith("data:")) {
+    const comma = ref.indexOf(",");
+    if (comma < 0) return null;
+    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 {
+      return null;
+    }
+    mapUrl = null;
+  } else {
+    let mapPath: string;
+    if (ref.startsWith("file://")) {
+      try {
+        mapPath = fileURLToPath(ref);
+      } catch {
+        return null;
+      }
+    } else if (/^[a-z]+:/i.test(ref)) {
+      return null; // an http(s) map is not in the container
+    } else {
+      mapPath = path.resolve(path.dirname(scriptPath), decodeURIComponent(ref));
+    }
+    const map = await ctx.readContainerFile(mapPath);
+    if (!map) return null;
+    mapText = map.toString("utf8");
+    mapUrl = pathToFileURL(mapPath).href;
+  }
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(mapText) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object" || !("mappings" in data)) return null;
+  const { sourcesContent: _dropped, ...slim } = data;
+  return { url: mapUrl, data: slim, lineLengths: lineLengthsOf(text) };
+}
+
+/** 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 (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>;
+  let found = 0;
+  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)) continue;
+    const entry = await resolve(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 +720,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(() => {});
+      }
+    },
   };
 }