@specific.dev/spectest 0.58.0 → 0.59.1

package/dist/coverage.d.ts

@@ -0,0 +1,142 @@
+import type { ServiceConfig } from "./index.js";
+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 socket the node hook answers on, relative to the coverage dir. */
+export declare const NODE_COVERAGE_SOCKET = ".ctl";
+/** What `configure` learns about the service it rewrites. */
+export interface CoverageConfigureInfo {
+    /** The services-map key. */
+    key: string;
+}
+/** The harness capabilities an adapter can ask for at `/load`. */
+export interface CoverageLoadContext {
+    /** The services-map key. */
+    service: string;
+    /**
+     * Collect V8 coverage for every script the guest browser
+     * (`ctx.browser()` / `ctx.mobile()`) loads from this service's origins:
+     * its key, `<key>.internal`, its `hostnames`/`dnsName` aliases, its
+     * `tls`/`proxy` hostnames and any service-targeted wildcard. The
+     * harness maps each script back to source through the served source
+     * map and keeps per-service totals in memory (they fork with the
+     * environment). `browser()` calls this and writes the totals
+     * at capture.
+     */
+    collectBrowserScripts(): void;
+}
+/** What one adapter's `capture` runs against. */
+export interface CoverageCaptureContext {
+    /** The services-map key. */
+    service: string;
+    /**
+     * The coverage directory, seen from the harness. It is the same
+     * directory the container sees at `/spectest/coverage/` (a bind
+     * mount), so a file written here is in the container and a socket the
+     * container bound here is reachable.
+     */
+    reportDir: 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;
+    }>;
+    /** Write one report file (name relative to the directory). */
+    writeReport(name: string, content: string): Promise<void>;
+    /** Aborts when the per-service capture budget runs out. */
+    signal: AbortSignal;
+}
+export interface CoverageAdapter {
+    /** Names the adapter in errors (`coverage adapter "node" on service …`). */
+    name: string;
+    /**
+     * Rewrite the service at config time. Must be pure and deterministic
+     * (the result is hashed into the warm-template key) and must **append**
+     * to `env` values like `NODE_OPTIONS` rather than replace them.
+     */
+    configure?(service: ServiceConfig, info: CoverageConfigureInfo): ServiceConfig;
+    /** Ask the harness for capabilities, at `/load`. */
+    load?(ctx: CoverageLoadContext): void | Promise<void>;
+    /** Make the report appear in the directory. A throw fails the test. */
+    capture?(ctx: CoverageCaptureContext): void | Promise<void>;
+}
+/** `ServiceConfig.coverage`: the program writes its own reports, or a
+ *  list of adapters gets them out. */
+export type ServiceCoverage = true | {
+    adapters: readonly CoverageAdapter[];
+};
+/** Type an inline adapter. Identity at runtime. */
+export declare function defineAdapter(adapter: CoverageAdapter): CoverageAdapter;
+/** Check one service's `coverage` field. Exported so the daemon applies
+ *  the same rule to a runtime `startService` spec. */
+export declare function validateCoverage(service: string, cov: unknown): void;
+/** The adapters of a `coverage` value (`true` has none). */
+export declare function coverageAdapters(cov: ServiceCoverage | undefined): readonly CoverageAdapter[];
+/**
+ * Apply every adapter's `configure` to a service, in list order. Called by
+ * `defineEnvironment` (after group expansion, before validation) and by
+ * the daemon for a runtime `startService` spec. The adapter list stays on
+ * the returned config for the harness; on the wire it serializes as the
+ * adapter names (`toJSON`), never as functions.
+ */
+export declare function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S;
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export declare function appendEnvFlag(env: Readonly<Record<string, string>> | undefined, name: string, value: string): Record<string, string>;
+/**
+ * The hook `node()` mounts and `--require`s into every node
+ * process of the container. Node writes V8 coverage JSON into
+ * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
+ * exits, so the hook binds a Unix socket in the coverage directory and
+ * calls `v8.takeCoverage()` for each connection. The first process to
+ * start owns the socket (a stale socket left by a dead process is
+ * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
+ * alone and writes at its own exit. No signal is used: signals are
+ * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
+ * nodemon), a socket is nobody's.
+ */
+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 the long-lived server process for a dump at capture time. 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
+ * report, which is what maps a TypeScript service back to its sources.
+ */
+export declare function node(): CoverageAdapter;
+/** A script is the app's own when it is a file outside node_modules. */
+export declare function isAppScriptUrl(url: string): boolean;
+/**
+ * Compact one V8 coverage document to the app's own scripts. What Node
+ * writes is everything the process loaded: `node:` internals, every
+ * `node_modules` file, and — under `--enable-source-maps` — a
+ * `source-map-cache` with each file's full map **and its sources**,
+ * repeated in every dump. Measured on a real project: a 12–20 MiB dump
+ * per capture, of which the app's own coverage was under 0.5 MiB, and a
+ * suite that hit the 64 MiB cap on its third test. Kept: `file://`
+ * scripts outside `node_modules`, the map entries of exactly those
+ * scripts, minus `sourcesContent` (the sources are the repo). Still a V8
+ * document — nothing is converted.
+ */
+export declare function compactV8Document(doc: Record<string, unknown>): Record<string, unknown>;
+/** Compact every not-yet-compacted V8 document in `dir`, in place. */
+export declare function compactV8Reports(dir: string): Promise<void>;
+/**
+ * Coverage for the frontend a service serves. The code runs in the guest
+ * browser — spectest's own process — so no report can be written by the
+ * container; spectest collects V8 coverage for every script the browser
+ * loads from this service's origins, maps it back to source through the
+ * served source map, and writes one lcov per capture. Nothing ran yet on
+ * this branch ⇒ an lcov with no records, which is a report saying so.
+ */
+export declare function browser(): CoverageAdapter;
+/**
+ * Run `command` (via `sh -c`) in the container at every capture, so the
+ * service writes a fresh report into `/spectest/coverage/`. The escape
+ * hatch for a runtime with no shipped adapter.
+ */
+export declare function command(command: string): CoverageAdapter;

package/dist/coverage.js

@@ -0,0 +1,314 @@
+// Coverage adapters — how spectest gets a coverage report out of a service.
+//
+// A service opts in with `coverage: true` (the program writes its own
+// reports into `/spectest/coverage/`) or `coverage: { adapters: [...] }`
+// (spectest gets the reports out). An adapter has three optional moments:
+//
+//   configure  — config time, inside `defineEnvironment`. Rewrites the
+//                service (env, files, command). Pure: its output is part
+//                of the wire config and of the warm-template hash.
+//   load       — harness, at /load. Asks the harness for capabilities a
+//                container cannot supply itself (browser scripts).
+//   capture    — harness, after bring-up and after every test. Must leave
+//                a report in the directory.
+//
+// After every adapter ran, the harness reads the directory the same way
+// it does for `coverage: true`: at least one well-formed report (lcov or
+// V8 JSON), shipped verbatim. Adapters convert nothing — the control
+// plane derives what it needs from the stored bytes.
+//
+// Imported from `@specific.dev/spectest/coverage`. The three shipped
+// adapters: `node()` (V8 JSON through a hook spectest mounts), `browser()`
+// (scripts the guest browser loads from the service), `command(cmd)` (run
+// a command, then read). A project writes its own with `defineAdapter`.
+//
+//   import * as coverage from "@specific.dev/spectest/coverage";
+//   coverage: { adapters: [coverage.node(), coverage.browser()] }
+import { browserCoverageReports } from "./browser-coverage.js";
+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 socket the node hook answers on, relative to the coverage dir. */
+export const NODE_COVERAGE_SOCKET = ".ctl";
+/** Type an inline adapter. Identity at runtime. */
+export function defineAdapter(adapter) {
+    return adapter;
+}
+/** Check one service's `coverage` field. Exported so the daemon applies
+ *  the same rule to a runtime `startService` spec. */
+export function validateCoverage(service, cov) {
+    if (cov === undefined || cov === true)
+        return;
+    const adapters = cov?.adapters;
+    if (typeof cov === "object" && cov !== null && Array.isArray(adapters)) {
+        for (const a of adapters) {
+            const ok = typeof a === "object" &&
+                a !== null &&
+                typeof a.name === "string" &&
+                a.name.length > 0 &&
+                ["configure", "load", "capture"].every((k) => a[k] === undefined ||
+                    typeof a[k] === "function");
+            if (!ok) {
+                throw new Error(`service "${service}" has an invalid coverage adapter — an adapter is \`{ name, configure?, load?, capture? }\` (see \`defineAdapter\` in @specific.dev/spectest/coverage)`);
+            }
+        }
+        return;
+    }
+    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\` (the program writes its own reports) or \`{ adapters: [...] }\` from @specific.dev/spectest/coverage (\`node()\`, \`browser()\`, \`command("…")\`)`);
+}
+/** The adapters of a `coverage` value (`true` has none). */
+export function coverageAdapters(cov) {
+    return typeof cov === "object" && cov !== null ? cov.adapters : [];
+}
+/**
+ * Apply every adapter's `configure` to a service, in list order. Called by
+ * `defineEnvironment` (after group expansion, before validation) and by
+ * the daemon for a runtime `startService` spec. The adapter list stays on
+ * the returned config for the harness; on the wire it serializes as the
+ * adapter names (`toJSON`), never as functions.
+ */
+export function applyCoverageAdapters(key, svc) {
+    validateCoverage(key, svc.coverage);
+    const adapters = coverageAdapters(svc.coverage);
+    if (adapters.length === 0)
+        return svc;
+    let out = svc;
+    for (const a of adapters) {
+        if (a.configure)
+            out = a.configure(out, { key });
+    }
+    const wire = { adapters: adapters.map((a) => withWireName(a)) };
+    return { ...out, coverage: wire };
+}
+function withWireName(a) {
+    if (Object.prototype.hasOwnProperty.call(a, "toJSON"))
+        return a;
+    return Object.assign(Object.create(Object.getPrototypeOf(a)), a, {
+        toJSON: () => ({ adapter: a.name }),
+    });
+}
+/** `env` with `value` appended to `name` (space-separated), or set. */
+export function appendEnvFlag(env, name, value) {
+    const prior = env?.[name]?.trim();
+    return { ...env, [name]: prior ? `${prior} ${value}` : value };
+}
+// ── node ──────────────────────────────────────────────────────────
+/**
+ * The hook `node()` mounts and `--require`s into every node
+ * process of the container. Node writes V8 coverage JSON into
+ * `NODE_V8_COVERAGE` when a process exits; a long-lived server never
+ * exits, so the hook binds a Unix socket in the coverage directory and
+ * calls `v8.takeCoverage()` for each connection. The first process to
+ * start owns the socket (a stale socket left by a dead process is
+ * reclaimed); a later process — a CLI run by `ctx.exec` — leaves it
+ * alone and writes at its own exit. No signal is used: signals are
+ * claimed by frameworks (SIGUSR2 stops a Temporal worker, restarts
+ * nodemon), a socket is nobody's.
+ */
+export const NODE_COVERAGE_HOOK = `"use strict";
+// spectest coverage hook (coverage.node() adapter). See \`spectest docs /services/coverage\`.
+if (process.env.NODE_V8_COVERAGE) {
+  const net = require("node:net");
+  const fs = require("node:fs");
+  const v8 = require("node:v8");
+  const SOCK = require("node:path").join(process.env.NODE_V8_COVERAGE, ${JSON.stringify(NODE_COVERAGE_SOCKET)});
+  const server = net.createServer((conn) => {
+    // A dump is taken only on an explicit "dump" request: a bystander's
+    // liveness probe connects and closes without one.
+    let buf = "";
+    conn.on("data", (chunk) => {
+      buf += chunk;
+      if (!buf.includes("\\n")) return;
+      let reply;
+      try {
+        if (!buf.startsWith("dump")) throw new Error("unknown request");
+        v8.takeCoverage();
+        reply = "ok\\n";
+      } catch (err) {
+        reply = "error " + (err && err.message ? err.message : String(err)) + "\\n";
+      }
+      conn.end(reply);
+    });
+  });
+  server.unref();
+  server.on("error", (err) => {
+    if (err.code !== "EADDRINUSE") return;
+    // Someone holds the socket. If it answers, it is the live server and
+    // this process is a bystander; if not, it is a stale file.
+    const probe = net.connect(SOCK);
+    probe.on("connect", () => probe.destroy());
+    probe.on("error", () => {
+      try { fs.unlinkSync(SOCK); } catch {}
+      server.listen(SOCK);
+    });
+  });
+  server.listen(SOCK);
+}
+`;
+/**
+ * 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 the long-lived server process for a dump at capture time. 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
+ * report, which is what maps a TypeScript service back to its sources.
+ */
+export function node() {
+    return {
+        name: "node",
+        configure(svc) {
+            const env = appendEnvFlag(svc.env, "NODE_OPTIONS", `--require ${NODE_COVERAGE_HOOK_PATH}`);
+            env.NODE_V8_COVERAGE = COVERAGE_CONTAINER_DIR;
+            return {
+                ...svc,
+                env,
+                files: [...(svc.files ?? []), { path: NODE_COVERAGE_HOOK_PATH, content: NODE_COVERAGE_HOOK }],
+            };
+        },
+        async capture(ctx) {
+            const { connect } = await import("node:net");
+            const path = await import("node:path");
+            const sock = path.join(ctx.reportDir, NODE_COVERAGE_SOCKET);
+            const reply = await new Promise((resolve, reject) => {
+                const chunks = [];
+                const c = connect(sock, () => c.write("dump\n"));
+                const onAbort = () => {
+                    c.destroy();
+                    reject(new Error("timed out waiting for the node hook to write a report"));
+                };
+                ctx.signal.addEventListener("abort", onAbort, { once: true });
+                c.on("data", (b) => chunks.push(b));
+                c.on("error", (err) => {
+                    ctx.signal.removeEventListener("abort", onAbort);
+                    reject(new Error(err.code === "ENOENT" || err.code === "ECONNREFUSED"
+                        ? `no node process is serving ${COVERAGE_CONTAINER_DIR}/${NODE_COVERAGE_SOCKET} — is the service's main process node, and does it run with the service's env (NODE_OPTIONS)?`
+                        : err.message));
+                });
+                c.on("close", () => {
+                    ctx.signal.removeEventListener("abort", onAbort);
+                    resolve(Buffer.concat(chunks).toString("utf8").trim());
+                });
+            });
+            if (reply !== "ok")
+                throw new Error(`the node hook answered: ${reply || "(nothing)"}`);
+            await compactV8Reports(ctx.reportDir);
+        },
+    };
+}
+/** 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. */
+export function isAppScriptUrl(url) {
+    return url.startsWith("file://") && !url.includes("/node_modules/");
+}
+/**
+ * Compact one V8 coverage document to the app's own scripts. What Node
+ * writes is everything the process loaded: `node:` internals, every
+ * `node_modules` file, and — under `--enable-source-maps` — a
+ * `source-map-cache` with each file's full map **and its sources**,
+ * repeated in every dump. Measured on a real project: a 12–20 MiB dump
+ * per capture, of which the app's own coverage was under 0.5 MiB, and a
+ * suite that hit the 64 MiB cap on its third test. Kept: `file://`
+ * scripts outside `node_modules`, the map entries of exactly those
+ * scripts, minus `sourcesContent` (the sources are the repo). Still a V8
+ * document — nothing is converted.
+ */
+export function compactV8Document(doc) {
+    const result = Array.isArray(doc.result) ? doc.result : [];
+    const kept = result.filter((s) => typeof s.url === "string" && isAppScriptUrl(s.url));
+    const out = { ...doc, result: kept };
+    const cache = doc["source-map-cache"];
+    if (cache && typeof cache === "object") {
+        const urls = new Set(kept.map((s) => s.url));
+        const slim = {};
+        for (const [url, entry] of Object.entries(cache)) {
+            if (!urls.has(url) || !entry || typeof entry !== "object")
+                continue;
+            const e = { ...entry };
+            if (e.data && typeof e.data === "object") {
+                const { sourcesContent: _dropped, ...data } = e.data;
+                e.data = data;
+            }
+            slim[url] = e;
+        }
+        if (Object.keys(slim).length > 0)
+            out["source-map-cache"] = slim;
+        else
+            delete out["source-map-cache"];
+    }
+    return out;
+}
+/** Compact every not-yet-compacted V8 document in `dir`, in place. */
+export async function compactV8Reports(dir) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith("coverage-") || !name.endsWith(".json"))
+            continue;
+        const file = path.join(dir, name);
+        if (COMPACTED_V8_REPORTS.has(file))
+            continue;
+        let doc;
+        try {
+            doc = JSON.parse(await fs.readFile(file, "utf8"));
+        }
+        catch {
+            continue; // a dump mid-write, or not ours; the read path judges it
+        }
+        if (!Array.isArray(doc.result))
+            continue;
+        const tmp = path.join(dir, `.${name}.compact`);
+        await fs.writeFile(tmp, JSON.stringify(compactV8Document(doc)));
+        await fs.rename(tmp, file);
+        COMPACTED_V8_REPORTS.add(file);
+    }
+}
+// ── browser ───────────────────────────────────────────────────────
+/**
+ * Coverage for the frontend a service serves. The code runs in the guest
+ * browser — spectest's own process — so no report can be written by the
+ * container; spectest collects V8 coverage for every script the browser
+ * loads from this service's origins, maps it back to source through the
+ * served source map, and writes one lcov per capture. Nothing ran yet on
+ * this branch ⇒ an lcov with no records, which is a report saying so.
+ */
+export function browser() {
+    return {
+        name: "browser",
+        load(ctx) {
+            ctx.collectBrowserScripts();
+        },
+        async capture(ctx) {
+            const lcov = browserCoverageReports().get(ctx.service) ?? "TN:\n";
+            await ctx.writeReport("browser.lcov", lcov);
+        },
+    };
+}
+// ── command ───────────────────────────────────────────────────────
+/**
+ * Run `command` (via `sh -c`) in the container at every capture, so the
+ * service writes a fresh report into `/spectest/coverage/`. The escape
+ * hatch for a runtime with no shipped adapter.
+ */
+export function command(command) {
+    if (typeof command !== "string" || command.trim().length === 0) {
+        throw new Error("coverage.command: `command` must be a non-empty shell command");
+    }
+    return {
+        name: "command",
+        async capture(ctx) {
+            await ctx.exec(command);
+        },
+    };
+}