@specific.dev/spectest 0.56.2 → 0.58.0

package/dist/browser-coverage.d.ts

@@ -0,0 +1,20 @@
+import type { CDPSession } from "playwright-core";
+export interface BrowserCoverageConfig {
+    /** Which covered service (if any) serves scripts from this host. */
+    serviceForHost(host: string): string | undefined;
+}
+/** Set (or clear, with `null`) at /load. */
+export declare function configureBrowserCoverage(config: BrowserCoverageConfig | null): void;
+export declare function browserCoverageActive(): boolean;
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export declare function attachBrowserCoverage(cdp: CDPSession): Promise<void>;
+/**
+ * Take the session's counters and fold them into the totals. Concurrent
+ * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
+ * a closed view) are swallowed: the counters then stay in V8 for the next
+ * take, nothing is lost.
+ */
+export declare function harvestBrowserCoverage(cdp: CDPSession): Promise<void>;
+/** One lcov document per service that has any browser coverage. */
+export declare function browserCoverageReports(): Map<string, string>;

package/dist/browser-coverage.js

@@ -0,0 +1,185 @@
+// Browser coverage — the collector.
+//
+// One collector per CDP session (i.e. per page view). `attach` turns on
+// V8 precise coverage and tracks parsed scripts; `harvest` takes the
+// counters (which RESETS them — V8 reports nothing for a script that ran
+// nothing since the last take, so the counts are summed here across
+// takes), maps each script the browser loaded from a covered service back
+// to its original sources through the served source map, and folds the
+// result into a per-service total in module memory — which forks with the
+// daemon, so a child test inherits its ancestors' browser coverage exactly
+// as a container's counters are inherited.
+//
+// Harvest runs before every browser step (a click that navigates
+// cross-site replaces the renderer, and the old counters with it) and at
+// every coverage capture. `browserCoverageReports` renders the totals as
+// one lcov per service for the `case-coverage` bundle.
+//
+// Configured by the daemon at /load with the host → service table; a
+// project with no `coverage: { browser: true }` service never attaches
+// anything, so it costs nothing.
+import { createHash } from "node:crypto";
+import { decodeSourceMap, lcovDocument, mapToOriginal, mergeFileCounts, rangesToLineCounts, } from "./harness/browser-coverage.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+let CONFIG = null;
+/** Set (or clear, with `null`) at /load. */
+export function configureBrowserCoverage(config) {
+    CONFIG = config;
+}
+export function browserCoverageActive() {
+    return CONFIG !== null;
+}
+/** service → file → line → count, summed over every harvest. */
+const TOTALS = new Map();
+const COLLECTORS = new WeakMap();
+/** Decoded maps by URL (or content hash for inline `data:` maps). */
+const SOURCE_MAPS = new Map();
+const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export async function attachBrowserCoverage(cdp) {
+    if (!CONFIG || COLLECTORS.has(cdp))
+        return;
+    const collector = { cdp, scripts: new Map(), inFlight: null };
+    COLLECTORS.set(cdp, collector);
+    cdp.on("Debugger.scriptParsed", (ev) => {
+        if (!ev.url)
+            return;
+        collector.scripts.set(ev.scriptId, {
+            url: ev.url,
+            sourceMapURL: ev.sourceMapURL || undefined,
+        });
+    });
+    await cdp.send("Debugger.enable");
+    await cdp.send("Profiler.enable");
+    await cdp.send("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+}
+/**
+ * Take the session's counters and fold them into the totals. Concurrent
+ * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
+ * a closed view) are swallowed: the counters then stay in V8 for the next
+ * take, nothing is lost.
+ */
+export async function harvestBrowserCoverage(cdp) {
+    const c = COLLECTORS.get(cdp);
+    if (!c || !CONFIG)
+        return;
+    if (c.inFlight)
+        return c.inFlight;
+    c.inFlight = harvestInner(c, CONFIG).catch(() => { }).finally(() => {
+        c.inFlight = null;
+    });
+    return c.inFlight;
+}
+async function harvestInner(c, config) {
+    const { result } = (await c.cdp.send("Profiler.takePreciseCoverage"));
+    for (const script of result) {
+        const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
+        if (!info)
+            continue;
+        let url;
+        try {
+            url = new URL(info.url);
+        }
+        catch {
+            continue;
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            continue;
+        const service = config.serviceForHost(url.hostname);
+        if (!service)
+            continue;
+        if (info.source === undefined) {
+            try {
+                const r = (await c.cdp.send("Debugger.getScriptSource", {
+                    scriptId: script.scriptId,
+                }));
+                info.source = r.scriptSource;
+            }
+            catch {
+                continue; // script gone with its document
+            }
+            c.scripts.set(script.scriptId, info);
+        }
+        const generated = rangesToLineCounts(info.source, script.functions);
+        if (generated.size === 0)
+            continue;
+        if (info.map === undefined)
+            info.map = await sourceMapFor(info, url);
+        const files = 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);
+    }
+}
+/** Resolve, fetch (or inline-decode) and decode a script's source map. */
+async function sourceMapFor(info, scriptUrl) {
+    let ref = info.sourceMapURL;
+    if (!ref && info.source) {
+        const m = /\/\/[#@]\s*sourceMappingURL=(\S+)\s*$/.exec(info.source.slice(-4096));
+        if (m)
+            ref = m[1];
+    }
+    if (!ref)
+        return null;
+    if (ref.startsWith("data:")) {
+        const key = "data:" + createHash("sha1").update(ref).digest("hex");
+        const cached = SOURCE_MAPS.get(key);
+        if (cached !== undefined)
+            return cached;
+        const map = decodeSourceMap(parseDataUrl(ref));
+        SOURCE_MAPS.set(key, map);
+        return map;
+    }
+    let mapUrl;
+    try {
+        mapUrl = new URL(ref, scriptUrl).toString();
+    }
+    catch {
+        return null;
+    }
+    const cached = SOURCE_MAPS.get(mapUrl);
+    if (cached !== undefined)
+        return cached;
+    let map = null;
+    try {
+        const res = await rawFetch(mapUrl, { signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) });
+        if (res.ok)
+            map = decodeSourceMap(await res.json());
+    }
+    catch {
+        map = null;
+    }
+    SOURCE_MAPS.set(mapUrl, map);
+    return map;
+}
+function parseDataUrl(ref) {
+    const comma = ref.indexOf(",");
+    if (comma < 0)
+        return null;
+    const meta = ref.slice(5, comma);
+    const payload = ref.slice(comma + 1);
+    try {
+        const text = /;base64$/i.test(meta)
+            ? Buffer.from(payload, "base64").toString("utf8")
+            : decodeURIComponent(payload);
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** One lcov document per service that has any browser coverage. */
+export function browserCoverageReports() {
+    const out = new Map();
+    for (const [service, files] of TOTALS) {
+        if (files.size > 0)
+            out.set(service, lcovDocument(files));
+    }
+    return out;
+}

package/dist/browser.js

@@ -35,6 +35,7 @@ import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
 import { chromium } from "playwright-core";
 /** Decoded byte count of a base64 string, without decoding it. */
@@ -792,6 +793,14 @@ async function spawnPage(context) {
             console.warn("[spectest] failed to install rrweb recorder:", err);
         }
     }
+    // Frontend coverage (opt-in): turn on V8 precise coverage for this page.
+    // A no-op unless a service declared `coverage: { browser: true }`.
+    try {
+        await attachBrowserCoverage(cdp);
+    }
+    catch {
+        /* coverage is best-effort; a page without it still works */
+    }
     return { page, cdp, recordingInstalled };
 }
 /** Create a default-desktop view (plus its context) for the pool. */
@@ -1080,6 +1089,14 @@ async function rebuildView(holder) {
     catch {
         /* page may already be gone */
     }
+    // The old renderer's coverage counters die with its page; harvest what
+    // it had before the swap (rebuild is triggered on a fresh navigation).
+    try {
+        await harvestBrowserCoverage(holder.cdp);
+    }
+    catch {
+        /* best-effort */
+    }
     const fresh = await spawnPage(holder.context);
     holder.page = fresh.page;
     holder.cdp = fresh.cdp;
@@ -1164,6 +1181,17 @@ function buildBackend(holder, recorder, buildOpts) {
                 durationMs: endT - t,
             }, resv);
             await drain(action);
+            // Fold this page's V8 counters into the per-service totals now — a
+            // navigation to another origin replaces the renderer and its
+            // counters, so harvesting per op is what keeps them.
+            if (browserCoverageActive()) {
+                try {
+                    await harvestBrowserCoverage(holder.cdp);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
             // Reads (`opts.wrap`) return user-visible JS values someone is likely to
             // assert on — provenance-wrap so `expect(...)` nests under this step.
             // Actions return void/internals; leave them raw to avoid Proxy surprises.
@@ -1193,6 +1221,14 @@ function buildBackend(holder, recorder, buildOpts) {
             return;
         // Final drain before we stop writing to this recorder.
         await drain("close");
+        if (browserCoverageActive()) {
+            try {
+                await harvestBrowserCoverage(holder.cdp);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
         recordingEnded = true;
     }
     const strategy = holder.device ? mobileStrategy : desktopStrategy;

package/dist/daemon.js

@@ -21,7 +21,10 @@ 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, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, validateCoverage, coverageUsesBrowser, coverageUsesContainer, } from "./index.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, readCoverageDir, } from "./harness/coverage.js";
+import { browserCoverageReports, configureBrowserCoverage, } from "./browser-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
@@ -510,6 +513,27 @@ async function ensureVolumes(svc) {
     }
     return flags;
 }
+/**
+ * The coverage directory for an opted-in service: one host dir per service
+ * under the workspace (so the delta-restore teardown wipes it), mounted
+ * writable at `/spectest/coverage/`. World-writable because the container
+ * may run as any user and spectest creates the dir as root. The reports in
+ * it ride snapshots and forks like everything else on the rootfs, which is
+ * what makes each read cumulative along the test's ancestor chain.
+ */
+async function ensureCoverage(svc) {
+    if (svc.coverage === undefined)
+        return [];
+    validateCoverage(svc.name, svc.coverage);
+    // A browser-only opt-in has no container process to write reports, so it
+    // gets no mount — its coverage comes from the guest browser.
+    if (!coverageUsesContainer(svc.coverage))
+        return [];
+    const host = coverageHostDir(WORKSPACE, svc.name);
+    await fs.mkdir(host, { recursive: true });
+    await fs.chmod(host, 0o777);
+    return [`--volume=${host}:${COVERAGE_CONTAINER_DIR}`];
+}
 /** Keyed by image ID, not tag: `spectest/<svc>:latest` is retagged onto
  *  new content every rebuild, and a stale uid is silently wrong. */
 const IMAGE_ID_TABLES = new Map();
@@ -1404,6 +1428,7 @@ function buildIngress(project) {
     // generic decl set the daemon executes. The special-casing lives in the
     // SDK's lowerIngress, not here.
     LOWERED = lowerIngress(project);
+    configureCoverageAttribution(project);
     if (!project.fakes)
         return;
     for (const [name, def] of Object.entries(project.fakes)) {
@@ -2309,6 +2334,7 @@ async function startRuntimeService(spec) {
             ...(await ensureVolumes(svc)),
             ...(await ensureFiles(svc, tag)),
             ...(await ensureCertificates(svc, tag)),
+            ...(await ensureCoverage(svc)),
         ];
         await runContainer(svc, tag, flags, aliases);
         await waitForReady(svc);
@@ -2707,6 +2733,7 @@ async function bootstrapInner() {
             ...(await ensureVolumes(svc)),
             ...(await ensureFiles(svc, tag)),
             ...(await ensureCertificates(svc, tag)),
+            ...(await ensureCoverage(svc)),
         ];
         const tRun = Date.now();
         progressService(svc.name, { status: "starting", detail: undefined });
@@ -2827,18 +2854,37 @@ async function runProjectSetupInner() {
 // bundle in guest RAM — entries older than the last few are always
 // already-fetched leftovers frozen into some snapshot.
 const REPLAY_BUNDLES = new Map();
-const REPLAY_BUNDLES_MAX = 8;
-function stashReplayBundle(caseId, gz) {
+/** Coverage bundles, same side-channel and same lifetime rules; pulled
+ *  through `coverageChunk`. The env-setup baseline parks under the
+ *  control plane's synthetic `__setup__` case id. */
+const COVERAGE_BUNDLES = new Map();
+const PARKED_BUNDLES_MAX = 8;
+/** The control plane's synthetic case id for env-setup captures
+ *  (`storage::SETUP_CASE_ID`). Not a real case id — those are kebab slugs. */
+const SETUP_CASE_ID = "__setup__";
+function stashBundle(map, caseId, gz) {
     // Re-insert to refresh recency (Map iterates in insertion order).
-    REPLAY_BUNDLES.delete(caseId);
-    REPLAY_BUNDLES.set(caseId, gz);
-    while (REPLAY_BUNDLES.size > REPLAY_BUNDLES_MAX) {
-        const oldest = REPLAY_BUNDLES.keys().next().value;
+    map.delete(caseId);
+    map.set(caseId, gz);
+    while (map.size > PARKED_BUNDLES_MAX) {
+        const oldest = map.keys().next().value;
         if (oldest === undefined)
             break;
-        REPLAY_BUNDLES.delete(oldest);
+        map.delete(oldest);
     }
 }
+function stashReplayBundle(caseId, gz) {
+    stashBundle(REPLAY_BUNDLES, caseId, gz);
+}
+/** Encode + park a case's coverage captures; returns the ref for the reply.
+ *  `undefined` when no service opted in, so uncovered projects ship nothing. */
+function parkCoverageBundle(caseId, captures) {
+    if (captures.length === 0)
+        return undefined;
+    const gz = encodeCoverageBundle(caseId, captures);
+    stashBundle(COVERAGE_BUNDLES, caseId, gz);
+    return coverageBundleRef(gz, captures);
+}
 // ────────────────────────────────────────────────────────────────────────
 // Cumulative service logs (per-case deltas → S3, reconstructed on the web)
 // ────────────────────────────────────────────────────────────────────────
@@ -2930,6 +2976,97 @@ async function captureServiceLogDeltas() {
         };
     }));
 }
+// ────────────────────────────────────────────────────────────────────────
+// Coverage capture (opt-in per service; see 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;
+/** Set the browser-coverage host→service attribution from the loaded
+ *  project: only services that opted in to `coverage: { browser: true }`
+ *  are attributed, so a script from an uncovered service is ignored. Null
+ *  when no service opted in — coverage then attaches nothing. Called on
+ *  every /load. */
+function configureCoverageAttribution(project) {
+    const env = project.environment;
+    const browserServices = new Set();
+    for (const svc of namedServices(env)) {
+        if (coverageUsesBrowser(svc.coverage))
+            browserServices.add(svc.name);
+    }
+    if (browserServices.size === 0) {
+        configureBrowserCoverage(null);
+        return;
+    }
+    const all = namedServices(env).map((s) => s.name);
+    const table = {
+        proxies: LOWERED.proxies,
+        aliasesByService: LOWERED.aliasesByService,
+        wildcards: LOWERED.wildcards,
+    };
+    configureBrowserCoverage({
+        serviceForHost(host) {
+            const svc = hostToService(host, all, table);
+            return svc && browserServices.has(svc) ? svc : undefined;
+        },
+    });
+}
+async function captureServiceCoverage() {
+    const l = loaded;
+    if (!l)
+        return [];
+    const byName = new Map();
+    for (const s of namedServices(l.project.environment))
+        byName.set(s.name, s);
+    for (const [name, s] of RUNTIME_SERVICES)
+        byName.set(name, s);
+    const services = [...byName.values()].filter((s) => s.coverage !== undefined);
+    // Browser coverage is per-service lcov, accumulated in module memory
+    // (browser-coverage.ts) across every harvest; read it once here.
+    const browser = browserCoverageReports();
+    return Promise.all(services.map(async (svc) => {
+        const cov = svc.coverage;
+        const reports = [];
+        // Container reports (a `command` runs first to flush a fresh dump).
+        if (coverageUsesContainer(cov)) {
+            if (typeof cov === "object" && cov !== null && cov.command) {
+                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 dir = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+            // A service that ALSO does browser coverage may legitimately have
+            // an empty container dir for a test — don't fail if the browser
+            // side has something. Otherwise the container contract stands.
+            if (dir.error && !(coverageUsesBrowser(cov) && browser.has(svc.name))) {
+                return dir;
+            }
+            reports.push(...dir.reports);
+        }
+        // Browser report for this service, when any script it served ran.
+        const lcov = browser.get(svc.name);
+        if (lcov)
+            reports.push({ name: "browser.lcov", content: lcov });
+        if (reports.length === 0 && coverageUsesBrowser(cov) && !coverageUsesContainer(cov)) {
+            // Browser-only service, no browser activity yet this branch. Not an
+            // error — a test needn't open a browser; the report appears once
+            // one does (and forks to descendants from there).
+            return { service: svc.name, reports: [] };
+        }
+        return { service: svc.name, reports };
+    }));
+}
 /**
  * Mint a session id. `idScope` (the running test's case id; `"eval"`
  * for eval-context sessions) is baked in because `randomUUID()` alone
@@ -4128,6 +4265,33 @@ async function runOne(testCase) {
         // eslint-disable-next-line no-console
         console.warn("[service-logs] delta capture failed:", err);
     }
+    // Coverage for the opted-in services, read after the clock stops like
+    // the log deltas. Unlike them it is NOT best-effort: a service that opted
+    // in and produced nothing readable fails the case, so a hole in the
+    // coverage data is visible where it happened rather than silently
+    // widening every later subset run.
+    let coverageCaptures = [];
+    try {
+        coverageCaptures = await captureServiceCoverage();
+    }
+    catch (err) {
+        coverageCaptures = [
+            {
+                service: "*",
+                reports: [],
+                error: `coverage capture failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ];
+    }
+    const coverageErrors = coverageCaptures
+        .filter((c) => c.error)
+        .map((c) => c.error);
+    if (coverageErrors.length > 0 && outcome.status === "passed") {
+        outcome = {
+            status: "failed",
+            error: { message: coverageErrors.join("\n") },
+        };
+    }
     const events = stopRecording();
     // Drop sessions whose linking event didn't survive — an exec/terminal
     // inside a failed `ctx.poll` iteration has its events removed by
@@ -4147,6 +4311,7 @@ async function runOne(testCase) {
         browserSessions: sessions.map((s) => s.record),
         terminalSessions: terminalSessions.filter((s) => referencedSessions.has(s.sessionId)),
         serviceLogDeltas,
+        coverageCaptures,
         error: outcome.error,
     };
 }
@@ -4898,7 +5063,20 @@ export function harnessMethods(state) {
                 // eslint-disable-next-line no-console
                 console.warn("[service-logs] baseline capture failed:", err);
             }
-            return { serviceLogDeltas };
+            // The coverage baseline rides the same call: what the opted-in
+            // services ran during bring-up + project setup, parked under the
+            // synthetic `__setup__` case for `coverageChunk`. A capture error is
+            // reported in the ref, not thrown — there is no case to fail here,
+            // the control plane logs it.
+            let coverage;
+            try {
+                coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn("[coverage] baseline capture failed:", err);
+            }
+            return { serviceLogDeltas, coverage };
         },
         run: async (params) => {
             const caseId = requireString(params, "caseId", "caseId");
@@ -4912,7 +5090,10 @@ export function harnessMethods(state) {
                 // (with a warning) rather than failing the case — and never falls
                 // back to inlining, which is exactly the oversized reply this path
                 // exists to avoid.
-                const { browserSessions, ...wire } = result;
+                const { browserSessions, coverageCaptures, ...wire } = result;
+                // Coverage reports take the same side channel: park, reply with a
+                // ref, let the control plane pull through `coverageChunk`.
+                const coverage = parkCoverageBundle(caseId, coverageCaptures);
                 let replay;
                 if (browserSessions.length > 0) {
                     try {
@@ -4925,7 +5106,7 @@ export function harnessMethods(state) {
                         console.warn("[replay] bundle encode failed; dropping recordings:", err);
                     }
                 }
-                return { ...wire, replay };
+                return { ...wire, replay, coverage };
             });
         },
         // One chunk of a parked replay bundle. Case ids are arbitrary user
@@ -4937,6 +5118,14 @@ export function harnessMethods(state) {
                 throw notFound(`no replay bundle for case: ${caseId}`);
             return replayChunk(gz, params.offset, params.limit);
         },
+        // One chunk of a parked coverage bundle (same shape as replayChunk).
+        coverageChunk: async (params) => {
+            const caseId = requireString(params, "caseId", "caseId");
+            const gz = COVERAGE_BUNDLES.get(caseId);
+            if (!gz)
+                throw notFound(`no coverage bundle for case: ${caseId}`);
+            return replayChunk(gz, params.offset, params.limit);
+        },
     };
 }
 /**

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;