@specific.dev/spectest 0.59.2 → 0.59.3

package/dist/coverage.d.ts

@@ -3,6 +3,8 @@ import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
 export declare const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
+/** The report `node()` writes when nothing has run yet on a branch. */
+export declare const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export declare const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
@@ -102,11 +104,13 @@ export declare function appendEnvFlag(env: Readonly<Record<string, string>> | un
  */
 export declare const NODE_COVERAGE_HOOK: string;
 /**
- * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
- * directory (every node process in the container then writes V8
- * coverage JSON when it exits) and `--require`s a hook that lets spectest
- * ask every live node process for a dump at capture time — the server,
- * and any wrapper it sits behind (`pnpm exec`, `tsx`). Nothing
+ * Coverage for a Node service — a long-lived server, or a container whose
+ * node processes are short-lived CLIs run by `ctx.exec`. Sets
+ * `NODE_V8_COVERAGE` to the coverage directory (every node process in the
+ * container then writes V8 coverage JSON when it exits) and `--require`s
+ * a hook that lets spectest ask every live node process for a dump at
+ * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
+ * `tsx`). Nothing
  * for the app to write. Each dump is compacted to the app's own scripts
  * at capture ({@link compactV8Document}). Source maps: with `--enable-source-maps` (or a
  * `sourceMappingURL` next to the file) Node records the map in the
@@ -120,7 +124,8 @@ export declare function node(): CoverageAdapter;
  * answered with an error throws.
  */
 export declare function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number>;
-/** A script is the app's own when it is a file outside node_modules. */
+/** 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 declare function isAppScriptUrl(url: string): boolean;
 /**
  * Compact one V8 coverage document to the app's own scripts. What Node

package/dist/coverage.js

@@ -29,6 +29,8 @@ import { COVERAGE_CONTAINER_DIR } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
+/** The report `node()` writes when nothing has run yet on a branch. */
+export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
@@ -142,11 +144,13 @@ if (process.env.NODE_V8_COVERAGE) {
 }
 `;
 /**
- * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
- * directory (every node process in the container then writes V8
- * coverage JSON when it exits) and `--require`s a hook that lets spectest
- * ask every live node process for a dump at capture time — the server,
- * and any wrapper it sits behind (`pnpm exec`, `tsx`). Nothing
+ * Coverage for a Node service — a long-lived server, or a container whose
+ * node processes are short-lived CLIs run by `ctx.exec`. Sets
+ * `NODE_V8_COVERAGE` to the coverage directory (every node process in the
+ * container then writes V8 coverage JSON when it exits) and `--require`s
+ * a hook that lets spectest ask every live node process for a dump at
+ * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
+ * `tsx`). Nothing
  * for the app to write. Each dump is compacted to the app's own scripts
  * at capture ({@link compactV8Document}). Source maps: with `--enable-source-maps` (or a
  * `sourceMappingURL` next to the file) Node records the map in the
@@ -165,11 +169,20 @@ export function node() {
             };
         },
         async capture(ctx) {
-            const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
-            if (live === 0) {
-                throw new Error(`no node process is serving a ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET_PREFIX}<pid> socket — does the service run node with the service's env (NODE_OPTIONS), and is it still alive?`);
-            }
+            // Two shapes, one adapter: a long-lived server answers its socket
+            // here; a service whose node processes are short-lived (a CLI run
+            // by `ctx.exec` from a `sleep infinity` container) has no socket to
+            // answer and its coverage is the exit-time dumps already on disk.
+            // So no live process is not an error. No report at all — nothing
+            // has run yet on this branch — is recorded as an empty document
+            // 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);
             await compactV8Reports(ctx.reportDir);
+            if (!(await hasV8Reports(ctx.reportDir))) {
+                await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
+            }
         },
     };
 }
@@ -227,12 +240,26 @@ export async function dumpAllNodeProcesses(dir, signal) {
     }
     return live;
 }
+/** True when `dir` holds at least one `coverage-*.json` other than the
+ *  empty placeholder. */
+async function hasV8Reports(dir) {
+    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;
+    }
+}
 /** 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();
-/** A script is the app's own when it is a file outside node_modules. */
+/** 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) {
-    return url.startsWith("file://") && !url.includes("/node_modules/");
+    return (url.startsWith("file://") &&
+        !url.includes("/node_modules/") &&
+        !url.endsWith("/" + NODE_COVERAGE_HOOK_PATH.split("/").pop()));
 }
 /**
  * Compact one V8 coverage document to the app's own scripts. What Node

package/package.json

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

package/src/coverage.test.ts

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import {
   NODE_COVERAGE_HOOK,
+  NODE_COVERAGE_EMPTY_REPORT,
   NODE_COVERAGE_HOOK_PATH,
   NODE_COVERAGE_SOCKET_PREFIX,
   applyCoverageAdapters,
@@ -157,7 +158,7 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     return (await fs.readdir(dir)).filter((n) => n.startsWith(NODE_COVERAGE_SOCKET_PREFIX)).sort();
   }
   async function reportsIn(dir: string): Promise<string[]> {
-    return (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-"));
+    return (await fs.readdir(dir)).filter((n) => n.startsWith("coverage-") && n.endsWith(".json"));
   }
   async function start(dir: string, entry: string, expectSockets: number): Promise<ChildProcess> {
     const hook = path.join(dir, "hook.cjs");
@@ -231,25 +232,51 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     }
   });
 
+  test("short-lived CLI processes: exit dumps are the coverage, no live process needed", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
+    const hook = path.join(dir, "coverage-hook.cjs");
+    await fs.writeFile(hook, NODE_COVERAGE_HOOK);
+    await fs.writeFile(path.join(dir, "cli.js"), "process.stdout.write('v1');\n");
+    // Nothing has run yet: an empty report, not a failure.
+    await node().capture!(fakeCtx(dir));
+    expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
+    // Two CLI runs, each its own process, each dumping at exit.
+    for (let i = 0; i < 2; i++) {
+      const cli = spawn("node", [path.join(dir, "cli.js")], {
+        env: { ...process.env, NODE_V8_COVERAGE: dir, NODE_OPTIONS: `--require ${hook}` },
+        stdio: "ignore",
+      });
+      expect(await new Promise<number | null>((r) => cli.on("exit", r))).toBe(0);
+    }
+    expect((await socketsIn(dir)).length).toBe(0);
+    await node().capture!(fakeCtx(dir));
+    const reports = (await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT);
+    expect(reports.length).toBe(2);
+    const doc = JSON.parse(await fs.readFile(path.join(dir, reports[0]!), "utf8")) as { result: { url: string }[] };
+    expect(doc.result.map((x) => x.url)).toEqual([`file://${path.join(dir, "cli.js")}`]); // compacted
+  });
+
   test("a stale socket left by a killed process is removed at capture", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
     const first = await start(dir, "server.js", 1);
     first.kill("SIGKILL");
     await new Promise<void>((resolve) => first.on("exit", () => resolve()));
     expect((await socketsIn(dir)).length).toBe(1); // stale
-    await expect(node().capture!(fakeCtx(dir))).rejects.toThrow(/no node process is serving/);
+    await node().capture!(fakeCtx(dir));
     expect((await socketsIn(dir)).length).toBe(0); // cleaned up
     const second = await start(dir, "server.js", 1);
     try {
       await node().capture!(fakeCtx(dir));
-      expect((await reportsIn(dir)).length).toBe(1);
+      expect((await reportsIn(dir)).filter((n) => n !== NODE_COVERAGE_EMPTY_REPORT).length).toBe(1);
     } finally {
       second.kill("SIGKILL");
     }
   });
 
-  test("no server: capture fails naming the socket", async () => {
+  test("no process and no dump: an empty report is written, once", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
-    await expect(node().capture!(fakeCtx(dir))).rejects.toThrow(/no node process is serving/);
+    await node().capture!(fakeCtx(dir));
+    await node().capture!(fakeCtx(dir));
+    expect(await reportsIn(dir)).toEqual([NODE_COVERAGE_EMPTY_REPORT]);
   });
 });

package/src/coverage.ts

@@ -34,6 +34,9 @@ export { COVERAGE_CONTAINER_DIR };
 /** Where `node()` mounts its hook inside the container. */
 export const NODE_COVERAGE_HOOK_PATH = "/spectest/coverage-hook.cjs";
 
+/** The report `node()` writes when nothing has run yet on a branch. */
+export const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json";
+
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
@@ -226,11 +229,13 @@ if (process.env.NODE_V8_COVERAGE) {
 `;
 
 /**
- * Coverage for a Node service. Sets `NODE_V8_COVERAGE` to the coverage
- * directory (every node process in the container then writes V8
- * coverage JSON when it exits) and `--require`s a hook that lets spectest
- * ask every live node process for a dump at capture time — the server,
- * and any wrapper it sits behind (`pnpm exec`, `tsx`). Nothing
+ * Coverage for a Node service — a long-lived server, or a container whose
+ * node processes are short-lived CLIs run by `ctx.exec`. Sets
+ * `NODE_V8_COVERAGE` to the coverage directory (every node process in the
+ * container then writes V8 coverage JSON when it exits) and `--require`s
+ * a hook that lets spectest ask every live node process for a dump at
+ * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
+ * `tsx`). Nothing
  * for the app to write. Each dump is compacted to the app's own scripts
  * at capture ({@link compactV8Document}). Source maps: with `--enable-source-maps` (or a
  * `sourceMappingURL` next to the file) Node records the map in the
@@ -249,13 +254,20 @@ export function node(): CoverageAdapter {
       };
     },
     async capture(ctx) {
-      const live = await dumpAllNodeProcesses(ctx.reportDir, ctx.signal);
-      if (live === 0) {
-        throw new Error(
-          `no node process is serving a ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET_PREFIX}<pid> socket — does the service run node with the service's env (NODE_OPTIONS), and is it still alive?`,
-        );
-      }
+      // Two shapes, one adapter: a long-lived server answers its socket
+      // here; a service whose node processes are short-lived (a CLI run
+      // by `ctx.exec` from a `sleep infinity` container) has no socket to
+      // answer and its coverage is the exit-time dumps already on disk.
+      // So no live process is not an error. No report at all — nothing
+      // has run yet on this branch — is recorded as an empty document
+      // 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);
       await compactV8Reports(ctx.reportDir);
+      if (!(await hasV8Reports(ctx.reportDir))) {
+        await ctx.writeReport(NODE_COVERAGE_EMPTY_REPORT, '{"result":[]}\n');
+      }
     },
   };
 }
@@ -310,13 +322,31 @@ 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> {
+  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;
+  }
+}
+
 /** 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. */
+/** 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 {
-  return url.startsWith("file://") && !url.includes("/node_modules/");
+  return (
+    url.startsWith("file://") &&
+    !url.includes("/node_modules/") &&
+    !url.endsWith("/" + NODE_COVERAGE_HOOK_PATH.split("/").pop())
+  );
 }
 
 /**