@specific.dev/spectest 0.79.2 → 0.81.0

package/src/coverage.ts

@@ -14,11 +14,10 @@
 //
 // After every adapter ran, the harness reads the directory the same way
 // it does for `coverage: true`: at least one well-formed report (lcov or
-// V8 JSON), shipped verbatim. The control plane derives what it needs
-// from the stored bytes. One adapter converts: `node()` turns the V8
-// dumps into lcov inside the container (with `c8`, which golden ships),
-// because the conversion needs the sources and the source maps, which
-// only the container has.
+// V8 JSON), shipped verbatim. Nothing is converted in the VM: `node()`
+// compacts its V8 dumps (the app's own scripts, each source map once per
+// branch) and ships them as they are. The control plane derives what it
+// needs from the stored bytes, off the test run.
 //
 // Imported from `@specific.dev/spectest/coverage`. The three shipped
 // adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
@@ -28,6 +27,8 @@
 //   import * as coverage from "@specific.dev/spectest/coverage";
 //   coverage: { adapters: [coverage.node(), coverage.browser()] }
 
+import { createHash } from "node:crypto";
+
 import type { ServiceConfig } from "./index.js";
 import { harvestAllBrowserCoverage, takeBrowserCoverageReports } from "./browser-coverage.js";
 
@@ -44,26 +45,11 @@ export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
  *  to the coverage dir: `.ctl-<pid>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
 
-/** Where golden keeps the conversion tools (`c8` and its dependencies),
- *  seen from the VM. `SPECTEST_COVERAGE_TOOLS_DIR` overrides it (tests).
- *  The daemon bind-mounts it read-only into every covered container at
- *  {@link NODE_COVERAGE_TOOLS_CONTAINER_DIR} when it exists. */
-export const NODE_COVERAGE_TOOLS_DIR = "/opt/spectest/coverage-tools";
-
-/** Where the container sees {@link NODE_COVERAGE_TOOLS_DIR}. */
-export const NODE_COVERAGE_TOOLS_CONTAINER_DIR = "/spectest/coverage-tools";
-
-/** The `c8` entry point, relative to the tools dir. */
-export const NODE_COVERAGE_C8_BIN = "node_modules/c8/bin/c8.js";
-
-/** The hidden subdirectory of the coverage dir where `node()` parks the
- *  V8 dumps it converts at one capture. Hidden, so the harness never
- *  ships them: the lcov is the report. Emptied at every capture — the
- *  lcov is this capture's delta, see {@link convertV8ReportsToLcov}. */
-export const NODE_COVERAGE_DUMPS_SUBDIR = ".v8";
-
-/** The lcov `node()` writes: the dumps of this capture, merged. */
-export const NODE_COVERAGE_LCOV = "node.lcov";
+/** Key of the content hash (`sha256:<hex>`) a shipped `source-map-cache`
+ *  entry carries, and key of the stub that stands in for an entry that
+ *  shipped earlier on the same branch. See {@link compactV8Document}. */
+export const SOURCE_MAP_HASH_KEY = "spectestHash";
+export const SOURCE_MAP_REF_KEY = "spectestRef";
 
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
@@ -104,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;
 }
@@ -296,23 +285,26 @@ if (process.env.NODE_V8_COVERAGE && require("node:worker_threads").isMainThread)
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
  * `tsx`). Nothing for the app to write.
  *
- * At capture the dumps are **converted to lcov inside the container**
- * with `c8` (`c8 report`), and `node.lcov` is the one report that
- * ships. It holds **what ran since the previous capture**: V8 resets its
- * counters at every `takeCoverage()`, so a live server's dump after a
- * test is that test's own execution — the boot dump (everything loaded,
- * which at file level is everything "ran") lands in the bring-up
- * capture and nowhere else. A run's total is the union over its cases
- * on the server; a test's set is the test's own. Merging every dump on
- * the branch instead was tried first and would have made a long-lived
- * server's per-test set the boot set, every time. The conversion runs
- * in the container, not in the harness, because `v8-to-istanbul` needs
- * the script text (for byte offsets → lines) and the source maps
- * (`--enable-source-maps`, or a `sourceMappingURL` next to each file),
- * and only the container has them. `c8` comes from golden
- * ({@link NODE_COVERAGE_TOOLS_DIR}); on a guest without it the raw V8
- * documents ship instead, compacted ({@link compactV8Document}), as they
- * did before SDK 0.60.
+ * 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. 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
+ * bring-up capture and nowhere else. The control plane derives lines
+ * from the stored documents, off the test run. Converting to lcov in
+ * the container (`c8`, SDK 0.60 to 0.79) took seconds per capture per
+ * service on a real project, inside the test run; a real project turned
+ * coverage off because of it, and the conversion went.
  */
 export function node(): CoverageAdapter {
   return {
@@ -337,114 +329,29 @@ export function node(): CoverageAdapter {
       // rather than failed: an empty report is a report. A server whose
       // hook never loaded (NODE_OPTIONS not reaching it) then shows as
       // empty reports after bring-up, which the boot log warns about.
-      await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
-      if (await nodeCoverageToolsAvailable()) {
-        await convertV8ReportsToLcov(ctx);
-        return;
-      }
-      await compactV8Reports(ctx.reportDir);
-      if (!(await hasV8Reports(ctx.reportDir))) {
+      //
+      // Each capture ships only its own dumps: what an earlier capture on
+      // this branch shipped is removed first (module memory, forks with
+      // the environment).
+      const t0 = performance.now();
+      await removeShippedV8Reports(ctx.reportDir);
+      const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
+      const t1 = performance.now();
+      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.mapsFromContainer} map(s) read from the container`,
+      );
     },
   };
 }
 
-/** The VM-side tools dir, after the test override. */
-export function nodeCoverageToolsDir(): string {
-  return process.env.SPECTEST_COVERAGE_TOOLS_DIR || NODE_COVERAGE_TOOLS_DIR;
-}
-
-/** True when golden (or the override) ships `c8`. The daemon mounts the
- *  directory into covered containers on the same check, so what the VM
- *  has is what the container sees. */
-export async function nodeCoverageToolsAvailable(): Promise<boolean> {
-  const fs = await import("node:fs/promises");
-  const path = await import("node:path");
-  try {
-    await fs.access(path.join(nodeCoverageToolsDir(), NODE_COVERAGE_C8_BIN));
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** The command `convertV8ReportsToLcov` runs in the container. From `/`,
- *  so lcov paths come out relative to the root (made absolute after). */
-export function nodeCoverageConvertCommand(): string {
-  const c8 = `${NODE_COVERAGE_TOOLS_CONTAINER_DIR}/${NODE_COVERAGE_C8_BIN}`;
-  const dumps = `${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_DUMPS_SUBDIR}`;
-  const out = `${COVERAGE_CONTAINER_DIR}/.c8`;
-  // `env -u`: the converter is a node process in a container whose env
-  // carries NODE_V8_COVERAGE and the `--require` hook, so without this it
-  // would load the hook and write a dump of itself at exit — a raw V8
-  // document at the root of the dir, shipped as a report (seen on the
-  // first run of hello-node under 0.60).
-  return `cd / && env -u NODE_V8_COVERAGE -u NODE_OPTIONS node ${c8} report --temp-directory ${dumps} --reporter=lcovonly --reports-dir ${out}`;
-}
-
-/**
- * Convert the V8 dumps written since the previous capture to one lcov,
- * `node.lcov`. New dumps at the root of the dir are compacted to the
- * app's scripts (their maps and `sourcesContent` kept — `v8-to-istanbul`
- * reads the original sources from there when they are not on disk, the
- * usual shape of a multi-stage image) and moved into `.v8/`, which is
- * emptied first; `c8 report` merges that directory. So the lcov is this
- * capture's delta: what the live processes ran since their last take,
- * plus every process that exited since. No new dump ⇒ `TN:` alone,
- * nothing ran. The `SF:` paths come out relative to `/` and are made
- * absolute, so they read as container paths like every other tool's.
- */
-export async function convertV8ReportsToLcov(ctx: CoverageCaptureContext): Promise<void> {
-  const fs = await import("node:fs/promises");
-  const path = await import("node:path");
-  const dumpsDir = path.join(ctx.reportDir, NODE_COVERAGE_DUMPS_SUBDIR);
-  await fs.rm(dumpsDir, { recursive: true, force: true });
-  await fs.mkdir(dumpsDir, { recursive: true });
-  await fs.chmod(dumpsDir, 0o755);
-  let dumps = 0;
-  for (const name of await fs.readdir(ctx.reportDir)) {
-    if (!name.startsWith("coverage-") || !name.endsWith(".json")) continue;
-    const file = path.join(ctx.reportDir, name);
-    if (name === NODE_COVERAGE_EMPTY_REPORT) {
-      await fs.unlink(file).catch(() => {}); // a pre-0.60 placeholder
-      continue;
-    }
-    let doc: Record<string, unknown>;
-    try {
-      doc = JSON.parse(await fs.readFile(file, "utf8")) as Record<string, unknown>;
-    } catch {
-      continue; // a dump mid-write; the next capture takes it
-    }
-    if (!Array.isArray(doc.result)) continue;
-    const target = path.join(dumpsDir, name);
-    await fs.writeFile(`${target}.tmp`, JSON.stringify(compactV8Document(doc, { keepSourcesContent: true })));
-    await fs.chmod(`${target}.tmp`, 0o644);
-    await fs.rename(`${target}.tmp`, target);
-    await fs.unlink(file);
-    dumps++;
-  }
-  if (dumps === 0) {
-    await ctx.writeReport(NODE_COVERAGE_LCOV, "TN:\n");
-    return;
-  }
-  await ctx.exec(nodeCoverageConvertCommand());
-  let lcov: string;
-  try {
-    lcov = await fs.readFile(path.join(ctx.reportDir, ".c8", "lcov.info"), "utf8");
-  } catch (err) {
-    throw new Error(`c8 wrote no lcov.info: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  await ctx.writeReport(NODE_COVERAGE_LCOV, absoluteLcovPaths(lcov));
-}
-
-/** `SF:` records relative to `/` (what `c8` run from `/` writes) made
- *  absolute. An lcov with nothing in it becomes the empty report. */
-export function absoluteLcovPaths(lcov: string): string {
-  if (lcov.trim().length === 0) return "TN:\n";
-  return lcov.replace(/^SF:(?!\/)/gm, "SF:/");
-}
-
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,
@@ -495,23 +402,40 @@ export async function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Pr
   return live;
 }
 
-/** True when `dir` holds at least one `coverage-*.json` other than the
- *  empty placeholder. */
-async function hasV8Reports(dir: string): Promise<boolean> {
+/** Report files shipped at an earlier capture on this branch, by host
+ *  path. Module memory: forks with the environment, so a forked child
+ *  removes its ancestors' reports at its first capture and ships only
+ *  its own. */
+const SHIPPED_V8_REPORTS = new Set<string>();
+
+/** Source-map entries shipped earlier on this branch: script URL → hash
+ *  of the entry. Module memory, forks with the environment. A later dump
+ *  of the same script carries a stub that refers to the hash instead of
+ *  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. */
+export async function removeShippedV8Reports(dir: string): Promise<void> {
   const fs = await import("node:fs/promises");
-  try {
-    return (await fs.readdir(dir)).some(
-      (n) => n.startsWith("coverage-") && n.endsWith(".json") && n !== NODE_COVERAGE_EMPTY_REPORT,
-    );
-  } catch {
-    return false;
+  for (const file of [...SHIPPED_V8_REPORTS]) {
+    if (!file.startsWith(dir + "/")) continue;
+    await fs.unlink(file).catch(() => {});
+    SHIPPED_V8_REPORTS.delete(file);
   }
 }
 
-/** V8 files already compacted, by path. Module memory: forks with the
- *  environment, so a child never re-parses its ancestors' dumps. */
-const COMPACTED_V8_REPORTS = new Set<string>();
-
 /** A script is the app's own when it is a file outside node_modules —
  *  and not our hook, which every dump would otherwise carry. */
 export function isAppScriptUrl(url: string): boolean {
@@ -525,25 +449,49 @@ export function isAppScriptUrl(url: string): boolean {
   );
 }
 
+interface V8Range {
+  count?: unknown;
+}
+interface V8Function {
+  ranges?: V8Range[];
+}
+interface V8Script {
+  url?: unknown;
+  functions?: V8Function[];
+}
+
+/** True when any range of any function of the script has a count above
+ *  zero: something in it ran since the previous take. A script whose
+ *  every count is zero is one V8 still lists after a reset; it says
+ *  nothing and is dropped. */
+export function scriptExecuted(script: V8Script): boolean {
+  const fns = Array.isArray(script.functions) ? script.functions : [];
+  return fns.some((f) => Array.isArray(f.ranges) && f.ranges.some((r) => typeof r.count === "number" && r.count > 0));
+}
+
 /**
- * Compact one V8 coverage document to the app's own scripts. What Node
- * writes is everything the process loaded: `node:` internals, every
+ * Compact one V8 coverage document to what the derivation needs. What
+ * Node writes is everything the process loaded: `node:` internals, every
  * `node_modules` file, and — under `--enable-source-maps` — a
  * `source-map-cache` with each file's full map **and its sources**,
  * repeated in every dump. Measured on a real project: a 12–20 MiB dump
  * per capture, of which the app's own coverage was under 0.5 MiB, and a
  * suite that hit the 64 MiB cap on its third test. Kept: `file://`
- * scripts outside `node_modules`, the map entries of exactly those
- * scripts, minus `sourcesContent` (the sources are the repo) unless
- * `keepSourcesContent` — the lcov conversion reads original sources from
- * there. Still a V8 document — nothing is converted here.
+ * scripts outside `node_modules` in which something ran, and the map
+ * entries of exactly those scripts, minus `sourcesContent` (the sources
+ * are the repo). Each kept map entry carries its content hash under
+ * {@link SOURCE_MAP_HASH_KEY}; when `shipped` holds the same hash for the
+ * URL — the map went out with an earlier dump on this branch — a stub
+ * `{ [SOURCE_MAP_REF_KEY]: hash }` stands in for it, and the reader finds
+ * the map in an earlier capture of the branch. `shipped` is updated in
+ * place. Still a V8 document — nothing is converted here.
  */
 export function compactV8Document(
   doc: Record<string, unknown>,
-  opts: { keepSourcesContent?: boolean } = {},
+  shipped?: Map<string, string>,
 ): Record<string, unknown> {
-  const result = Array.isArray(doc.result) ? (doc.result as { url?: unknown }[]) : [];
-  const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url));
+  const result = Array.isArray(doc.result) ? (doc.result as V8Script[]) : [];
+  const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url) && scriptExecuted(s));
   const out: Record<string, unknown> = { ...doc, result: kept };
   const cache = doc["source-map-cache"];
   if (cache && typeof cache === "object") {
@@ -552,11 +500,17 @@ export function compactV8Document(
     for (const [url, entry] of Object.entries(cache as Record<string, unknown>)) {
       if (!urls.has(url) || !entry || typeof entry !== "object") continue;
       const e = { ...(entry as Record<string, unknown>) };
-      if (!opts.keepSourcesContent && e.data && typeof e.data === "object") {
+      if (e.data && typeof e.data === "object") {
         const { sourcesContent: _dropped, ...data } = e.data as Record<string, unknown>;
         e.data = data;
       }
-      slim[url] = e;
+      const hash = sourceMapEntryHash(e);
+      if (shipped?.get(url) === hash) {
+        slim[url] = { [SOURCE_MAP_REF_KEY]: hash };
+      } else {
+        slim[url] = { ...e, [SOURCE_MAP_HASH_KEY]: hash };
+        shipped?.set(url, hash);
+      }
     }
     if (Object.keys(slim).length > 0) out["source-map-cache"] = slim;
     else delete out["source-map-cache"];
@@ -564,32 +518,221 @@ export function compactV8Document(
   return out;
 }
 
-/** Compact every not-yet-compacted V8 document in `dir`, in place. */
-export async function compactV8Reports(dir: string): Promise<void> {
+/** What {@link prepareV8Reports} did, for the capture's log line. */
+export interface PrepareV8Stats {
+  dumps: number;
+  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, 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, 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, mapsFromContainer: 0 };
   let names: string[];
   try {
     names = await fs.readdir(dir);
   } catch {
-    return;
+    return stats;
   }
-  for (const name of names) {
-    if (!name.startsWith("coverage-") || !name.endsWith(".json")) continue;
+  for (const name of names.sort()) {
+    if (!name.startsWith("coverage-") || !name.endsWith(".json") || name === NODE_COVERAGE_EMPTY_REPORT) continue;
     const file = path.join(dir, name);
-    if (COMPACTED_V8_REPORTS.has(file)) continue;
+    if (SHIPPED_V8_REPORTS.has(file)) continue;
+    let text: string;
     let doc: Record<string, unknown>;
     try {
-      doc = JSON.parse(await fs.readFile(file, "utf8")) as Record<string, unknown>;
+      text = await fs.readFile(file, "utf8");
+      doc = JSON.parse(text) as Record<string, unknown>;
     } catch {
       continue; // a dump mid-write, or not ours; the read path judges it
     }
     if (!Array.isArray(doc.result)) continue;
+    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, JSON.stringify(compactV8Document(doc)));
+    await fs.writeFile(tmp, out);
     await fs.rename(tmp, file);
-    COMPACTED_V8_REPORTS.add(file);
+    SHIPPED_V8_REPORTS.add(file);
+    stats.dumps++;
+    stats.scripts += (doc.result as unknown[]).length;
+    stats.bytesIn += text.length;
+    stats.bytesOut += out.length;
   }
+  return stats;
 }
 
 // ── browser ───────────────────────────────────────────────────────