canary-test-cli 7.2.0 → 8.0.0

package/dist/engine/guardian/pr-check.js

@@ -25,10 +25,9 @@
  *     to the later CLI wave. This module is the pure library logic.
  */
 import { readFileSync } from 'node:fs';
-import { extname, join } from 'node:path';
+import { join } from 'node:path';
 import { readJsonWithWarning } from '../core/config-validation.js';
-import { isAssertionFreeTest } from '../core/quality-scorer.js';
-import { Fidelity, coverageDegradedNotice, coverageStatus, isSourcePath, isTestPath, isTestSupportPath, isTypeOnlyModule, } from './coverage.js';
+import { Fidelity, coverageDegradedNotice, coverageDeltaNotice, coverageDeltaStatus, coverageCauses, coverageStatus, isSourcePath, isTestPath, isTestSupportPath, isTypeOnlyModule, } from './coverage.js';
 import { Severity, severitySortKey } from './impact-mapper.js';
 import { ensureAscii } from '../util/ensure-ascii.js';
 const HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
@@ -69,72 +68,143 @@ function mergeLines(lines) {
  */
 export function scopeDiff(diffText) {
     const addedByPath = new Map();
-    let currentPath = null;
-    let newLineno = 0;
-    let skipCurrent = false;
+    walkDiff(diffText, (line) => {
+        if (!line.added)
+            return;
+        const lines = addedByPath.get(line.path);
+        if (lines)
+            lines.push(line.lineno);
+        else
+            addedByPath.set(line.path, [line.lineno]);
+    });
+    const units = [];
+    for (const [path, lines] of addedByPath) {
+        units.push({ path, added_ranges: mergeLines(lines) });
+    }
+    return units;
+}
+// Single-character C escapes git's `quote_c_style` emits, per `sq_lookup`.
+const C_ESCAPES = {
+    a: 0x07,
+    b: 0x08,
+    f: 0x0c,
+    n: 0x0a,
+    r: 0x0d,
+    t: 0x09,
+    v: 0x0b,
+    '"': 0x22,
+    '\\': 0x5c,
+};
+const UTF8_DECODER = new TextDecoder('utf-8');
+/**
+ * Undo git's C-style path quoting (`core.quotePath`, on by default).
+ *
+ * A path with a non-ASCII (or control) byte is emitted by `git diff` wrapped in
+ * double quotes with its bytes octal-escaped:
+ * `+++ "b/caf\303\251.ts"`. Left as-is, the quotes ride along in the unit's
+ * path, so the file resolves to nothing: `extname` reads `.ts"`,
+ * {@link isSourcePath} says "not program source", and
+ * {@link filterHeuristicNoise} drops the finding — a silent false negative on
+ * every non-ASCII-named file. A value that is not quoted is returned verbatim.
+ */
+function unquoteCStyle(value) {
+    if (!isCQuoted(value))
+        return value;
+    const body = value.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch !== '\\') {
+            // Any non-escaped character is already a decoded code point; re-encode it
+            // so the whole path decodes as one UTF-8 byte stream.
+            for (const byte of new TextEncoder().encode(ch))
+                bytes.push(byte);
+            continue;
+        }
+        const next = body[i + 1];
+        if (next === undefined)
+            return value; // trailing backslash → not quoted
+        if (next >= '0' && next <= '7') {
+            const octal = /^[0-7]{1,3}/.exec(body.slice(i + 1))[0];
+            bytes.push(Number.parseInt(octal, 8) & 0xff);
+            i += octal.length;
+            continue;
+        }
+        const mapped = C_ESCAPES[next];
+        if (mapped === undefined)
+            return value; // unknown escape → leave alone
+        bytes.push(mapped);
+        i += 1;
+    }
+    return UTF8_DECODER.decode(new Uint8Array(bytes));
+}
+/**
+ * True when `value` is wrapped in the double quotes git uses for C-style path
+ * quoting. Split out of {@link unquoteCStyle} to keep its decode loop under
+ * the cyclomatic-complexity threshold.
+ */
+function isCQuoted(value) {
+    return value.length >= 2 && value.startsWith('"') && value.endsWith('"');
+}
+/** The new-side path a `+++ ` header names, or `null` for a deleted file. */
+function headerPath(line) {
+    // A quoted path is unquoted BEFORE the `b/` strip: the quotes wrap the
+    // prefix too (`"b/caf\303\251.ts"`), so stripping first would never match.
+    const target = unquoteCStyle(line.slice(4).trim());
+    if (target === '/dev/null')
+        return null;
+    // Strip the conventional "b/" prefix.
+    return target.startsWith('b/') ? target.slice(2) : target;
+}
+/**
+ * Walk a unified diff, calling `emit` once per NEW-SIDE line, in file order.
+ *
+ * The single parser behind {@link scopeDiff}, {@link addedContentByPath} and
+ * `visibleLinesByPath`. Those three read different things off the same walk —
+ * added line numbers, added text, and added-plus-context text — and each used
+ * to carry its own copy of the header/hunk bookkeeping, which is three places
+ * for a diff-format edge case to be fixed in two of.
+ *
+ * Removed (`-`) lines and the `` marker are not
+ * emitted and do not advance the new-side counter, since neither exists on that
+ * side. Deleted files (`+++ /dev/null`) emit nothing at all.
+ *
+ * FIX 7: `--- `/`+++ ` are file headers ONLY before the first hunk of a file.
+ * Inside a hunk body a `+++ ...` line is ADDED CONTENT whose real text is
+ * `++ ...`, and mistaking it for a header loses the rest of the file.
+ */
+export function walkDiff(diffText, emit) {
+    let path = null;
+    let lineno = 0;
     let inHunk = false;
     for (const line of splitLines(diffText)) {
         if (line.startsWith('diff --git')) {
-            // New file block begins → leave any prior hunk body; path is set by the
-            // upcoming `+++ ` header.
+            // A new file block begins → leave any prior hunk body; the path is set
+            // by the upcoming `+++ ` header.
             inHunk = false;
-            currentPath = null;
-            skipCurrent = false;
+            path = null;
             continue;
         }
-        // `--- `/`+++ ` are file headers ONLY before the first hunk of a file. Once
-        // inside a hunk body a `+++ ...` line is an ADDED content line whose real
-        // text is `++ ...` and must not be mistaken for a header (FIX 7).
         if (!inHunk && line.startsWith('+++ ')) {
-            const target = line.slice(4).trim();
-            if (target === '/dev/null') {
-                skipCurrent = true;
-                currentPath = null;
-                continue;
-            }
-            skipCurrent = false;
-            // Strip the conventional "b/" prefix.
-            currentPath = target.startsWith('b/') ? target.slice(2) : target;
-            if (!addedByPath.has(currentPath))
-                addedByPath.set(currentPath, []);
+            path = headerPath(line);
             continue;
         }
-        if (!inHunk && line.startsWith('--- ')) {
-            // Old-file header; ignored (path comes from +++).
+        // Old-file header; ignored (the path comes from `+++`).
+        if (!inHunk && line.startsWith('--- '))
             continue;
-        }
         const hunk = HUNK_RE.exec(line);
         if (hunk) {
-            newLineno = Number.parseInt(hunk[1], 10);
+            lineno = Number.parseInt(hunk[1], 10);
             inHunk = true;
             continue;
         }
-        if (skipCurrent || currentPath === null)
+        if (path === null)
             continue;
-        if (line.startsWith('+')) {
-            addedByPath.get(currentPath).push(newLineno);
-            newLineno += 1;
-        }
-        else if (line.startsWith('-')) {
-            // Removed line: does not advance the new-file counter.
-            continue;
-        }
-        else if (line.startsWith('\\')) {
-            // "" — metadata, ignore.
+        if (line.startsWith('-') || line.startsWith('\\'))
             continue;
-        }
-        else {
-            // Context line (leading space) or blank — advances new-file counter.
-            newLineno += 1;
-        }
+        emit({ path, lineno, text: line.slice(1), added: line.startsWith('+') });
+        lineno += 1;
     }
-    const units = [];
-    for (const [path, lines] of addedByPath) {
-        if (lines.length === 0)
-            continue;
-        units.push({ path, added_ranges: mergeLines(lines) });
-    }
-    return units;
 }
 // FIX 2 (signal-quality): a changed file whose ADDED lines are ONLY imports /
 // re-exports (no real declarations or logic) is a barrel/index file
@@ -173,48 +243,20 @@ function isNeutralLine(stripped) {
 /**
  * Map each changed file to the CONTENT of its added (`+`) lines.
  *
- * Mirrors {@link scopeDiff}'s parser but captures the added-line *text* (the
- * `+` stripped) rather than line numbers. Deleted files (`+++ /dev/null`) are
- * excluded; a `+++ ` line inside a hunk body is added content, not a header
- * (same FIX 7 guard as `scopeDiff`).
+ * The same walk {@link scopeDiff} takes, reading the added-line *text* rather
+ * than its line number.
  */
-function addedContentByPath(diffText) {
+export function addedContentByPath(diffText) {
     const added = new Map();
-    let currentPath = null;
-    let skipCurrent = false;
-    let inHunk = false;
-    for (const line of splitLines(diffText)) {
-        if (line.startsWith('diff --git')) {
-            inHunk = false;
-            currentPath = null;
-            skipCurrent = false;
-            continue;
-        }
-        if (!inHunk && line.startsWith('+++ ')) {
-            const target = line.slice(4).trim();
-            if (target === '/dev/null') {
-                skipCurrent = true;
-                currentPath = null;
-                continue;
-            }
-            skipCurrent = false;
-            currentPath = target.startsWith('b/') ? target.slice(2) : target;
-            if (!added.has(currentPath))
-                added.set(currentPath, []);
-            continue;
-        }
-        if (!inHunk && line.startsWith('--- '))
-            continue;
-        if (HUNK_RE.test(line)) {
-            inHunk = true;
-            continue;
-        }
-        if (skipCurrent || currentPath === null)
-            continue;
-        if (line.startsWith('+')) {
-            added.get(currentPath).push(line.slice(1));
-        }
-    }
+    walkDiff(diffText, (line) => {
+        if (!line.added)
+            return;
+        const texts = added.get(line.path);
+        if (texts)
+            texts.push(line.text);
+        else
+            added.set(line.path, [line.text]);
+    });
     return added;
 }
 /**
@@ -656,283 +698,63 @@ export function buildFindings(results) {
     }
     return [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
 }
-// Map a test file's extension to the framework whose assertion/test patterns
-// the quality scorer should use. Unknown → pytest (the scorer's own fallback).
-const TEST_FRAMEWORK_BY_EXT = {
-    '.py': 'pytest',
-    '.ts': 'vitest',
-    '.tsx': 'vitest',
-    '.js': 'vitest',
-    '.jsx': 'vitest',
-    '.mjs': 'vitest',
-    '.cjs': 'vitest',
-};
-function frameworkForTestPath(path) {
-    return TEST_FRAMEWORK_BY_EXT[extname(path).toLowerCase()] ?? 'pytest';
-}
-// A test-function signature / decorator / block-close / comment — lines that
-// are not a test *body*. If a diff's added lines are ONLY these (e.g. a rename
-// that adds just `def test_new():` while the asserting body stays as context),
-// there is no added body to judge and we must not flag it.
-const TEST_SIGNATURE_RE = /^\s*(?:async\s+)?def\s+test\w*\s*\(|^\s*(?:it|test|describe)\s*\(/;
-const BLOCK_DELIMITERS = new Set(['})', '});', '}', ')', '{']);
-/**
- * True iff the added lines contain a real body line — not just a test
- * signature, decorator, comment, or a bare block delimiter.
- */
-function hasAddedTestBody(added) {
-    for (const line of added) {
-        const stripped = line.trim();
-        if (!stripped)
-            continue;
-        if (stripped.startsWith('#') ||
-            stripped.startsWith('//') ||
-            stripped.startsWith('@') ||
-            stripped.startsWith('*') ||
-            stripped.startsWith('/*')) {
-            continue;
-        }
-        if (BLOCK_DELIMITERS.has(stripped))
-            continue;
-        if (TEST_SIGNATURE_RE.test(line))
-            continue;
-        return true;
-    }
-    return false;
-}
 /**
- * The declaration line of a single test, per framework family (#747).
+ * Percentage-point bands for a coverage **regression** (#606).
  *
- * Narrower than {@link TEST_SIGNATURE_RE} on purpose: `describe(` opens a
- * *group*, and judging assertion presence over a whole describe block would
- * suppress a genuinely empty test sitting beside an asserting sibling. A
- * modifier chain (`it.only`, `test.each`) still opens one test, so it counts.
+ * A drop is graded by how far it fell and stops at `HIGH` — it never reaches
+ * `CRITICAL`. An uncovered new block is a fact about one artifact; a drop is a
+ * *relative* measurement across two, and guardian cannot verify that the base
+ * artifact it was handed is genuinely the base of this PR. The top of the scale
+ * is reserved for what guardian can prove on its own.
  */
-const TEST_DECL_PY = /^\s*(?:async\s+)?def\s+test\w*\s*\(/;
-const TEST_DECL_JS = /^\s*(?:async\s+)?(?:it|test)(?:\.\w+)*\s*\(/;
-function testDeclRe(framework) {
-    return framework === 'pytest' ? TEST_DECL_PY : TEST_DECL_JS;
-}
-/** Indentation width of `line`, counting a tab as one column. */
-function indentWidth(line) {
-    return line.length - line.trimStart().length;
+const REGRESSION_HIGH_POINTS = 20;
+const REGRESSION_MEDIUM_POINTS = 5;
+/** `92.0% (23/25)` — a ratio a reviewer can check without doing the division. */
+function ratioLabel(ratio) {
+    const pct = ((ratio.covered / ratio.coverable) * 100).toFixed(1);
+    return `${pct}% (${ratio.covered}/${ratio.coverable})`;
 }
-// String literals and line comments are blanked before delimiter counting, so
-// a brace inside `'a { b'` or a trailing `// }` cannot unbalance a block.
-const JS_STRING_OR_COMMENT = /(['"`])(?:\\.|(?!\1).)*?\1|\/\/.*$|\/\*[\s\S]*?\*\//g;
 /**
- * Consume a `diff --git` / `+++` / `---` / `@@` line, returning whether the
- * line was a header. Split out from the content handling so neither half has
- * to carry the other's branches.
- */
-function applyDiffHeader(line, cur, files) {
-    if (line.startsWith('diff --git')) {
-        cur.inHunk = false;
-        cur.current = null;
-        cur.skipCurrent = false;
-        return true;
-    }
-    if (!cur.inHunk && line.startsWith('+++ ')) {
-        const target = line.slice(4).trim();
-        if (target === '/dev/null') {
-            cur.skipCurrent = true;
-            cur.current = null;
-            return true;
-        }
-        cur.skipCurrent = false;
-        const path = target.startsWith('b/') ? target.slice(2) : target;
-        cur.current = files.get(path) ?? { text: new Map(), added: new Set() };
-        files.set(path, cur.current);
-        return true;
-    }
-    if (!cur.inHunk && line.startsWith('--- '))
-        return true;
-    const hunk = HUNK_RE.exec(line);
-    if (hunk) {
-        cur.newLineno = Number.parseInt(hunk[1], 10);
-        cur.inHunk = true;
-        return true;
-    }
-    return false;
-}
-/** Record one content line against the file the cursor is pointing at. */
-function applyDiffContent(line, cur) {
-    const file = cur.current;
-    if (!file)
-        return;
-    // `-` is gone from the new file and `\` is the no-newline marker; neither
-    // occupies a line number on the `+` side.
-    if (line.startsWith('-') || line.startsWith('\\'))
-        return;
-    const added = line.startsWith('+');
-    file.text.set(cur.newLineno, line.slice(1));
-    if (added)
-        file.added.add(cur.newLineno);
-    cur.newLineno += 1;
-}
-function visibleLinesByPath(diffText) {
-    const files = new Map();
-    const cur = {
-        current: null,
-        newLineno: 0,
-        skipCurrent: false,
-        inHunk: false,
-    };
-    for (const line of splitLines(diffText)) {
-        if (applyDiffHeader(line, cur, files))
-            continue;
-        if (cur.skipCurrent || cur.current === null)
-            continue;
-        applyDiffContent(line, cur);
-    }
-    return files;
-}
-/**
- * The line the enclosing test declaration sits on, or `null` when none is
- * visible (#747).
+ * Turn regressed base-vs-head deltas into `coverage-regression` findings (#606).
  *
- * Walks up through the CONTIGUOUS visible run only: a gap between hunks means
- * the lines between are unknown, so a declaration on the far side of it is not
- * evidence about this line. Returning `null` is the abstention — a changed line
- * whose enclosing test cannot be resolved (a Playwright `setup(...)` fixture, a
- * bare helper) is not judged at all rather than reported as assertion-free.
- */
-function enclosingTestDecl(file, lineNo, declRe) {
-    for (let n = lineNo; file.text.has(n); n--) {
-        if (declRe.test(file.text.get(n)))
-            return n;
-    }
-    return null;
-}
-/**
- * The last line of the test block opened at `start`, bounded by what the diff
- * shows (#747).
- *
- * Python closes on the first non-blank line indented no deeper than the `def`;
- * JS/TS closes when the delimiter depth opened by the declaration returns to
- * zero. When neither lands inside the visible run the span is truncated at its
- * end — the assertion search is then over less than the whole block, which can
- * still miss an assertion further down. That residual is accepted: it is a
- * strictly smaller window of error than scoring the added lines alone, which is
- * what #747 measured, and widening the span past what the diff shows would mean
- * reading the working tree, which this function deliberately does not do.
- */
-function testBlockEnd(file, start, isPython) {
-    let last = start;
-    if (isPython) {
-        const declIndent = indentWidth(file.text.get(start));
-        for (let n = start + 1; file.text.has(n); n++) {
-            const text = file.text.get(n);
-            if (text.trim() && indentWidth(text) <= declIndent)
-                return n - 1;
-            last = n;
-        }
-        return last;
-    }
-    let depth = 0;
-    let opened = false;
-    for (let n = start; file.text.has(n); n++) {
-        const text = file.text.get(n).replace(JS_STRING_OR_COMMENT, '');
-        for (const ch of text) {
-            if (ch === '{' || ch === '(') {
-                depth += 1;
-                opened = true;
-            }
-            else if (ch === '}' || ch === ')')
-                depth -= 1;
-        }
-        last = n;
-        if (opened && depth <= 0)
-            return n;
-    }
-    return last;
-}
-/**
- * True iff some test block touched by `unit`'s added lines asserts nothing.
+ * Only `regressed` deltas become findings — an improvement and a flat result
+ * are not news. Fidelity is `COVERAGE_VERIFIED` because both sides of the
+ * comparison were measured by a real coverage run; there is no graph or
+ * heuristic path to a delta, and a tier that cannot measure must not guess one.
  *
- * A block qualifies for judgement only when it is resolvable AND at least one
- * of its own added lines is a real body line — the FP-3 rename guard, applied
- * per block rather than per file so a rename in one test cannot excuse an empty
- * one elsewhere in the same diff. Blocks are visited once each.
+ * The evidence carries both ratios AND both raw counts on purpose: base and
+ * head can disagree about how many lines are coverable at all (a diff adds
+ * lines; two producers may instrument differently), and a bare pair of
+ * percentages would hide that.
  */
-function weakBlockIn(file, unit, framework) {
-    const declRe = testDeclRe(framework);
-    const isPython = framework === 'pytest';
-    const seen = new Set();
-    for (const lineNo of linesInRanges(unit.added_ranges)) {
-        const start = enclosingTestDecl(file, lineNo, declRe);
-        if (start === null || seen.has(start))
-            continue;
-        seen.add(start);
-        const end = testBlockEnd(file, start, isPython);
-        const span = [];
-        const addedInBlock = [];
-        for (let n = start; n <= end; n++) {
-            const text = file.text.get(n);
-            if (text === undefined)
-                continue;
-            span.push(text);
-            if (file.added.has(n))
-                addedInBlock.push(text);
-        }
-        if (!hasAddedTestBody(addedInBlock))
-            continue;
-        if (isAssertionFreeTest(span.join('\n'), framework))
-            return true;
-    }
-    return false;
-}
-/**
- * Advisory `weak-test` findings for ADDED tests that assert nothing.
- *
- * Consumes the test-path units {@link filterTestUnits} sets aside (a test file
- * needs no test of its own, but an added test that asserts nothing is itself a
- * gap). A high-precision signal by construction: a snapshot or table-driven
- * test still matches an assertion pattern, so it is not flagged.
- *
- * #747: the span scored is the ENCLOSING TEST BLOCK of each added line, not the
- * added lines themselves. Scoring the added lines alone reported every
- * arrange/act-only edit as assertion-free, because a test's setup is edited far
- * more often than its `expect` — six such findings, all wrong, in the run that
- * produced the report. A changed line whose enclosing test cannot be resolved
- * from the diff is ABSTAINED on, never reported.
- *
- * These findings are `LOW`/`weak-test` and are **never** gated (see
- * {@link computeExitCode}): they surface, never block.
- */
-export function buildWeakTestFindings(testUnits, diffText) {
-    const addedByPath = addedContentByPath(diffText);
-    const visibleByPath = visibleLinesByPath(diffText);
+export function buildRegressionFindings(deltas) {
     const findings = [];
-    for (const unit of testUnits) {
-        const added = addedByPath.get(unit.path);
-        if (!added || added.length === 0)
-            continue;
-        // A rename adds only the signature line (body is unchanged context) —
-        // nothing new to judge, so don't flag it (FP guard).
-        if (!hasAddedTestBody(added))
-            continue;
-        const framework = frameworkForTestPath(unit.path);
-        const file = visibleByPath.get(unit.path);
-        if (!file)
+    for (const delta of deltas) {
+        if (!delta.regressed)
             continue;
-        if (weakBlockIn(file, unit, framework)) {
-            findings.push(new GuardianFinding({
-                path: unit.path,
-                unit: unit.path,
-                kind: 'weak-test',
-                fidelity: Fidelity.Heuristic,
-                severity: Severity.LOW,
-                evidence: 'added test asserts nothing (advisory — never blocks the gate)',
-                suggestion: 'add at least one assertion, or delete the test if it is a placeholder.',
-                added_ranges: [...unit.added_ranges],
-            }));
-        }
+        const points = delta.dropPoints;
+        const severity = points >= REGRESSION_HIGH_POINTS
+            ? Severity.HIGH
+            : points >= REGRESSION_MEDIUM_POINTS
+                ? Severity.MEDIUM
+                : Severity.LOW;
+        findings.push(new GuardianFinding({
+            path: delta.path,
+            unit: delta.path,
+            kind: 'coverage-regression',
+            fidelity: Fidelity.CoverageVerified,
+            severity,
+            evidence: `coverage fell ${points.toFixed(1)} points on a file this change ` +
+                `touches: base ${ratioLabel(delta.base)} ${ARROW} head ` +
+                `${ratioLabel(delta.head)}`,
+            suggestion: `Restore the lost coverage in \`${delta.path}\` — a test that ` +
+                'exercised this file on the base ref no longer reaches part of it.',
+        }));
     }
-    return findings;
+    return [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
 }
 /** Flatten inclusive `[start, end]` ranges into a sorted list of line numbers. */
-function linesInRanges(ranges) {
+export function linesInRanges(ranges) {
     const lines = new Set();
     for (const [start, end] of ranges) {
         for (let ln = start; ln <= end; ln++)
@@ -946,7 +768,7 @@ function linesInRanges(ranges) {
  * Requires a `//`/`#` comment leader (FIX 1), strips a trailing inline-comment
  * close (e.g. `*​/`), and trims surrounding whitespace.
  */
-function suppressionReason(line) {
+export function suppressionReason(line) {
     const match = SUPPRESS_RE.exec(line);
     if (match === null)
         return null;
@@ -1038,26 +860,11 @@ export function computeExitCode(findings, gate) {
     return 0;
 }
 const STICKY_MARKER = '<!-- canary-pr-guardian -->';
-// Severity → status icon for the sticky comment (encodes severity in form, not
-// just text, so the most urgent findings read at a glance).
-//
-// Written as `\u{...}` escapes, not literal glyphs: this file is `.ts`, and the
-// house rule keeps emitted non-ASCII out of non-Markdown source (see the
-// "Output data glyphs" block in `cli.ts`). They are emitted verbatim.
 /**
- * Character budget for a rendered sticky comment (#457).
- *
- * GitHub rejects an issue/PR comment body over **65,536** characters. The post
- * path reports that as "could not post", so an over-long body means the gate
- * silently produces nothing on exactly the large PRs that need it most -- the
- * same silent-green failure #369 was filed for.
- *
- * 60,000 leaves ~5.5k of headroom for anything appended outside
- * `renderFindings` (degradation annotations, upsert wrappers) without inviting
- * a body that only *just* fits and then breaks when a filename grows.
- *
- * The cap applies ONLY to the comment. The `--emit-analysis` JSON record is the
- * authoritative complete set and is never truncated.
+ * Character budget for a rendered sticky comment (#457). GitHub rejects a body
+ * over 65,536 characters, which would silently post nothing on the largest PRs
+ * (#369); 60,000 leaves headroom for appended annotations. The comment only:
+ * the `--emit-analysis` record is complete and never truncated.
  */
 export const COMMENT_CHAR_BUDGET = 60_000;
 /** The line that accounts for findings the budget could not fit (#457). */
@@ -1135,30 +942,11 @@ function coverageBlock(state) {
     return { status: coverageStatus(state), ...state };
 }
 /**
- * True when this run VERIFIED NO COVERAGE and every finding it produced is a
- * naming-heuristic guess (#761) — an abstention, not a result.
- *
- * Guardian's existing abstention keys off the *findings-eligible* count, which
- * is the wrong denominator: a run can have plenty of eligible units and still
- * have verified nothing, because "findings-eligible" and "coverage-verifiable"
- * are different counts. The measured shape is a code PR whose lcov never
- * reached the runner: N eligible units, zero coverage denominator, and a
- * confident "6 files need test coverage" headline under a green check.
- *
- * Two narrowings keep this honest rather than merely loud:
- *
- *   - `unitsTotal === 0` is NOT this case. A run that judged nothing makes no
- *     coverage claim in either direction; the eligible-count abstention owns it,
- *     the same boundary {@link coverageDegradedNotice} already draws.
- *   - A single coverage- or graph-verified finding disproves it. Real evidence
- *     means the run measured something, so it is a result and must not be
- *     downgraded to an abstention.
- *   - A run with NO findings is left alone. It states nothing a reader can
- *     mistake for a measurement: #554 already replaced its all-clear headline
- *     with "no gaps found, but coverage was unavailable" plus the body line
- *     saying that is an abstention, not a pass. The defect #761 reports is
- *     specifically a CONFIDENT COUNT over a zero coverage denominator, so that
- *     is what changes here.
+ * True when this run VERIFIED NO COVERAGE and every finding is a naming guess
+ * (#761): a confident count over a zero coverage denominator is an abstention.
+ * Not this case: `unitsTotal === 0` (no claim either way), any coverage- or
+ * graph-verified finding (real evidence), or no findings at all (the per-cause
+ * headline already says what was not verified, #928).
  */
 export function isCoverageAbstention(coverage, findings) {
     if (!coverage || coverage.unitsTotal === 0)
@@ -1182,22 +970,62 @@ function abstentionHeadline(checked) {
 const ABSTENTION_BODY = 'No coverage report reached this run, so nothing below is a coverage ' +
     'verdict — every finding is a filename-level guess. A gate that verified ' +
     'zero items has abstained; this is not a pass.';
+const files = (n) => `${n} file${n === 1 ? '' : 's'}`;
+/** The unverified-unit causes present on a run, worst first (#928). */
+function causeEntries(state) {
+    const { stale, scopeGap, nonCoverable } = coverageCauses(state);
+    const trees = (state.instrumentedTrees ?? []).map((t) => t || '.');
+    const entries = [
+        [
+            stale,
+            `${WARNING} coverage report stale: ${stale} changed ${files(stale).split(' ')[1]} missing from it`,
+            'coverage report stale (changed lines missing from it)',
+        ],
+        [
+            scopeGap,
+            `${WARNING} not coverage-checked: ${files(scopeGap)} outside instrumented trees (${trees.join(', ')})`,
+            'not coverage-checked (outside instrumented trees)',
+        ],
+        [
+            nonCoverable,
+            `${WHITE_CHECK} nothing to test: only non-executable lines changed (${files(nonCoverable)})`,
+            'nothing to test (only non-executable lines changed)',
+        ],
+    ];
+    return entries.filter(([n]) => n > 0);
+}
 /**
- * The comment body for a run with zero active findings.
- *
- * #554: the ✅ all-clear headline is reserved for a run whose coverage report
- * spoke to every changed file. Anything less says so in the body — a `<sub>`
- * footer under a green headline is read as boilerplate, and this is the exact
- * shape that let 43 coverage-blind PRs read as covered.
+ * One headline per cause (#928) plus the lesser causes as count lines. ✅ only
+ * when the report spoke to every changed unit (#554): any B or C unit is ⚠️.
+ */
+function coverageHeadline(state, notice) {
+    const clean = `${WHITE_CHECK} no test-coverage gaps`;
+    if (state?.unitsTotal === 0) {
+        return [`${WHITE_CHECK} nothing to test: no source files changed`, []];
+    }
+    if (!state?.parsed) {
+        const blind = `${WARNING} no gaps found, but coverage was ${state ? coverageStatus(state) : ''}`;
+        return [notice ? blind : clean, []];
+    }
+    const [worst, ...rest] = causeEntries(state);
+    // Matched units plus non-executable ones: nothing is missing, so plain ✅.
+    if (!worst || (worst[1].startsWith(WHITE_CHECK) && state.unitsMatched > 0)) {
+        return [clean, []];
+    }
+    return [worst[1], rest.map(([n, , label]) => `- ${files(n)}: ${label}`)];
+}
+/**
+ * The comment body for a run with zero active findings. The notice goes in the
+ * body, not only a `<sub>` footer, which is read as boilerplate (#554).
  */
 function noGapsLines(coverageState, suppressedCount, abstained = false, checked = 0) {
     const notice = coverageState ? coverageDegradedNotice(coverageState) : null;
-    const headline = abstained
-        ? abstentionHeadline(checked)
-        : notice
-            ? `${WARNING} no gaps found, but coverage was ${coverageStatus(coverageState)}`
-            : `${WHITE_CHECK} no test-coverage gaps`;
-    const lines = [`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ${headline}`];
+    const [cause, counts] = coverageHeadline(coverageState, notice);
+    const headline = abstained ? abstentionHeadline(checked) : cause;
+    const lines = [
+        `## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ${headline}`,
+        ...counts,
+    ];
     if (notice) {
         lines.push(`> **${notice}**`, '', 'Zero files matched is an abstention, not a pass — nothing here is ' +
             'evidence that the changed lines are covered.');
@@ -1216,7 +1044,11 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
     const coverageNotice = coverageState
         ? coverageDegradedNotice(coverageState)
         : null;
-    const notice = combineNotices(degradedNotice, coverageNotice);
+    // #606: the delta's own degradation is a THIRD independent reason a run can
+    // be blind, so it joins the same combined notice rather than replacing one.
+    const deltaState = gateMeta?.coverageDelta ?? null;
+    const deltaNotice = deltaState ? coverageDeltaNotice(deltaState) : null;
+    const notice = combineNotices(degradedNotice, coverageNotice, deltaNotice);
     if (fmt === 'json') {
         const payload = {
             findings: ordered.map(findingDict),
@@ -1234,6 +1066,14 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
             payload['skipped'] = gateMeta.skipped ?? [];
             if (coverageState)
                 payload['coverage'] = coverageBlock(coverageState);
+            // #606: the delta's denominator, so a machine consumer can tell "no
+            // regressions" from "never compared" without re-deriving it.
+            if (deltaState) {
+                payload['coverage_delta'] = {
+                    status: coverageDeltaStatus(deltaState),
+                    ...deltaState,
+                };
+            }
             // #761: machine consumers need the diff's endpoints for the same reason
             // humans do — every count in this payload is scoped by them.
             if (gateMeta.provenance)
@@ -1286,10 +1126,10 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
     const CONFIDENCE_NOTE = 'Confidence — **coverage-verified**: measured from a real coverage run · ' +
         '**graph-verified**: inferred from the call graph · **heuristic**: filename ' +
         `guess (lowest). tier ${tier}: deterministic check, no LLM.`;
-    const footerLine = `<sub>${CONFIDENCE_NOTE}${notice ? ` ${EM_DASH} ${notice}` : ''}</sub>`;
-    // #554: a coverage-blind run must not present as a run that checked and found
-    // nothing. The notice goes in the BODY, not only the footer — a `<sub>` line
-    // under a green headline is read as boilerplate.
+    // #928: the coverage notice is rendered in the body, so the footer omits it.
+    const footerNotice = combineNotices(degradedNotice, deltaNotice);
+    const footerLine = `<sub>${CONFIDENCE_NOTE}${footerNotice ? ` ${EM_DASH} ${footerNotice}` : ''}</sub>`;
+    // #554: a coverage-blind run must not present as one that checked and passed.
     const coverageLine = coverageNotice ? `> **${coverageNotice}**` : null;
     // #761: shown on EVERY comment, clean or not. The run that motivated this was
     // a findings run whose findings were all phantom, so gating the line on a
@@ -1359,10 +1199,9 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
         return lines.join('\n');
     }
     // fmt == "text" (default fallback): plain, no markdown/HTML.
-    const cleanHeadline = coverageNotice
-        ? // #554: same rule as the comment surface — a blind run never claims clean.
-            `Canary PR Guardian — no gaps found, but coverage was ${coverageStatus(coverageState)}`
-        : 'Canary PR Guardian — no test-coverage gaps';
+    // #554/#928: the comment surface's per-cause headline, without its glyph.
+    const [cause, causeCounts] = coverageHeadline(coverageState, coverageNotice);
+    const cleanHeadline = `Canary PR Guardian — ${cause.replace(/^\S+ /, '')}`;
     // #761: the same rule on the surface an engineer reads at their desk. The
     // headline is stripped of the comment surface's markdown-era glyph so the
     // terminal line stays plain text.
@@ -1374,6 +1213,7 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
             : active.length === 0
                 ? cleanHeadline
                 : `Canary PR Guardian — ${new Set(active.map((f) => f.path)).size} file(s) need test coverage`,
+        ...(abstained || active.length > 0 ? [] : causeCounts),
     ];
     for (const finding of ordered) {
         const unit = finding.unit && finding.unit !== finding.path ? ` → ${finding.unit}` : '';
@@ -1441,16 +1281,8 @@ export const DEFAULT_SKIP_GLOBS = [
     '**/__generated__/**',
 ];
 /**
- * Parsed `canary.guardian` config block.
- *
- * Phase 1 stores every field but only `pr_*` gate/tier drive behavior.
- * `skip_globs` and the `precommit_*`/`coverage_paths` fields are read into the
- * object (scaffold) for later phases (SC-2 skip, SC-5 tier).
- *
- * `skip_globs` defaults to docs/markdown PLUS generated/dependency artifacts
- * (lockfiles, `dist`/`build` outputs, minified JS, snapshots — see
- * {@link DEFAULT_SKIP_GLOBS}) so noise-only paths skip out of the box; an
- * explicit `skipGlobs` in config (even `[]`) overrides it.
+ * Parsed `canary.guardian` config block. `skip_globs` defaults to
+ * {@link DEFAULT_SKIP_GLOBS}; an explicit `skipGlobs` (even `[]`) overrides it.
  */
 export class GuardianConfig {
     pr_enabled;