@specific.dev/spectest 0.82.0 → 0.85.0

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 }); }
+});

package/src/environment-ca.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+
+/** @internal Shared by certificate issuance, trust mounts and the public reader. */
+export const ENVIRONMENT_CA_PATH = process.env.SPECTEST_CA_PATH ?? "/etc/spectest/ca.crt";
+
+/** Read the environment's public CA certificate as a PEM string.
+ * The base VM creates it before importing the environment definition, so it
+ * can be used directly in service env, file contents or runtime client options.
+ * Normal TLS trust is automatic; use this only when explicit CA data is needed.
+ */
+export function ca(): string {
+  try {
+    return readFileSync(ENVIRONMENT_CA_PATH, "utf8");
+  } catch (cause) {
+    throw new Error(
+      `ca(): cannot read the environment CA at ${ENVIRONMENT_CA_PATH}; run this code inside a Spectest environment`,
+      { cause },
+    );
+  }
+}

package/src/harness/container-run.test.ts

@@ -91,13 +91,13 @@ describe("certificate trust", () => {
     expect(envOf(args, "NODE_EXTRA_CA_CERTS")).toBe("/etc/spectest/ca.crt");
   });
 
-  /** The load-bearing one. These three variables REPLACE the trust store,
+  /** The load-bearing one. These variables REPLACE the trust store,
    *  so handing them the bare CA leaves the container trusting spectest and
    *  no public root — Python requests and every AWS SDK then fail to verify
    *  real HTTPS, in any image. They must get the combined bundle. */
   test("the replacing variables get the bundle, never the bare CA", () => {
     const args = runContainerArgs(base({ caBundle: "/etc/spectest/ca-bundle.crt" }));
-    for (const name of ["SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "AWS_CA_BUNDLE"]) {
+    for (const name of ["SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "AWS_CA_BUNDLE", "PGSSLROOTCERT"]) {
       expect(envOf(args, name)).toBe("/etc/spectest/ca-bundle.crt");
       expect(envOf(args, name)).not.toBe("/etc/spectest/ca.crt");
     }
@@ -118,10 +118,22 @@ describe("certificate trust", () => {
     const args = runContainerArgs(base({ caBundle: null }));
     expect(envOf(args, "SSL_CERT_FILE")).toBeUndefined();
     expect(envOf(args, "AWS_CA_BUNDLE")).toBeUndefined();
+    expect(envOf(args, "PGSSLROOTCERT")).toBeUndefined();
     // The appending one is still safe to set on its own.
     expect(envOf(args, "NODE_EXTRA_CA_CERTS")).toBe("/etc/spectest/ca.crt");
   });
 
+  test("libpq gets trusted roots without forcing TLS, and may override them", () => {
+    const args = runContainerArgs(base({
+      caBundle: "/etc/spectest/ca-bundle.crt",
+      svc: { name: "web", env: { PGSSLROOTCERT: "/custom.pem" } },
+    }));
+    expect(envOf(args, "PGSSLMODE")).toBeUndefined();
+    expect(args.indexOf("PGSSLROOTCERT=/custom.pem")).toBeGreaterThan(
+      args.indexOf("PGSSLROOTCERT=/etc/spectest/ca-bundle.crt"),
+    );
+  });
+
   test("a bundle equal to the CA path is not mounted twice", () => {
     const args = runContainerArgs(base({ caBundle: "/etc/spectest/ca.crt" }));
     const mounts = args.filter((a) => a === "--volume=/etc/spectest/ca.crt:/etc/spectest/ca.crt:ro");

package/src/harness/container-run.ts

@@ -181,6 +181,9 @@ export function runContainerArgs(input: ContainerRunInput): string[] {
     args.push("-e", `SSL_CERT_FILE=${bundle}`);
     args.push("-e", `REQUESTS_CA_BUNDLE=${bundle}`);
     args.push("-e", `AWS_CA_BUNDLE=${bundle}`);
+    // libpq does not use the system trust store by default. Supply the
+    // same combined roots to psql/psycopg without changing their SSL mode.
+    args.push("-e", `PGSSLROOTCERT=${bundle}`);
     // The system store itself, for clients that read no variable at all.
     // Only a real bundle: the caller falls back to the bare CA when the
     // guest's roots are unreadable, and the bare CA over the system store

package/src/harness/coverage.test.ts

@@ -101,7 +101,7 @@ describe("readCoverageDir", () => {
     await fs.writeFile(path.join(dir, "coverage.json"), "{}");
     const r = await readCoverageDir("web", dir);
     expect(r.reports.length).toBe(1);
-    expect(r.error).toContain("none is an lcov report or a V8 coverage JSON document");
+    expect(r.error).toContain("none is an lcov report, a V8 coverage JSON document, or a `.units` list");
   });
 
   test("listReportFiles skips dotfiles", async () => {
@@ -138,6 +138,8 @@ import {
   renderLcovCounts,
   resetCoverageDeltaMemory,
   subtractLcovCounts,
+  isUnitsReport,
+  walkProjectFiles,
 } from "./coverage.js";
 
 describe("coverage delta", () => {
@@ -216,3 +218,32 @@ describe("coverage delta", () => {
     expect(err.error).toBe("x");
   });
 });
+
+describe("units reports", () => {
+  test("isUnitsReport: one scheme-prefixed id per line, blanks allowed, an empty file is a report", () => {
+    expect(isUnitsReport("npm:picocolors@1.1.1\nmanifest:packages/cli/package.json#3f9a1b2c\n")).toBe(true);
+    expect(isUnitsReport("")).toBe(true);
+    expect(isUnitsReport("\n\n")).toBe(true);
+    expect(isUnitsReport("picocolors\n")).toBe(false);
+    expect(isUnitsReport("npm:a b\n")).toBe(false);
+  });
+  test("readCoverageDir accepts a .units file beside lcov and rejects a malformed one", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-units-"));
+    await fs.writeFile(path.join(dir, "node.lcov"), "TN:\nSF:/app/a.js\nDA:1,1\nend_of_record\n");
+    await fs.writeFile(path.join(dir, "inventory.units"), "npm:a@1.0.0\n");
+    const ok = await readCoverageDir("api", dir);
+    expect(ok.error).toBeUndefined();
+    expect(ok.reports.map((r) => r.name)).toEqual(["inventory.units", "node.lcov"]);
+    await fs.writeFile(path.join(dir, "bad.units"), "no scheme here\n");
+    const bad = await readCoverageDir("api", dir);
+    expect(bad.error).toContain("bad.units");
+  });
+  test("walkProjectFiles lists project files and skips node_modules, .git and build output", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-walk-"));
+    for (const f of ["package.json", "packages/cli/package.json", "packages/cli/src/a.ts", "node_modules/x/package.json", ".git/HEAD", "packages/cli/dist/cli.js"]) {
+      await fs.mkdir(path.join(root, path.dirname(f)), { recursive: true });
+      await fs.writeFile(path.join(root, f), "x");
+    }
+    expect(await walkProjectFiles(root)).toEqual(["package.json", "packages/cli/package.json", "packages/cli/src/a.ts"]);
+  });
+});

package/src/harness/coverage.ts

@@ -108,9 +108,10 @@ export function isLcovShaped(text: string): boolean {
 
 /**
  * True when `text` looks like a V8 coverage JSON document — what
- * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
- * `result` array of scripts. A cheap shape check, not a parse (a report
- * can be megabytes); the control plane parses for real.
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write, and the shape the
+ * `node()` hook's dumps keep: an object with a `result` array of
+ * scripts. A cheap shape check, not a parse (a report can be
+ * megabytes); the control plane parses for real.
  */
 export function isV8CoverageJson(text: string): boolean {
   return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);
@@ -123,19 +124,56 @@ export function isSpectestScriptRecord(text: string): boolean {
   return /^\s*\{\s*"spectestScript"\s*:/.test(text);
 }
 
-/** True when `text` is a report spectest stores: lcov, V8 JSON, or a
- *  node() script record. */
-export function isWellFormedReport(text: string): boolean {
+/** True when `text` is a `.units` report: one unit id per non-blank
+ *  line, `<scheme>:<rest>` (`npm:picocolors@1.1.1`,
+ *  `manifest:packages/cli/package.json#3f9a…`). An empty file is a
+ *  report that names no unit. What a unit means is the adapter's; here
+ *  and on the control plane an id is an opaque string. */
+export function isUnitsReport(text: string): boolean {
+  return text.split(/\r?\n/).every((l) => l.trim().length === 0 || /^[a-z][a-z0-9+.-]*:\S+$/.test(l.trim()));
+}
+
+/** True when `text` is a report spectest stores: lcov, V8 JSON, a node()
+ *  script record, or (by name) a `.units` list. */
+export function isWellFormedReport(text: string, name = ""): boolean {
+  if (name.endsWith(".units")) return isUnitsReport(text);
   return isLcovShaped(text) || isV8CoverageJson(text) || isSpectestScriptRecord(text);
 }
 
 /** True when a well-formed report names no source file at all (an lcov
- *  with no `SF:`, a V8 document with an empty `result`). */
+ *  with no `SF:`, a V8 document with an empty `result`, a units list
+ *  with no unit). */
 export function isEmptyReport(text: string): boolean {
   if (isV8CoverageJson(text)) return /"result"\s*:\s*\[\s*\]/.test(text);
+  if (isSpectestScriptRecord(text)) return false;
+  if (isUnitsReport(text) && !isLcovShaped(text)) return text.trim().length === 0;
   return !hasLcovSourceFile(text);
 }
 
+/** Every regular file under `root`, recursively, as `/`-separated paths
+ *  relative to it, with the directories no project file lives in
+ *  skipped. The harness's project file list for an adapter's inventory. */
+export async function walkProjectFiles(root: string): Promise<string[]> {
+  const skip = new Set(["node_modules", ".git", ".spectest", "target", "__pycache__", ".venv", "dist", "build", ".next"]);
+  const out: string[] = [];
+  async function walk(d: string, rel: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (skip.has(e.name)) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) await walk(path.join(d, e.name), r);
+      else if (e.isFile()) out.push(r);
+    }
+  }
+  await walk(root, "");
+  return out.sort();
+}
+
 /** Every regular file under `dir`, recursively, as paths relative to it.
  *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
  *  a tmp file mid-write — is not a report). */
@@ -197,7 +235,7 @@ export async function readCoverageDir(
         error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — that is a runaway, not coverage`,
       };
     }
-    if (isWellFormedReport(content)) anyReport = true;
+    if (isWellFormedReport(content, name)) anyReport = true;
     else malformed.push(name);
     reports.push({ name, content });
   }
@@ -207,7 +245,7 @@ export async function readCoverageDir(
       reports,
       error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but ${
         anyReport ? `${malformed.slice(0, 5).join(", ")} ${malformed.length === 1 ? "is" : "are"} neither` : "none is"
-      } an lcov report or a V8 coverage JSON document — only those two formats are read`,
+      } an lcov report, a V8 coverage JSON document, or a \`.units\` list — only those are read`,
     };
   }
   return { service, reports };

package/src/index.ts

@@ -159,6 +159,7 @@ export {
 } from "./coverage.js";
 import { applyCoverageAdapters, validateCoverage, type ServiceCoverage } from "./coverage.js";
 import { resolveExistingProjectPath } from "./project-files.js";
+export { ca } from "./environment-ca.js";
 
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See