coverage-check 0.5.0 → 0.6.0

package/README.md

@@ -135,6 +135,33 @@ rules:
 
 Rules are matched in order; the first match wins. Files in the diff not matched by any rule are reported as informational (not gated).
 
+### `no_coverage_drop`
+
+Add `no_coverage_drop: true` to a rule to also gate total line-coverage regression — not just patch lines. When enabled, the check fails if the overall line-coverage percentage of files matched by that rule falls below the `main` baseline stored in the suite store.
+
+```yaml
+rules:
+  - paths: backend/scripts/**
+    patch_coverage_min: 0 # exempt from patch gate
+  - paths: backend/**
+    patch_coverage_min: 95
+    no_coverage_drop: true # also gate overall regression
+  - paths: web/**
+    patch_coverage_min: 80
+    no_coverage_drop: true
+    max_coverage_drop: 0.5 # allow up to 0.5 percentage-point drop
+```
+
+`max_coverage_drop` (default `0`) sets the tolerance in percentage points. First-match-wins applies: `backend/scripts/**` files are matched by the earlier rule and are not included in the `backend/**` total.
+
+**Requirements:**
+
+- A suite store (`--store-s3` or `--store-fs`) must be configured on the `check` command.
+- A baseline must exist in the store (written by `store-put --sha ... --branch main` on main pushes).
+- When no baseline is available (e.g. fork PRs without store access), the no-drop check is **skipped non-blockingly** with a warning — the patch coverage gate still runs.
+
+First-match-wins means that if you have a more specific rule before a broader one (e.g. `backend/scripts/**` before `backend/**`), only files matched by the broader rule's first-match contribute to its total — scripts are excluded from the broader `backend/**` aggregate.
+
 ## CLI reference
 
 ### `coverage-check check`

package/dist/src/commands/check-output.d.mts

@@ -0,0 +1,6 @@
+import type { DropResult, DiffLines, LcovData } from "../types.mts";
+export declare function warnNonContributing(parsedSources: {
+    name: string;
+    lcov: LcovData;
+}[], diff: DiffLines): void;
+export declare function printDropOutput(drops: DropResult[]): void;

package/dist/src/commands/check-output.mjs

@@ -0,0 +1,54 @@
+const stdout = (msg) => process.stdout.write(`${msg}\n`);
+const stderr = (msg) => process.stderr.write(`${msg}\n`);
+function fmtPct(n) {
+    return n === null ? "—" : `${n.toFixed(2)}%`;
+}
+function fmtDrop(n) {
+    /* c8 ignore next -- failing drops always have non-null drop (drop===null implies passed===true) */
+    return n === null ? "—" : `${n.toFixed(2)}pp`;
+}
+function lcovContributesToDiff(sourceLcov, diff) {
+    for (const [file, changedLines] of diff) {
+        const fileLines = sourceLcov.get(file);
+        if (fileLines) {
+            for (const lineNo of changedLines) {
+                if (fileLines.has(lineNo))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+export function warnNonContributing(parsedSources, diff) {
+    if (diff.size === 0)
+        return;
+    for (const { name, lcov: sourceLcov } of parsedSources) {
+        if (!lcovContributesToDiff(sourceLcov, diff)) {
+            stderr(`coverage-check: warning: coverage from ${name} contributed 0 coverable lines to the patch result. This may indicate a path prefix mismatch.`);
+        }
+    }
+}
+export function printDropOutput(drops) {
+    if (drops.length === 0)
+        return;
+    const skippedDrops = drops.filter((d) => d.skipped);
+    const failingDrops = drops.filter((d) => !d.passed && !d.skipped);
+    const passingDrops = drops.filter((d) => d.passed && !d.skipped);
+    if (skippedDrops.length > 0) {
+        stdout("\ncoverage-check: coverage drop check skipped (no baseline)\n");
+        for (const d of skippedDrops) {
+            stdout(`  ${d.rule}: no baseline available`);
+        }
+    }
+    if (failingDrops.length > 0) {
+        stdout("\ncoverage-check: COVERAGE REGRESSION\n");
+        for (const d of failingDrops) {
+            stdout(`  ${d.rule}: ${fmtPct(d.currentPct)} (was ${fmtPct(d.baselinePct)}, dropped ${fmtDrop(d.drop)}, max allowed ${d.maxDrop}pp)`);
+        }
+    }
+    if (passingDrops.length > 0) {
+        for (const d of passingDrops) {
+            stdout(`  ${d.rule}: ${fmtPct(d.currentPct)} (baseline ${fmtPct(d.baselinePct)}) ✓`);
+        }
+    }
+}

package/dist/src/commands/check.mjs

@@ -5,11 +5,13 @@ import { getChangedLines } from "../diff-parser.mjs";
 import { getChangedLineContent } from "../diff-parser-content.mjs";
 import { loadRules } from "../rules.mjs";
 import { computePatchCoverage } from "../patch-coverage.mjs";
+import { computeCoverageDrop } from "../coverage-drop.mjs";
 import { collapseRanges, renderFailureComment } from "../report.mjs";
 import { upsertComment } from "../github-comment.mjs";
 import { collectLcovFiles, buildStripPrefixes } from "../load-artifacts.mjs";
 import { writeSummary } from "../step-summary.mjs";
 import { parseCheckArgs } from "./check-args.mjs";
+import { warnNonContributing, printDropOutput } from "./check-output.mjs";
 const stdout = (msg) => process.stdout.write(`${msg}\n`);
 const stderr = (msg) => process.stderr.write(`${msg}\n`);
 export async function main(argv) {
@@ -86,30 +88,27 @@ export async function runCheck(args) {
         stderr(`coverage-check: git diff failed: ${err}`);
         return 2;
     }
-    if (diff.size > 0) {
-        for (const { name, lcov: sourceLcov } of parsedSources) {
-            let contributes = false;
-            for (const [file, changedLines] of diff) {
-                const fileLines = sourceLcov.get(file);
-                if (fileLines) {
-                    for (const lineNo of changedLines) {
-                        if (fileLines.has(lineNo)) {
-                            contributes = true;
-                            break;
-                        }
-                    }
-                }
-                if (contributes)
-                    break;
-            }
-            if (!contributes) {
-                stderr(`coverage-check: warning: coverage from ${name} contributed 0 coverable lines to the patch result. This may indicate a path prefix mismatch.`);
+    warnNonContributing(parsedSources, diff);
+    let baseline = null;
+    if (args.store !== null) {
+        try {
+            const suites = await args.store.list();
+            const baselineReports = (await Promise.all(suites.map(async (suite) => {
+                const buf = await args.store.get(suite, { branch });
+                return buf === null ? null : parseLcov(buf.toString("utf8"), stripPrefixes);
+            }))).filter((report) => report !== null);
+            if (baselineReports.length > 0) {
+                baseline = mergeLcov(baselineReports);
             }
         }
+        catch (err) {
+            stderr(`coverage-check: warning: failed to load baseline from store: ${String(err)}`);
+        }
     }
     const { buckets, informational } = computePatchCoverage(diff, lcov, rules);
-    const passed = buckets.every((b) => b.passed);
-    const result = { buckets, informational, passed };
+    const drops = computeCoverageDrop(lcov, baseline, rules);
+    const passed = buckets.every((b) => b.passed) && drops.every((d) => d.passed || d.skipped);
+    const result = { buckets, drops, informational, passed };
     if (args.json) {
         writeFileSync(args.json, JSON.stringify(result, null, 2));
     }
@@ -145,6 +144,7 @@ export async function runCheck(args) {
             stdout(`  ${bucket.rule}: ${pct} ✓`);
         }
     }
+    printDropOutput(drops);
     const summaryFile = args.summaryFile !== undefined
         ? args.summaryFile
         : (process.env["GITHUB_STEP_SUMMARY"] ?? null);

package/dist/src/coverage-check.d.mts

@@ -7,4 +7,5 @@ export type { CheckArgs } from "./commands/check.mts";
 export type { StorePutArgs } from "./commands/store-put.mts";
 export type { SuiteStore, SuiteMeta } from "./suite-store.mts";
 export type { S3SuiteStoreOptions } from "./s3-suite-store.mts";
-export type { CoverageCheckResult, BucketResult, FileCoverageResult, LcovData, DiffLines, DiffLineContent, CoverageRule, } from "./types.mts";
+export { computeCoverageDrop } from "./coverage-drop.mts";
+export type { CoverageCheckResult, BucketResult, DropResult, FileCoverageResult, LcovData, DiffLines, DiffLineContent, CoverageRule, } from "./types.mts";

package/dist/src/coverage-check.mjs

@@ -3,3 +3,4 @@ export { runStorePut } from "./commands/store-put.mjs";
 export { FileSystemSuiteStore } from "./suite-store.mjs";
 export { S3SuiteStore } from "./s3-suite-store.mjs";
 export { parseDiffWithContent, getChangedLineContent } from "./diff-parser-content.mjs";
+export { computeCoverageDrop } from "./coverage-drop.mjs";

package/dist/src/coverage-drop.d.mts

@@ -0,0 +1,2 @@
+import type { CoverageRule, DropResult, LcovData } from "./types.mts";
+export declare function computeCoverageDrop(current: LcovData, baseline: LcovData | null, rules: CoverageRule[]): DropResult[];

package/dist/src/coverage-drop.mjs

@@ -0,0 +1,39 @@
+import { matchRule } from "./rules.mjs";
+function fileTotals(lcov, targetRule, allRules) {
+    let hit = 0;
+    let total = 0;
+    for (const [file, lines] of lcov) {
+        if (matchRule(file, allRules) !== targetRule)
+            continue;
+        for (const count of lines.values()) {
+            total++;
+            if (count > 0)
+                hit++;
+        }
+    }
+    return { hit, total };
+}
+export function computeCoverageDrop(current, baseline, rules) {
+    const dropRules = rules.filter((r) => r.no_coverage_drop);
+    return dropRules.map((rule) => {
+        const maxDrop = rule.max_coverage_drop ?? 0;
+        if (baseline === null) {
+            return {
+                rule: rule.paths,
+                currentPct: null,
+                baselinePct: null,
+                drop: null,
+                maxDrop,
+                passed: true,
+                skipped: true,
+            };
+        }
+        const cur = fileTotals(current, rule, rules);
+        const base = fileTotals(baseline, rule, rules);
+        const currentPct = cur.total === 0 ? null : (cur.hit / cur.total) * 100;
+        const baselinePct = base.total === 0 ? null : (base.hit / base.total) * 100;
+        const drop = currentPct !== null && baselinePct !== null ? baselinePct - currentPct : null;
+        const passed = drop === null || drop <= maxDrop + 1e-9;
+        return { rule: rule.paths, currentPct, baselinePct, drop, maxDrop, passed, skipped: false };
+    });
+}

package/dist/src/report.mjs

@@ -31,6 +31,29 @@ function renderFileList(files) {
         .map((f) => `- \`${f.file}\`: ${collapseRanges(f.uncoveredLines)}`)
         .join("\n");
 }
+function pctOrDash(n) {
+    /* c8 ignore next -- failing drops always have non-null currentPct/baselinePct */
+    return n === null ? "—" : `${n.toFixed(2)}%`;
+}
+function dropOrDash(n) {
+    /* c8 ignore next -- failing drops always have non-null drop */
+    return n === null ? "—" : `${n.toFixed(2)}pp`;
+}
+function renderRegressionSection(drops) {
+    const failingDrops = drops.filter((d) => !d.passed && !d.skipped);
+    if (failingDrops.length === 0)
+        return "";
+    const rows = failingDrops.map((d) => {
+        const safeRule = d.rule.replaceAll("|", "\\|").replaceAll("`", "\\`");
+        return `| \`${safeRule}\` | ${pctOrDash(d.currentPct)} | ${pctOrDash(d.baselinePct)} | ${dropOrDash(d.drop)} | ${d.maxDrop}pp |`;
+    });
+    const table = [
+        "| Rule | Current | Baseline | Drop | Max allowed |",
+        "|---|---|---|---|---|",
+        ...rows,
+    ].join("\n");
+    return `\n### Coverage regression\n\n${table}`;
+}
 export function renderFailureComment(result, runUrl, now = new Date().toISOString()) {
     const failingBuckets = result.buckets.filter((b) => !b.passed);
     const table = [
@@ -51,6 +74,7 @@ export function renderFailureComment(result, runUrl, now = new Date().toISOStrin
     const informationalSection = informationalLines.length > 0
         ? `\n<details><summary>Informational (no rule)</summary>\n\n${informationalLines}\n</details>`
         : "";
+    const regressionSection = renderRegressionSection(result.drops);
     return `${COMMENT_MARKER}
 ## Patch coverage gate failed
 
@@ -59,7 +83,7 @@ ${table}
 ### Uncovered lines
 
 ${sections}
-${informationalSection}
+${informationalSection}${regressionSection}
 
 _Last updated: ${now} · [Workflow run](${runUrl})_`;
 }

package/dist/src/rules.mjs

@@ -2,6 +2,21 @@
 import { readFileSync } from "node:fs";
 import { matchesGlob } from "node:path";
 import yaml from "js-yaml";
+function validateDropRuleFields(rule, i, rulesPath) {
+    const noDrop = rule.no_coverage_drop;
+    if (noDrop !== undefined && typeof noDrop !== "boolean") {
+        throw new Error(`${rulesPath}: rule[${i}].no_coverage_drop must be a boolean`);
+    }
+    const maxDrop = rule.max_coverage_drop;
+    if (maxDrop !== undefined) {
+        if (!Number.isFinite(maxDrop) || maxDrop < 0) {
+            throw new Error(`${rulesPath}: rule[${i}].max_coverage_drop must be a non-negative number`);
+        }
+        if (!noDrop) {
+            throw new Error(`${rulesPath}: rule[${i}].max_coverage_drop requires no_coverage_drop: true`);
+        }
+    }
+}
 export function loadRules(rulesPath) {
     const text = readFileSync(rulesPath, "utf8");
     const parsed = yaml.load(text);
@@ -17,6 +32,7 @@ export function loadRules(rulesPath) {
         if (!Number.isFinite(min) || min < 0 || min > 100) {
             throw new Error(`${rulesPath}: rule[${i}].patch_coverage_min must be a number between 0 and 100`);
         }
+        validateDropRuleFields(rule, i, rulesPath);
     }
     return parsed.rules;
 }

package/dist/src/step-summary.mjs

@@ -52,18 +52,33 @@ export function buildSummaryMarkdown(suiteSources, result, runUrl, branch = "mai
         "|---|---|---|---|",
         ruleRows || "| — | — | — | — |",
     ].join("\n");
+    let dropSection = "";
+    if (result.drops.length > 0) {
+        const dropRows = result.drops
+            .map((d) => {
+            let status;
+            if (d.skipped)
+                status = "⏭️";
+            else if (d.passed)
+                status = "✅";
+            else
+                status = "❌";
+            const baselinePct = d.baselinePct === null ? "—" : `${d.baselinePct.toFixed(2)}%`;
+            const currentPct = d.currentPct === null ? "—" : `${d.currentPct.toFixed(2)}%`;
+            const drop = d.drop === null ? "—" : `${d.drop.toFixed(2)}pp`;
+            return `| ${codeSpan(d.rule)} | ${d.maxDrop}pp | ${baselinePct} | ${currentPct} | ${drop} | ${status} |`;
+        })
+            .join("\n");
+        const dropTable = [
+            "| Rule | Max drop | Baseline | Current | Drop | Status |",
+            "|---|---|---|---|---|---|",
+            dropRows,
+        ].join("\n");
+        dropSection = `\n### Coverage drop\n\n${dropTable}\n`;
+    }
     const overall = result.passed ? "✅ passed" : "❌ failed";
     const runLink = runUrl !== "N/A" ? `\n\n_[View run](${runUrl})_` : "";
-    return `## Coverage summary — ${overall}
-
-### Suite totals
-
-${suiteTable}
-
-### Patch coverage
-
-${ruleTable}${runLink}
-`;
+    return `## Coverage summary — ${overall}\n\n### Suite totals\n\n${suiteTable}\n\n### Patch coverage\n\n${ruleTable}${dropSection}${runLink}\n`;
 }
 export function writeSummary(summaryFile, suiteSources, result, runUrl, branch) {
     appendFileSync(summaryFile, buildSummaryMarkdown(suiteSources, result, runUrl, branch), "utf8");

package/dist/src/types.d.mts

@@ -1,6 +1,8 @@
 export type CoverageRule = {
     paths: string;
     patch_coverage_min: number;
+    no_coverage_drop?: boolean;
+    max_coverage_drop?: number;
 };
 /** Map from repo-root-relative file path to map of added line number → trimmed source text. */
 export type DiffLineContent = Map<string, Map<number, string>>;
@@ -26,8 +28,18 @@ export type BucketResult = {
     files: FileCoverageResult[];
     passed: boolean;
 };
+export type DropResult = {
+    rule: string;
+    currentPct: number | null;
+    baselinePct: number | null;
+    drop: number | null;
+    maxDrop: number;
+    passed: boolean;
+    skipped: boolean;
+};
 export type CoverageCheckResult = {
     buckets: BucketResult[];
+    drops: DropResult[];
     informational: FileCoverageResult[];
     passed: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverage-check",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Patch-coverage gate: checks that newly added lines meet per-path coverage thresholds. Supports per-suite LCOV accumulation for conditional CI.",
   "license": "MIT",
   "author": "Jonathan Ong",