canary-test-cli 6.5.0 → 6.7.0

package/dist/engine/guardian/github-paging.js

@@ -0,0 +1,97 @@
+/**
+ * GitHub REST pagination for the guardian's read paths (#528).
+ *
+ * Both guardian clients used to call GitHub's list endpoints bare, which caps
+ * silently at the API default of 30 rows. That is the worst shape a denominator
+ * can take: a zero would look wrong, but "30 of 30" reads as a complete sample.
+ * A PR past 30 comments hid the sticky comment; a sticky past 30 reactions
+ * biased the precision tally toward whichever verdicts sorted first.
+ *
+ * The loop lives here, behind an injected {@link PageReader}, so it is unit
+ * tested while the network stays quarantined in the clients that construct the
+ * real reader.
+ */
+/** GitHub's maximum page size for list endpoints. */
+export const DEFAULT_PER_PAGE = 100;
+/**
+ * Page ceiling ({@link DEFAULT_PER_PAGE} * this = 2000 rows). Crossing it
+ * throws rather than returning what was read so far: a partial list that the
+ * caller cannot distinguish from a complete one is the defect this module
+ * exists to remove, and rebuilding it inside the fix would be worse than the
+ * original.
+ */
+export const MAX_PAGES = 20;
+/**
+ * `<url>; rel="next"` entries in a `Link` header. The angle brackets are
+ * required — a header with a bare `rel="next"` and no URL yields no match, so
+ * a malformed header degrades to "no next page" instead of a guessed URL.
+ */
+const LINK_ENTRY = /<([^>]+)>\s*;\s*rel\s*=\s*"?([a-zA-Z]+)"?/g;
+/** The `rel="next"` URL from a `Link` header, or null if there is no next. */
+export function parseNextLink(header) {
+    if (header === null || header.trim() === '')
+        return null;
+    for (const match of header.matchAll(LINK_ENTRY)) {
+        if (match[2].toLowerCase() !== 'next')
+            continue;
+        const url = match[1].trim();
+        // Only absolute http(s) — never relay a relative or garbage target.
+        return /^https?:\/\//i.test(url) ? url : null;
+    }
+    return null;
+}
+/**
+ * Request the largest page GitHub will serve. An explicit `per_page` already on
+ * the URL wins, so a caller can still ask for a small page deliberately.
+ */
+export function withPerPage(url, perPage = DEFAULT_PER_PAGE) {
+    const parsed = new URL(url);
+    if (!parsed.searchParams.has('per_page')) {
+        parsed.searchParams.set('per_page', String(perPage));
+    }
+    return parsed.toString();
+}
+/**
+ * Read every page from `startUrl`, following `Link: rel="next"`.
+ *
+ * Throws on a `Link` cycle or past {@link MAX_PAGES}; a non-array body counts
+ * as zero rows (matching the clients' prior defensive shape for an error
+ * payload). Never returns a short list quietly.
+ */
+export async function readAllPages(startUrl, read) {
+    const rows = [];
+    const visited = new Set();
+    let url = withPerPage(startUrl);
+    let pages = 0;
+    while (url !== null) {
+        if (visited.has(url)) {
+            throw new Error(`GitHub paging cycle: ${url} was already read`);
+        }
+        visited.add(url);
+        pages += 1;
+        if (pages > MAX_PAGES) {
+            throw new Error(`GitHub paging exceeded ${MAX_PAGES} pages (${MAX_PAGES * DEFAULT_PER_PAGE}+ rows) ` +
+                `starting at ${startUrl} -- refusing to report a truncated read`);
+        }
+        const page = await read(url);
+        if (Array.isArray(page.body))
+            rows.push(...page.body);
+        url = parseNextLink(page.linkHeader);
+    }
+    return rows;
+}
+/**
+ * A {@link PageReader} over `fetch`. The ONLY place in this module that touches
+ * the network; `onError` lets each client keep its own status mapping (the
+ * comment client distinguishes 403 as a permission error, the reactions client
+ * does not).
+ */
+export function restPageReader(headers, onError) {
+    return async (url) => {
+        const resp = await fetch(url, { method: 'GET', headers });
+        if (!resp.ok)
+            throw onError(resp.status, url);
+        return { body: await resp.json(), linkHeader: resp.headers.get('link') };
+    };
+}
+//# sourceMappingURL=github-paging.js.map

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

@@ -28,7 +28,7 @@ import { readFileSync } from 'node:fs';
 import { extname, join } from 'node:path';
 import { readJsonWithWarning } from '../core/config-validation.js';
 import { isAssertionFreeTest } from '../core/quality-scorer.js';
-import { Fidelity, isSourcePath, isTestPath, } from './coverage.js';
+import { Fidelity, coverageDegradedNotice, coverageStatus, isSourcePath, isTestPath, isTestSupportPath, isTypeOnlyModule, } from './coverage.js';
 import { Severity, severitySortKey } from './impact-mapper.js';
 const HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
 // Suppression annotation: `// canary:allow-untested <reason>` or the `#`
@@ -359,6 +359,58 @@ export function filterTestUnits(units) {
     }
     return [kept, testUnits];
 }
+/**
+ * Partition `units` into `[kept, supportUnits]` by test-support name (#565).
+ *
+ * The sibling of {@link filterTestUnits} for files that are test infrastructure
+ * by *filename idiom* rather than by test-path convention — a pytest
+ * `conftest`, a Playwright fixture module. See {@link isTestSupportPath} for
+ * why the match is component-scoped and why it stays out of `isTestPath`.
+ *
+ * Runs before coverage is resolved, so the suppression holds at **every**
+ * fidelity tier — matching where the existing `fixtures/` convention already
+ * sits in {@link DEFAULT_SKIP_GLOBS}. An lcov row proving a fixture's lines are
+ * uncovered is true and still cannot make "this needs a test" satisfiable.
+ *
+ * Partitioned separately from `testUnits` rather than folded into it: those
+ * feed {@link buildWeakTestFindings}, and a conftest asserts nothing by design,
+ * so folding would swap one bogus finding for another. Order-preserving in both.
+ */
+export function filterTestSupportUnits(units) {
+    const kept = [];
+    const supportUnits = [];
+    for (const unit of units) {
+        if (isTestSupportPath(unit.path))
+            supportUnits.push(unit);
+        else
+            kept.push(unit);
+    }
+    return [kept, supportUnits];
+}
+/**
+ * Partition `units` into `[kept, typeOnlyUnits]` by type-only content (#562).
+ *
+ * The sibling of {@link filterTestSupportUnits} for modules that contain no
+ * runtime code at all. Runs pre-resolution for the same reason: a type
+ * declaration has no runtime existence at ANY tier, so a suppression scoped to
+ * one tier would leave the measured false positives in place — which is
+ * precisely how #413 missed this class. See {@link isTypeOnlyModule} for why
+ * content, not the filename, is the evidence.
+ *
+ * `repoRoot` is needed because the decision requires reading the file; a unit
+ * whose file cannot be read keeps its finding. Order-preserving in both.
+ */
+export function filterTypeOnlyUnits(units, repoRoot) {
+    const kept = [];
+    const typeOnlyUnits = [];
+    for (const unit of units) {
+        if (isTypeOnlyModule(unit.path, repoRoot))
+            typeOnlyUnits.push(unit);
+        else
+            kept.push(unit);
+    }
+    return [kept, typeOnlyUnits];
+}
 /**
  * Default glob layer over the {@link isSourcePath} extension floor (#413).
  *
@@ -433,6 +485,14 @@ export class Finding {
     // the changed lines (FIX 1). Empty → suppression falls back to a whole-file
     // scan (still comment-leader gated).
     added_ranges;
+    // The specific 1-based line numbers the coverage run proved unhit.
+    //
+    // Only the COVERAGE_VERIFIED tier can supply these — the graph and heuristic
+    // tiers answer "is this reached at all?", not "which lines ran" — so an empty
+    // array means "this tier does not know", NEVER "nothing is uncovered". The
+    // renderer must therefore omit the detail rather than print an empty list,
+    // which would read as a measurement that came back clean.
+    uncovered_lines;
     constructor(init) {
         this.path = init.path;
         this.unit = init.unit;
@@ -444,17 +504,113 @@ export class Finding {
         this.suppressed = init.suppressed ?? false;
         this.suppression_reason = init.suppression_reason ?? null;
         this.added_ranges = init.added_ranges ?? [];
+        this.uncovered_lines = init.uncovered_lines ?? [];
     }
 }
+/** Basename minus its extension — the token a heuristic test-file match uses. */
+function pathStem(path) {
+    const base = path.split('/').pop() ?? path;
+    const dot = base.indexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+/**
+ * Render ranges as `44-49, 52-56, 58`, capped at `max` with a `+N more` tail.
+ *
+ * The cap is a budget guard, not cosmetics: a file with hundreds of scattered
+ * uncovered lines would otherwise produce a single table cell long enough to
+ * push other findings out of the comment entirely (#457).
+ */
+function rangeList(ranges, max = 6) {
+    const shown = ranges
+        .slice(0, max)
+        .map(([start, end]) => (start === end ? `${start}` : `${start}-${end}`));
+    const rest = ranges.length - shown.length;
+    return rest > 0 ? `${shown.join(', ')} +${rest} more` : shown.join(', ');
+}
+/**
+ * The deterministic next action for a finding.
+ *
+ * Every branch states only what its tier actually established, because a
+ * suggestion that guesses (naming a test file that does not exist, say) is
+ * worse than none: it sends the reader somewhere before they distrust it. The
+ * coverage tier can name lines; the graph tier can name a symbol; the heuristic
+ * tier knows only that no filename matched, and says exactly that.
+ */
+function suggestionFor(path, unit, fidelity, uncovered) {
+    const symbol = unit && unit !== path ? unit : pathStem(path);
+    if (fidelity === Fidelity.CoverageVerified && uncovered.length > 0) {
+        // The path is deliberately not repeated: the record carries it as a
+        // sibling field, and the comment already shows it in the File column.
+        return `extend a test to execute lines ${rangeList(mergeLines(uncovered))}.`;
+    }
+    if (fidelity === Fidelity.GraphVerified) {
+        return `add a test that calls \`${symbol}\`, directly or through a caller.`;
+    }
+    if (fidelity === Fidelity.Heuristic) {
+        return `no test file mentions \`${pathStem(path)}\` — name a test after it, or reference it from an existing test.`;
+    }
+    return `add a test covering \`${symbol}\`.`;
+}
+// Thresholds for the coverage-verified severity split (#553). Volume is a line
+// count; share is the fraction of the unit's ADDED lines that came back unhit.
+//
+// The pair matters more than either number: volume alone ranks a 30-line
+// function that is 10% uncovered above a 3-line function nothing executes, and
+// share alone ranks a one-line addition alongside a 132-line one.
+const CRITICAL_UNCOVERED_LINES = 20;
+const CRITICAL_UNCOVERED_SHARE = 0.8;
+const HIGH_UNCOVERED_LINES = 5;
+const HIGH_UNCOVERED_SHARE = 0.5;
+/** Total lines a diff added for a unit, summed over its inclusive ranges. */
+function addedLineCount(ranges) {
+    return ranges.reduce((total, [start, end]) => total + (end - start + 1), 0);
+}
+/**
+ * Severity for an uncovered **coverage-verified** result (#553).
+ *
+ * Only this tier can be graded, because only this tier knows *which* lines ran
+ * (see the `uncovered_lines` comment on {@link Finding}). The grade combines
+ * how much is unhit with how much of the change that represents:
+ *
+ *   - `CRITICAL` — a large block (>= 20 lines) that is essentially untouched
+ *     (>= 80% unhit). Nothing executes it; this is what a gate should stop.
+ *   - `HIGH` — a meaningful volume (>= 5 lines) *or* a concentrated gap
+ *     (>= 50% unhit).
+ *   - `MEDIUM` — a handful of lines inside a change that is otherwise tested.
+ *     Real, still reported, not worth blocking a PR over.
+ *
+ * Both unknowns escalate rather than downgrade. No line detail means the tier
+ * could not say which lines were unhit, not that few were; no added-line count
+ * means the share denominator is unknown. An absent measurement must never read
+ * as a low score (ADR 0010) — that is the same silent-abstention shape this
+ * whole module exists to avoid.
+ */
+function coverageVerifiedSeverity(result) {
+    const uncovered = result.uncovered_lines?.length ?? 0;
+    if (uncovered === 0)
+        return Severity.HIGH;
+    const added = addedLineCount(result.unit.added_ranges);
+    const share = added > 0 ? uncovered / added : 1;
+    if (uncovered >= CRITICAL_UNCOVERED_LINES &&
+        share >= CRITICAL_UNCOVERED_SHARE)
+        return Severity.CRITICAL;
+    if (uncovered >= HIGH_UNCOVERED_LINES || share >= HIGH_UNCOVERED_SHARE)
+        return Severity.HIGH;
+    return Severity.MEDIUM;
+}
 /**
  * Turn uncovered coverage results into fidelity-labeled findings.
  *
- * Only **uncovered** results become findings. Severity policy (Phase 1):
+ * Only **uncovered** results become findings. Severity policy:
  *
- *   - `COVERAGE_VERIFIED` uncovered → `HIGH`
+ *   - `COVERAGE_VERIFIED` uncovered → graded by
+ *     {@link coverageVerifiedSeverity} (`CRITICAL` / `HIGH` / `MEDIUM`)
  *   - `GRAPH_VERIFIED` uncovered    → `HIGH`
  *   - `HEURISTIC` uncovered         → `MEDIUM` (lower confidence)
  *
+ * The graph and heuristic tiers stay flat on purpose: neither can measure how
+ * much of a unit is unhit, so any spread across them would be invented.
+ *
  * Results are sorted by severity sort-key (critical → low).
  */
 export function buildFindings(results) {
@@ -462,15 +618,24 @@ export function buildFindings(results) {
     for (const result of results) {
         if (result.covered)
             continue;
-        const severity = result.fidelity === Fidelity.Heuristic ? Severity.MEDIUM : Severity.HIGH;
+        let severity;
+        if (result.fidelity === Fidelity.CoverageVerified)
+            severity = coverageVerifiedSeverity(result);
+        else if (result.fidelity === Fidelity.Heuristic)
+            severity = Severity.MEDIUM;
+        else
+            severity = Severity.HIGH;
         const unit = result.unit;
+        const uncovered = [...(result.uncovered_lines ?? [])];
         findings.push(new Finding({
             path: unit.path,
             unit: unit.symbol || unit.path,
             fidelity: result.fidelity,
             severity,
             evidence: result.evidence,
+            suggestion: suggestionFor(unit.path, unit.symbol || unit.path, result.fidelity, uncovered),
             added_ranges: [...unit.added_ranges],
+            uncovered_lines: uncovered,
         }));
     }
     return [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
@@ -551,6 +716,7 @@ export function buildWeakTestFindings(testUnits, diffText) {
                 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],
             }));
         }
@@ -694,13 +860,21 @@ function overflowNote(omitted) {
 }
 const EM_DASH = '\u{2014}';
 const RED_CIRCLE = '\u{1F534}';
+const ORANGE_CIRCLE = '\u{1F7E0}';
 const YELLOW_CIRCLE = '\u{1F7E1}';
 const WHITE_CIRCLE = '\u{26AA}';
 const BABY_CHICK = '\u{1F424}';
+const ARROW = '\u{2192}';
 const WHITE_CHECK = '\u{2705}';
+const WARNING = '\u{26A0}\u{FE0F}';
+// `CRITICAL` and `HIGH` shared the red circle for as long as `CRITICAL` was
+// unreachable (#553) — a collision with nothing to collide with. Now that the
+// two are distinguishable, the icon column has to distinguish them, or the
+// ranking exists only in the text of a cell nobody scans. Matches
+// `summary-emitter.ts`, which has always used the four-color scale.
 const SEVERITY_ICON = {
     [Severity.CRITICAL]: RED_CIRCLE,
-    [Severity.HIGH]: RED_CIRCLE,
+    [Severity.HIGH]: ORANGE_CIRCLE,
     [Severity.MEDIUM]: YELLOW_CIRCLE,
     [Severity.LOW]: WHITE_CIRCLE,
 };
@@ -727,53 +901,134 @@ function findingDict(finding) {
         suggestion: finding.suggestion,
         suppressed: finding.suppressed,
         suppression_reason: finding.suppression_reason,
+        uncovered_lines: finding.uncovered_lines,
     };
 }
-export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta = null) {
+/**
+ * Join every degradation notice this run produced into one line, dropping the
+ * empty ones. Notices are independent (the agent tier and the coverage input
+ * degrade for unrelated reasons), so a reader must see both or neither (#554).
+ */
+export function combineNotices(...notices) {
+    const kept = notices.filter((n) => Boolean(n));
+    return kept.length > 0 ? kept.join('; ') : null;
+}
+/** The `coverage` block the json/analysis surfaces carry (#554). */
+export function coverageBlock(state) {
+    return { status: coverageStatus(state), ...state };
+}
+/**
+ * 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.
+ */
+function noGapsLines(coverageState, suppressedCount) {
+    const notice = coverageState ? coverageDegradedNotice(coverageState) : null;
+    const headline = 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}`];
+    if (notice) {
+        lines.push(`> **${notice}**`, '', 'Zero files matched is an abstention, not a pass — nothing here is ' +
+            'evidence that the changed lines are covered.');
+    }
+    if (suppressedCount) {
+        lines.push(`_${suppressedCount} finding(s) suppressed as intentional._`);
+    }
+    return lines;
+}
+export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta = null, blobBase = null) {
     const ordered = [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
+    // #554: the coverage ladder's own degradation, stated alongside the tier's.
+    const coverageState = gateMeta?.coverage ?? null;
+    const coverageNotice = coverageState
+        ? coverageDegradedNotice(coverageState)
+        : null;
+    const notice = combineNotices(degradedNotice, coverageNotice);
     if (fmt === 'json') {
         const payload = {
             findings: ordered.map(findingDict),
             tier,
         };
-        if (degradedNotice)
-            payload['degraded_notice'] = degradedNotice;
+        if (notice)
+            payload['degraded_notice'] = notice;
         if (gateMeta !== null) {
             payload['checked'] = gateMeta.checked;
             payload['abstained'] = gateMeta.abstained;
+            if (coverageState)
+                payload['coverage'] = coverageBlock(coverageState);
         }
         return ensureAscii(JSON.stringify(payload, null, 2));
     }
     const active = ordered.filter((f) => !f.suppressed);
     const suppressed = ordered.filter((f) => f.suppressed);
-    // A finding's file label shows the path once, appending the unit only when
-    // it is a distinct symbol within the file (never `path (path)`).
-    const fileLabel = (f) => f.unit && f.unit !== f.path
-        ? `\`${f.path}\` → \`${f.unit}\``
-        : `\`${f.path}\``;
     const cell = (s) => s.replace(/\|/g, '\\|');
+    // The line range a permalink should open at: the first range the coverage run
+    // proved unhit, else the first range the diff added. Empty when neither is
+    // known, so the link degrades to the file rather than to a wrong line.
+    const linkAnchor = (f) => {
+        const ranges = f.uncovered_lines.length
+            ? mergeLines(f.uncovered_lines)
+            : f.added_ranges;
+        const first = ranges[0];
+        if (!first)
+            return '';
+        return first[0] === first[1]
+            ? `#L${first[0]}`
+            : `#L${first[0]}-L${first[1]}`;
+    };
+    // A finding's file label shows the path once, appending the unit only when
+    // it is a distinct symbol within the file (never `path (path)`). The path
+    // becomes a permalink when a blob base is resolvable; with no base it stays
+    // plain code text, because a dead link reads as actionable and is not.
+    // Parentheses must be percent-encoded inside a markdown link target: a bare
+    // `)` closes the link early, so a Next.js route group (`app/(marketing)/…`)
+    // or any parenthesized directory would render as broken markup.
+    const urlPath = (path) => path.replace(/\(/g, '%28').replace(/\)/g, '%29');
+    const fileLabel = (f) => {
+        const shown = `\`${f.path}\``;
+        const linked = blobBase
+            ? `[${shown}](${blobBase}/${urlPath(f.path)}${linkAnchor(f)})`
+            : shown;
+        return f.unit && f.unit !== f.path ? `${linked} → \`${f.unit}\`` : linked;
+    };
+    // Evidence, then the suggested action on its own line. The specific uncovered
+    // lines live in the suggestion rather than in a second parenthetical, so the
+    // list is stated exactly once. A finding with no suggestion (a hand-built or
+    // pre-existing record) renders evidence alone — never a dangling arrow.
+    const whatCell = (f) => {
+        const action = f.suggestion
+            ? `<br><sub>${ARROW} ${cell(f.suggestion)}</sub>`
+            : '';
+        return `${cell(f.evidence)}${action}`;
+    };
     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}${degradedNotice ? ` ${EM_DASH} ${degradedNotice}` : ''}</sub>`;
+    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.
+    const coverageLine = coverageNotice ? `> **${coverageNotice}**` : null;
     if (fmt === 'comment') {
         const fileCount = new Set(active.map((f) => f.path)).size;
         const lines = [STICKY_MARKER];
         if (active.length === 0) {
-            lines.push(`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ` +
-                `${WHITE_CHECK} no test-coverage gaps`);
-            if (suppressed.length) {
-                lines.push(`_${suppressed.length} finding(s) suppressed as intentional._`);
-            }
+            lines.push(...noGapsLines(coverageState, suppressed.length));
         }
         else {
             const noun = fileCount === 1 ? 'file needs' : 'files need';
             lines.push(`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ` +
                 `${fileCount} ${noun} test coverage`);
             lines.push('These lines were changed by this PR but no test exercises them. Add or ' +
-                'extend a test that covers them, or reply ' +
-                '`/guardian suppress <file> <reason>` if they are intentionally untested.');
-            lines.push('', '| Sev | File | What is uncovered | Confidence |', '| --- | --- | --- | --- |');
+                'extend a test that covers them, or mark the line ' +
+                '`// canary:allow-untested <reason>` if it is intentionally untested.');
+            if (coverageLine)
+                lines.push('', coverageLine);
+            lines.push('', '| Sev | File | What is uncovered, and what to do | Confidence |', '| --- | --- | --- | --- |');
             // #457: fill rows against a character budget instead of emitting all of
             // them. `active` is already severity-ordered, so the rows that survive
             // are the most severe -- a critical finding is never dropped to make room
@@ -790,7 +1045,7 @@ export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta
             let used = lines.join('\n').length;
             let shown = 0;
             for (const f of active) {
-                const row = `| ${SEVERITY_ICON[f.severity] ?? ''} ${f.severity} | ${cell(fileLabel(f))} | ${cell(f.evidence)} | ${f.fidelity} |`;
+                const row = `| ${SEVERITY_ICON[f.severity] ?? ''} ${f.severity} | ${cell(fileLabel(f))} | ${whatCell(f)} | ${f.fidelity} |`;
                 if (used + row.length + 1 + reserve > COMMENT_CHAR_BUDGET)
                     break;
                 lines.push(row);
@@ -808,9 +1063,13 @@ export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta
         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';
     const lines = [
         active.length === 0
-            ? 'Canary PR Guardian — no test-coverage gaps'
+            ? cleanHeadline
             : `Canary PR Guardian — ${new Set(active.map((f) => f.path)).size} file(s) need test coverage`,
     ];
     for (const finding of ordered) {
@@ -819,8 +1078,8 @@ export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta
         lines.push(`[${finding.severity}] ${finding.path}${unit} — ${finding.evidence} (${finding.fidelity})${mark}`);
     }
     let footer = `tier ${tier}: deterministic check, no LLM`;
-    if (degradedNotice)
-        footer += ` - ${degradedNotice}`;
+    if (notice)
+        footer += ` - ${notice}`;
     lines.push(footer);
     return lines.join('\n');
 }

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

@@ -15,8 +15,9 @@
  *   test — **no network**. It can simulate a fork read-only token via
  *   `deny_writes=true` (writes reject with {@link GitHubPermissionError}).
  * - {@link RestGitHubClient} (Python's private `_RestGitHubClient`) is the thin
- *   real client. Network lives **only** here and is never exercised in unit
- *   tests.
+ *   real client. Network lives **only** here; `guardian-rest-clients.test.ts`
+ *   drives it through a stubbed global `fetch`, so the URL, headers, error
+ *   mapping, and #528 pagination are covered without a socket.
  *
  * Python→TS nuances:
  *   - **async**: Python's `urllib` client is synchronous; Node's global `fetch`
@@ -30,6 +31,7 @@
  *     rather than off a raised `HTTPError`. As in the oracle, ONLY 403 maps to a
  *     permission error here; any other non-2xx propagates as a generic error.
  */
+import { readAllPages, restPageReader } from './github-paging.js';
 // Single source of truth for the sticky-comment marker. `pr_check.render`
 // emits the identical literal at the head of a `comment`-format body so
 // `findSticky` can locate the guardian comment for in-place upsert.
@@ -46,6 +48,17 @@ export class GitHubPermissionError extends Error {
         this.name = 'GitHubPermissionError';
     }
 }
+/**
+ * Map a non-2xx status to an error. As in the Python reference, ONLY 403 is a
+ * permission error; every other non-2xx propagates (the analog of urllib's
+ * HTTPError re-raise). Shared by the write path and the paged read path so the
+ * two cannot drift.
+ */
+function toGitHubError(status, url) {
+    return status === 403
+        ? new GitHubPermissionError(`GitHub API 403 (read-only token / fork PR?): ${url}`)
+        : new Error(`GitHub API ${status}: ${url}`);
+}
 /**
  * In-memory {@link GitHubClient} for unit tests — no network.
  *
@@ -135,8 +148,10 @@ export function degradationAnnotation(notice) {
  * Thin real {@link GitHubClient} over the GitHub REST API (`fetch`).
  *
  * Python's private `_RestGitHubClient`, exported here (public, like
- * {@link RestBranchProtectionClient}). Network lives ONLY here; **no unit test
- * exercises this class**. A 403 (fork read-only token) surfaces as
+ * {@link RestBranchProtectionClient}). Network lives ONLY in `request` and in
+ * the default {@link restPageReader}; the write paths have no unit test by
+ * design, while the paged read path is covered through the injected `read`
+ * seam (#528). A 403 (fork read-only token) surfaces as
  * {@link GitHubPermissionError} so the caller degrades loudly rather than
  * crashing.
  *
@@ -148,10 +163,16 @@ export class RestGitHubClient {
     prNumber;
     token;
     static API = 'https://api.github.com';
-    constructor(repo, prNumber, token) {
+    read;
+    constructor(repo, prNumber, token, read) {
         this.repo = repo;
         this.prNumber = prNumber;
         this.token = token;
+        // The `read` seam exists so #528's paging is testable without a socket;
+        // production callers pass three arguments and get the real reader. It
+        // shares `request`'s 403 mapping so a fork PR degrades identically on a
+        // paged read and an unpaged write.
+        this.read = read ?? restPageReader(this.headers(), toGitHubError);
     }
     headers() {
         return {
@@ -168,20 +189,13 @@ export class RestGitHubClient {
             init.body = JSON.stringify(payload);
         }
         const resp = await fetch(url, init);
-        if (!resp.ok) {
-            // As in the oracle, ONLY 403 maps to a permission error; any other
-            // non-2xx propagates (the analog of urllib's HTTPError re-raise).
-            if (resp.status === 403) {
-                throw new GitHubPermissionError(`GitHub API 403 (read-only token / fork PR?): ${url}`);
-            }
-            throw new Error(`GitHub API ${resp.status}: ${url}`);
-        }
+        if (!resp.ok)
+            throw toGitHubError(resp.status, url);
         return resp.json();
     }
     async listComments() {
         const url = `${RestGitHubClient.API}/repos/${this.repo}/issues/${this.prNumber}/comments`;
-        const result = await this.request('GET', url);
-        return Array.isArray(result) ? result : [];
+        return (await readAllPages(url, this.read));
     }
     async createComment(body) {
         const url = `${RestGitHubClient.API}/repos/${this.repo}/issues/${this.prNumber}/comments`;

package/dist/engine/history/async-store.js

@@ -0,0 +1,20 @@
+/**
+ * The async history-store contract.
+ *
+ * Extracted from `store.ts` to break a circular dependency (#543): the store
+ * factory has to import every concrete backend it can return, while each
+ * backend has to import the interface it implements. Both now point at this
+ * leaf and neither points at the other. `store.ts` re-exports the type, so
+ * existing importers are unaffected.
+ *
+ * The dependency was type-only, and type-only imports are erased before
+ * anything runs — so this was never a runtime hazard. It is fixed anyway
+ * because `harness check-deps` counts it, and a cycle the gate reports is a
+ * cycle whatever the emitted JavaScript does.
+ *
+ * The contract itself is async (unlike the synchronous Python `HistoryStore`
+ * ABC) because `@supabase/supabase-js` is Promise-based; see `store.ts` for the
+ * full boundary note.
+ */
+export {};
+//# sourceMappingURL=async-store.js.map