@specific.dev/spectest 0.56.2 → 0.58.0

package/dist/harness/browser-coverage.js

@@ -0,0 +1,257 @@
+// Browser coverage — the pure part.
+//
+// A frontend runs in the guest Chromium, which is spectest's own process,
+// so the user cannot write a coverage report for it the way a service
+// process can. A service declares `coverage: { browser: true }` and
+// spectest collects it: V8 precise coverage over CDP for every script the
+// browser loads from that service, mapped back to original sources
+// through the served source maps, and written as one lcov report per
+// service into the same `case-coverage` bundle the container path uses.
+//
+// This module has no CDP in it: source-map decoding, V8 range → line
+// counts, host → service attribution, lcov output. The collector that
+// talks to the page is `../browser-coverage.ts`.
+// ── V8 precise coverage → generated line counts ─────────────────────────
+/** Byte offset at which each line starts. */
+export function lineStartsOf(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source.charCodeAt(i) === 10)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 1-based line holding `offset`. */
+export function lineOf(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}
+/**
+ * Fold a script's block ranges onto its lines. Ranges come outer-first
+ * and a narrower range overrides the lines it spans, so a line inside an
+ * unexecuted branch ends at 0 even though its enclosing function ran.
+ * Blank lines are dropped. Approximate — a line holding two blocks gets
+ * the narrower one's count — which is exact at the file level, the only
+ * level anything reads today.
+ */
+export function rangesToLineCounts(source, functions) {
+    const starts = lineStartsOf(source);
+    const counts = new Map();
+    for (const fn of functions) {
+        for (const r of fn.ranges) {
+            const a = lineOf(starts, r.startOffset);
+            const b = lineOf(starts, Math.max(r.startOffset, r.endOffset - 1));
+            for (let l = a; l <= b; l++)
+                counts.set(l, r.count);
+        }
+    }
+    for (const l of [...counts.keys()]) {
+        const text = source.slice(starts[l - 1], starts[l] ?? source.length);
+        if (text.trim().length === 0)
+            counts.delete(l);
+    }
+    return counts;
+}
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_INDEX = new Map([...B64].map((c, i) => [c, i]));
+/** Decode one VLQ-encoded segment into its fields. */
+export function decodeVlq(segment) {
+    const out = [];
+    let value = 0;
+    let shift = 0;
+    for (const ch of segment) {
+        const digit = B64_INDEX.get(ch);
+        if (digit === undefined)
+            throw new Error(`bad VLQ char ${JSON.stringify(ch)}`);
+        value += (digit & 31) << shift;
+        if (digit & 32) {
+            shift += 5;
+        }
+        else {
+            const negative = value & 1;
+            value >>>= 1;
+            out.push(negative ? -value : value);
+            value = 0;
+            shift = 0;
+        }
+    }
+    return out;
+}
+/**
+ * Normalise a source-map `sources` entry to a plain path. Bundlers prefix
+ * their own scheme (`webpack:///./src/a.ts`), dev servers serve absolute
+ * URLs paths (`/src/a.ts`), builds write relative ones (`../src/a.ts`).
+ * The server maps these onto the repo by suffix, so all that matters here
+ * is stripping what is not a path.
+ */
+export function normalizeSourcePath(src, sourceRoot) {
+    let s = src;
+    if (sourceRoot && !/^[a-z]+:/i.test(s)) {
+        s = sourceRoot.replace(/\/?$/, "/") + s;
+    }
+    s = s.replace(/^webpack:\/\/\/?/, "").replace(/^file:\/\//, "");
+    // A URL (`http://host/src/a.ts`, Vite's `/@fs/…`) keeps only its path.
+    const m = /^[a-z]+:\/\/[^/]*(\/.*)$/i.exec(s);
+    if (m)
+        s = m[1];
+    s = s.replace(/^\/@fs\//, "/");
+    s = s.replace(/\?.*$/, "");
+    while (s.startsWith("./"))
+        s = s.slice(2);
+    return s;
+}
+/** Sources nobody's change can be attributed to: dependencies and bundler
+ *  runtime shims. */
+export function isForeignSource(path) {
+    return (path.length === 0 ||
+        path.includes("node_modules/") ||
+        path.startsWith("webpack/") ||
+        path.startsWith("(webpack)") ||
+        path.startsWith("\0") ||
+        path.startsWith("vite/") ||
+        path.startsWith("@vite/"));
+}
+/**
+ * Decode a source map document. Index maps (`sections`) are not
+ * supported and decode to `null`, as does anything malformed — the
+ * caller then falls back to attributing the script to its own URL, which
+ * the repo mapping cannot resolve, which is the safe answer.
+ */
+export function decodeSourceMap(doc) {
+    if (!doc || typeof doc !== "object")
+        return null;
+    const m = doc;
+    if (m.sections || !Array.isArray(m.sources) || typeof m.mappings !== "string") {
+        return null;
+    }
+    const sourceRoot = typeof m.sourceRoot === "string" ? m.sourceRoot : undefined;
+    const sources = m.sources.map((s) => typeof s === "string" ? normalizeSourcePath(s, sourceRoot) : "");
+    const lines = [];
+    let src = 0;
+    let line = 0;
+    try {
+        for (const group of m.mappings.split(";")) {
+            const segs = [];
+            let col = 0;
+            if (group.length > 0) {
+                for (const seg of group.split(",")) {
+                    if (seg.length === 0)
+                        continue;
+                    const f = decodeVlq(seg);
+                    col += f[0];
+                    if (f.length >= 4) {
+                        src += f[1];
+                        line += f[2];
+                        segs.push({ col, src, line });
+                    }
+                }
+            }
+            lines.push(segs);
+        }
+    }
+    catch {
+        return null;
+    }
+    return { sources, lines };
+}
+/**
+ * Attribute generated line counts to original (file, line)s through the
+ * map. Every original line a generated line's segments name gets that
+ * line's count (max over the generated lines that touch it). Foreign
+ * sources are dropped.
+ */
+export function mapToOriginal(map, generated) {
+    const out = new Map();
+    for (const [genLine, count] of generated) {
+        const segs = map.lines[genLine - 1];
+        if (!segs || segs.length === 0)
+            continue;
+        for (const seg of segs) {
+            const file = map.sources[seg.src];
+            if (file === undefined || isForeignSource(file))
+                continue;
+            let lc = out.get(file);
+            if (!lc) {
+                lc = new Map();
+                out.set(file, lc);
+            }
+            const l = seg.line + 1;
+            lc.set(l, Math.max(lc.get(l) ?? 0, count));
+        }
+    }
+    return out;
+}
+// ── Accumulation + lcov ─────────────────────────────────────────────────
+/** Add `from` into `into` (sums — takes reset V8's counters). */
+export function mergeLineCounts(into, from) {
+    for (const [l, c] of from)
+        into.set(l, (into.get(l) ?? 0) + c);
+}
+export function mergeFileCounts(into, from) {
+    for (const [file, counts] of from) {
+        let target = into.get(file);
+        if (!target) {
+            target = new Map();
+            into.set(file, target);
+        }
+        mergeLineCounts(target, counts);
+    }
+}
+/** One lcov document for a set of files. */
+export function lcovDocument(files) {
+    let out = "TN:\n";
+    for (const [file, counts] of [...files].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        out += `SF:${file}\n`;
+        let found = 0;
+        let hit = 0;
+        for (const [l, c] of [...counts].sort((a, b) => a[0] - b[0])) {
+            out += `DA:${l},${c}\n`;
+            found++;
+            if (c > 0)
+                hit++;
+        }
+        out += `LF:${found}\nLH:${hit}\nend_of_record\n`;
+    }
+    return out;
+}
+/**
+ * Which service a script URL's host belongs to: the service key itself,
+ * `<key>.internal`, its `hostnames`/`dnsName` aliases, a `tls`/`proxy`
+ * hostname routed to it, or a wildcard pointed at it. Exact first, then
+ * the longest wildcard suffix — the resolver's own precedence.
+ */
+export function serviceForHost(host, services, table) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    for (const s of services) {
+        if (h === s.toLowerCase() || h === `${s.toLowerCase()}.internal`)
+            return s;
+    }
+    for (const [svc, aliases] of Object.entries(table.aliasesByService)) {
+        if (aliases.some((a) => a.toLowerCase() === h))
+            return svc;
+    }
+    for (const p of table.proxies) {
+        if (p.hostname.toLowerCase() === h)
+            return p.service;
+    }
+    let best;
+    for (const w of table.wildcards) {
+        const service = w.target.service;
+        if (!service)
+            continue;
+        const suffix = w.pattern.toLowerCase().replace(/^\*/, "");
+        if (h.endsWith(suffix) && h.length > suffix.length) {
+            if (!best || suffix.length > best.len)
+                best = { len: suffix.length, service };
+        }
+    }
+    return best?.service;
+}

package/dist/harness/coverage.d.ts

@@ -0,0 +1,60 @@
+/** Where the directory is mounted inside an opted-in container. */
+export declare const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
+/** Raw bytes of reports one service may ship per capture. Reports are
+ *  cumulative and bounded by code size, so anything past this is a
+ *  runaway (a tool writing a new file per request), not coverage. */
+export declare const COVERAGE_MAX_BYTES_PER_SERVICE: number;
+/** Root of the per-service host directories, under the workspace so the
+ *  delta-restore teardown wipes them with everything else. */
+export declare function coverageHostDir(workspace: string, service: string): string;
+/** One report file, verbatim. `name` is its path relative to the
+ *  coverage directory. */
+export interface CoverageReport {
+    name: string;
+    content: string;
+}
+/** One service's capture: every report in its directory, verbatim. */
+export interface ServiceCoverageCapture {
+    service: string;
+    reports: CoverageReport[];
+    /** Set when the capture failed: the command failed, the directory was
+     *  empty, no file held an `SF:` record, or the reports were too large.
+     *  A case with an error here fails — a hole in the coverage data must
+     *  never be silent. */
+    error?: string;
+}
+/** The small ref that rides the `run` reply in place of the bundle. */
+export interface CoverageBundleRef {
+    /** Gzipped bundle size; the control plane pulls exactly this many bytes
+     *  through `coverageChunk`. */
+    bytes: number;
+    services: {
+        service: string;
+        reports: number;
+        /** Raw (uncompressed) bytes of this service's reports. */
+        bytes: number;
+        error?: string;
+    }[];
+}
+/** The gzipped JSON document `coverageChunk` serves. Mirrors
+ *  `storage::CaseCoverageBundle` on the server. */
+export interface CoverageBundle {
+    caseId: string;
+    services: ServiceCoverageCapture[];
+}
+/** True when `text` holds at least one lcov `SF:` record. */
+export declare function hasLcovSourceFile(text: string): boolean;
+/** 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). */
+export declare function listReportFiles(dir: string): Promise<string[]>;
+/**
+ * Read every report under `dir`, verbatim. An empty directory, or one with
+ * no `SF:` record anywhere, is an error rather than an empty capture: the
+ * contract is that an opted-in service always has a report to read.
+ */
+export declare function readCoverageDir(service: string, dir: string): Promise<ServiceCoverageCapture>;
+/** Gzip a case's captures into the bundle `coverageChunk` serves. */
+export declare function encodeCoverageBundle(caseId: string, services: ServiceCoverageCapture[]): Buffer;
+/** The ref for a bundle: its size plus a per-service summary. */
+export declare function coverageBundleRef(gz: Buffer, services: ServiceCoverageCapture[]): CoverageBundleRef;

package/dist/harness/coverage.js

@@ -0,0 +1,122 @@
+// Coverage collection — the pure part.
+//
+// A service that opts in (`coverage: true | { command }`) gets a writable
+// directory bind-mounted at `/spectest/coverage/` in its container. The
+// service's own tool writes lcov reports there. The daemon reads the
+// directory from the VM side (no `docker exec` to fetch) after bring-up
+// and after each test, and ships the reports **verbatim** to the control
+// plane as a gzipped bundle. Nothing is interpreted here beyond the one
+// contract the harness must fail a case on: at least one report, and at
+// least one lcov `SF:` record among them. The server derives whatever it
+// needs (today the set of source files; later, finer things) from the
+// stored bytes, so a change in that derivation is a re-read of stored
+// runs, never a hole in the history.
+//
+// The container side (mount flag, `command` exec) is in `daemon.ts`.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+/** Where the directory is mounted inside an opted-in container. */
+export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
+/** Raw bytes of reports one service may ship per capture. Reports are
+ *  cumulative and bounded by code size, so anything past this is a
+ *  runaway (a tool writing a new file per request), not coverage. */
+export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
+/** Root of the per-service host directories, under the workspace so the
+ *  delta-restore teardown wipes them with everything else. */
+export function coverageHostDir(workspace, service) {
+    return path.join(workspace, ".spectest", "coverage", service);
+}
+/** True when `text` holds at least one lcov `SF:` record. */
+export function hasLcovSourceFile(text) {
+    return /^SF:\S/m.test(text);
+}
+/** 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). */
+export async function listReportFiles(dir) {
+    const out = [];
+    async function walk(d, rel) {
+        let entries;
+        try {
+            entries = await fs.readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith("."))
+                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(dir, "");
+    return out.sort();
+}
+/**
+ * Read every report under `dir`, verbatim. An empty directory, or one with
+ * no `SF:` record anywhere, is an error rather than an empty capture: the
+ * contract is that an opted-in service always has a report to read.
+ */
+export async function readCoverageDir(service, dir) {
+    const names = await listReportFiles(dir);
+    if (names.length === 0) {
+        return {
+            service,
+            reports: [],
+            error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov file there`,
+        };
+    }
+    const reports = [];
+    let total = 0;
+    let anyLcov = false;
+    for (const name of names) {
+        let content;
+        try {
+            content = await fs.readFile(path.join(dir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        total += content.length;
+        if (total > COVERAGE_MAX_BYTES_PER_SERVICE) {
+            return {
+                service,
+                reports: [],
+                error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — reports must be cumulative, not one file per dump`,
+            };
+        }
+        if (hasLcovSourceFile(content))
+            anyLcov = true;
+        reports.push({ name, content });
+    }
+    if (!anyLcov) {
+        return {
+            service,
+            reports,
+            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but none holds an lcov \`SF:\` record — only lcov reports are read`,
+        };
+    }
+    return { service, reports };
+}
+/** Gzip a case's captures into the bundle `coverageChunk` serves. */
+export function encodeCoverageBundle(caseId, services) {
+    const doc = { caseId, services };
+    return gzipSync(Buffer.from(JSON.stringify(doc)));
+}
+/** The ref for a bundle: its size plus a per-service summary. */
+export function coverageBundleRef(gz, services) {
+    return {
+        bytes: gz.length,
+        services: services.map((s) => ({
+            service: s.service,
+            reports: s.reports.length,
+            bytes: s.reports.reduce((n, r) => n + r.content.length, 0),
+            ...(s.error ? { error: s.error } : {}),
+        })),
+    };
+}

package/dist/index.d.ts

@@ -115,6 +115,27 @@ export interface ServiceConfig {
     tls?: readonly ServiceTls[];
     /** Bind-mounted volumes for state that survives snapshot/fork. */
     volumes?: readonly VolumeMount[];
+    /**
+     * Opt this service in to **code coverage collection** (experimental).
+     *
+     * The service gets a writable directory bind-mounted at
+     * `/spectest/coverage/`. The service's own coverage tool writes **lcov**
+     * reports there — cumulative from process start, never reset. After
+     * bring-up and after every test, spectest runs `command` (if given) inside
+     * the container, then reads every file in the directory and records the
+     * set of source files that ran. Only the `SF:` records are read.
+     *
+     * - `true`: the service writes its reports by itself (a dump on a timer,
+     *   an exit-time dump for short-lived processes).
+     * - `{ command }`: run this (via `sh -c`) in the container to make the
+     *   service write a report, before the directory is read.
+     *
+     * The directory must hold at least one lcov report each time it is read;
+     * an empty directory or a failed command fails the test with a clear
+     * error, so a hole in the coverage data is never silent. See
+     * `spectest docs /services/coverage`.
+     */
+    coverage?: ServiceCoverage;
     /**
      * Files seeded into the container's filesystem **before it starts**.
      * Each entry's `content` is written to a VM-host staging path and
@@ -642,6 +663,29 @@ export type ServiceImage = {
     /** Extra glob patterns to exclude from the build context. */
     exclude?: readonly string[];
 };
+/**
+ * A service's opt-in to coverage collection — see `ServiceConfig.coverage`.
+ * `true` when the service writes its own reports; `{ command }` when
+ * spectest must run a command in the container to produce one.
+ */
+export type ServiceCoverage = true | {
+    /** Run this (via `sh -c`) in the container before the coverage
+     *  directory is read, so the service writes a fresh lcov report. */
+    command?: string;
+    /**
+     * Collect **frontend** coverage for the app this service serves.
+     * The code runs in the guest browser — spectest's own process — so
+     * the user cannot write a report for it: spectest turns on V8
+     * coverage for every script `ctx.browser()`/`ctx.mobile()` loads
+     * from this service's origin, maps it back to original sources
+     * through the served source maps, and adds one lcov report to this
+     * service's capture. Scripts a source map can't resolve are
+     * attributed to their served path (which the repo mapping then
+     * treats as unknown — the safe answer). Needs the app to serve
+     * source maps to the test environment.
+     */
+    browser?: boolean;
+};
 export interface VolumeMount {
     /**
      * Named shared volume. Two services mounting the same `name` share one
@@ -854,6 +898,17 @@ export interface FakeContext {
      *  for a TLS-provisioning provider hands back to the app under test. */
     certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
 }
+/**
+ * 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;
+/** Whether a `coverage` value collects reports from the container's own
+ *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
+ *  any object that isn't browser-only. */
+export declare function coverageUsesContainer(cov: ServiceCoverage | undefined): boolean;
+/** Whether a `coverage` value collects frontend (browser) coverage. */
+export declare function coverageUsesBrowser(cov: ServiceCoverage | undefined): boolean;
 /**
  * A single test step. Created via `test(...)` or `createTest(services)`.
  * Tests are referenced (not named by string) when one test depends on

package/dist/index.js

@@ -215,6 +215,37 @@ function expandServiceGroups(input) {
     }
     return out;
 }
+/**
+ * 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;
+    if (typeof cov === "object" && cov !== null) {
+        const o = cov;
+        const cmdOk = o.command === undefined ||
+            (typeof o.command === "string" && o.command.trim().length > 0);
+        const browserOk = o.browser === undefined || typeof o.browser === "boolean";
+        if (cmdOk && browserOk && (o.command !== undefined || o.browser === true))
+            return;
+    }
+    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\`, \`{ command: "<shell command>" }\`, or \`{ browser: true }\``);
+}
+/** Whether a `coverage` value collects reports from the container's own
+ *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
+ *  any object that isn't browser-only. */
+export function coverageUsesContainer(cov) {
+    if (cov === undefined)
+        return false;
+    if (cov === true)
+        return true;
+    return cov.command !== undefined || cov.browser !== true;
+}
+/** Whether a `coverage` value collects frontend (browser) coverage. */
+export function coverageUsesBrowser(cov) {
+    return typeof cov === "object" && cov.browser === true;
+}
 function validateEnvironmentConfig(config) {
     const entries = Object.entries(config.services);
     const serviceNames = new Set(entries.map(([n]) => n));
@@ -246,6 +277,7 @@ function validateEnvironmentConfig(config) {
                 throw new Error(`service "${name}" volume name ${JSON.stringify(vol.name)} must be alphanumeric plus [._-]`);
             }
         }
+        validateCoverage(name, svc.coverage);
         for (const raw of svc.hostnames ?? []) {
             const h = raw.toLowerCase();
             if (!HOSTNAME_RE.test(hostPatternBody(h))) {

package/package.json

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