@specific.dev/spectest 0.59.3 → 0.60.0

package/dist/daemon.js

@@ -22,9 +22,9 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, } from "./harness/coverage.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
-import { applyCoverageAdapters, coverageAdapters, validateCoverage, } from "./coverage.js";
+import { applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, nodeCoverageToolsAvailable, nodeCoverageToolsDir, NODE_COVERAGE_TOOLS_CONTAINER_DIR, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -529,7 +529,16 @@ async function ensureCoverage(svc) {
     const host = coverageHostDir(WORKSPACE, svc.name);
     await fs.mkdir(host, { recursive: true });
     await fs.chmod(host, 0o777);
-    return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+    const flags = [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+    // The conversion tools golden ships (`c8` for `coverage.node()`),
+    // read-only, on the same existence check the adapter makes at capture
+    // — so the VM and the container agree on whether they are there. A
+    // plain `--volume`, never a config `volumes` entry: an absolute-source
+    // volume dir is listed in the delta-restore manifest and wiped.
+    if (await nodeCoverageToolsAvailable()) {
+        flags.push(`--volume=${nodeCoverageToolsDir()}:${NODE_COVERAGE_TOOLS_CONTAINER_DIR}:ro`);
+    }
+    return flags;
 }
 /** Keyed by image ID, not tag: `spectest/<svc>:latest` is retagged onto
  *  new content every rebuild, and a stale uid is silently wrong. */
@@ -3037,8 +3046,10 @@ function rebuildBrowserCoverageResolver() {
         },
     });
 }
-/** The context one adapter's `capture` runs against. */
-function coverageCaptureContext(svc, signal) {
+/** The context one adapter's `capture` runs against. Every report it
+ *  writes through `writeReport` is added to `written`, so the delta step
+ *  knows which files came from which adapter. */
+function coverageCaptureContext(svc, signal, written) {
     const reportDir = coverageHostDir(WORKSPACE, svc.name);
     return {
         service: svc.name,
@@ -3061,20 +3072,25 @@ function coverageCaptureContext(svc, signal) {
             const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
             await fs.writeFile(tmp, content);
             await fs.rename(tmp, file);
+            written.add(path.relative(reportDir, file));
         },
     };
 }
 /** Run one service's adapters in order under one budget. Returns the
- *  error to fail the capture with, naming the adapter. */
+ *  error to fail the capture with, naming the adapter, and the reports
+ *  written by adapters that declare `reports: "delta"`. */
 async function runCoverageAdapters(svc) {
+    const deltaReports = new Set();
     const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
     if (adapters.length === 0)
-        return undefined;
+        return { deltaReports };
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
-    const ctx = coverageCaptureContext(svc, ac.signal);
+    const written = new Set();
+    const ctx = coverageCaptureContext(svc, ac.signal, written);
     try {
         for (const a of adapters) {
+            written.clear();
             try {
                 await Promise.race([
                     a.capture(ctx),
@@ -3084,10 +3100,16 @@ async function runCoverageAdapters(svc) {
                 ]);
             }
             catch (err) {
-                return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${err instanceof Error ? err.message : String(err)}`;
+                return {
+                    error: `coverage adapter "${a.name}" on service "${svc.name}" failed: ${err instanceof Error ? err.message : String(err)}`,
+                    deltaReports,
+                };
             }
+            if (a.reports === "delta")
+                for (const n of written)
+                    deltaReports.add(n);
         }
-        return undefined;
+        return { deltaReports };
     }
     finally {
         clearTimeout(timer);
@@ -3104,10 +3126,15 @@ async function captureServiceCoverage() {
         byName.set(name, s);
     const services = [...byName.values()].filter((s) => s.coverage !== undefined);
     return Promise.all(services.map(async (svc) => {
-        const error = await runCoverageAdapters(svc);
+        const { error, deltaReports } = await runCoverageAdapters(svc);
         if (error)
             return { service: svc.name, reports: [], error };
-        return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        const read = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        // What ships is what ran during this capture, whatever the tool
+        // counts: cumulative lcov is subtracted against the previous
+        // capture (module memory, forks with the env); a delta adapter's
+        // files and V8 JSON pass through.
+        return applyCoverageDelta(read, coverageReportsMode(svc.coverage), deltaReports);
     }));
 }
 /**

package/dist/harness/browser-coverage.d.ts

@@ -51,6 +51,14 @@ export declare function normalizeSourcePath(src: string, sourceRoot?: string): s
 /** Sources nobody's change can be attributed to: dependencies and bundler
  *  runtime shims. */
 export declare function isForeignSource(path: string): boolean;
+/**
+ * A script with no source map is attributed to its served path — unless
+ * that path is a page, not a file: an inline `<script>` in an HTML
+ * document reports the document's URL (`/`, `/projects/123`), and no
+ * repository file can ever be named by it. Extension-less paths are
+ * treated as pages.
+ */
+export declare function isDocumentScriptPath(pathname: string): boolean;
 /**
  * Decode a source map document. Index maps (`sections`) are not
  * supported and decode to `null`, as does anything malformed — the

package/dist/harness/browser-coverage.js

@@ -104,6 +104,10 @@ export function normalizeSourcePath(src, sourceRoot) {
         s = m[1];
     s = s.replace(/^\/@fs\//, "/");
     s = s.replace(/\?.*$/, "");
+    // Turbopack (Next.js) roots every source at the `[project]` token —
+    // `/[project]/dashboard/app/page.tsx` — which is the workspace root,
+    // i.e. repo-relative once stripped.
+    s = s.replace(/^\/?\[project\]\//, "");
     while (s.startsWith("./"))
         s = s.slice(2);
     return s;
@@ -117,7 +121,20 @@ export function isForeignSource(path) {
         path.startsWith("(webpack)") ||
         path.startsWith("\0") ||
         path.startsWith("vite/") ||
-        path.startsWith("@vite/"));
+        path.startsWith("@vite/") ||
+        path.startsWith("[turbopack]/") ||
+        path.startsWith("/[turbopack]/"));
+}
+/**
+ * A script with no source map is attributed to its served path — unless
+ * that path is a page, not a file: an inline `<script>` in an HTML
+ * document reports the document's URL (`/`, `/projects/123`), and no
+ * repository file can ever be named by it. Extension-less paths are
+ * treated as pages.
+ */
+export function isDocumentScriptPath(pathname) {
+    const last = pathname.split("/").pop() ?? "";
+    return !last.includes(".");
 }
 /**
  * Decode a source map document. Index maps (`sections`) are not

package/dist/harness/coverage.d.ts

@@ -77,3 +77,38 @@ export declare function readCoverageDir(service: string, dir: string): Promise<S
 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;
+/** How a report's counters behave across captures. */
+export type CoverageReportsMode = "delta" | "cumulative";
+/** One lcov record's execution counts: `DA:` by line, `FNDA:` by function
+ *  name. Branch data is dropped: file and line are what the derivation
+ *  reads. */
+export interface LcovRecordCounts {
+    lines: Map<number, number>;
+    functions: Map<string, number>;
+    /** `FN:<line>,<name>` declarations, kept so the delta names them. */
+    functionLines: Map<string, number>;
+}
+/** An lcov document parsed to counts, by `SF:` path. Records for one
+ *  path are merged (a tool may split a file across records). */
+export declare function parseLcovCounts(text: string): Map<string, LcovRecordCounts>;
+/**
+ * `now` minus `prev`, per line and per function. A count that went
+ * *down* is a counter that restarted (the process was replaced): the
+ * new value stands on its own. A file not in `prev` is new: everything
+ * in it counts. Only records with at least one execution are kept — a
+ * file with nothing new in it did not run.
+ */
+export declare function subtractLcovCounts(now: Map<string, LcovRecordCounts>, prev: Map<string, LcovRecordCounts>): Map<string, LcovRecordCounts>;
+/** Counts rendered back to lcov, records in path order. */
+export declare function renderLcovCounts(counts: Map<string, LcovRecordCounts>): string;
+/** Forget every previous capture (tests). */
+export declare function resetCoverageDeltaMemory(): void;
+/**
+ * Turn a capture's cumulative lcov reports into deltas against the
+ * previous capture of the same service and report name, and remember
+ * this capture as the new previous. Reports named in `deltaReports`
+ * (written by an adapter that declares `reports: "delta"`) and
+ * non-lcov reports (V8 JSON is a delta by construction) pass through
+ * untouched. With `mode === "delta"` every report passes through.
+ */
+export declare function applyCoverageDelta(capture: ServiceCoverageCapture, mode: CoverageReportsMode, deltaReports: ReadonlySet<string>): ServiceCoverageCapture;

package/dist/harness/coverage.js

@@ -15,6 +15,17 @@
 // stored bytes, so a change in that derivation is a re-read of stored
 // runs, never a hole in the history.
 //
+// The one transformation done here is the **delta**: a stored report
+// describes what ran between the previous capture and this one, for
+// every source alike. A tool that resets its own counters (V8) writes
+// deltas already; a cumulative tool (coverage.py, Go, JaCoCo — most)
+// gets subtracted against the previous capture, which lives in module
+// memory and so forks with the environment: a forked child's "previous"
+// is its parent's last capture, exactly the state it started from. Which
+// of the two a file is must be declared (an adapter's `reports`, or the
+// service's) — nothing in the bytes tells a delta that happens to equal
+// the previous one from a cumulative report with no new execution.
+//
 // The container side (mount flag, `command` exec) is in `daemon.ts`.
 import { promises as fs } from "node:fs";
 import path from "node:path";
@@ -156,3 +167,149 @@ export function coverageBundleRef(gz, services) {
         })),
     };
 }
+/** An lcov document parsed to counts, by `SF:` path. Records for one
+ *  path are merged (a tool may split a file across records). */
+export function parseLcovCounts(text) {
+    const out = new Map();
+    let cur = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("SF:")) {
+            const file = line.slice(3).trim();
+            if (!file) {
+                cur = null;
+                continue;
+            }
+            cur = out.get(file) ?? { lines: new Map(), functions: new Map(), functionLines: new Map() };
+            out.set(file, cur);
+        }
+        else if (!cur) {
+            continue;
+        }
+        else if (line.startsWith("DA:")) {
+            const [ln, hits] = line.slice(3).split(",");
+            const l = Number(ln), h = Number(hits);
+            if (Number.isFinite(l) && Number.isFinite(h))
+                cur.lines.set(l, (cur.lines.get(l) ?? 0) + h);
+        }
+        else if (line.startsWith("FNDA:")) {
+            const i = line.indexOf(",", 5);
+            if (i < 0)
+                continue;
+            const h = Number(line.slice(5, i)), name = line.slice(i + 1);
+            if (Number.isFinite(h))
+                cur.functions.set(name, (cur.functions.get(name) ?? 0) + h);
+        }
+        else if (line.startsWith("FN:")) {
+            const i = line.indexOf(",", 3);
+            if (i < 0)
+                continue;
+            const l = Number(line.slice(3, i)), name = line.slice(i + 1);
+            if (Number.isFinite(l))
+                cur.functionLines.set(name, l);
+        }
+        else if (line === "end_of_record") {
+            cur = null;
+        }
+    }
+    return out;
+}
+/**
+ * `now` minus `prev`, per line and per function. A count that went
+ * *down* is a counter that restarted (the process was replaced): the
+ * new value stands on its own. A file not in `prev` is new: everything
+ * in it counts. Only records with at least one execution are kept — a
+ * file with nothing new in it did not run.
+ */
+export function subtractLcovCounts(now, prev) {
+    const out = new Map();
+    for (const [file, rec] of now) {
+        const before = prev.get(file);
+        const lines = new Map();
+        const functions = new Map();
+        let executed = false;
+        for (const [l, h] of rec.lines) {
+            const b = before?.lines.get(l) ?? 0;
+            const d = h < b ? h : h - b;
+            lines.set(l, d);
+            if (d > 0)
+                executed = true;
+        }
+        for (const [name, h] of rec.functions) {
+            const b = before?.functions.get(name) ?? 0;
+            const d = h < b ? h : h - b;
+            functions.set(name, d);
+            if (d > 0)
+                executed = true;
+        }
+        // A record with no counts at all carries presence as its only
+        // signal; it is new only when it was not there before.
+        if (rec.lines.size === 0 && rec.functions.size === 0 && !before)
+            executed = true;
+        if (executed)
+            out.set(file, { lines, functions, functionLines: rec.functionLines });
+    }
+    return out;
+}
+/** Counts rendered back to lcov, records in path order. */
+export function renderLcovCounts(counts) {
+    const parts = ["TN:"];
+    for (const file of [...counts.keys()].sort()) {
+        const rec = counts.get(file);
+        parts.push(`SF:${file}`);
+        for (const [name, l] of [...rec.functionLines].sort((a, b) => a[1] - b[1]))
+            parts.push(`FN:${l},${name}`);
+        let fnh = 0;
+        for (const [name, h] of rec.functions) {
+            parts.push(`FNDA:${h},${name}`);
+            if (h > 0)
+                fnh++;
+        }
+        parts.push(`FNF:${rec.functions.size}`, `FNH:${fnh}`);
+        let lh = 0;
+        for (const [l, h] of [...rec.lines].sort((a, b) => a[0] - b[0])) {
+            parts.push(`DA:${l},${h}`);
+            if (h > 0)
+                lh++;
+        }
+        parts.push(`LF:${rec.lines.size}`, `LH:${lh}`, "end_of_record");
+    }
+    return parts.join("\n") + "\n";
+}
+/** The previous capture's counts: service → report name → parsed lcov.
+ *  Module memory, so it forks with the environment — a forked child's
+ *  previous capture is its parent's last one. */
+const PREVIOUS_CAPTURE = new Map();
+/** Forget every previous capture (tests). */
+export function resetCoverageDeltaMemory() {
+    PREVIOUS_CAPTURE.clear();
+}
+/**
+ * Turn a capture's cumulative lcov reports into deltas against the
+ * previous capture of the same service and report name, and remember
+ * this capture as the new previous. Reports named in `deltaReports`
+ * (written by an adapter that declares `reports: "delta"`) and
+ * non-lcov reports (V8 JSON is a delta by construction) pass through
+ * untouched. With `mode === "delta"` every report passes through.
+ */
+export function applyCoverageDelta(capture, mode, deltaReports) {
+    if (capture.error)
+        return capture;
+    let prevByName = PREVIOUS_CAPTURE.get(capture.service);
+    if (!prevByName) {
+        prevByName = new Map();
+        PREVIOUS_CAPTURE.set(capture.service, prevByName);
+    }
+    const reports = [];
+    for (const r of capture.reports) {
+        if (mode === "delta" || deltaReports.has(r.name) || !isLcovShaped(r.content)) {
+            reports.push(r);
+            continue;
+        }
+        const now = parseLcovCounts(r.content);
+        const prev = prevByName.get(r.name) ?? new Map();
+        prevByName.set(r.name, now);
+        reports.push({ name: r.name, content: renderLcovCounts(subtractLcovCounts(now, prev)) });
+    }
+    return { ...capture, reports };
+}

package/package.json

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

package/src/browser-coverage.ts

@@ -25,6 +25,7 @@ import {
   type DecodedSourceMap,
   type FileCounts,
   decodeSourceMap,
+  isDocumentScriptPath,
   lcovDocument,
   mapToOriginal,
   mergeFileCounts,
@@ -67,6 +68,9 @@ interface Collector {
 }
 
 const COLLECTORS = new WeakMap<CDPSession, Collector>();
+/** The collectors of every session attached so far, for the harvest at
+ *  capture; a closed session's take fails and is dropped there. */
+const LIVE_COLLECTORS = new Set<Collector>();
 
 /** Decoded maps by URL (or content hash for inline `data:` maps). */
 const SOURCE_MAPS = new Map<string, DecodedSourceMap | null>();
@@ -79,6 +83,7 @@ export async function attachBrowserCoverage(cdp: CDPSession): Promise<void> {
   if (!CONFIG || COLLECTORS.has(cdp)) return;
   const collector: Collector = { cdp, scripts: new Map(), inFlight: null };
   COLLECTORS.set(cdp, collector);
+  LIVE_COLLECTORS.add(collector);
   cdp.on("Debugger.scriptParsed", (ev: { scriptId: string; url: string; sourceMapURL?: string }) => {
     if (!ev.url) return;
     collector.scripts.set(ev.scriptId, {
@@ -108,9 +113,13 @@ export async function harvestBrowserCoverage(cdp: CDPSession): Promise<void> {
 }
 
 async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promise<void> {
-  const { result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as {
-    result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
-  };
+  let result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
+  try {
+    ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as { result: typeof result });
+  } catch (err) {
+    LIVE_COLLECTORS.delete(c); // the session is gone
+    throw err;
+  }
   for (const script of result) {
     const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
     if (!info) continue;
@@ -137,16 +146,22 @@ async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promis
     const generated = rangesToLineCounts(info.source, script.functions);
     if (generated.size === 0) continue;
     if (info.map === undefined) info.map = await sourceMapFor(info, url);
+    if (!info.map && isDocumentScriptPath(url.pathname)) continue; // inline script in a page
     const files: FileCounts = info.map
       ? mapToOriginal(info.map, generated)
       : new Map([[url.pathname, generated]]);
-    let totals = TOTALS.get(service);
-    if (!totals) {
-      totals = new Map();
-      TOTALS.set(service, totals);
-    }
-    mergeFileCounts(totals, files);
+    foldBrowserCoverage(service, files);
+  }
+}
+
+/** Fold one script's per-file counts into a service's totals. */
+export function foldBrowserCoverage(service: string, files: FileCounts): void {
+  let totals = TOTALS.get(service);
+  if (!totals) {
+    totals = new Map();
+    TOTALS.set(service, totals);
   }
+  mergeFileCounts(totals, files);
 }
 
 /** Resolve, fetch (or inline-decode) and decode a script's source map. */
@@ -199,7 +214,26 @@ function parseDataUrl(ref: string): unknown {
   }
 }
 
-/** One lcov document per service that has any browser coverage. */
+/** Harvest every live session, so a capture sees the counters of code
+ *  that ran since the last browser op. */
+export async function harvestAllBrowserCoverage(): Promise<void> {
+  await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp)));
+}
+
+/** One lcov document per service that has any browser coverage — and
+ *  the totals are cleared, so the next capture holds only what runs
+ *  from now on. Module memory forks with the environment, so a forked
+ *  child starts from its parent's last capture, empty. */
+export function takeBrowserCoverageReports(): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [service, files] of TOTALS) {
+    if (files.size > 0) out.set(service, lcovDocument(files));
+  }
+  TOTALS.clear();
+  return out;
+}
+
+/** The current totals, without clearing them (tests). */
 export function browserCoverageReports(): Map<string, string> {
   const out = new Map<string, string>();
   for (const [service, files] of TOTALS) {