Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* scripts/coverage-diff-gate.ts — changed-line coverage gate (containment
* sprint). Verifies that lines ADDED/CHANGED by this branch are executed by
* the merged PR test corpus.
*
* Usage:
* bun scripts/coverage-diff-gate.ts --summary <merged json> [--base <ref>]
* --summary JSON artifact written by scripts/merge-lcov.ts (its
* lineHits extension key is the per-line input; this gate
* never re-parses lcov text and never stdout-parses tools)
* --base diff base ref (default origin/master)
*
* Behavior:
* a. `bun scripts/select-e2e.ts --classify-only`: EMPTY|DOC_ONLY → PASS.
* b. Diff scope: `git diff --unified=0 <base>...HEAD -- src`, filtered in
* code to *.ts minus *.test.ts / *.generated.ts / *.d.ts. (The in-code
* filter, not a 'src/**\/*.ts' pathspec, because git's default fnmatch
* for that pattern misses top-level files like src/cli.ts.) Paths in
* scripts/coverage-gate-exemptions.txt AS IT EXISTS ON origin/master
* (mirroring the baseline-gate's governance — a PR cannot add its own
* files to the list and self-exempt; working-tree additions are inert
* until merged) are excluded from the gate but still REPORTED with
* their tag. If the file is absent on master (first landing) the
* working-tree copy is used; if git itself fails, exit 2 infra unless
* report-only (which warns and falls back to the working tree).
* c. Zero gate-scoped changed lines → PASS.
* d. Per changed file with a coverage record: added line present in DA
* with hits>0 → covered; present with 0 → uncovered; absent from DA →
* non-executable (excluded). A gate-scoped changed file with NO record
* is ONE violation ("never loaded by any test in the PR corpus — add a
* test that imports it"); its physical line count is deliberately NOT
* used.
* e. Verdict: covered/(covered+uncovered) >= 0.80 AND zero never-loaded
* violations.
* f. Escape hatch: any commit body in <base>..HEAD containing
* '[coverage-exempt:' → PASS with a loud warning.
* g. Degraded summary → report-only for this run (DEGRADED banner,
* verdict printed, exit 0).
* h. COVERAGE_GATE_ENFORCE: anything but '1' = report-only (WOULD
* PASS/WOULD FAIL + per-file table, exit 0); '1' = exit 1 on fail.
* i. Exit codes: 0 pass/report-only; 1 gate fail (enforcing); 2
* infrastructure error (missing summary, git failure, unresolvable
* base).
*
* Test seams (fixture injection; production ignores them when unset):
* COVERAGE_GATE_CLASSIFY literal EMPTY|DOC_ONLY|SRC (skips select-e2e)
* COVERAGE_GATE_DIFF_FILE path to unified-diff text (skips git diff)
* COVERAGE_GATE_COMMITS_FILE path to commit-message text (skips git log)
* COVERAGE_GATE_EXEMPTIONS_OVERRIDE literal exemptions-file CONTENT; wins
* over both origin/master and the working tree
*/
import { spawnSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
// ---------------------------------------------------------------------------
// Diff parsing
// ---------------------------------------------------------------------------
/**
* Parse `git diff --unified=0` text into new-side added/changed line numbers
* per file. Deletions (`+++ /dev/null`) are skipped; a hunk `@@ -a,b +c,d @@`
* contributes lines c..c+d-1 (d defaults to 1; d=0 contributes nothing).
*/
export function parseUnifiedDiff(text: string): Map<string, number[]> {
const out = new Map<string, number[]>();
let current: string | null = null;
for (const line of text.split("\n")) {
if (line.startsWith("+++ ")) {
const p = line.slice(4).trim();
current = p === "/dev/null" ? null : p.replace(/^b\//, "");
continue;
}
if (!current) continue;
const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
if (!m) continue;
const start = parseInt(m[1]!, 10);
const count = m[2] === undefined ? 1 : parseInt(m[2]!, 10);
if (count <= 0) continue;
const arr = out.get(current) ?? [];
for (let i = 0; i < count; i++) arr.push(start + i);
out.set(current, arr);
}
return out;
}
// ---------------------------------------------------------------------------
// Exemptions
// ---------------------------------------------------------------------------
export interface Exemptions {
exact: Set<string>;
prefixes: string[];
}
export function parseExemptions(text: string): Exemptions {
const exact = new Set<string>();
const prefixes: string[] = [];
for (const raw of text.split("\n")) {
const line = raw.trim();
if (line === "" || line.startsWith("#")) continue;
if (line.endsWith("/")) prefixes.push(line);
else exact.add(line);
}
return { exact, prefixes };
}
export function isExempt(path: string, ex: Exemptions): boolean {
if (ex.exact.has(path)) return true;
return ex.prefixes.some((p) => path.startsWith(p));
}
/** Gate scope: src/ TypeScript, excluding tests/generated/declarations. */
export function isGateScopedPath(path: string): boolean {
return (
path.startsWith("src/") &&
path.endsWith(".ts") &&
!path.endsWith(".test.ts") &&
!path.endsWith(".generated.ts") &&
!path.endsWith(".d.ts")
);
}
// ---------------------------------------------------------------------------
// Reporting
// ---------------------------------------------------------------------------
interface FileRow {
file: string;
added: number;
covered: number | null;
uncovered: number | null;
uncoveredLines: number[];
status: string;
}
function formatLineList(lines: number[]): string {
const shown = lines.slice(0, 20).map((l) => `L${l}`);
const extra = lines.length > 20 ? `, +${lines.length - 20} more` : "";
return shown.join(", ") + extra;
}
function printTable(rows: FileRow[]): void {
if (rows.length === 0) return;
console.log("");
console.log("| file | added lines | covered | uncovered | status |");
console.log("|---|---|---|---|---|");
for (const r of rows) {
const cov = r.covered === null ? "-" : String(r.covered);
const unc =
r.uncovered === null
? "-"
: r.uncoveredLines.length > 0
? `${r.uncovered} (${formatLineList(r.uncoveredLines)})`
: String(r.uncovered);
console.log(`| ${r.file} | ${r.added} | ${cov} | ${unc} | ${r.status} |`);
}
console.log("");
}
// ---------------------------------------------------------------------------
// main
// ---------------------------------------------------------------------------
function infraFail(msg: string): never {
process.stderr.write(`coverage-diff-gate: infrastructure error: ${msg}\n`);
process.exit(2);
}
function runGit(args: string[]): string {
const res = spawnSync("git", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
if (res.error || res.status !== 0) {
infraFail(`git ${args.join(" ")} failed: ${res.error ? String(res.error) : (res.stderr || "").trim()}`);
}
return res.stdout;
}
const EXEMPTIONS_REPO_PATH = "scripts/coverage-gate-exemptions.txt";
/**
* Resolve the exemption LIST from origin/master, never the working tree —
* mirroring coverage-baseline-gate.ts's governance. Otherwise a PR could add
* its own files to the list and self-exempt from the 80% gate the moment
* enforcement graduates. Working-tree additions are INERT until merged.
*
* Resolution order:
* 1. COVERAGE_GATE_EXEMPTIONS_OVERRIDE (test seam; literal file content).
* 2. `git show origin/master:scripts/coverage-gate-exemptions.txt`.
* 3. Path absent on master (first landing) → working-tree copy.
* 4. git itself failed (unresolvable ref, ...) → exit 2 infra when
* enforcing; report-only warns and falls back to the working tree so
* the report still prints.
*/
function resolveExemptionsText(enforcing: boolean): string {
const override = process.env.COVERAGE_GATE_EXEMPTIONS_OVERRIDE;
if (override !== undefined) return override;
const res = spawnSync("git", ["show", `origin/master:${EXEMPTIONS_REPO_PATH}`], {
encoding: "utf8",
maxBuffer: 16 * 1024 * 1024,
});
if (!res.error && res.status === 0) return res.stdout;
const stderr = res.error ? String(res.error) : res.stderr || "";
const worktreePath = join(import.meta.dir, "coverage-gate-exemptions.txt");
const readWorktree = (): string => {
if (!existsSync(worktreePath)) infraFail(`exemptions file missing: ${worktreePath}`);
return readFileSync(worktreePath, "utf8");
};
// Path errors mean the ref resolved but the file is not on master yet.
if (!res.error && /does not exist in|exists on disk, but not in/.test(stderr)) {
return readWorktree();
}
if (enforcing) {
infraFail(`cannot read ${EXEMPTIONS_REPO_PATH} from origin/master: ${stderr.trim()}`);
}
process.stderr.write(
`coverage-diff-gate: warning: cannot read ${EXEMPTIONS_REPO_PATH} from origin/master (${stderr.trim()}) — report-only run falls back to the working-tree copy\n`,
);
return readWorktree();
}
interface SummaryJson {
degraded?: boolean;
files?: Record<string, { lines: number; covered: number; pct: number }>;
lineHits?: Record<string, Record<string, number>>;
}
function main(): void {
const argv = process.argv.slice(2);
let summaryPath = "";
let base = "origin/master";
for (let i = 0; i < argv.length; i++) {
const a = argv[i]!;
if (a === "--summary") summaryPath = argv[++i] ?? "";
else if (a === "--base") base = argv[++i] ?? "origin/master";
else infraFail(`unknown argument: ${a}`);
}
if (!summaryPath) infraFail("--summary <merged json> is required");
if (!existsSync(summaryPath)) infraFail(`summary JSON not found: ${summaryPath}`);
const enforcing = process.env.COVERAGE_GATE_ENFORCE === "1";
let summary: SummaryJson;
try {
summary = JSON.parse(readFileSync(summaryPath, "utf8")) as SummaryJson;
} catch (err) {
infraFail(`summary JSON unparseable: ${String(err)}`);
}
// (a) change classification — doc-only/empty diffs are not gated.
let classification = process.env.COVERAGE_GATE_CLASSIFY ?? "";
if (!classification) {
const res = spawnSync("bun", ["scripts/select-e2e.ts", "--classify-only"], { encoding: "utf8" });
if (res.error || res.status !== 0) {
infraFail(`select-e2e --classify-only failed: ${res.error ? String(res.error) : (res.stderr || "").trim()}`);
}
classification = res.stdout.trim();
} else {
classification = classification.trim();
}
if (classification === "EMPTY" || classification === "DOC_ONLY") {
console.log(`PASS: change classified ${classification} — coverage diff gate not applicable.`);
process.exit(0);
}
// (b) diff scope.
const diffFile = process.env.COVERAGE_GATE_DIFF_FILE;
let diffText: string;
if (diffFile) {
if (!existsSync(diffFile)) infraFail(`COVERAGE_GATE_DIFF_FILE not found: ${diffFile}`);
diffText = readFileSync(diffFile, "utf8");
} else {
diffText = runGit(["diff", "--unified=0", `${base}...HEAD`, "--", "src"]);
}
const changed = parseUnifiedDiff(diffText);
const exemptions = parseExemptions(resolveExemptionsText(enforcing));
const rows: FileRow[] = [];
let covered = 0;
let uncovered = 0;
let neverLoadedViolations = 0;
let gatedChangedLines = 0;
const lineHits = summary.lineHits;
const filesWithRecords = new Set([
...Object.keys(summary.files ?? {}),
...Object.keys(lineHits ?? {}),
]);
const scopedFiles = [...changed.keys()].filter(isGateScopedPath).sort();
for (const file of scopedFiles) {
const addedLines = changed.get(file)!;
if (isExempt(file, exemptions)) {
// Exempt: reported, never gated. The CLI entry and dispatcher get their own honest tag.
const tag = file === "src/cli.ts" || file === "src/cli/main.ts" ? "[subprocess-undercount]" : "[e2e-exempt]";
rows.push({ file, added: addedLines.length, covered: null, uncovered: null, uncoveredLines: [], status: tag });
continue;
}
gatedChangedLines += addedLines.length;
if (!filesWithRecords.has(file)) {
// (d) no coverage record at all: ONE violation; do NOT count physical lines.
neverLoadedViolations++;
rows.push({
file,
added: addedLines.length,
covered: null,
uncovered: null,
uncoveredLines: [],
status: "VIOLATION: never loaded by any test in the PR corpus — add a test that imports it",
});
continue;
}
if (!lineHits) {
infraFail("summary JSON has no lineHits key — regenerate it with the current scripts/merge-lcov.ts");
}
const da = lineHits[file] ?? {};
let fileCovered = 0;
const fileUncoveredLines: number[] = [];
for (const line of addedLines) {
const hits = da[String(line)];
if (hits === undefined) continue; // non-executable — excluded
if (hits > 0) fileCovered++;
else fileUncoveredLines.push(line);
}
covered += fileCovered;
uncovered += fileUncoveredLines.length;
rows.push({
file,
added: addedLines.length,
covered: fileCovered,
uncovered: fileUncoveredLines.length,
uncoveredLines: fileUncoveredLines,
status: "gated",
});
}
// (c) zero gate-scoped changed lines.
if (gatedChangedLines === 0) {
printTable(rows); // exempt-only changes still get reported
console.log("PASS: no gate-scoped changes.");
process.exit(0);
}
// (e) verdict.
const denom = covered + uncovered;
const ratio = denom === 0 ? 1 : covered / denom;
const pass = ratio >= 0.8 - 1e-9 && neverLoadedViolations === 0;
const pctStr = (ratio * 100).toFixed(2);
printTable(rows);
console.log(`Changed-line coverage: ${covered}/${denom} = ${pctStr}% (threshold 80%)`);
if (neverLoadedViolations > 0) {
console.log(`Never-loaded gate-scoped files: ${neverLoadedViolations} (each is a violation)`);
}
// (f) escape hatch trailer.
const commitsFile = process.env.COVERAGE_GATE_COMMITS_FILE;
let commitsText: string;
if (commitsFile) {
if (!existsSync(commitsFile)) infraFail(`COVERAGE_GATE_COMMITS_FILE not found: ${commitsFile}`);
commitsText = readFileSync(commitsFile, "utf8");
} else {
commitsText = runGit(["log", `${base}..HEAD`, "--format=%B"]);
}
if (commitsText.includes("[coverage-exempt:")) {
console.log("");
console.log("WARNING: '[coverage-exempt:' trailer found in a commit body — coverage diff gate BYPASSED for this branch.");
console.log(`PASS (escape hatch): verdict without the trailer would have been ${pass ? "PASS" : "FAIL"}.`);
process.exit(0);
}
// (g) degraded coverage data → report-only for this run.
if (summary.degraded === true) {
console.log("");
console.log("DEGRADED: coverage data is degraded (lane incomplete/malformed) — gate downgraded to report-only for this run.");
console.log(`Verdict: ${pass ? "WOULD PASS" : "WOULD FAIL"}`);
process.exit(0);
}
// (h) enforcement.
if (!enforcing) {
console.log(`Report-only (COVERAGE_GATE_ENFORCE != '1'): ${pass ? "WOULD PASS" : "WOULD FAIL"}`);
process.exit(0);
}
if (pass) {
console.log("PASS: changed-line coverage gate.");
process.exit(0);
}
console.log("FAIL: changed-line coverage below 80% or never-loaded files present.");
process.exit(1);
}
if (import.meta.main) main();