@specific.dev/spectest 0.82.0 → 0.85.0

package/src/coverage.test.ts

@@ -11,6 +11,9 @@ import {
   NODE_COVERAGE_SCRIPTS_SUBDIR,
   NODE_COVERAGE_MARKERS_SUBDIR,
   NODE_COVERAGE_SOCKET_PREFIX,
+  NODE_EXPLAINS,
+  NODE_INVENTORY_SCRIPT,
+  npmManifestUnit,
   applyCoverageAdapters,
   appendEnvFlag,
   browser,
@@ -67,6 +70,7 @@ describe("applyCoverageAdapters", () => {
     expect(out.env?.NODE_OPTIONS).toBe(`--max-old-space-size=512 --require ${NODE_COVERAGE_HOOK_PATH}`);
     expect(out.env?.[NODE_COVERAGE_DIR_ENV]).toBe("/spectest/coverage");
     expect(out.env?.NODE_V8_COVERAGE).toBeUndefined();
+    expect((out.coverage as { explains?: string[] }).explains).toEqual([...NODE_EXPLAINS]);
     expect(out.files?.map((f) => f.path)).toEqual([NODE_COVERAGE_HOOK_PATH]);
     expect(out.files?.[0]?.content).toBe(NODE_COVERAGE_HOOK);
   });
@@ -78,6 +82,7 @@ describe("applyCoverageAdapters", () => {
     expect(typeof list[1]?.load).toBe("function");
     expect(JSON.parse(JSON.stringify(out)).coverage).toEqual({
       adapters: [{ adapter: "node" }, { adapter: "browser" }],
+      explains: [...NODE_EXPLAINS],
     });
   });
   test("true and undefined pass through untouched", () => {
@@ -109,6 +114,20 @@ function fakeCtx(dir: string, signal = new AbortController().signal): CoverageCa
   };
 }
 
+describe("units", () => {
+  test("npmManifestUnit ignores metadata keys and formatting, moves on scripts and dependencies", () => {
+    const a = npmManifestUnit("packages/cli/package.json", JSON.stringify({ name: "cli", version: "0.1.219", scripts: { build: "x" }, dependencies: { a: "1" } }));
+    const b = npmManifestUnit("packages/cli/package.json", JSON.stringify({ version: "0.1.220", name: "cli", dependencies: { a: "1" }, scripts: { build: "x" } }, null, 2));
+    expect(a).toBe(b);
+    expect(a).toMatch(/^manifest:packages\/cli\/package\.json#[0-9a-f]{16}$/);
+    const c = npmManifestUnit("packages/cli/package.json", JSON.stringify({ name: "cli", version: "0.1.220", scripts: { build: "y" }, dependencies: { a: "1" } }));
+    const d = npmManifestUnit("packages/cli/package.json", JSON.stringify({ name: "cli", version: "0.1.220", scripts: { build: "x" }, dependencies: { a: "2" } }));
+    expect(c).not.toBe(a);
+    expect(d).not.toBe(a);
+    expect(npmManifestUnit("x/package.json", "not json")).toMatch(/^manifest:x\/package\.json#/);
+  });
+});
+
 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-"));
@@ -159,14 +178,14 @@ const WRAPPER_JS =
 
 interface Dump {
   spectestVersion: number;
-  result: { url: string; spectestScript: string; functions: { functionName: string; ranges: { count: 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;
+    sourceMap: { url: string | null; data: Record<string, unknown>; sourceUnits?: (string | null)[] } | null;
   };
 }
 
@@ -190,6 +209,11 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     }
     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-"));
@@ -221,11 +245,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
       await node().capture!(fakeCtx(dir));
       const [name] = await dumpsIn(dir);
       const dump = await readDump(dir, name!);
-      expect(dump.spectestVersion).toBe(1);
+      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;
-      expect(fns.every((f) => f.ranges.some((r) => r.count > 0))).toBe(true);
+      // 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();
@@ -241,7 +268,7 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
       expect(names.length).toBe(1);
       expect(names[0]).not.toBe(name);
       const second = await readDump(dir, names[0]!);
-      expect(second.result[0]!.functions.map((f) => f.functionName)).toEqual(["tick"]);
+      expect(ranNames(second, rec)).toEqual(["tick"]);
       expect((await fs.readdir(path.join(dir, NODE_COVERAGE_SCRIPTS_SUBDIR))).length).toBe(0);
     } finally {
       server.kill("SIGKILL");
@@ -277,14 +304,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     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(d.result[0]!.functions.map((f) => f.functionName).sort()).toEqual(["", "used"]);
+      expect(ranNames(d, rec).sort()).toEqual(["", "used"]);
     }
-    const recs = await records(dir);
-    expect(recs.size).toBe(1);
-    const rec = recs.get(`file://${path.join(dir, "cli.js")}`)!;
     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")}`);
@@ -312,8 +339,9 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     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" },
+      sourceUnits: [null],
     });
-    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, "b.js")}`)!.sourceMap).toEqual({ url: null, data: { version: 3, sources: ["b.ts"], mappings: "AACA" }, sourceUnits: [null] });
     expect(recs.get(`file://${path.join(dir, "c.js")}`)!.sourceMap).toBeNull();
     expect(recs.get(`file://${path.join(dir, "main.js")}`)!.sourceMap).toBeNull();
   });
@@ -333,11 +361,63 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     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(worker.result[0]!.functions.some((f) => f.functionName === "inWorker")).toBe(true);
+    expect(ranNames(worker, rec)).toContain("inWorker");
     const main = byThread.get("0")!;
-    expect(main.result[0]!.functions.some((f) => f.functionName === "inWorker")).toBe(false);
-    expect((await records(dir)).size).toBe(1); // one script, one record, whichever thread came first
+    expect(ranNames(main, rec)).not.toContain("inWorker");
+  });
+
+  test("a dependency that ran is a unit in the dump, never a script; a bundled dependency is a unit on the map", async () => {
+    const dir = await scratch();
+    // hoisted: node_modules/dep/index.js; pnpm store: node_modules/.pnpm/pkg@2.0.0/node_modules/pkg/index.js
+    await fs.mkdir(path.join(dir, "node_modules", "dep"), { recursive: true });
+    await fs.writeFile(path.join(dir, "node_modules", "dep", "package.json"), JSON.stringify({ name: "dep", version: "1.2.3" }));
+    await fs.writeFile(path.join(dir, "node_modules", "dep", "index.js"), "exports.f = function f() { return 1 };\n");
+    await fs.mkdir(path.join(dir, "node_modules", ".pnpm", "pkg@2.0.0", "node_modules", "pkg"), { recursive: true });
+    await fs.writeFile(path.join(dir, "node_modules", ".pnpm", "pkg@2.0.0", "node_modules", "pkg", "index.js"), "exports.g = () => 2;\n");
+    await fs.writeFile(
+      path.join(dir, "main.js"),
+      "require('./node_modules/dep/index.js').f(); require('./node_modules/.pnpm/pkg@2.0.0/node_modules/pkg/index.js').g();\n",
+    );
+    // A bundle whose map names a dependency source that is not on disk.
+    const map = JSON.stringify({ version: 3, sources: ["../src/app.ts", "../node_modules/.pnpm/picocolors@1.1.1/node_modules/picocolors/picocolors.js"], mappings: "AAAA;AACA" });
+    await fs.mkdir(path.join(dir, "dist"));
+    await fs.writeFile(path.join(dir, "dist", "bundle.js"), `x = 1;\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(map).toString("base64")}\n`);
+    await fs.writeFile(path.join(dir, "entry.js"), "require('./main.js'); require('./dist/bundle.js');\n");
+    expect(await runOnce(dir, "entry.js")).toBe(0);
+    await node().capture!(fakeCtx(dir));
+    const [name] = await dumpsIn(dir);
+    const dump = JSON.parse(await fs.readFile(path.join(dir, name!), "utf8")) as Dump & { units: string[] };
+    expect(dump.units).toEqual(["npm:dep@1.2.3", "npm:pkg@2.0.0"]); // pkg has no package.json: name and version from the pnpm path
+    expect(dump.result.map((s) => s.url).every((u) => !u.includes("/node_modules/"))).toBe(true);
+    const rec = (await records(dir)).get(`file://${path.join(dir, "dist", "bundle.js")}`)!;
+    expect((rec.sourceMap as { sourceUnits?: (string | null)[] }).sourceUnits).toEqual([null, "npm:picocolors@1.1.1"]);
+    expect([...(await records(dir)).keys()].every((u) => !u.includes("/node_modules/"))).toBe(true);
+  });
+
+  test("the inventory script lists hoisted, scoped, nested and pnpm-store packages from the cwd upward", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-inv-"));
+    const w = async (rel: string, name: string, version?: string) => {
+      await fs.mkdir(path.join(root, rel), { recursive: true });
+      await fs.writeFile(path.join(root, rel, "package.json"), JSON.stringify(version ? { name, version } : { name }));
+    };
+    await w("node_modules/a", "a", "1.0.0");
+    await w("node_modules/@s/b", "@s/b", "2.0.0");
+    await w("node_modules/a/node_modules/c", "c", "3.0.0");
+    await w("node_modules/.pnpm/d@4.0.0/node_modules/d", "d", "4.0.0");
+    await w("node_modules/.pnpm/d@4.0.0/node_modules/e", "e"); // a symlink target in real pnpm; a real dir here, so listed
+    await fs.mkdir(path.join(root, "packages", "cli", "node_modules", "f"), { recursive: true });
+    await fs.writeFile(path.join(root, "packages", "cli", "node_modules", "f", "package.json"), JSON.stringify({ name: "f", version: "6.0.0" }));
+    await fs.symlink(path.join(root, "node_modules", ".pnpm", "d@4.0.0", "node_modules", "d"), path.join(root, "node_modules", "d"));
+    const p = spawn("node", ["-"], { cwd: path.join(root, "packages", "cli"), stdio: ["pipe", "pipe", "inherit"] });
+    p.stdin!.end(NODE_INVENTORY_SCRIPT);
+    let out = "";
+    p.stdout!.on("data", (b: Buffer) => (out += b));
+    expect(await new Promise<number | null>((r) => p.on("exit", r))).toBe(0);
+    expect(out.trim().split("\n")).toEqual(["npm:@s/b@2.0.0", "npm:a@1.0.0", "npm:c@3.0.0", "npm:d@4.0.0", "npm:e", "npm:f@6.0.0"]);
   });
 
   test("a stale socket left by a killed process is removed at capture", async () => {

package/src/coverage.ts

@@ -27,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";
 
@@ -67,6 +69,27 @@ export interface CoverageLoadContext {
   collectBrowserScripts(): void;
 }
 
+/**
+ * What one adapter's `inventory` runs against, once per environment, at
+ * the bring-up capture. The inventory is the set of **units** the
+ * environment resolved for this service — dependencies, and fingerprints
+ * of the manifests that declare them (see {@link CoverageAdapter.inventory}).
+ */
+export interface CoverageInventoryContext {
+  /** The services-map key. */
+  service: string;
+  /** Run a shell command (`sh -c`) inside the container. Rejects on a
+   *  non-zero exit with the command's output in the message. */
+  exec(command: string): Promise<{ stdout: string; stderr: string }>;
+  /** Every file of the uploaded project, project-relative, `/`-separated,
+   *  `node_modules`, `.git` and the like skipped. */
+  projectFiles(): Promise<string[]>;
+  /** One project file's text (project-relative path); `null` when absent. */
+  readProjectFile(path: string): Promise<string | null>;
+  /** Aborts when the inventory budget runs out. */
+  signal: AbortSignal;
+}
+
 /** What one adapter's `capture` runs against. */
 export interface CoverageCaptureContext {
   /** The services-map key. */
@@ -109,8 +132,33 @@ export interface CoverageAdapter {
   load?(ctx: CoverageLoadContext): void | Promise<void>;
   /** Make the report appear in the directory. A throw fails the test. */
   capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+  /**
+   * Project paths (gitignore-style patterns, project-relative) whose
+   * changes this adapter's **inventory** accounts for — a package
+   * manifest, a lockfile. The subset selector sets such a changed file
+   * aside instead of treating it as a file no coverage names (which is a
+   * full run), and judges the change by the inventory instead: a unit
+   * that is gone selects the tests that ran it; a gone unit no test ran
+   * is a full run. Part of the wire config (`coverage.explains`).
+   */
+  explains?: readonly string[];
+  /**
+   * The **units** the environment resolved for this service, once per
+   * environment at the bring-up capture: one opaque id per line of the
+   * `inventory.units` report. Dependencies as `<scheme>:<name>@<version>`
+   * (`npm:picocolors@1.1.1`), and a fingerprint per manifest as
+   * `manifest:<project path>#<hash>` over the manifest minus its metadata
+   * keys, so a version bump does not move it and a `scripts` change does.
+   * The control plane compares inventories across runs by string
+   * equality and knows no scheme; what a unit is, is the adapter's.
+   */
+  inventory?(ctx: CoverageInventoryContext): Promise<readonly string[]>;
 }
 
+/** The report name the harness writes an adapter's inventory to, in the
+ *  bring-up capture only. */
+export const INVENTORY_REPORT = "inventory.units";
+
 /** `ServiceConfig.coverage`: the program writes its own reports (`true`),
  *  or a list of adapters gets them out, and/or how the reports the
  *  program itself writes count (`reports`, default `"cumulative"`). */
@@ -149,14 +197,17 @@ export function validateCoverage(service: string, cov: unknown): void {
         ((a as CoverageAdapter).reports === undefined ||
           (a as CoverageAdapter).reports === "delta" ||
           (a as CoverageAdapter).reports === "cumulative") &&
-        ["configure", "load", "capture"].every(
+        ((a as CoverageAdapter).explains === undefined ||
+          (Array.isArray((a as CoverageAdapter).explains) &&
+            ((a as CoverageAdapter).explains as unknown[]).every((e) => typeof e === "string"))) &&
+        ["configure", "load", "capture", "inventory"].every(
           (k) =>
             (a as Record<string, unknown>)[k] === undefined ||
             typeof (a as Record<string, unknown>)[k] === "function",
         );
       if (!ok) {
         throw new Error(
-          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
+          `service "${service}" has an invalid coverage adapter — an adapter is \`{ name, reports?, explains?, configure?, load?, capture?, inventory? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`,
         );
       }
     }
@@ -188,7 +239,14 @@ export function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc:
     if (a.configure) out = a.configure(out, { key });
   }
   const mode = (svc.coverage as { reports?: CoverageReportsMode }).reports;
-  const wire = { adapters: adapters.map((a) => withWireName(a)), ...(mode ? { reports: mode } : {}) };
+  // `explains` rides the wire config so the control plane's selector can
+  // read it without knowing any adapter.
+  const explains = [...new Set(adapters.flatMap((a) => a.explains ?? []))];
+  const wire = {
+    adapters: adapters.map((a) => withWireName(a)),
+    ...(mode ? { reports: mode } : {}),
+    ...(explains.length > 0 ? { explains } : {}),
+  };
   return { ...out, coverage: wire } as unknown as S;
 }
 
@@ -255,12 +313,21 @@ export const NODE_COVERAGE_DUMP_PREFIX = "node-";
  *   counters: every dump is the delta since the previous take. No
  *   signal is used: signals are claimed by frameworks (SIGUSR2 stops a
  *   Temporal worker, restarts nodemon), a socket is nobody's.
+ * - Reports **dependencies as units**: a ran script under `node_modules`
+ *   becomes `npm:<name>@<version>` (from the nearest package.json, or the
+ *   path's text) in the dump's `units`; a bundled script's map sources
+ *   under `node_modules` become `sourceUnits` beside the map in its
+ *   record. The control plane compares unit ids by equality and never
+ *   learns what `node_modules` is.
  * - Writes a **dump** `node-<pid>-<thread>-<ms>-<n>.json`: the app's own
  *   scripts (`file://`, outside `node_modules` and `.cache`, not the
  *   hook) in which some range count is above zero, and of each only the
- *   functions that ran, ranges and counts as V8 reported them. Nothing
- *   when nothing ran. Still a V8 coverage document (`result`), plus
- *   `spectestScript` on each script naming its record.
+ *   functions that ran, each one flat array: `[start, length, count]`
+ *   for its extent (V8's first range), then `[offset from start,
+ *   length, count]` per block range in V8's order. Name and block flag
+ *   are in the record, joined on the extent. Nothing when nothing ran.
+ *   `{ spectestVersion: 2, result: [{ url, spectestScript, functions:
+ *   [[s, l, c, o, l, c, …], …] }] }`.
  * - Writes, **once per script per branch**, a **script record**
  *   `scripts/<id>.json` (`id` = sha256 of the URL): the length of every
  *   line of the source V8 compiled (`Debugger.getScriptSource`, so a
@@ -323,6 +390,48 @@ export const NODE_COVERAGE_HOOK = `"use strict";
   function isApp(u) {
     return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") < 0 && u.indexOf("/.cache/") < 0 && u !== SELF;
   }
+  function isDep(u) {
+    return typeof u === "string" && u.startsWith("file://") && u.indexOf("/node_modules/") >= 0 && u !== SELF;
+  }
+  // A dependency's unit id, npm:<name>@<version>, from the nearest
+  // package.json above a path inside node_modules (read once per
+  // directory); when the file is not on disk (a bundled dependency whose
+  // sources a multi-stage image dropped), from the path's text.
+  const UNIT_CACHE = new Map();
+  function unitFromText(p) {
+    let m = /\\/node_modules\\/\\.pnpm\\/((?:@[^/@+]+\\+)?[^/@]+)@([^/_]+)/.exec(p);
+    if (m) return "npm:" + m[1].replace("+", "/") + "@" + m[2];
+    m = /\\/node_modules\\/(@[^/]+\\/[^/]+|[^/@.][^/]*)(?:\\/|$)/.exec(p);
+    return m ? "npm:" + m[1] : null;
+  }
+  function unitOf(p) {
+    if (p.indexOf("/node_modules/") < 0) return null;
+    // Walk up to the innermost node_modules boundary and no further: the
+    // directories above it are shared with every other package, so a
+    // cached answer must never sit on them.
+    const visited = [];
+    let d = path.dirname(p);
+    while (d && d !== "/" && path.basename(d) !== "node_modules") {
+      if (UNIT_CACHE.has(d)) {
+        const hit = UNIT_CACHE.get(d);
+        for (const v of visited) UNIT_CACHE.set(v, hit);
+        return hit;
+      }
+      visited.push(d);
+      try {
+        const pj = JSON.parse(fs.readFileSync(path.join(d, "package.json"), "utf8"));
+        if (pj && typeof pj.name === "string" && pj.name) {
+          const u = "npm:" + pj.name + (typeof pj.version === "string" && pj.version ? "@" + pj.version : "");
+          for (const v of visited) UNIT_CACHE.set(v, u);
+          return u;
+        }
+      } catch (e) {}
+      d = path.dirname(d);
+    }
+    const u = unitFromText(p);
+    for (const v of visited) UNIT_CACHE.set(v, u);
+    return u;
+  }
   function ran(f) {
     return f.ranges.some(function (r) { return r.count > 0; });
   }
@@ -378,7 +487,29 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     }
     if (!data || typeof data !== "object" || !("mappings" in data)) return null;
     delete data.sourcesContent;
-    return { url: mapUrl, data: data };
+    // A source inside node_modules is a dependency: its unit id rides
+    // beside the map (\`sourceUnits[i]\`, null for the project's own), so
+    // the control plane never has to know what node_modules is.
+    const mapDir = mapUrl ? path.dirname(url.fileURLToPath(mapUrl)) : path.dirname(scriptPath);
+    const root = typeof data.sourceRoot === "string" && data.sourceRoot ? data.sourceRoot : "";
+    const sourceUnits = (Array.isArray(data.sources) ? data.sources : []).map(function (src) {
+      if (typeof src !== "string") return null;
+      let abs;
+      if (src.startsWith("file://")) {
+        try {
+          abs = url.fileURLToPath(src);
+        } catch (e) {
+          return null;
+        }
+      } else if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
+        return src.indexOf("/node_modules/") >= 0 ? unitFromText(src) : null;
+      } else {
+        const rel = root && !src.startsWith("/") ? root.replace(/\\/$/, "") + "/" + src : src;
+        abs = path.resolve(mapDir, rel);
+      }
+      return abs.indexOf("/node_modules/") >= 0 ? unitOf(abs) : null;
+    });
+    return { url: mapUrl, data: data, sourceUnits: sourceUnits };
   }
   function writeAtomic(file, text) {
     const tmp = file + "." + process.pid + "-" + wt.threadId + ".tmp";
@@ -409,10 +540,19 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     const res = post("Profiler.takePreciseCoverage");
     if (!res || !Array.isArray(res.result)) return;
     const kept = [];
+    const units = new Set();
     for (const s of res.result) {
-      if (isApp(s.url) && Array.isArray(s.functions) && s.functions.some(ran)) kept.push(s);
+      if (!Array.isArray(s.functions) || !s.functions.some(ran)) continue;
+      if (isApp(s.url)) kept.push(s);
+      else if (isDep(s.url)) {
+        let u = null;
+        try {
+          u = unitOf(url.fileURLToPath(s.url));
+        } catch (e) {}
+        if (u) units.add(u);
+      }
     }
-    if (kept.length === 0) return;
+    if (kept.length === 0 && units.size === 0) return;
     const fresh = [];
     for (const s of kept) {
       if (known.has(s.url)) continue;
@@ -433,10 +573,28 @@ export const NODE_COVERAGE_HOOK = `"use strict";
       }
       post("Debugger.disable");
     }
+    // A ran function is one flat array: [start, length, count] for its
+    // extent (V8's first range), then [offset from start, length, count]
+    // per block range in V8's order. Small numbers, so the dump gzips to
+    // less than half of V8's own JSON; name and block flag live in the
+    // script record, joined on the extent.
     const doc = {
-      spectestVersion: 1,
+      spectestVersion: 2,
+      units: Array.from(units).sort(),
       result: kept.map(function (s) {
-        return { url: s.url, scriptId: s.scriptId, spectestScript: idOf(s.url), functions: s.functions.filter(ran) };
+        return {
+          url: s.url,
+          spectestScript: idOf(s.url),
+          functions: s.functions.filter(ran).map(function (f) {
+            const first = f.ranges[0];
+            const out = [first.startOffset, first.endOffset - first.startOffset, first.count];
+            for (let i = 1; i < f.ranges.length; i++) {
+              const r = f.ranges[i];
+              out.push(r.startOffset - first.startOffset, r.endOffset - r.startOffset, r.count);
+            }
+            return out;
+          }),
+        };
       }),
     };
     const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + process.pid + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";
@@ -496,10 +654,136 @@ export const NODE_COVERAGE_HOOK = `"use strict";
  * only its own files: what an earlier capture on this branch shipped is
  * removed first (module memory, forks with the environment).
  */
+/** Manifests and lockfiles whose changes the node inventory accounts for. */
+export const NODE_EXPLAINS: readonly string[] = [
+  "**/package.json",
+  "**/package-lock.json",
+  "**/npm-shrinkwrap.json",
+  "**/pnpm-lock.yaml",
+  "**/pnpm-workspace.yaml",
+  "**/yarn.lock",
+  "**/bun.lock",
+  "**/bun.lockb",
+];
+
+/** package.json keys that describe the package rather than shape what
+ *  runs: a change confined to them does not move the manifest's unit. */
+export const NPM_MANIFEST_METADATA_KEYS: readonly string[] = [
+  "version",
+  "description",
+  "keywords",
+  "author",
+  "contributors",
+  "maintainers",
+  "license",
+  "repository",
+  "homepage",
+  "bugs",
+  "funding",
+  "private",
+  "publishConfig",
+  "readme",
+  "readmeFilename",
+  "gitHead",
+  "_id",
+];
+
+/** JSON with every object's keys sorted, at every depth. */
+function canonicalJson(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+  if (v && typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(v);
+}
+
+/** `manifest:<path>#<hash>` over a package.json minus its metadata keys,
+ *  keys sorted, so formatting and a version bump leave it unchanged and a
+ *  `scripts`, `exports`, `bin` or dependency change moves it. A file that
+ *  is not JSON hashes as text. */
+export function npmManifestUnit(projectPath: string, text: string): string {
+  let canon = text;
+  try {
+    const doc = JSON.parse(text) as Record<string, unknown>;
+    if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+      for (const k of NPM_MANIFEST_METADATA_KEYS) delete doc[k];
+      canon = canonicalJson(doc);
+    }
+  } catch {
+    // not JSON: the text is the fingerprint
+  }
+  const hash = createHash("sha256").update(canon).digest("hex").slice(0, 16);
+  return `manifest:${projectPath}#${hash}`;
+}
+
+/**
+ * The node script the inventory runs inside the container: every package
+ * installed in a `node_modules` on the path from the working directory up
+ * to `/` — hoisted (`node_modules/<name>`, `@scope/<name>`), nested, and
+ * pnpm's store (`node_modules/.pnpm/<pkg>/node_modules/<name>`, the real
+ * directories only; the symlinks beside them point back into the store).
+ * Prints one `npm:<name>@<version>` per line.
+ */
+export const NODE_INVENTORY_SCRIPT = `"use strict";
+const fs = require("node:fs"), path = require("node:path");
+const out = new Set();
+function isRealDir(p) { try { return fs.lstatSync(p).isDirectory(); } catch (e) { return false; } }
+function readPkg(d) {
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(d, "package.json"), "utf8"));
+    if (j && typeof j.name === "string" && j.name) out.add("npm:" + j.name + (typeof j.version === "string" && j.version ? "@" + j.version : ""));
+  } catch (e) {}
+}
+function visit(d, depth) {
+  readPkg(d);
+  if (depth < 3) { const nested = path.join(d, "node_modules"); if (isRealDir(nested)) walkNm(nested, depth + 1); }
+}
+function walkNm(nm, depth) {
+  let names; try { names = fs.readdirSync(nm); } catch (e) { return; }
+  for (const n of names) {
+    if (n === ".bin" || n === ".cache" || n === ".modules.yaml") continue;
+    if (n === ".pnpm") {
+      let ps; try { ps = fs.readdirSync(path.join(nm, ".pnpm")); } catch (e) { continue; }
+      for (const p of ps) { const inner = path.join(nm, ".pnpm", p, "node_modules"); if (isRealDir(inner)) walkNm(inner, depth + 1); }
+      continue;
+    }
+    if (n.startsWith("@")) {
+      let ss; try { ss = fs.readdirSync(path.join(nm, n)); } catch (e) { continue; }
+      for (const s of ss) { const d = path.join(nm, n, s); if (isRealDir(d)) visit(d, depth); }
+    } else { const d = path.join(nm, n); if (isRealDir(d)) visit(d, depth); }
+  }
+}
+let d = process.cwd();
+for (;;) {
+  const nm = path.join(d, "node_modules");
+  if (isRealDir(nm)) walkNm(nm, 0);
+  const up = path.dirname(d);
+  if (up === d) break;
+  d = up;
+}
+process.stdout.write(Array.from(out).sort().join("\\n") + (out.size ? "\\n" : ""));
+`;
+
 export function node(): CoverageAdapter {
   return {
     name: "node",
     reports: "delta",
+    explains: NODE_EXPLAINS,
+    async inventory(ctx) {
+      // Installed packages, from inside the container (the script goes
+      // in through stdin so no quoting crosses the shell); manifest
+      // fingerprints from the project's own package.json files.
+      const b64 = Buffer.from(NODE_INVENTORY_SCRIPT).toString("base64");
+      const r = await ctx.exec(`echo ${b64} | base64 -d | node -`);
+      const units = new Set<string>(r.stdout.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("npm:")));
+      for (const f of await ctx.projectFiles()) {
+        if (f !== "package.json" && !f.endsWith("/package.json")) continue;
+        const text = await ctx.readProjectFile(f);
+        if (text !== null) units.add(npmManifestUnit(f, text));
+      }
+      return [...units].sort();
+    },
     configure(svc) {
       const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
       env[NODE_COVERAGE_DIR_ENV] = COVERAGE_CONTAINER_DIR;