@specific.dev/spectest 0.59.4 → 0.60.1

package/src/harness/coverage.ts

@@ -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";
@@ -211,3 +222,178 @@ export function coverageBundleRef(
     })),
   };
 }
+
+// ── delta ─────────────────────────────────────────────────────────
+
+/** 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 function parseLcovCounts(text: string): Map<string, LcovRecordCounts> {
+  const out = new Map<string, LcovRecordCounts>();
+  let cur: LcovRecordCounts | null = 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 file not in `prev`
+ * is new: everything in it counts. A **record in which any count went
+ * down** is a process that restarted (a restart resets every counter of
+ * that process at once): the whole record stands as-is, never
+ * subtracted — per line would report a line that ran exactly as often
+ * again as "not executed", and the restarted boot set (1 − 1) would
+ * vanish. Per record, not per report: a combined coverage.py file can
+ * hold several processes. A restart in which no counter dropped is not
+ * detectable from counts and is accepted as the residual (a service
+ * restarting mid-test is an anomaly already). Lines with a zero delta
+ * stay in the record: the server distinguishes "ran 0 times" from "not
+ * a counted line". Only records with at least one execution are kept —
+ * a file with nothing new in it did not run. `restarted` receives the
+ * paths of the records taken as-is.
+ */
+export function subtractLcovCounts(
+  now: Map<string, LcovRecordCounts>,
+  prev: Map<string, LcovRecordCounts>,
+  restarted?: string[],
+): Map<string, LcovRecordCounts> {
+  const out = new Map<string, LcovRecordCounts>();
+  for (const [file, rec] of now) {
+    const before = prev.get(file);
+    const dropped =
+      !!before &&
+      ([...rec.lines].some(([l, h]) => h < (before.lines.get(l) ?? 0)) ||
+        [...rec.functions].some(([n, h]) => h < (before.functions.get(n) ?? 0)));
+    if (dropped) restarted?.push(file);
+    const lines = new Map<number, number>();
+    const functions = new Map<string, number>();
+    let executed = false;
+    for (const [l, h] of rec.lines) {
+      const d = dropped ? h : h - (before?.lines.get(l) ?? 0);
+      lines.set(l, d);
+      if (d > 0) executed = true;
+    }
+    for (const [name, h] of rec.functions) {
+      const d = dropped ? h : h - (before?.functions.get(name) ?? 0);
+      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: Map<string, LcovRecordCounts>): string {
+  const parts: string[] = ["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<string, Map<string, Map<string, LcovRecordCounts>>>();
+
+/** Forget every previous capture (tests). */
+export function resetCoverageDeltaMemory(): void {
+  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: ServiceCoverageCapture,
+  mode: CoverageReportsMode,
+  deltaReports: ReadonlySet<string>,
+): ServiceCoverageCapture {
+  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: CoverageReport[] = [];
+  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<string, LcovRecordCounts>();
+    prevByName.set(r.name, now);
+    const restarted: string[] = [];
+    reports.push({ name: r.name, content: renderLcovCounts(subtractLcovCounts(now, prev, restarted)) });
+    if (restarted.length > 0) {
+      console.warn(
+        `[coverage] service "${capture.service}" report ${r.name}: counters dropped in ${restarted.length} file(s) (${restarted.slice(0, 3).join(", ")}) — a process restarted; those records count whole`,
+      );
+    }
+  }
+  return { ...capture, reports };
+}