@specific.dev/spectest 0.81.1 → 0.83.0

package/src/coverage.test.ts

@@ -4,27 +4,21 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
+  NODE_COVERAGE_DIR_ENV,
   NODE_COVERAGE_HOOK,
   NODE_COVERAGE_EMPTY_REPORT,
   NODE_COVERAGE_HOOK_PATH,
+  NODE_COVERAGE_SCRIPTS_SUBDIR,
+  NODE_COVERAGE_MARKERS_SUBDIR,
   NODE_COVERAGE_SOCKET_PREFIX,
-  SOURCE_MAP_HASH_KEY,
-  SOURCE_MAP_REF_KEY,
   applyCoverageAdapters,
   appendEnvFlag,
-  attachSourceMaps,
-  lineLengthsOf,
-  resolveSourceMapsFromContainer,
-  sourceMapProbeCommand,
   browser,
   command,
   coverageReportsMode,
-  compactV8Document,
+  isNodeDumpName,
   node,
-  prepareV8Reports,
-  removeShippedV8Reports,
   resetNodeCoverageMemory,
-  scriptExecuted,
   validateCoverage,
   type CoverageCaptureContext,
 } from "./coverage.js";
@@ -68,10 +62,11 @@ describe("validateCoverage", () => {
 });
 
 describe("applyCoverageAdapters", () => {
-  test("node: appends NODE_OPTIONS, sets NODE_V8_COVERAGE, mounts the hook", () => {
+  test("node: appends NODE_OPTIONS, sets the coverage dir env, mounts the hook — never NODE_V8_COVERAGE", () => {
     const out = applyCoverageAdapters("api", { ...base, coverage: { adapters: [node()] } });
     expect(out.env?.NODE_OPTIONS).toBe(`--max-old-space-size=512 --require ${NODE_COVERAGE_HOOK_PATH}`);
-    expect(out.env?.NODE_V8_COVERAGE).toBe("/spectest/coverage");
+    expect(out.env?.[NODE_COVERAGE_DIR_ENV]).toBe("/spectest/coverage");
+    expect(out.env?.NODE_V8_COVERAGE).toBeUndefined();
     expect(out.files?.map((f) => f.path)).toEqual([NODE_COVERAGE_HOOK_PATH]);
     expect(out.files?.[0]?.content).toBe(NODE_COVERAGE_HOOK);
   });
@@ -99,217 +94,21 @@ describe("applyCoverageAdapters", () => {
   });
 });
 
-const ran = { functions: [{ functionName: "", ranges: [{ startOffset: 0, endOffset: 10, count: 1 }] }] };
-const idle = { functions: [{ functionName: "", ranges: [{ startOffset: 0, endOffset: 10, count: 0 }] }] };
-
-describe("compactV8Document", () => {
-  const doc = {
-    result: [
-      { scriptId: "1", url: "file:///app/src/a.ts", ...ran },
-      { scriptId: "2", url: "file:///app/node_modules/x/index.js", ...ran },
-      { scriptId: "3", url: "node:fs", ...ran },
-      { scriptId: "5", url: "file:///root/.cache/node/corepack/v1/pnpm/10.0.0/dist/pnpm.cjs", ...ran },
-      { scriptId: "6", url: "file:///app/src/idle.ts", ...idle },
-      { scriptId: "4", url: "", ...ran },
-    ],
-    "source-map-cache": {
-      "file:///app/src/a.ts": { lineLengths: [1], data: { mappings: "AAAA", sources: ["a.ts"], sourcesContent: ["x"] }, url: null },
-      "file:///app/src/idle.ts": { lineLengths: [1], data: { mappings: "AAAA", sources: ["idle.ts"] }, url: null },
-      "file:///app/node_modules/x/index.js": { lineLengths: [1], data: { mappings: "AAAA" }, url: null },
-    },
-  };
-  type Cache = Record<string, Record<string, unknown>>;
-
-  test("scriptExecuted: any range count above zero", () => {
-    expect(scriptExecuted(ran)).toBe(true);
-    expect(scriptExecuted(idle)).toBe(false);
-    expect(scriptExecuted({})).toBe(false);
-  });
-  test("keeps app scripts that ran and their maps, drops the rest and sourcesContent", () => {
-    const out = compactV8Document(doc) as typeof doc;
-    expect(out.result.map((s) => s.url)).toEqual(["file:///app/src/a.ts"]);
-    const cache = out["source-map-cache"] as unknown as Cache;
-    expect(Object.keys(cache)).toEqual(["file:///app/src/a.ts"]);
-    expect(cache["file:///app/src/a.ts"].data).toEqual({ mappings: "AAAA", sources: ["a.ts"] });
-    expect(cache["file:///app/src/a.ts"][SOURCE_MAP_HASH_KEY]).toMatch(/^sha256:[0-9a-f]{64}$/);
-    expect(cache["file:///app/src/a.ts"][SOURCE_MAP_REF_KEY]).toBeUndefined();
-  });
-  test("a map shipped earlier on the branch becomes a stub that refers to its hash", () => {
-    const shipped = new Map<string, string>();
-    const first = compactV8Document(doc, shipped) as typeof doc;
-    const hash = (first["source-map-cache"] as unknown as Cache)["file:///app/src/a.ts"][SOURCE_MAP_HASH_KEY];
-    expect(shipped.get("file:///app/src/a.ts")).toBe(hash as string);
-    const second = compactV8Document(doc, shipped) as typeof doc;
-    expect((second["source-map-cache"] as unknown as Cache)["file:///app/src/a.ts"]).toEqual({ [SOURCE_MAP_REF_KEY]: hash });
-    // The hash is over the compacted entry, so the same map with its
-    // sources dropped is the same map; a changed map ships again.
-    const changed = {
-      ...doc,
-      "source-map-cache": { "file:///app/src/a.ts": { lineLengths: [2], data: { mappings: "AAAC", sources: ["a.ts"] }, url: null } },
-    };
-    const third = compactV8Document(changed, shipped) as typeof doc;
-    const entry = (third["source-map-cache"] as unknown as Cache)["file:///app/src/a.ts"];
-    expect(entry[SOURCE_MAP_REF_KEY]).toBeUndefined();
-    expect(entry[SOURCE_MAP_HASH_KEY]).not.toBe(hash);
-  });
-  test("a dump with no app script keeps an empty result and no cache", () => {
-    const out = compactV8Document({ result: [doc.result[2]], "source-map-cache": doc["source-map-cache"] });
-    expect(out.result).toEqual([]);
-    expect("source-map-cache" in out).toBe(false);
-  });
-  test("prepareV8Reports compacts coverage-*.json once, ships maps once, and the next capture removes them", async () => {
-    resetNodeCoverageMemory();
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
-    await fs.writeFile(path.join(dir, "coverage-1-2-0.json"), JSON.stringify(doc));
-    await fs.writeFile(path.join(dir, "browser.lcov"), "TN:\n");
-    const stats = await prepareV8Reports(dir);
-    expect(stats.dumps).toBe(1);
-    expect(stats.bytesOut).toBeLessThan(stats.bytesIn);
-    const back = JSON.parse(await fs.readFile(path.join(dir, "coverage-1-2-0.json"), "utf8")) as typeof doc;
-    expect(back.result.length).toBe(1);
-    expect((back["source-map-cache"] as unknown as Cache)["file:///app/src/a.ts"][SOURCE_MAP_HASH_KEY]).toBeDefined();
-    expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
-    // Shipped: a second pass leaves it alone, even when it is not JSON any more.
-    await fs.writeFile(path.join(dir, "coverage-1-2-0.json"), "not json");
-    expect((await prepareV8Reports(dir)).dumps).toBe(0);
-    expect(await fs.readFile(path.join(dir, "coverage-1-2-0.json"), "utf8")).toBe("not json");
-    // A later dump of the same script carries a stub for the map.
-    await fs.writeFile(path.join(dir, "coverage-1-3-0.json"), JSON.stringify(doc));
-    expect((await prepareV8Reports(dir)).dumps).toBe(1);
-    const later = JSON.parse(await fs.readFile(path.join(dir, "coverage-1-3-0.json"), "utf8")) as typeof doc;
-    expect(Object.keys((later["source-map-cache"] as unknown as Cache)["file:///app/src/a.ts"])).toEqual([SOURCE_MAP_REF_KEY]);
-    // The next capture starts by removing what shipped; other files stay.
-    await removeShippedV8Reports(dir);
-    expect((await fs.readdir(dir)).sort()).toEqual(["browser.lcov"]);
-    resetNodeCoverageMemory();
-  });
-});
-
 /** A capture context over a real directory, no container. */
 function fakeCtx(dir: string, signal = new AbortController().signal): CoverageCaptureContext {
   return {
     service: "api",
     reportDir: dir,
     signal,
-    // 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 exec() {
+      throw new Error("no container");
     },
     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-"));
@@ -334,219 +133,237 @@ describe("browserCoverage", () => {
 });
 
 // The node hook against a real `node` (the box has one; skipped where it
-// does not). Every process armed with the hook must answer its own
-// socket with a fresh V8 report — including a server that sits behind a
-// wrapper process, the pnpm/tsx shape; stale sockets must be cleaned up;
-// the socket path must work across a bind mount — which is what a plain
-// directory path stands in for here.
+// does not). The hook is the collector: every process armed with it
+// must answer its own socket with a fresh dump — including a server
+// behind a wrapper process, the pnpm/tsx shape — and write one at exit;
+// a worker thread writes its own; a script record appears once per
+// branch with the source's line lengths, every function, and the map
+// found by comment, inline, or next to the script; stale sockets are
+// removed; NODE_V8_COVERAGE is never set.
 const hasNode = await new Promise<boolean>((resolve) => {
   const p = spawn("node", ["--version"]);
   p.on("error", () => resolve(false));
   p.on("exit", (code) => resolve(code === 0));
 });
 
-const SERVER_JS = "setInterval(() => {}, 1000); process.stdout.write('up\\n');\n";
+const SERVER_JS = "function tick() { return 1 }\nsetInterval(tick, 5); process.stdout.write('up\\n');\n";
 // A wrapper that spawns the real server as a child node process and
 // waits on it — what `pnpm exec`, `npm run` and the `tsx` binary do.
+// It takes its child down with it on SIGTERM, so the test leaves no
+// orphan holding the test runner's stdout pipe open.
 const WRAPPER_JS =
   "const { spawn } = require('node:child_process');\n" +
   "const c = spawn(process.execPath, [require('node:path').join(__dirname, 'server.js')], { stdio: 'inherit' });\n" +
-  "c.on('exit', (code) => process.exit(code ?? 1));\n";
+  "c.on('exit', (code) => process.exit(code ?? 1));\n" +
+  "process.on('SIGTERM', () => { c.kill('SIGKILL'); process.exit(1); });\n";
+
+interface Dump {
+  spectestVersion: number;
+  result: { url: string; spectestScript: string; functions: number[][] }[];
+}
+interface ScriptRecord {
+  spectestScript: {
+    url: string;
+    lineLengths: number[] | null;
+    functions: [string, number, number][];
+    sourceMap: { url: string | null; data: Record<string, unknown> } | null;
+  };
+}
 
 describe.if(hasNode)("nodeCoverage hook (real node)", () => {
+  const hookEnv = (dir: string) => ({ ...process.env, [NODE_COVERAGE_DIR_ENV]: dir, NODE_OPTIONS: `--require ${path.join(dir, "hook.cjs")}` });
   async function socketsIn(dir: string): Promise<string[]> {
     return (await fs.readdir(dir)).filter((n) => n.startsWith(NODE_COVERAGE_SOCKET_PREFIX)).sort();
   }
-  async function reportsIn(dir: string): Promise<string[]> {
-    return (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-") && n.endsWith(".json"));
+  async function dumpsIn(dir: string): Promise<string[]> {
+    return (await fs.readdir(dir)).filter(isNodeDumpName).sort();
+  }
+  async function readDump(dir: string, name: string): Promise<Dump> {
+    return JSON.parse(await fs.readFile(path.join(dir, name), "utf8")) as Dump;
+  }
+  async function records(dir: string): Promise<Map<string, ScriptRecord["spectestScript"]>> {
+    const out = new Map<string, ScriptRecord["spectestScript"]>();
+    const d = path.join(dir, NODE_COVERAGE_SCRIPTS_SUBDIR);
+    for (const n of (await fs.readdir(d).catch(() => [] as string[])).filter((n) => n.endsWith(".json"))) {
+      const r = JSON.parse(await fs.readFile(path.join(d, n), "utf8")) as ScriptRecord;
+      out.set(r.spectestScript.url, r.spectestScript);
+    }
+    return out;
+  }
+  /** The names of a dump's ran functions, joined to the record on the extent. */
+  function ranNames(dump: Dump, rec: ScriptRecord["spectestScript"]): string[] {
+    const byExtent = new Map(rec.functions.map(([name, start, end]) => [`${start}-${end}`, name]));
+    return dump.result[0]!.functions.map((f) => byExtent.get(`${f[0]}-${f[0]! + f[1]!}`) ?? "?");
+  }
+  async function scratch(): Promise<string> {
+    resetNodeCoverageMemory();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    await fs.writeFile(path.join(dir, "hook.cjs"), NODE_COVERAGE_HOOK);
+    await fs.mkdir(path.join(dir, NODE_COVERAGE_SCRIPTS_SUBDIR));
+    await fs.mkdir(path.join(dir, NODE_COVERAGE_MARKERS_SUBDIR), { recursive: true });
+    return dir;
   }
   async function start(dir: string, entry: string, expectSockets: number): Promise<ChildProcess> {
-    const hook = path.join(dir, "hook.cjs");
-    await fs.writeFile(hook, NODE_COVERAGE_HOOK);
     await fs.writeFile(path.join(dir, "server.js"), SERVER_JS);
     await fs.writeFile(path.join(dir, "wrapper.js"), WRAPPER_JS);
-    const child = spawn("node", [path.join(dir, entry)], {
-      env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
-      stdio: ["ignore", "pipe", "inherit"],
-    });
+    const child = spawn("node", [path.join(dir, entry)], { env: hookEnv(dir), stdio: ["ignore", "pipe", "inherit"] });
     await new Promise<void>((resolve) => child.stdout!.once("data", () => resolve()));
     for (let i = 0; i < 100 && (await socketsIn(dir)).length < expectSockets; i++) {
       await new Promise((r) => setTimeout(r, 20));
     }
     return child;
   }
+  async function runOnce(dir: string, entry: string): Promise<number | null> {
+    const p = spawn("node", [path.join(dir, entry)], { env: hookEnv(dir), stdio: "ignore" });
+    return new Promise<number | null>((r) => p.on("exit", r));
+  }
 
-  test("capture asks the live server; a short-lived process exits and unlinks its socket", async () => {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+  test("capture asks the live server: a dump of what ran, a script record once, and only the app's code", async () => {
+    const dir = await scratch();
     const server = await start(dir, "server.js", 1);
     try {
-      expect(await reportsIn(dir)).toEqual([]);
+      expect(await dumpsIn(dir)).toEqual([]);
       await node().capture!(fakeCtx(dir));
-      const reports = await reportsIn(dir);
-      expect(reports.length).toBe(1);
-      const doc = JSON.parse(await fs.readFile(path.join(dir, reports[0]!), "utf8")) as {
-        result: { url: string }[];
-      };
-      expect(doc.result.some((s) => s.url.endsWith("/server.js"))).toBe(true);
-
-      const short = spawn("node", ["-e", "1"], {
-        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${path.join(dir, "hook.cjs")}` },
-        stdio: "ignore",
-      });
-      const code = await new Promise<number | null>((resolve) => short.on("exit", resolve));
-      expect(code).toBe(0);
-      expect((await socketsIn(dir)).length).toBe(1); // its socket is gone with it
-      expect((await reportsIn(dir)).length).toBe(2); // its exit-time report is there
+      const [name] = await dumpsIn(dir);
+      const dump = await readDump(dir, name!);
+      expect(dump.spectestVersion).toBe(2);
+      expect(dump.result.map((s) => s.url)).toEqual([`file://${path.join(dir, "server.js")}`]);
+      const fns = dump.result[0]!.functions;
+      // Triples: the extent, then blocks relative to it; some count > 0.
+      expect(fns.every((f) => f.length >= 3 && f.length % 3 === 0)).toBe(true);
+      expect(fns.every((f) => f.some((_, i) => i % 3 === 2 && f[i]! > 0))).toBe(true);
+      const rec = (await records(dir)).get(`file://${path.join(dir, "server.js")}`)!;
+      expect(ranNames(dump, rec).sort()).toEqual(["", "tick"]);
+      expect(rec.lineLengths).toEqual([28, 51, 0]);
+      expect(rec.functions.map((f) => f[0])).toEqual(["", "tick"]);
+      expect(rec.sourceMap).toBeNull();
+      expect(dump.result[0]!.spectestScript).toBeDefined();
+      const markers = await fs.readdir(path.join(dir, NODE_COVERAGE_MARKERS_SUBDIR));
+      expect(markers).toEqual([dump.result[0]!.spectestScript]);
 
-      // The next capture ships only what is new: the first dump goes,
-      // the short process's exit dump and the server's fresh dump stay.
+      // The next capture: the first dump is gone, a new one describes
+      // only what ran since (tick), and the record is not written again.
+      await new Promise((r) => setTimeout(r, 30));
       await node().capture!(fakeCtx(dir));
-      const next = await reportsIn(dir);
-      expect(next.length).toBe(2);
-      expect(next).not.toContain(reports[0]!);
+      const names = await dumpsIn(dir);
+      expect(names.length).toBe(1);
+      expect(names[0]).not.toBe(name);
+      const second = await readDump(dir, names[0]!);
+      expect(ranNames(second, rec)).toEqual(["tick"]);
+      expect((await fs.readdir(path.join(dir, NODE_COVERAGE_SCRIPTS_SUBDIR))).length).toBe(0);
     } finally {
       server.kill("SIGKILL");
     }
   });
 
   test("a server behind a wrapper process is dumped too (pnpm exec / tsx shape)", async () => {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const dir = await scratch();
     const wrapper = await start(dir, "wrapper.js", 2);
     try {
       expect((await socketsIn(dir)).length).toBe(2);
       await node().capture!(fakeCtx(dir));
-      const reports = await reportsIn(dir);
-      expect(reports.length).toBe(2);
       const urls = new Set<string>();
-      for (const r of reports) {
-        const doc = JSON.parse(await fs.readFile(path.join(dir, r), "utf8")) as { result: { url: string }[] };
-        for (const s of doc.result) urls.add(s.url);
-      }
+      for (const n of await dumpsIn(dir)) for (const s of (await readDump(dir, n)).result) urls.add(s.url);
       expect([...urls].some((u) => u.endsWith("/server.js"))).toBe(true);
       expect([...urls].some((u) => u.endsWith("/wrapper.js"))).toBe(true);
     } finally {
-      wrapper.kill("SIGKILL");
-      // The wrapper's child is orphaned by SIGKILL; find and kill it too.
-      const pids = (await socketsIn(dir)).map((n) => Number(n.slice(NODE_COVERAGE_SOCKET_PREFIX.length)));
-      for (const pid of pids) {
-        try {
-          process.kill(pid, "SIGKILL");
-        } catch {}
-      }
+      wrapper.kill("SIGTERM");
+      await new Promise<void>((r) => wrapper.on("exit", () => r()));
     }
   });
 
-  test("short-lived CLI processes: exit dumps are the coverage, no live process needed", async () => {
-    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"), "process.stdout.write('v1');\n");
+  test("short-lived CLI processes write at exit; the map next to the script is recorded once, no NODE_V8_COVERAGE", async () => {
+    const dir = await scratch();
+    await fs.writeFile(path.join(dir, "cli.js"), "function used() { return 1 }\nfunction unused() { return 2 }\nused();\n");
+    await fs.writeFile(path.join(dir, "cli.js.map"), JSON.stringify({ version: 3, sources: ["cli.ts"], mappings: "AAAA;AACA", sourcesContent: ["src"] }));
     // Nothing has run yet: an empty report, not a failure.
     await node().capture!(fakeCtx(dir));
-    expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
-    // Two CLI runs, each its own process, each dumping at exit.
-    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);
-    }
+    expect(await fs.readdir(dir).then((n) => n.filter((x) => x === NODE_COVERAGE_EMPTY_REPORT))).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
+    for (let i = 0; i < 2; i++) expect(await runOnce(dir, "cli.js")).toBe(0);
     expect((await socketsIn(dir)).length).toBe(0);
+    expect(await fs.readdir(dir).then((n) => n.filter((x) => x.startsWith("coverage-") && x !== NODE_COVERAGE_EMPTY_REPORT))).toEqual([]); // no NODE_V8_COVERAGE dumps
+    await node().capture!(fakeCtx(dir));
+    const names = await dumpsIn(dir);
+    expect(names.length).toBe(2);
+    const recs = await records(dir);
+    expect(recs.size).toBe(1);
+    const rec = recs.get(`file://${path.join(dir, "cli.js")}`)!;
+    for (const n of names) {
+      const d = await readDump(dir, n);
+      expect(d.result.map((s) => s.url)).toEqual([`file://${path.join(dir, "cli.js")}`]);
+      expect(ranNames(d, rec).sort()).toEqual(["", "used"]);
+    }
+    expect(rec.functions.map((f) => f[0])).toEqual(["", "used", "unused"]);
+    expect(rec.lineLengths).toEqual([28, 30, 7, 0]);
+    expect(rec.sourceMap!.url).toBe(`file://${path.join(dir, "cli.js.map")}`);
+    expect(rec.sourceMap!.data).toEqual({ version: 3, sources: ["cli.ts"], mappings: "AAAA;AACA" });
+    // The next capture removes what shipped; a third run is a new dump
+    // and still no new record.
+    expect(await runOnce(dir, "cli.js")).toBe(0);
     await node().capture!(fakeCtx(dir));
-    const reports = (await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT);
-    expect(reports.length).toBe(2);
-    const doc = JSON.parse(await fs.readFile(path.join(dir, reports[0]!), "utf8")) as { result: { url: string }[] };
-    expect(doc.result.map((x) => x.url)).toEqual([`file://${path.join(dir, "cli.js")}`]); // compacted
+    expect((await dumpsIn(dir)).length).toBe(1);
+    expect((await records(dir)).size).toBe(0);
   });
 
-  test("a worker thread does not bind the socket; the main thread's dump is the app's", async () => {
-    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, "server.js"),
-      "function appWork() { return 1 } appWork();\n" +
-        "new (require('node:worker_threads').Worker)('setInterval(() => {}, 1000)', { eval: true });\n" +
-        SERVER_JS,
-    );
-    const child = spawn("node", [path.join(dir, "server.js")], {
-      env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
-      stdio: ["ignore", "pipe", "inherit"],
+  test("maps: the file a comment names, and an inline data: map; a comment Node would have cached costs nothing", async () => {
+    const dir = await scratch();
+    await fs.mkdir(path.join(dir, "maps"));
+    await fs.writeFile(path.join(dir, "a.js"), "x = 1;\n//# sourceMappingURL=maps/a.map\n");
+    await fs.writeFile(path.join(dir, "maps", "a.map"), JSON.stringify({ version: 3, sources: ["../a.ts"], mappings: "AAAA" }));
+    const inline = JSON.stringify({ version: 3, sources: ["b.ts"], mappings: "AACA" });
+    await fs.writeFile(path.join(dir, "b.js"), `y = 2;\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(inline).toString("base64")}\n`);
+    await fs.writeFile(path.join(dir, "c.js"), "z = 3;\n//# sourceMappingURL=https://cdn.test/c.map\n");
+    await fs.writeFile(path.join(dir, "main.js"), "require('./a.js'); require('./b.js'); require('./c.js');\n");
+    expect(await runOnce(dir, "main.js")).toBe(0);
+    await node().capture!(fakeCtx(dir));
+    const recs = await records(dir);
+    expect(recs.get(`file://${path.join(dir, "a.js")}`)!.sourceMap).toEqual({
+      url: `file://${path.join(dir, "maps", "a.map")}`,
+      data: { version: 3, sources: ["../a.ts"], mappings: "AAAA" },
     });
-    await new Promise<void>((resolve) => child.stdout!.once("data", () => resolve()));
-    try {
-      await new Promise((r) => setTimeout(r, 300)); // let the worker thread start
-      expect((await socketsIn(dir)).length).toBe(1);
-      await node().capture!(fakeCtx(dir));
-      const reports = (await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT);
-      expect(reports.length).toBe(1);
-      const doc = JSON.parse(await fs.readFile(path.join(dir, reports[0]!), "utf8")) as { result: { url: string }[] };
-      expect(doc.result.some((s) => s.url.endsWith("/server.js"))).toBe(true);
-    } finally {
-      child.kill("SIGKILL");
-    }
+    expect(recs.get(`file://${path.join(dir, "b.js")}`)!.sourceMap).toEqual({ url: null, data: { version: 3, sources: ["b.ts"], mappings: "AACA" } });
+    expect(recs.get(`file://${path.join(dir, "c.js")}`)!.sourceMap).toBeNull();
+    expect(recs.get(`file://${path.join(dir, "main.js")}`)!.sourceMap).toBeNull();
   });
 
-  test("a stale socket left by a killed process is removed at capture", async () => {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
-    const first = await start(dir, "server.js", 1);
-    first.kill("SIGKILL");
-    await new Promise<void>((resolve) => first.on("exit", () => resolve()));
-    expect((await socketsIn(dir)).length).toBe(1); // stale
+  test("a worker thread writes its own dump at exit; only the main thread binds the socket", async () => {
+    const dir = await scratch();
+    await fs.writeFile(
+      path.join(dir, "threads.js"),
+      "const { Worker, isMainThread } = require('node:worker_threads');\n" +
+        "function inWorker() { return 1 }\n" +
+        "if (isMainThread) { new Worker(__filename); } else { inWorker(); }\n",
+    );
+    expect(await runOnce(dir, "threads.js")).toBe(0);
+    expect((await socketsIn(dir)).length).toBe(0);
     await node().capture!(fakeCtx(dir));
-    expect((await socketsIn(dir)).length).toBe(0); // cleaned up
-    const second = await start(dir, "server.js", 1);
-    try {
-      await node().capture!(fakeCtx(dir));
-      expect((await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT).length).toBe(1);
-    } finally {
-      second.kill("SIGKILL");
-    }
+    const names = await dumpsIn(dir);
+    expect(names.length).toBe(2);
+    const byThread = new Map<string, Dump>();
+    for (const n of names) byThread.set(n.split("-")[2]!, await readDump(dir, n));
+    const recs = await records(dir);
+    expect(recs.size).toBe(1); // one script, one record, whichever thread came first
+    const rec = recs.get(`file://${path.join(dir, "threads.js")}`)!;
+    const worker = [...byThread.entries()].find(([t]) => t !== "0")![1];
+    expect(ranNames(worker, rec)).toContain("inWorker");
+    const main = byThread.get("0")!;
+    expect(ranNames(main, rec)).not.toContain("inWorker");
   });
 
-  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("a stale socket left by a killed process is removed at capture", async () => {
+    const dir = await scratch();
+    const server = await start(dir, "server.js", 1);
+    server.kill("SIGKILL");
+    await new Promise<void>((r) => server.on("exit", () => r()));
+    expect((await socketsIn(dir)).length).toBe(1); // SIGKILL: no exit handler, socket left behind
+    await node().capture!(fakeCtx(dir));
+    expect((await socketsIn(dir)).length).toBe(0);
   });
 
   test("no process and no dump: an empty report is written, once", async () => {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const dir = await scratch();
     await node().capture!(fakeCtx(dir));
     await node().capture!(fakeCtx(dir));
-    expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
+    expect((await fs.readdir(dir)).filter((n) => n.endsWith(".json"))).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
   });
 });