@specific.dev/spectest 0.59.4 → 0.60.0

package/dist/daemon.js

@@ -22,9 +22,9 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, } from "./harness/coverage.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
-import { applyCoverageAdapters, coverageAdapters, validateCoverage, } from "./coverage.js";
+import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, nodeCoverageToolsAvailable, nodeCoverageToolsDir, NODE_COVERAGE_TOOLS_CONTAINER_DIR, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -529,7 +529,16 @@ async function ensureCoverage(svc) {
     const host = coverageHostDir(WORKSPACE, svc.name);
     await fs.mkdir(host, { recursive: true });
     await fs.chmod(host, 0o777);
-    return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+    const flags = [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+    // The conversion tools golden ships (`c8` for `coverage.node()`),
+    // read-only, on the same existence check the adapter makes at capture
+    // — so the VM and the container agree on whether they are there. A
+    // plain `--volume`, never a config `volumes` entry: an absolute-source
+    // volume dir is listed in the delta-restore manifest and wiped.
+    if (await nodeCoverageToolsAvailable()) {
+        flags.push(`--volume=${nodeCoverageToolsDir()}:${NODE_COVERAGE_TOOLS_CONTAINER_DIR}:ro`);
+    }
+    return flags;
 }
 /** Keyed by image ID, not tag: `spectest/<svc>:latest` is retagged onto
  *  new content every rebuild, and a stale uid is silently wrong. */
@@ -3037,8 +3046,10 @@ function rebuildBrowserCoverageResolver() {
         },
     });
 }
-/** The context one adapter's `capture` runs against. */
-function coverageCaptureContext(svc, signal) {
+/** The context one adapter's `capture` runs against. Every report it
+ *  writes through `writeReport` is added to `written`, so the delta step
+ *  knows which files came from which adapter. */
+function coverageCaptureContext(svc, signal, written) {
     const reportDir = coverageHostDir(WORKSPACE, svc.name);
     return {
         service: svc.name,
@@ -3061,20 +3072,25 @@ function coverageCaptureContext(svc, signal) {
             const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
             await fs.writeFile(tmp, content);
             await fs.rename(tmp, file);
+            written.add(path.relative(reportDir, file));
         },
     };
 }
 /** Run one service's adapters in order under one budget. Returns the
- *  error to fail the capture with, naming the adapter. */
+ *  error to fail the capture with, naming the adapter, and the reports
+ *  written by adapters that declare `reports: "delta"`. */
 async function runCoverageAdapters(svc) {
+    const deltaReports = new Set();
     const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
     if (adapters.length === 0)
-        return undefined;
+        return { deltaReports };
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
-    const ctx = coverageCaptureContext(svc, ac.signal);
+    const written = new Set();
+    const ctx = coverageCaptureContext(svc, ac.signal, written);
     try {
         for (const a of adapters) {
+            written.clear();
             try {
                 await Promise.race([
                     a.capture(ctx),
@@ -3084,10 +3100,16 @@ async function runCoverageAdapters(svc) {
                 ]);
             }
             catch (err) {
-                return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${err instanceof Error ? err.message : String(err)}`;
+                return {
+                    error: `coverage adapter "${a.name}" on service "${svc.name}" failed: ${err instanceof Error ? err.message : String(err)}`,
+                    deltaReports,
+                };
             }
+            if (a.reports === "delta")
+                for (const n of written)
+                    deltaReports.add(n);
         }
-        return undefined;
+        return { deltaReports };
     }
     finally {
         clearTimeout(timer);
@@ -3104,10 +3126,15 @@ async function captureServiceCoverage() {
         byName.set(name, s);
     const services = [...byName.values()].filter((s) => s.coverage !== undefined);
     return Promise.all(services.map(async (svc) => {
-        const error = await runCoverageAdapters(svc);
+        const { error, deltaReports } = await runCoverageAdapters(svc);
         if (error)
             return { service: svc.name, reports: [], error };
-        return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        // What ships is what ran during this capture, whatever the tool
+        // counts: cumulative lcov is subtracted against the previous
+        // capture (module memory, forks with the env); a delta adapter's
+        // files and V8 JSON pass through.
+        return applyCoverageDelta(read, coverageReportsMode(svc.coverage), deltaReports);
     }));
 }
 /**

package/dist/harness/coverage.d.ts

@@ -77,3 +77,38 @@ export declare function readCoverageDir(service: string, dir: string): Promise<S
 export declare function encodeCoverageBundle(caseId: string, services: ServiceCoverageCapture[]): Buffer;
 /** The ref for a bundle: its size plus a per-service summary. */
 export declare function coverageBundleRef(gz: Buffer, services: ServiceCoverageCapture[]): CoverageBundleRef;
+/** How a report's counters behave across captures. */
+export type CoverageReportsMode = "delta" | "cumulative";
+/** One lcov record's execution counts: `DA:` by line, `FNDA:` by function
+ *  name. Branch data is dropped: file and line are what the derivation
+ *  reads. */
+export interface LcovRecordCounts {
+    lines: Map<number, number>;
+    functions: Map<string, number>;
+    /** `FN:<line>,<name>` declarations, kept so the delta names them. */
+    functionLines: Map<string, number>;
+}
+/** An lcov document parsed to counts, by `SF:` path. Records for one
+ *  path are merged (a tool may split a file across records). */
+export declare function parseLcovCounts(text: string): Map<string, LcovRecordCounts>;
+/**
+ * `now` minus `prev`, per line and per function. A count that went
+ * *down* is a counter that restarted (the process was replaced): the
+ * new value stands on its own. A file not in `prev` is new: everything
+ * in it counts. Only records with at least one execution are kept — a
+ * file with nothing new in it did not run.
+ */
+export declare function subtractLcovCounts(now: Map<string, LcovRecordCounts>, prev: Map<string, LcovRecordCounts>): Map<string, LcovRecordCounts>;
+/** Counts rendered back to lcov, records in path order. */
+export declare function renderLcovCounts(counts: Map<string, LcovRecordCounts>): string;
+/** Forget every previous capture (tests). */
+export declare function resetCoverageDeltaMemory(): void;
+/**
+ * Turn a capture's cumulative lcov reports into deltas against the
+ * previous capture of the same service and report name, and remember
+ * this capture as the new previous. Reports named in `deltaReports`
+ * (written by an adapter that declares `reports: "delta"`) and
+ * non-lcov reports (V8 JSON is a delta by construction) pass through
+ * untouched. With `mode === "delta"` every report passes through.
+ */
+export declare function applyCoverageDelta(capture: ServiceCoverageCapture, mode: CoverageReportsMode, deltaReports: ReadonlySet<string>): ServiceCoverageCapture;

package/dist/harness/coverage.js

@@ -15,6 +15,17 @@
 // stored bytes, so a change in that derivation is a re-read of stored
 // runs, never a hole in the history.
 //
+// The one transformation done here is the **delta**: a stored report
+// describes what ran between the previous capture and this one, for
+// every source alike. A tool that resets its own counters (V8) writes
+// deltas already; a cumulative tool (coverage.py, Go, JaCoCo — most)
+// gets subtracted against the previous capture, which lives in module
+// memory and so forks with the environment: a forked child's "previous"
+// is its parent's last capture, exactly the state it started from. Which
+// of the two a file is must be declared (an adapter's `reports`, or the
+// service's) — nothing in the bytes tells a delta that happens to equal
+// the previous one from a cumulative report with no new execution.
+//
 // The container side (mount flag, `command` exec) is in `daemon.ts`.
 import { promises as fs } from "node:fs";
 import path from "node:path";
@@ -156,3 +167,149 @@ export function coverageBundleRef(gz, services) {
         })),
     };
 }
+/** An lcov document parsed to counts, by `SF:` path. Records for one
+ *  path are merged (a tool may split a file across records). */
+export function parseLcovCounts(text) {
+    const out = new Map();
+    let cur = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("SF:")) {
+            const file = line.slice(3).trim();
+            if (!file) {
+                cur = null;
+                continue;
+            }
+            cur = out.get(file) ?? { lines: new Map(), functions: new Map(), functionLines: new Map() };
+            out.set(file, cur);
+        }
+        else if (!cur) {
+            continue;
+        }
+        else if (line.startsWith("DA:")) {
+            const [ln, hits] = line.slice(3).split(",");
+            const l = Number(ln), h = Number(hits);
+            if (Number.isFinite(l) && Number.isFinite(h))
+                cur.lines.set(l, (cur.lines.get(l) ?? 0) + h);
+        }
+        else if (line.startsWith("FNDA:")) {
+            const i = line.indexOf(",", 5);
+            if (i < 0)
+                continue;
+            const h = Number(line.slice(5, i)), name = line.slice(i + 1);
+            if (Number.isFinite(h))
+                cur.functions.set(name, (cur.functions.get(name) ?? 0) + h);
+        }
+        else if (line.startsWith("FN:")) {
+            const i = line.indexOf(",", 3);
+            if (i < 0)
+                continue;
+            const l = Number(line.slice(3, i)), name = line.slice(i + 1);
+            if (Number.isFinite(l))
+                cur.functionLines.set(name, l);
+        }
+        else if (line === "end_of_record") {
+            cur = null;
+        }
+    }
+    return out;
+}
+/**
+ * `now` minus `prev`, per line and per function. A count that went
+ * *down* is a counter that restarted (the process was replaced): the
+ * new value stands on its own. A file not in `prev` is new: everything
+ * in it counts. Only records with at least one execution are kept — a
+ * file with nothing new in it did not run.
+ */
+export function subtractLcovCounts(now, prev) {
+    const out = new Map();
+    for (const [file, rec] of now) {
+        const before = prev.get(file);
+        const lines = new Map();
+        const functions = new Map();
+        let executed = false;
+        for (const [l, h] of rec.lines) {
+            const b = before?.lines.get(l) ?? 0;
+            const d = h < b ? h : h - b;
+            lines.set(l, d);
+            if (d > 0)
+                executed = true;
+        }
+        for (const [name, h] of rec.functions) {
+            const b = before?.functions.get(name) ?? 0;
+            const d = h < b ? h : h - b;
+            functions.set(name, d);
+            if (d > 0)
+                executed = true;
+        }
+        // A record with no counts at all carries presence as its only
+        // signal; it is new only when it was not there before.
+        if (rec.lines.size === 0 && rec.functions.size === 0 && !before)
+            executed = true;
+        if (executed)
+            out.set(file, { lines, functions, functionLines: rec.functionLines });
+    }
+    return out;
+}
+/** Counts rendered back to lcov, records in path order. */
+export function renderLcovCounts(counts) {
+    const parts = ["TN:"];
+    for (const file of [...counts.keys()].sort()) {
+        const rec = counts.get(file);
+        parts.push(`SF:${file}`);
+        for (const [name, l] of [...rec.functionLines].sort((a, b) => a[1] - b[1]))
+            parts.push(`FN:${l},${name}`);
+        let fnh = 0;
+        for (const [name, h] of rec.functions) {
+            parts.push(`FNDA:${h},${name}`);
+            if (h > 0)
+                fnh++;
+        }
+        parts.push(`FNF:${rec.functions.size}`, `FNH:${fnh}`);
+        let lh = 0;
+        for (const [l, h] of [...rec.lines].sort((a, b) => a[0] - b[0])) {
+            parts.push(`DA:${l},${h}`);
+            if (h > 0)
+                lh++;
+        }
+        parts.push(`LF:${rec.lines.size}`, `LH:${lh}`, "end_of_record");
+    }
+    return parts.join("\n") + "\n";
+}
+/** The previous capture's counts: service → report name → parsed lcov.
+ *  Module memory, so it forks with the environment — a forked child's
+ *  previous capture is its parent's last one. */
+const PREVIOUS_CAPTURE = new Map();
+/** Forget every previous capture (tests). */
+export function resetCoverageDeltaMemory() {
+    PREVIOUS_CAPTURE.clear();
+}
+/**
+ * Turn a capture's cumulative lcov reports into deltas against the
+ * previous capture of the same service and report name, and remember
+ * this capture as the new previous. Reports named in `deltaReports`
+ * (written by an adapter that declares `reports: "delta"`) and
+ * non-lcov reports (V8 JSON is a delta by construction) pass through
+ * untouched. With `mode === "delta"` every report passes through.
+ */
+export function applyCoverageDelta(capture, mode, deltaReports) {
+    if (capture.error)
+        return capture;
+    let prevByName = PREVIOUS_CAPTURE.get(capture.service);
+    if (!prevByName) {
+        prevByName = new Map();
+        PREVIOUS_CAPTURE.set(capture.service, prevByName);
+    }
+    const reports = [];
+    for (const r of capture.reports) {
+        if (mode === "delta" || deltaReports.has(r.name) || !isLcovShaped(r.content)) {
+            reports.push(r);
+            continue;
+        }
+        const now = parseLcovCounts(r.content);
+        const prev = prevByName.get(r.name) ?? new Map();
+        prevByName.set(r.name, now);
+        reports.push({ name: r.name, content: renderLcovCounts(subtractLcovCounts(now, prev)) });
+    }
+    return { ...capture, reports };
+}

package/package.json

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

package/src/browser-coverage.ts

@@ -68,6 +68,9 @@ interface Collector {
 }
 
 const COLLECTORS = new WeakMap<CDPSession, Collector>();
+/** The collectors of every session attached so far, for the harvest at
+ *  capture; a closed session's take fails and is dropped there. */
+const LIVE_COLLECTORS = new Set<Collector>();
 
 /** Decoded maps by URL (or content hash for inline `data:` maps). */
 const SOURCE_MAPS = new Map<string, DecodedSourceMap | null>();
@@ -80,6 +83,7 @@ export async function attachBrowserCoverage(cdp: CDPSession): Promise<void> {
   if (!CONFIG || COLLECTORS.has(cdp)) return;
   const collector: Collector = { cdp, scripts: new Map(), inFlight: null };
   COLLECTORS.set(cdp, collector);
+  LIVE_COLLECTORS.add(collector);
   cdp.on("Debugger.scriptParsed", (ev: { scriptId: string; url: string; sourceMapURL?: string }) => {
     if (!ev.url) return;
     collector.scripts.set(ev.scriptId, {
@@ -109,9 +113,13 @@ export async function harvestBrowserCoverage(cdp: CDPSession): Promise<void> {
 }
 
 async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promise<void> {
-  const { result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as {
-    result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
-  };
+  let result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
+  try {
+    ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as { result: typeof result });
+  } catch (err) {
+    LIVE_COLLECTORS.delete(c); // the session is gone
+    throw err;
+  }
   for (const script of result) {
     const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
     if (!info) continue;
@@ -142,13 +150,18 @@ async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promis
     const files: FileCounts = info.map
       ? mapToOriginal(info.map, generated)
       : new Map([[url.pathname, generated]]);
-    let totals = TOTALS.get(service);
-    if (!totals) {
-      totals = new Map();
-      TOTALS.set(service, totals);
-    }
-    mergeFileCounts(totals, files);
+    foldBrowserCoverage(service, files);
+  }
+}
+
+/** Fold one script's per-file counts into a service's totals. */
+export function foldBrowserCoverage(service: string, files: FileCounts): void {
+  let totals = TOTALS.get(service);
+  if (!totals) {
+    totals = new Map();
+    TOTALS.set(service, totals);
   }
+  mergeFileCounts(totals, files);
 }
 
 /** Resolve, fetch (or inline-decode) and decode a script's source map. */
@@ -201,7 +214,26 @@ function parseDataUrl(ref: string): unknown {
   }
 }
 
-/** One lcov document per service that has any browser coverage. */
+/** Harvest every live session, so a capture sees the counters of code
+ *  that ran since the last browser op. */
+export async function harvestAllBrowserCoverage(): Promise<void> {
+  await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp)));
+}
+
+/** One lcov document per service that has any browser coverage — and
+ *  the totals are cleared, so the next capture holds only what runs
+ *  from now on. Module memory forks with the environment, so a forked
+ *  child starts from its parent's last capture, empty. */
+export function takeBrowserCoverageReports(): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [service, files] of TOTALS) {
+    if (files.size > 0) out.set(service, lcovDocument(files));
+  }
+  TOTALS.clear();
+  return out;
+}
+
+/** The current totals, without clearing them (tests). */
 export function browserCoverageReports(): Map<string, string> {
   const out = new Map<string, string>();
   for (const [service, files] of TOTALS) {

package/src/coverage.test.ts

@@ -4,21 +4,32 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
+  NODE_COVERAGE_C8_BIN,
+  NODE_COVERAGE_DUMPS_SUBDIR,
   NODE_COVERAGE_HOOK,
   NODE_COVERAGE_EMPTY_REPORT,
+  NODE_COVERAGE_LCOV,
+  NODE_COVERAGE_TOOLS_CONTAINER_DIR,
   NODE_COVERAGE_HOOK_PATH,
   NODE_COVERAGE_SOCKET_PREFIX,
+  absoluteLcovPaths,
   applyCoverageAdapters,
   appendEnvFlag,
   browser,
   command,
+  coverageReportsMode,
   compactV8Document,
   compactV8Reports,
+  COVERAGE_CONTAINER_DIR,
   node,
+  nodeCoverageConvertCommand,
+  nodeCoverageToolsAvailable,
+  nodeCoverageToolsDir,
   validateCoverage,
   type CoverageCaptureContext,
 } from "./coverage.js";
 import type { ServiceConfig } from "./index.js";
+import { foldBrowserCoverage } from "./browser-coverage.js";
 
 const base: ServiceConfig = {
   image: { type: "registry", reference: "node:20" },
@@ -36,6 +47,23 @@ describe("validateCoverage", () => {
     expect(() => validateCoverage("a", [node()])).toThrow(/invalid `coverage` value/);
     expect(() => validateCoverage("a", { adapters: [{ name: "" }] })).toThrow(/invalid coverage adapter/);
     expect(() => validateCoverage("a", { adapters: [{ name: "x", capture: 1 }] })).toThrow(/invalid coverage adapter/);
+    validateCoverage("a", { reports: "delta" });
+    validateCoverage("a", { reports: "cumulative", adapters: [] });
+    expect(() => validateCoverage("a", { reports: "sometimes" })).toThrow(/invalid `coverage` value/);
+    expect(() => validateCoverage("a", { adapters: [{ name: "x", reports: "no" }] })).toThrow(/invalid coverage adapter/);
+    expect(() => validateCoverage("a", { adapters: [], extra: 1 })).toThrow(/invalid `coverage` value/);
+    expect(() => validateCoverage("a", {})).toThrow(/invalid `coverage` value/);
+  });
+  test("reports mode: cumulative unless declared; the shipped adapters write deltas", () => {
+    expect(coverageReportsMode(undefined)).toBe("cumulative");
+    expect(coverageReportsMode(true)).toBe("cumulative");
+    expect(coverageReportsMode({ adapters: [] })).toBe("cumulative");
+    expect(coverageReportsMode({ reports: "delta" })).toBe("delta");
+    expect(node().reports).toBe("delta");
+    expect(browser().reports).toBe("delta");
+    expect(command("x").reports).toBeUndefined();
+    const out = applyCoverageAdapters("api", { ...base, coverage: { reports: "delta", adapters: [command("x")] } });
+    expect(JSON.parse(JSON.stringify(out)).coverage).toEqual({ adapters: [{ adapter: "command" }], reports: "delta" });
   });
 });
 
@@ -91,6 +119,21 @@ describe("compactV8Document", () => {
     expect(Object.keys(out["source-map-cache"])).toEqual(["file:///app/src/a.ts"]);
     expect(out["source-map-cache"]["file:///app/src/a.ts"].data).toEqual({ mappings: "AAAA", sources: ["a.ts"] });
   });
+  test("keepSourcesContent keeps the sources for the in-container conversion", () => {
+    const out = compactV8Document(doc, { keepSourcesContent: true }) as typeof doc;
+    expect(out["source-map-cache"]["file:///app/src/a.ts"].data).toEqual({
+      mappings: "AAAA",
+      sources: ["a.ts"],
+      sourcesContent: ["x"],
+    });
+  });
+  test("absoluteLcovPaths makes c8's root-relative SF records container paths", () => {
+    expect(absoluteLcovPaths("TN:\nSF:app/src/a.ts\nDA:1,1\nend_of_record\nSF:/abs.js\nend_of_record\n")).toBe(
+      "TN:\nSF:/app/src/a.ts\nDA:1,1\nend_of_record\nSF:/abs.js\nend_of_record\n",
+    );
+    expect(absoluteLcovPaths("")).toBe("TN:\n");
+    expect(absoluteLcovPaths("  \n")).toBe("TN:\n");
+  });
   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([]);
@@ -132,6 +175,21 @@ describe("browserCoverage", () => {
     await browser().capture!(fakeCtx(dir));
     expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
   });
+  test("capture takes the totals and clears them: the next capture is a delta", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
+    foldBrowserCoverage("api", new Map([["src/a.ts", new Map([[1, 2]])]]));
+    await browser().capture!(fakeCtx(dir));
+    const first = await fs.readFile(path.join(dir, "browser.lcov"), "utf8");
+    expect(first).toContain("SF:src/a.ts");
+    expect(first).toContain("DA:1,2");
+    await browser().capture!(fakeCtx(dir));
+    expect(await fs.readFile(path.join(dir, "browser.lcov"), "utf8")).toBe("TN:\n");
+    foldBrowserCoverage("api", new Map([["src/b.ts", new Map([[3, 1]])]]));
+    await browser().capture!(fakeCtx(dir));
+    const third = await fs.readFile(path.join(dir, "browser.lcov"), "utf8");
+    expect(third).toContain("SF:src/b.ts");
+    expect(third).not.toContain("SF:src/a.ts");
+  });
 });
 
 // The node hook against a real `node` (the box has one; skipped where it
@@ -309,3 +367,99 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
   });
 });
+
+// The conversion to lcov against a real `node` and a real `c8` tree.
+// Golden ships the tree at /opt/spectest/coverage-tools; on a dev box
+// point SPECTEST_C8_TEST_DIR at one (`bun install --linker=hoisted` of
+// `c8` in a scratch dir). Skipped where either is missing. The exec here
+// is the container's `sh -c` with the container paths rewritten to this
+// directory: the command is exactly what a container runs.
+const c8TestDir = process.env.SPECTEST_C8_TEST_DIR || "/opt/spectest/coverage-tools";
+const hasC8 = await fs
+  .access(path.join(c8TestDir, NODE_COVERAGE_C8_BIN))
+  .then(() => true)
+  .catch(() => false);
+
+describe.if(hasNode && hasC8)("nodeCoverage → lcov (real node + c8)", () => {
+  function c8Ctx(dir: string): CoverageCaptureContext {
+    return {
+      ...fakeCtx(dir),
+      async exec(command: string) {
+        const local = command
+          .replaceAll(NODE_COVERAGE_TOOLS_CONTAINER_DIR, c8TestDir)
+          .replaceAll(COVERAGE_CONTAINER_DIR, dir);
+        return new Promise((resolve, reject) => {
+          const p = spawn("sh", ["-c", local], { stdio: ["ignore", "pipe", "pipe"] });
+          let out = "";
+          p.stdout!.on("data", (b: Buffer) => (out += b));
+          p.stderr!.on("data", (b: Buffer) => (out += b));
+          p.on("exit", (code) => (code === 0 ? resolve({ stdout: out, stderr: "" }) : reject(new Error(out))));
+        });
+      },
+    };
+  }
+  async function withTools<T>(f: () => Promise<T>): Promise<T> {
+    const prior = process.env.SPECTEST_COVERAGE_TOOLS_DIR;
+    process.env.SPECTEST_COVERAGE_TOOLS_DIR = c8TestDir;
+    try {
+      return await f();
+    } finally {
+      if (prior === undefined) delete process.env.SPECTEST_COVERAGE_TOOLS_DIR;
+      else process.env.SPECTEST_COVERAGE_TOOLS_DIR = prior;
+    }
+  }
+
+  test("the tools dir is found through the override, and the command is the container's", async () => {
+    await withTools(async () => {
+      expect(nodeCoverageToolsDir()).toBe(c8TestDir);
+      expect(await nodeCoverageToolsAvailable()).toBe(true);
+    });
+    expect(nodeCoverageConvertCommand()).toBe(
+      `cd / && env -u NODE_V8_COVERAGE -u NODE_OPTIONS node ${NODE_COVERAGE_TOOLS_CONTAINER_DIR}/${NODE_COVERAGE_C8_BIN} report --temp-directory ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_DUMPS_SUBDIR} --reporter=lcovonly --reports-dir ${COVERAGE_CONTAINER_DIR}/.c8`,
+    );
+  });
+
+  test("dumps are converted to node.lcov, the delta of this capture; the raw dumps never ship", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covc8-"));
+    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 }\nfunction unused() { return 2 }\nused();\n");
+    await withTools(async () => {
+      // Nothing ran yet: an empty lcov, no exec.
+      await node().capture!(c8Ctx(dir));
+      expect(await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8")).toBe("TN:\n");
+      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!(c8Ctx(dir));
+      const lcov = await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8");
+      expect(lcov).toContain(`SF:${path.join(dir, "cli.js")}\n`);
+      expect(lcov).toMatch(/FNDA:1,used/);
+      expect(lcov).toMatch(/FNDA:0,unused/);
+      // The hook itself is not the app's code.
+      expect(lcov).not.toContain("coverage-hook.cjs");
+      // Raw dumps moved under the hidden .v8/ dir: the visible reports
+      // are the lcov alone.
+      const visible = (await fs.readdir(dir)).filter((n) => !n.startsWith(".") && n.startsWith("coverage-") && n.endsWith(".json"));
+      expect(visible).toEqual([]);
+      const dumps = (await fs.readdir(path.join(dir, NODE_COVERAGE_DUMPS_SUBDIR))).filter((n) => n.endsWith(".json"));
+      expect(dumps.length).toBe(1);
+      // Nothing new since: the next capture is an empty report, not the
+      // previous one again — the lcov is a delta.
+      await node().capture!(c8Ctx(dir));
+      expect(await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8")).toBe("TN:\n");
+      // A new run is a new delta on its own: counts of 1, not 2.
+      const again = spawn("node", [path.join(dir, "cli.js")], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
+        stdio: "ignore",
+      });
+      await new Promise((r) => again.on("exit", r));
+      await node().capture!(c8Ctx(dir));
+      const lcov2 = await fs.readFile(path.join(dir, NODE_COVERAGE_LCOV), "utf8");
+      expect(lcov2).toMatch(/FNDA:1,used/);
+      expect((await fs.readdir(path.join(dir, NODE_COVERAGE_DUMPS_SUBDIR))).filter((n) => n.endsWith(".json")).length).toBe(1);
+    });
+  });
+});