@specific.dev/spectest 0.83.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-"));
@@ -166,7 +185,7 @@ interface ScriptRecord {
     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;
   };
 }
 
@@ -320,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();
   });
@@ -350,6 +370,56 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     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 () => {
     const dir = await scratch();
     const server = await start(dir, "server.js", 1);

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,6 +313,12 @@ 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
@@ -326,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; });
   }
@@ -381,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";
@@ -412,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;
@@ -443,6 +580,7 @@ export const NODE_COVERAGE_HOOK = `"use strict";
     // script record, joined on the extent.
     const doc = {
       spectestVersion: 2,
+      units: Array.from(units).sort(),
       result: kept.map(function (s) {
         return {
           url: s.url,
@@ -516,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;

package/src/daemon.ts

@@ -23,6 +23,7 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { ENVIRONMENT_CA_PATH as CA_PATH } from "./environment-ca.js";
 
 import {
   assert,
@@ -43,12 +44,14 @@ import {
   isEmptyReport,
   readCoverageDir,
   applyCoverageDelta,
+  walkProjectFiles,
   type CoverageBundleRef,
   type CoverageReport,
   type ServiceCoverageCapture,
 } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import {
+  INVENTORY_REPORT,
   NODE_COVERAGE_MARKERS_SUBDIR,
   NODE_COVERAGE_SCRIPTS_SUBDIR,
   applyCoverageAdapters,
@@ -57,6 +60,7 @@ import {
   validateCoverage,
   type CoverageAdapter,
   type CoverageCaptureContext,
+  type CoverageInventoryContext,
 } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
@@ -300,7 +304,6 @@ const BUN_BIN = "/usr/local/bin/bun";
 // (see base.rs::BASE_SETUP_SH). Bind-mounted into every service
 // container so apps can verify HTTPS to the daemon's fakes, and
 // referenced when we layer it into each image's system trust store.
-const CA_PATH = process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt";
 const CA_KEY_PATH = process.env.SPECTEST_CA_KEY_PATH ?? "/etc/spectest/ca.key";
 // Public roots ⧺ the spectest CA, materialized by `ensureCaBundle` and
 // bind-mounted into every container. `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`/
@@ -4124,7 +4127,62 @@ async function coverageRoot(service: string): Promise<string> {
   return root;
 }
 
-async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
+/** Budget for one service's inventory adapters, all of them. */
+const COVERAGE_INVENTORY_TIMEOUT_MS = 120_000;
+
+/**
+ * Run one service's `inventory` adapters and write the union as the
+ * `inventory.units` report — for the bring-up capture only: the
+ * inventory is a property of the environment, not of a case. The file
+ * is removed after the read so no later capture ships it again. A
+ * failure is the capture's error, like a failing `capture`.
+ */
+async function writeCoverageInventory(svc: NamedService): Promise<string | undefined> {
+  const adapters = coverageAdapters(svc.coverage).filter((a) => a.inventory);
+  if (adapters.length === 0) return undefined;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), COVERAGE_INVENTORY_TIMEOUT_MS);
+  const reportDir = coverageHostDir(WORKSPACE, svc.name);
+  const ctx: CoverageInventoryContext = {
+    service: svc.name,
+    signal: ac.signal,
+    async exec(command: string) {
+      const r = await docker(["exec", svc.name, "sh", "-c", command], COVERAGE_INVENTORY_TIMEOUT_MS);
+      if (r.code !== 0) {
+        const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
+        throw new Error(`${JSON.stringify(command)} exited ${r.code}${tail ? `\n${tail}` : ""}`);
+      }
+      return { stdout: r.stdout, stderr: r.stderr };
+    },
+    projectFiles: () => walkProjectFiles(WORKSPACE),
+    async readProjectFile(p: string) {
+      try {
+        return await fs.readFile(resolveProjectPath(p), "utf8");
+      } catch {
+        return null;
+      }
+    },
+  };
+  const units = new Set<string>();
+  try {
+    for (const a of adapters) {
+      try {
+        for (const u of await (a as Required<Pick<CoverageAdapter, "inventory">>).inventory(ctx)) units.add(u);
+      } catch (err) {
+        return `coverage adapter "${a.name}" on service "${svc.name}" inventory failed: ${err instanceof Error ? err.message : String(err)}`;
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+  const file = path.join(reportDir, INVENTORY_REPORT);
+  await fs.mkdir(reportDir, { recursive: true });
+  await fs.writeFile(file, [...units].sort().join("\n") + (units.size ? "\n" : ""));
+  console.log(`[coverage] ${svc.name}: inventory of ${units.size} unit(s)`);
+  return undefined;
+}
+
+async function captureServiceCoverage(baseline = false): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
   if (!l) return [];
   const byName = new Map<string, NamedService>();
@@ -4135,7 +4193,14 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
       const { error, deltaReports } = await runCoverageAdapters(svc);
       if (error) return { service: svc.name, reports: [], error };
+      if (baseline) {
+        const invError = await writeCoverageInventory(svc);
+        if (invError) return { service: svc.name, reports: [], error: invError };
+      }
       const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+      if (baseline) {
+        await fs.rm(path.join(coverageHostDir(WORKSPACE, svc.name), INVENTORY_REPORT), { force: true }).catch(() => {});
+      }
       const root = await coverageRoot(svc.name);
       if (root) read.root = root;
       // What ships is what ran during this capture, whatever the tool
@@ -6516,7 +6581,7 @@ export function harnessMethods(state: RouteState): MethodTable {
       // the control plane logs it.
       let coverage: CoverageBundleRef | undefined;
       try {
-        const captures = await captureServiceCoverage();
+        const captures = await captureServiceCoverage(true);
         for (const c of captures) {
           // After bring-up the code that started the service has run, so a
           // report set that names no file at all is a misconfigured tool —

package/src/environment-ca.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runContainerArgs } from "./harness/container-run.js";
+
+test("the CA is a plain PEM string when the environment definition is evaluated", () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-ca-"));
+  const caPath = join(dir, "ca.crt");
+  const pem = "-----BEGIN CERTIFICATE-----\npublic certificate\n-----END CERTIFICATE-----\n";
+  try {
+    writeFileSync(caPath, pem);
+    const result = Bun.spawnSync([process.execPath, "-e", `
+      import { defineEnvironment, ca } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+      const certificate = ca();
+      const env = defineEnvironment({ name: "test", services: { app: {
+        image: { type: "registry", reference: "test:latest" },
+        env: { CUSTOM_CA: certificate, LITERAL: "$(not a command)" },
+        files: [{ path: "/app/ca.pem", content: certificate }],
+      } } });
+      console.log(JSON.stringify(env.config.services.app));
+    `], { env: { ...process.env, SPECTEST_CA_PATH: caPath } });
+    expect(result.exitCode).toBe(0);
+    const svc = JSON.parse(result.stdout.toString());
+    expect(svc.env.CUSTOM_CA).toBe(pem);
+    expect(svc.files[0].content).toBe(pem);
+    const args = runContainerArgs({ svc: { name: "app", env: svc.env },
+      tag: "app", network: "test", hostCacheName: "spectest-host", caPath });
+    expect(args).toContain(`CUSTOM_CA=${pem}`);
+    expect(args).toContain("LITERAL=$(not a command)");
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("a missing environment CA fails at the call site with an actionable error", () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-ca-"));
+  try {
+    const result = Bun.spawnSync([process.execPath, "-e", `
+      import { ca } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+      ca();
+    `], { env: { ...process.env, SPECTEST_CA_PATH: join(dir, "missing.crt") } });
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stderr.toString()).toContain("run this code inside a Spectest environment");
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});