feat(coverage): pnpm coverage:diff script + L1 implementation

Lands L1 of the agent-first coverage architecture (ADR-020) — the cover-the-diff gate. Reads a merged lcov + git diff against a base ref, asserts every changed *executable* line was exercised. Script: scripts/coverage/diff.mjs (zero-dep Node ESM) - parseLcov: SF -> Map<line, count>; only DA records read - parseGitDiff: parses --unified=0 output into Map<file, Set<line>> - computeDiffCoverage: cross-references both, emits result tree - Allowlist of paths that don't gate (tests, configs, docs, .sh, DI bootstrap, interfaces, CMS, factories, contracts, UI) - Path matching handles three lcov path conventions: absolute, repo-relative, and per-package relative - CLI flags: --base (default origin/main), --lcov (default coverage/lcov.info), --json (suppress stderr summary) - stdout: machine-readable JSON for the dispatch loop - stderr: human summary - Exit 0 on pass, 1 on fail or error Test surface: scripts/coverage/diff.test.mjs (14 tests, all green) - Fixtures at scripts/coverage/__fixtures__/{sample.lcov,sample-diff.patch} - Covers: lcov parsing, diff parsing, pass path, uncovered lines, non-executable line skipping, no-coverage-data detection, allowlist filtering, end-to-end mixed case, path matching Wired: - root package.json adds "coverage:diff" script - .gitignore anchored so per-package coverage/ stays ignored but scripts/coverage/ stays tracked Smoke-tested end-to-end against packages/auth/coverage/lcov.info — correctly skips shell scripts + manifest files (via allowlist + path suffix match), correctly flags files not present in the per-package lcov (which is expected; full repo coverage needs the L2 aggregate that the next story lands). CI integration deferred to the L2 aggregate story (the merged coverage/lcov.info this script reads doesn't exist yet — pnpm coverage:aggregate produces it). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-13 14:04:09 +02:00
parent f7baa8bfd1
commit 412d994733
6 changed files with 584 additions and 2 deletions
--- a/scripts/coverage/diff.mjs
+++ b/scripts/coverage/diff.mjs
@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// scripts/coverage/diff.mjs — L1 of the coverage architecture (ADR-020).
+//
+// Reads the merged lcov (`coverage/lcov.info`) and the working tree's git
+// diff against a base ref, then asserts cover-the-diff: every changed
+// *executable* line must have execution count > 0.
+//
+// Output:
+//   - stdout: JSON `{ status, summary, uncovered: [{ file, line, kind }] }`
+//     (machine-readable for the dispatch loop)
+//   - stderr: human summary
+// Exit: 0 on pass, 1 on fail.
+//
+// Usage:
+//   pnpm coverage:diff                        # default base: origin/main
+//   pnpm coverage:diff -- --base HEAD~1       # override base ref
+//   pnpm coverage:diff -- --lcov path/to.info # override lcov path
+//   pnpm coverage:diff -- --json              # JSON only (no stderr)
+//
+// Implementation: zero deps. Pure Node ESM + child_process + fs.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+/**
+ * Files that don't need diff-coverage gating. Test files, configs, docs,
+ * lockfiles, generated artifacts. Also covers the per-feature exclude
+ * patterns documented in vitest configs (DI bootstrap, interfaces, CMS
+ * collections, factories, contracts, UI).
+ */
+const ALLOWED_GLOBS = [
+  // Test artifacts
+  /\.test\.(ts|tsx|js|mjs)$/,
+  /\/__factories__\//,
+  /\/__contracts__\//,
+  /\/__fixtures__\//,
+  /\/__seeds__\//,
+  // Configs
+  /\.config\.(ts|js|mjs|cjs)$/,
+  /(^|\/)package\.json$/,
+  /(^|\/)tsconfig.*\.json$/,
+  /(^|\/)turbo\.json$/,
+  // Docs / data
+  /\.md$/,
+  /\.json$/,
+  /\.ya?ml$/,
+  /\.gitignore$/,
+  /\.npmrc$/,
+  // Shell scripts (not Vitest-covered)
+  /\.sh$/,
+  /\.bash$/,
+  // Per-package coverage excludes (mirror vitest config)
+  /\/di\/bind-production\.ts$/,
+  /\/application\/repositories\//,
+  /\/application\/services\//,
+  /\/integrations\/cms\//,
+  /\/ui\//,
+  // Pure type-alias / interface files (no executable code)
+  /\.interface\.ts$/,
+  /\/index\.ts$/, // barrel re-exports — no executable code
+  // Build artifacts
+  /\.tsbuildinfo$/,
+  /\.lock$/,
+  /(^|\/)dist\//,
+  /(^|\/)\.next\//,
+  /(^|\/)\.turbo\//,
+  /(^|\/)node_modules\//,
+  /(^|\/)coverage\//,
+];
+
+function isAllowed(file) {
+  return ALLOWED_GLOBS.some((re) => re.test(file));
+}
+
+/**
+ * Parse lcov into a map of file -> Map<lineNumber, executionCount>.
+ * Only DA records are read; LF/LH/BRDA/BRF/BRH/etc. are ignored.
+ *
+ * lcov is a simple line-oriented format:
+ *   SF:<file>
+ *   DA:<line>,<count>
+ *   ...
+ *   end_of_record
+ */
+export function parseLcov(text) {
+  const result = new Map();
+  let currentFile = null;
+  let currentLines = null;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("SF:")) {
+      currentFile = line.slice(3);
+      currentLines = new Map();
+      result.set(currentFile, currentLines);
+    } else if (line.startsWith("DA:") && currentLines) {
+      const [lineNo, count] = line.slice(3).split(",");
+      currentLines.set(Number(lineNo), Number(count));
+    } else if (line === "end_of_record") {
+      currentFile = null;
+      currentLines = null;
+    }
+  }
+  return result;
+}
+
+/**
+ * Parse `git diff --unified=0` output into a map of file -> Set<lineNumber>.
+ *
+ * Only NEW or MODIFIED lines in the new version are tracked (the `+N,M`
+ * portion of `@@ -A,B +N,M @@`). Removed-only hunks contribute no lines
+ * to check (the line is gone).
+ *
+ * Renamed files are tracked by their new path.
+ */
+export function parseGitDiff(text) {
+  const result = new Map();
+  let currentFile = null;
+  let currentLines = null;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("+++ ")) {
+      const p = line.slice(4).trim();
+      if (p === "/dev/null") {
+        currentFile = null;
+        currentLines = null;
+        continue;
+      }
+      // Strip `b/` prefix git adds
+      currentFile = p.startsWith("b/") ? p.slice(2) : p;
+      currentLines = new Set();
+      result.set(currentFile, currentLines);
+    } else if (line.startsWith("@@ ") && currentLines) {
+      // @@ -A,B +N,M @@
+      const m = /@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+      if (!m) continue;
+      const start = Number(m[1]);
+      const count = m[2] === undefined ? 1 : Number(m[2]);
+      if (count === 0) continue; // hunk has no lines in new version
+      for (let i = 0; i < count; i++) {
+        currentLines.add(start + i);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Given parsed lcov + parsed diff, return the list of uncovered hits.
+ * Each hit: { file, line, kind }
+ *   - kind = "uncovered": line is executable in lcov but count is 0
+ *   - kind = "no-coverage-data": file is not in lcov at all
+ *   - kind = "non-executable": line has no DA record (not flagged; for
+ *     visibility only, currently filtered out)
+ */
+export function computeDiffCoverage(diff, lcov, opts = {}) {
+  const repoRoot = opts.repoRoot ?? process.cwd();
+  const uncovered = [];
+  const fileSummaries = [];
+
+  for (const [file, lines] of diff) {
+    if (isAllowed(file)) continue;
+
+    // Match lcov keys (absolute paths) to diff keys (repo-relative)
+    let lcovLines = lcov.get(file);
+    if (!lcovLines) {
+      const abs = path.resolve(repoRoot, file);
+      lcovLines = lcov.get(abs);
+    }
+    if (!lcovLines) {
+      // Try matching by suffix in either direction. lcov paths can be:
+      //   - absolute (vitest with `coverage.reportsDirectory` at default)
+      //   - repo-relative (after `pnpm coverage:aggregate` normalizes)
+      //   - package-relative (per-package lcov from `pnpm test -- --coverage`)
+      // The diff path is always repo-relative.
+      for (const [k, v] of lcov.entries()) {
+        if (file.endsWith("/" + k) || k.endsWith("/" + file) || k === file) {
+          lcovLines = v;
+          break;
+        }
+      }
+    }
+
+    if (!lcovLines) {
+      uncovered.push({ file, line: 0, kind: "no-coverage-data" });
+      fileSummaries.push({ file, changed: lines.size, missed: lines.size });
+      continue;
+    }
+
+    let missedInFile = 0;
+    for (const line of [...lines].sort((a, b) => a - b)) {
+      const count = lcovLines.get(line);
+      if (count === undefined) {
+        // Line isn't executable per lcov — skip (blank, comment, type-only)
+        continue;
+      }
+      if (count === 0) {
+        uncovered.push({ file, line, kind: "uncovered" });
+        missedInFile++;
+      }
+    }
+    fileSummaries.push({ file, changed: lines.size, missed: missedInFile });
+  }
+
+  return {
+    status: uncovered.length === 0 ? "pass" : "fail",
+    summary: {
+      filesChanged: diff.size,
+      filesGated: fileSummaries.length,
+      uncoveredCount: uncovered.length,
+    },
+    fileSummaries,
+    uncovered,
+  };
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const out = { base: "origin/main", lcov: "coverage/lcov.info", json: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--base") out.base = argv[++i];
+    else if (a === "--lcov") out.lcov = argv[++i];
+    else if (a === "--json") out.json = true;
+    else if (a === "--help" || a === "-h") {
+      console.log(
+        "Usage: pnpm coverage:diff [-- --base <ref>] [--lcov <path>] [--json]",
+      );
+      process.exit(0);
+    }
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const repoRoot = process.cwd();
+
+  // Load lcov
+  const lcovPath = path.resolve(repoRoot, args.lcov);
+  if (!fs.existsSync(lcovPath)) {
+    process.stderr.write(
+      `[coverage:diff] lcov file not found at ${lcovPath}\n` +
+        `Run \`pnpm test -- --coverage\` first, then \`pnpm coverage:aggregate\`.\n`,
+    );
+    // Emit JSON anyway so the dispatch loop can read it
+    process.stdout.write(
+      JSON.stringify({ status: "error", reason: "lcov-missing", lcovPath }) +
+        "\n",
+    );
+    process.exit(1);
+  }
+  const lcov = parseLcov(fs.readFileSync(lcovPath, "utf8"));
+
+  // Get diff
+  let diffText;
+  try {
+    diffText = execSync(`git diff --unified=0 --no-color ${args.base}...HEAD`, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[coverage:diff] git diff against base "${args.base}" failed: ${err.message}\n`,
+    );
+    process.stdout.write(
+      JSON.stringify({ status: "error", reason: "git-diff-failed" }) + "\n",
+    );
+    process.exit(1);
+  }
+  const diff = parseGitDiff(diffText);
+
+  // Compute
+  const result = computeDiffCoverage(diff, lcov, { repoRoot });
+
+  // Emit JSON to stdout
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+
+  // Emit human summary to stderr (unless --json)
+  if (!args.json) {
+    const { status, summary, uncovered } = result;
+    if (status === "pass") {
+      process.stderr.write(
+        `[coverage:diff] PASS — ${summary.filesGated} file(s) gated, all changed lines covered.\n`,
+      );
+    } else {
+      process.stderr.write(
+        `[coverage:diff] FAIL — ${summary.uncoveredCount} uncovered hit(s) across ${summary.filesGated} file(s):\n`,
+      );
+      const byFile = new Map();
+      for (const u of uncovered) {
+        if (!byFile.has(u.file)) byFile.set(u.file, []);
+        byFile.get(u.file).push(u);
+      }
+      for (const [file, hits] of byFile) {
+        const noData = hits[0]?.kind === "no-coverage-data";
+        if (noData) {
+          process.stderr.write(
+            `  ${file}\n    no coverage data (new untested file?)\n`,
+          );
+        } else {
+          const lines = hits.map((h) => h.line).join(", ");
+          process.stderr.write(`  ${file}\n    uncovered lines: ${lines}\n`);
+        }
+      }
+    }
+  }
+
+  process.exit(result.status === "pass" ? 0 : 1);
+}
+
+// Only run main when invoked directly (not when imported by tests)
+const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+  main();
+}