@specific.dev/spectest 0.57.0 → 0.59.0

package/dist/daemon.js

@@ -21,8 +21,11 @@ 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 { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, validateCoverage, } from "./index.js";
-import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, readCoverageDir, } from "./harness/coverage.js";
+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 { configureBrowserCoverage } from "./browser-coverage.js";
+import { applyCoverageAdapters, coverageAdapters, validateCoverage, } from "./coverage.js";
+import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
@@ -1422,6 +1425,11 @@ function buildIngress(project) {
     // generic decl set the daemon executes. The special-casing lives in the
     // SDK's lowerIngress, not here.
     LOWERED = lowerIngress(project);
+    BROWSER_COVERAGE_SERVICES.clear();
+    void runCoverageLoadHooks(namedServices(project.environment)).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn("[coverage] load hook failed:", err);
+    });
     if (!project.fakes)
         return;
     for (const [name, def] of Object.entries(project.fakes)) {
@@ -2306,7 +2314,9 @@ const RUNTIME_SERVICES = new Map();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec) {
     const { name, ...rest } = spec;
-    return { name, ...rest };
+    // A runtime spec skipped `defineEnvironment`, so its coverage adapters
+    // get their config-time pass here.
+    return { name, ...applyCoverageAdapters(name, rest) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
  *  Prepares the image (pulling on first use through the host cache), runs
@@ -2319,6 +2329,7 @@ async function startRuntimeService(spec) {
     const t0 = Date.now();
     const resv = reserveEvent();
     const svc = specToNamedService(spec);
+    await runCoverageLoadHooks([svc]);
     const aliases = (spec.hostnames ?? []).map((h) => h.toLowerCase());
     const imageRef = svc.image.type === "registry" ? svc.image.reference : "(dockerfile)";
     try {
@@ -2970,16 +2981,118 @@ async function captureServiceLogDeltas() {
     }));
 }
 // ────────────────────────────────────────────────────────────────────────
-// Coverage capture (opt-in per service; see harness/coverage.ts)
+// Coverage capture (opt-in per service; see coverage.ts + harness/coverage.ts)
 // ────────────────────────────────────────────────────────────────────────
 //
-// Read after bring-up and after every test, on every case. The reports are
-// cumulative from process start and live on the rootfs, so what a child
-// fork reads already includes everything its ancestors ran — no markers,
-// no deltas (unlike the service logs above). A `command` runs in the
-// container first so the service writes a fresh report. The reports ship
-// verbatim; the server derives what it needs from the stored bytes.
-const COVERAGE_COMMAND_TIMEOUT_MS = 60_000;
+// Read after bring-up and after every test, on every case. A service's
+// adapters run first (each makes its report appear in the directory —
+// `nodeCoverage` asks the hook for a dump, `browserCoverage` writes the
+// harness's totals, `commandCoverage` runs the command), then the
+// directory is read the same way for every service, `coverage: true`
+// included. The reports live on the rootfs, so what a child fork reads
+// already includes everything its ancestors ran — no markers, no deltas
+// (unlike the service logs above). The reports ship verbatim; the server
+// derives what it needs from the stored bytes.
+/** Budget for one service's adapters at one capture, all of them. */
+const COVERAGE_CAPTURE_TIMEOUT_MS = 60_000;
+/** Services whose adapters asked for browser scripts at /load
+ *  (`CoverageLoadContext.collectBrowserScripts`). Cleared on every /load;
+ *  a runtime service's adapters add to it when it starts. */
+const BROWSER_COVERAGE_SERVICES = new Set();
+/** Run every adapter's `load` hook for `services`, then rebuild the
+ *  browser-coverage attribution from whoever asked. The attribution is a
+ *  host → service resolver over the lowered ingress, restricted to those
+ *  services, so a script from an uncovered service is ignored; null when
+ *  nobody asked, which costs nothing. */
+async function runCoverageLoadHooks(services) {
+    for (const svc of services) {
+        for (const a of coverageAdapters(svc.coverage)) {
+            if (!a.load)
+                continue;
+            await a.load({
+                service: svc.name,
+                collectBrowserScripts: () => {
+                    BROWSER_COVERAGE_SERVICES.add(svc.name);
+                },
+            });
+        }
+    }
+    rebuildBrowserCoverageResolver();
+}
+function rebuildBrowserCoverageResolver() {
+    if (BROWSER_COVERAGE_SERVICES.size === 0 || !loaded) {
+        configureBrowserCoverage(null);
+        return;
+    }
+    const all = [...namedServices(loaded.project.environment).map((s) => s.name), ...RUNTIME_SERVICES.keys()];
+    const table = {
+        proxies: LOWERED.proxies,
+        aliasesByService: LOWERED.aliasesByService,
+        wildcards: LOWERED.wildcards,
+    };
+    configureBrowserCoverage({
+        serviceForHost(host) {
+            const svc = hostToService(host, all, table);
+            return svc && BROWSER_COVERAGE_SERVICES.has(svc) ? svc : undefined;
+        },
+    });
+}
+/** The context one adapter's `capture` runs against. */
+function coverageCaptureContext(svc, signal) {
+    const reportDir = coverageHostDir(WORKSPACE, svc.name);
+    return {
+        service: svc.name,
+        reportDir,
+        signal,
+        async exec(command) {
+            const r = await docker(["exec", svc.name, "sh", "-c", command], COVERAGE_CAPTURE_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 };
+        },
+        async writeReport(name, content) {
+            const file = path.join(reportDir, name);
+            if (path.relative(reportDir, file).startsWith("..")) {
+                throw new Error(`writeReport: ${JSON.stringify(name)} leaves the coverage directory`);
+            }
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
+            await fs.writeFile(tmp, content);
+            await fs.rename(tmp, file);
+        },
+    };
+}
+/** Run one service's adapters in order under one budget. Returns the
+ *  error to fail the capture with, naming the adapter. */
+async function runCoverageAdapters(svc) {
+    const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
+    if (adapters.length === 0)
+        return undefined;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
+    const ctx = coverageCaptureContext(svc, ac.signal);
+    try {
+        for (const a of adapters) {
+            try {
+                await Promise.race([
+                    a.capture(ctx),
+                    new Promise((_, reject) => {
+                        ac.signal.addEventListener("abort", () => reject(new Error(`no report within ${COVERAGE_CAPTURE_TIMEOUT_MS / 1000}s`)), { once: true });
+                    }),
+                ]);
+            }
+            catch (err) {
+                return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function captureServiceCoverage() {
     const l = loaded;
     if (!l)
@@ -2991,18 +3104,9 @@ async function captureServiceCoverage() {
         byName.set(name, s);
     const services = [...byName.values()].filter((s) => s.coverage !== undefined);
     return Promise.all(services.map(async (svc) => {
-        const cov = svc.coverage;
-        if (typeof cov === "object" && cov !== null) {
-            const r = await docker(["exec", svc.name, "sh", "-c", cov.command], COVERAGE_COMMAND_TIMEOUT_MS);
-            if (r.code !== 0) {
-                const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
-                return {
-                    service: svc.name,
-                    reports: [],
-                    error: `coverage command for service "${svc.name}" failed (exit ${r.code}): ${JSON.stringify(cov.command)}${tail ? `\n${tail}` : ""}`,
-                };
-            }
-        }
+        const error = await runCoverageAdapters(svc);
+        if (error)
+            return { service: svc.name, reports: [], error };
         return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
     }));
 }
@@ -5009,7 +5113,17 @@ export function harnessMethods(state) {
             // the control plane logs it.
             let coverage;
             try {
-                coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+                const captures = await captureServiceCoverage();
+                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 —
+                    // visible in the boot log, never a failure (there is no case).
+                    if (!c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[coverage] service "${c.service}": every report is empty after bring-up — is coverage enabled at process start?`);
+                    }
+                }
+                coverage = parkCoverageBundle(SETUP_CASE_ID, captures);
             }
             catch (err) {
                 // eslint-disable-next-line no-console

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

@@ -0,0 +1,95 @@
+/** Per-line hit counts, 1-based line numbers. */
+export type LineCounts = Map<number, number>;
+/** Per-file line counts. Keys are source paths as the source map (or the
+ *  script URL, when there is no map) reports them. */
+export type FileCounts = Map<string, LineCounts>;
+/** Byte offset at which each line starts. */
+export declare function lineStartsOf(source: string): number[];
+/** 1-based line holding `offset`. */
+export declare function lineOf(starts: number[], offset: number): number;
+/** One V8 `FunctionCoverage` as `Profiler.takePreciseCoverage` reports it. */
+export interface V8FunctionCoverage {
+    functionName?: string;
+    ranges: {
+        startOffset: number;
+        endOffset: number;
+        count: number;
+    }[];
+    isBlockCoverage?: boolean;
+}
+/**
+ * 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 declare function rangesToLineCounts(source: string, functions: readonly V8FunctionCoverage[]): LineCounts;
+/** One mapping segment: generated column → original (source, line). */
+export interface Segment {
+    col: number;
+    src: number;
+    line: number;
+}
+export interface DecodedSourceMap {
+    /** Normalised source paths, indexed by segment `src`. */
+    sources: string[];
+    /** Segments per generated line (0-based), sorted by column. */
+    lines: Segment[][];
+}
+/** Decode one VLQ-encoded segment into its fields. */
+export declare function decodeVlq(segment: string): number[];
+/**
+ * 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 declare function normalizeSourcePath(src: string, sourceRoot?: string): string;
+/** Sources nobody's change can be attributed to: dependencies and bundler
+ *  runtime shims. */
+export declare function isForeignSource(path: string): boolean;
+/**
+ * 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 declare function decodeSourceMap(doc: unknown): DecodedSourceMap | null;
+/**
+ * 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 declare function mapToOriginal(map: DecodedSourceMap, generated: LineCounts): FileCounts;
+/** Add `from` into `into` (sums — takes reset V8's counters). */
+export declare function mergeLineCounts(into: LineCounts, from: LineCounts): void;
+export declare function mergeFileCounts(into: FileCounts, from: FileCounts): void;
+/** One lcov document for a set of files. */
+export declare function lcovDocument(files: FileCounts): string;
+/** The slice of the lowered ingress that names hosts. */
+export interface HostTable {
+    proxies: readonly {
+        hostname: string;
+        service: string;
+    }[];
+    aliasesByService: Readonly<Record<string, readonly string[]>>;
+    wildcards: readonly {
+        pattern: string;
+        target: {
+            service?: string;
+        } | {
+            ingress?: boolean;
+        } | Record<string, unknown>;
+    }[];
+}
+/**
+ * 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 declare function serviceForHost(host: string, services: readonly string[], table: HostTable): string | undefined;

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

@@ -1,7 +1,7 @@
 /** 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
+ *  bounded by code size times chain depth, 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
@@ -44,14 +44,33 @@ export interface CoverageBundle {
 }
 /** True when `text` holds at least one lcov `SF:` record. */
 export declare function hasLcovSourceFile(text: string): boolean;
+/** True when `text` is lcov-shaped: at least one line, every non-blank
+ *  line an `XX:` record or `end_of_record`. An lcov with no `SF:` record
+ *  at all (`TN:` alone) is well-formed — it is a report that says
+ *  nothing ran. */
+export declare 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.
+ */
+export declare function isV8CoverageJson(text: string): boolean;
+/** True when `text` is a report spectest stores: lcov or V8 JSON. */
+export declare function isWellFormedReport(text: string): boolean;
+/** True when a well-formed report names no source file at all (an lcov
+ *  with no `SF:`, a V8 document with an empty `result`). */
+export declare function isEmptyReport(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.
+ * Read every report under `dir`, verbatim. An empty directory, or a file
+ * that is neither lcov nor V8 JSON, is an error rather than an empty
+ * capture: the contract is that an opted-in service always has a
+ * well-formed report to read. A report that names no file is fine — it
+ * says nothing ran.
  */
 export declare function readCoverageDir(service: string, dir: string): Promise<ServiceCoverageCapture>;
 /** Gzip a case's captures into the bundle `coverageChunk` serves. */