@specific.dev/spectest 0.79.1 → 0.80.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 {
@@ -296,23 +282,17 @@ 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. 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 +317,28 @@ 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);
+      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`,
+      );
     },
   };
 }
 
-/** 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 +389,34 @@ 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>();
+
+/** Forget the branch memory (tests). */
+export function resetNodeCoverageMemory(): void {
+  SHIPPED_V8_REPORTS.clear();
+  SHIPPED_SOURCE_MAPS.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 +430,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 +481,19 @@ 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;
+      delete e[SOURCE_MAP_HASH_KEY];
+      delete e[SOURCE_MAP_REF_KEY];
+      const hash = "sha256:" + createHash("sha256").update(JSON.stringify(e)).digest("hex");
+      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 +501,53 @@ 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;
+}
+
+/**
+ * Compact, in place, every `coverage-*.json` in `dir` that no earlier
+ * capture shipped, and mark it shipped. A dump mid-write (not yet valid
+ * JSON) is left for the next capture.
+ */
+export async function prepareV8Reports(dir: string): 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 };
   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 out = JSON.stringify(compactV8Document(doc, SHIPPED_SOURCE_MAPS));
     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 ───────────────────────────────────────────────────────