@specific.dev/spectest 0.57.0 → 0.59.0

package/src/daemon.ts

@@ -32,7 +32,6 @@ import {
   dnsName as makeDnsDecl,
   isWildcard,
   proxy as makeProxyDecl,
-  validateCoverage,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
 import {
@@ -40,10 +39,21 @@ import {
   coverageBundleRef,
   coverageHostDir,
   encodeCoverageBundle,
+  isEmptyReport,
   readCoverageDir,
   type CoverageBundleRef,
+  type CoverageReport,
   type ServiceCoverageCapture,
 } from "./harness/coverage.js";
+import { configureBrowserCoverage } from "./browser-coverage.js";
+import {
+  applyCoverageAdapters,
+  coverageAdapters,
+  validateCoverage,
+  type CoverageAdapter,
+  type CoverageCaptureContext,
+} 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
@@ -1802,6 +1812,11 @@ function buildIngress(project: Project): void {
   // 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)) {
     FAKES.set(name, {
@@ -2785,7 +2800,9 @@ const RUNTIME_SERVICES = new Map<string, NamedService>();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec: RuntimeServiceSpec): NamedService {
   const { name, ...rest } = spec;
-  return { name, ...(rest as ServiceConfig) };
+  // A runtime spec skipped `defineEnvironment`, so its coverage adapters
+  // get their config-time pass here.
+  return { name, ...applyCoverageAdapters(name, rest as ServiceConfig) };
 }
 
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
@@ -2799,6 +2816,7 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
   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 {
@@ -3589,17 +3607,126 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
 }
 
 // ────────────────────────────────────────────────────────────────────────
-// 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.
+// 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<string>();
+
+/** 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: NamedService[]): Promise<void> {
+  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();
+}
 
-const COVERAGE_COMMAND_TIMEOUT_MS = 60_000;
+function rebuildBrowserCoverageResolver(): void {
+  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: string): string | undefined {
+      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: NamedService, signal: AbortSignal): CoverageCaptureContext {
+  const reportDir = coverageHostDir(WORKSPACE, svc.name);
+  return {
+    service: svc.name,
+    reportDir,
+    signal,
+    async exec(command: string) {
+      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: string, content: string) {
+      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: NamedService): Promise<string | undefined> {
+  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 as Required<Pick<CoverageAdapter, "capture">>).capture(ctx),
+          new Promise<never>((_, 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(): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
@@ -3610,21 +3737,8 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   const services = [...byName.values()].filter((s) => s.coverage !== undefined);
   return Promise.all(
     services.map(async (svc): Promise<ServiceCoverageCapture> => {
-      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));
     }),
   );
@@ -6078,7 +6192,19 @@ export function harnessMethods(state: RouteState): MethodTable {
       // the control plane logs it.
       let coverage: CoverageBundleRef | undefined;
       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
         console.warn("[coverage] baseline capture failed:", err);

package/src/harness/browser-coverage.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeSourceMap,
+  decodeVlq,
+  isForeignSource,
+  lcovDocument,
+  mapToOriginal,
+  mergeFileCounts,
+  normalizeSourcePath,
+  rangesToLineCounts,
+  serviceForHost,
+} from "./browser-coverage";
+
+describe("rangesToLineCounts", () => {
+  test("outer range sets lines, narrower ranges override, blanks dropped", () => {
+    const src = "function f() {\n  if (x) {\n    a();\n  }\n\n  b();\n}\n";
+    const fnRange = { startOffset: 0, endOffset: src.length, count: 3 };
+    const ifBlock = { startOffset: src.indexOf("{\n    a"), endOffset: src.indexOf("}\n\n") + 1, count: 0 };
+    const counts = rangesToLineCounts(src, [{ ranges: [fnRange, ifBlock] }]);
+    expect(counts.get(1)).toBe(3);
+    expect(counts.get(3)).toBe(0);
+    expect(counts.get(6)).toBe(3);
+    expect(counts.has(5)).toBe(false);
+  });
+});
+
+describe("source maps", () => {
+  test("decodeVlq", () => {
+    expect(decodeVlq("AAAA")).toEqual([0, 0, 0, 0]);
+    expect(decodeVlq("IACC")).toEqual([4, 0, 1, 1]);
+    expect(decodeVlq("D")).toEqual([-1]);
+  });
+
+  test("decode + map generated lines onto original files", () => {
+    // Two generated lines: line 1 maps to src/a.ts:1 and node_modules/x.js:1,
+    // line 2 maps to src/b.ts:5 (columns irrelevant for line attribution).
+    const map = decodeSourceMap({
+      version: 3,
+      sources: ["webpack:///./src/a.ts", "webpack:///./node_modules/x.js", "./src/b.ts"],
+      mappings: "AAAA,ICAA;ACIA",
+    });
+    expect(map).not.toBeNull();
+    expect(map!.sources).toEqual(["src/a.ts", "node_modules/x.js", "src/b.ts"]);
+    const files = mapToOriginal(map!, new Map([[1, 2], [2, 0]]));
+    expect([...files.keys()]).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(files.get("src/a.ts")!.get(1)).toBe(2);
+    expect(files.get("src/b.ts")!.get(5)).toBe(0);
+  });
+
+  test("index maps and garbage decode to null", () => {
+    expect(decodeSourceMap({ version: 3, sections: [] })).toBeNull();
+    expect(decodeSourceMap({ version: 3, sources: ["a"], mappings: "!!" })).toBeNull();
+    expect(decodeSourceMap("nope")).toBeNull();
+  });
+
+  test("normalizeSourcePath strips schemes, roots and queries", () => {
+    expect(normalizeSourcePath("webpack:///./src/a.ts")).toBe("src/a.ts");
+    expect(normalizeSourcePath("http://app.test/src/a.ts?t=1")).toBe("/src/a.ts");
+    expect(normalizeSourcePath("/@fs/repo/src/a.ts")).toBe("/repo/src/a.ts");
+    expect(normalizeSourcePath("a.ts", "/app/src")).toBe("/app/src/a.ts");
+    expect(normalizeSourcePath("file:///app/src/a.ts")).toBe("/app/src/a.ts");
+    expect(isForeignSource("webpack/bootstrap")).toBe(true);
+    expect(isForeignSource("src/a.ts")).toBe(false);
+  });
+});
+
+test("lcovDocument is sorted, one record per file, merge sums", () => {
+  const files = new Map([["b.js", new Map([[2, 1]])], ["a.js", new Map([[1, 0], [3, 2]])]]);
+  mergeFileCounts(files, new Map([["a.js", new Map([[3, 1]])]]));
+  expect(lcovDocument(files)).toBe(
+    "TN:\nSF:a.js\nDA:1,0\nDA:3,3\nLF:2\nLH:1\nend_of_record\nSF:b.js\nDA:2,1\nLF:1\nLH:1\nend_of_record\n",
+  );
+});
+
+describe("serviceForHost", () => {
+  const table = {
+    proxies: [{ hostname: "app.test", service: "web" }],
+    aliasesByService: { api: ["api.todos.local"] },
+    wildcards: [
+      { pattern: "*.apps.test", target: { service: "k8s" } },
+      { pattern: "*.fake.test", target: { ingress: true } },
+    ],
+  };
+  const services = ["web", "api", "k8s"];
+  test("service key, .internal, alias, proxy, wildcard", () => {
+    expect(serviceForHost("web", services, table)).toBe("web");
+    expect(serviceForHost("WEB.internal", services, table)).toBe("web");
+    expect(serviceForHost("api.todos.local", services, table)).toBe("api");
+    expect(serviceForHost("app.test", services, table)).toBe("web");
+    expect(serviceForHost("a.b.apps.test", services, table)).toBe("k8s");
+    expect(serviceForHost("x.fake.test", services, table)).toBeUndefined();
+    expect(serviceForHost("example.com", services, table)).toBeUndefined();
+  });
+});

package/src/harness/browser-coverage.ts

@@ -0,0 +1,310 @@
+// 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`.
+
+/** 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>;
+
+// ── V8 precise coverage → generated line counts ─────────────────────────
+
+/** Byte offset at which each line starts. */
+export function lineStartsOf(source: string): number[] {
+  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: number[], offset: number): number {
+  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;
+}
+
+/** 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 function rangesToLineCounts(
+  source: string,
+  functions: readonly V8FunctionCoverage[],
+): LineCounts {
+  const starts = lineStartsOf(source);
+  const counts: LineCounts = 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;
+}
+
+// ── Source maps ─────────────────────────────────────────────────────────
+
+/** 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[][];
+}
+
+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: string): number[] {
+  const out: number[] = [];
+  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: string, sourceRoot?: string): string {
+  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: string): boolean {
+  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: unknown): DecodedSourceMap | null {
+  if (!doc || typeof doc !== "object") return null;
+  const m = doc as {
+    version?: number;
+    sources?: unknown;
+    sourceRoot?: unknown;
+    mappings?: unknown;
+    sections?: unknown;
+  };
+  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: Segment[][] = [];
+  let src = 0;
+  let line = 0;
+  try {
+    for (const group of m.mappings.split(";")) {
+      const segs: Segment[] = [];
+      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: DecodedSourceMap, generated: LineCounts): FileCounts {
+  const out: FileCounts = 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: LineCounts, from: LineCounts): void {
+  for (const [l, c] of from) into.set(l, (into.get(l) ?? 0) + c);
+}
+
+export function mergeFileCounts(into: FileCounts, from: FileCounts): void {
+  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: FileCounts): string {
+  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;
+}
+
+// ── Host → service ──────────────────────────────────────────────────────
+
+/** 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 function serviceForHost(
+  host: string,
+  services: readonly string[],
+  table: HostTable,
+): string | undefined {
+  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: { len: number; service: string } | undefined;
+  for (const w of table.wildcards) {
+    const service = (w.target as { service?: string }).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;
+}