canary-test-cli 6.5.0 → 6.7.0

package/dist/engine/guardian/cli.js

@@ -53,12 +53,12 @@ import { AuthoringContext, InSessionAgentProbe, InSessionAgentTier, decideBlock,
 import { RestReactionsClient, collectAdjudications, loadAdjudicationRecords, renderPrecision, summarizePrecision, } from './adjudication.js';
 import { emitAnalysis } from './analysis-emit.js';
 import { gateOutcome } from '../core/gate-result.js';
-import { resolveCoverage, validateCoverageJson, } from './coverage.js';
+import { coverageDegradedNotice, resolveCoverage, resolveCoverageWithInput, validateCoverageJson, } from './coverage.js';
 import { buildApiDelta, writeApiDelta } from './delta-emitter.js';
 import { extractApiDiff } from './diff-extractor.js';
 import { HardGateAbstained, HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
 import { mapImpact } from './impact-mapper.js';
-import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestUnits, findReexportOnly, loadGuardianConfig, render, scopeDiff, } from './pr-check.js';
+import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestSupportUnits, filterTestUnits, filterTypeOnlyUnits, findReexportOnly, loadGuardianConfig, render, scopeDiff, } from './pr-check.js';
 import { RestGitHubClient, degradationAnnotation, upsertStickyComment, } from './pr-comment.js';
 import { buildSummary } from './summary-emitter.js';
 import { resolveTier } from './tier.js';
@@ -202,6 +202,53 @@ export function prContextFromEnv(env) {
     }
     return null;
 }
+/**
+ * The `https://github.com/<owner>/<repo>/blob/<sha>` prefix for comment
+ * permalinks, or `null` when it cannot be resolved.
+ *
+ * Prefers `pull_request.head.sha` from the event payload over `GITHUB_SHA`: on
+ * a `pull_request` event `GITHUB_SHA` is the ephemeral merge commit, and a blob
+ * URL against it can 404 once the ref is gone. The head SHA is a real commit on
+ * the contributor's branch and stays resolvable.
+ *
+ * Returns `null` rather than a partial URL whenever repo or SHA is missing, so
+ * {@link render} falls back to plain code text. That degradation is deliberate:
+ * an unresolvable link still *looks* clickable, which is worse than no link.
+ */
+export function blobBaseFromEnv(env) {
+    const repo = env['GITHUB_REPOSITORY'];
+    if (!repo || !repo.includes('/'))
+        return null;
+    const sha = headShaFromEvent(env['GITHUB_EVENT_PATH']) ?? env['GITHUB_SHA'];
+    if (!sha)
+        return null;
+    return `https://github.com/${repo}/blob/${sha}`;
+}
+/**
+ * `pull_request.head.sha` from the event payload at `eventPath`, or `null`.
+ *
+ * Every failure — no path, unreadable file, non-JSON body, a payload without a
+ * `pull_request` — returns `null` so {@link blobBaseFromEnv} falls through to
+ * `GITHUB_SHA` rather than dropping links entirely: a merge-commit link still
+ * beats no link.
+ */
+function headShaFromEvent(eventPath) {
+    if (!eventPath)
+        return null;
+    try {
+        // Optional chaining carries the shape check: on a payload that is not an
+        // object (a bare number or string), `?.` short-circuits to `undefined`
+        // exactly as an explicit `typeof === 'object'` guard would.
+        const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+        const head = event?.pull_request?.head?.sha;
+        if (typeof head !== 'string')
+            return null;
+        return head || null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * At-desk fork signal (guard b), FAIL-CLOSED on ambiguity.
  *
@@ -787,8 +834,8 @@ function precisionCmd(opts, deps) {
  * PR context is resolvable from env, prints the body instead of crashing; a
  * read-only-token degradation is surfaced LOUDLY.
  */
-async function postStickyComment(findings, resolution, deps) {
-    const body = render(findings, 'comment', resolution.effective, resolution.degraded_notice);
+async function postStickyComment(findings, resolution, deps, gateMeta = null) {
+    const body = render(findings, 'comment', resolution.effective, resolution.degraded_notice, gateMeta, blobBaseFromEnv(deps.env));
     const ctx = prContextFromEnv(deps.env);
     if (ctx === null) {
         deps.out(`guardian: no PR context in env ${EM_DASH} printing instead.`);
@@ -806,10 +853,17 @@ async function postStickyComment(findings, resolution, deps) {
 // D7: every filtered path stays visible as a SkipEntry, never folded
 // into "passed". One entry per path so the rendered count still equals
 // the path count the old `N path(s) skipped` line reported.
-function prCheckSkipEntries(skipped, testUnits, barrelUnits, noisePaths = []) {
+function prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits = [], noisePaths = [], typeOnlyUnits = []) {
     return [
         ...skipped.map((u) => ({ name: u.path, reason: 'skipGlobs' })),
         ...testUnits.map((u) => ({ name: u.path, reason: 'test path' })),
+        // #565: distinct from 'test path' on purpose -- these are test
+        // infrastructure recognised by filename idiom, and adjudication needs to
+        // tell the two suppression causes apart.
+        ...supportUnits.map((u) => ({ name: u.path, reason: 'test support' })),
+        // #562: likewise distinct -- adjudication has to be able to measure this
+        // class separately, since it is the one that held precision at 13/20.
+        ...typeOnlyUnits.map((u) => ({ name: u.path, reason: 'type-only module' })),
         ...barrelUnits.map((u) => ({
             name: u.path,
             reason: 're-export barrel',
@@ -839,7 +893,12 @@ function abstainPrCheck(skipped, format, deps) {
     for (const line of PR_CHECK_ABSTAIN_REMEDIATION)
         deps.out(line);
     if (format === 'json') {
-        deps.out(ensureAscii(JSON.stringify({ findings: [], tier: 0, checked: 0, abstained: true }, null, 2)));
+        deps.out(ensureAscii(JSON.stringify(
+        // #579: `skipped` carries the denominator the abstention collapsed
+        // to. Without it a consumer sees `abstained: true` and cannot tell
+        // WHAT was dropped or why -- the #508 class one layer down, on the
+        // only surface a machine can read.
+        { findings: [], tier: 0, checked: 0, abstained: true, skipped }, null, 2)));
     }
     throw new CliExit(outcome.exitCode); // EXIT_ABSTAINED
 }
@@ -923,19 +982,31 @@ async function prCheckCmd(opts, deps) {
     const [keptSkip, skipped] = filterSkipped(units, config.skip_globs);
     // FIX A: drop test-path units -- a test does not itself need a test.
     const [keptTest, testUnits] = filterTestUnits(keptSkip);
+    // #565: drop test *support* units -- a conftest / fixture module is the
+    // harness the tests run inside, so no test can cover it at any tier.
+    const [keptSupport, supportUnits] = filterTestSupportUnits(keptTest);
+    // #562: drop modules with no runtime content -- an interface cannot be
+    // executed, so its uncovered lines are a finding no test could ever satisfy.
+    // `.` (cwd), matching the repoRoot convention `resolveCoverageWithInput`
+    // already uses for the heuristic tier's own file reads.
+    const [keptTyped, typeOnlyUnits] = filterTypeOnlyUnits(keptSupport, '.');
     // FIX 2: drop pure re-export/barrel files.
     const reexportPaths = findReexportOnly(diffText);
-    const barrelUnits = keptTest.filter((u) => reexportPaths.has(u.path));
-    const kept = keptTest.filter((u) => !reexportPaths.has(u.path));
+    const barrelUnits = keptTyped.filter((u) => reexportPaths.has(u.path));
+    const kept = keptTyped.filter((u) => !reexportPaths.has(u.path));
     // Advisory weak-test findings for added tests that assert nothing.
     const weakFindings = config.weak_tests
         ? buildWeakTestFindings(testUnits, diffText)
         : [];
-    const preFilterSkipped = skipped.length + testUnits.length + barrelUnits.length;
+    const preFilterSkipped = skipped.length +
+        testUnits.length +
+        barrelUnits.length +
+        supportUnits.length +
+        typeOnlyUnits.length;
     if (kept.length === 0 && weakFindings.length === 0) {
-        abstainPrCheck(prCheckSkipEntries(skipped, testUnits, barrelUnits), opts.format, deps);
+        abstainPrCheck(prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits, [], typeOnlyUnits), opts.format, deps);
     }
-    const results = resolveCoverage(kept, {
+    const { results, coverage } = resolveCoverageWithInput(kept, {
         coveragePath: opts.coverage ?? null,
         // #320: under a hard gate the graph tier requires a DIRECT test->source edge
         // (depth 1); soft stays unbounded. An explicit config value wins.
@@ -953,7 +1024,7 @@ async function prCheckCmd(opts, deps) {
     // SKIP rather than rendering an empty "0 unaddressed" report -- an adopter
     // must be able to tell "nothing was judgeable" from "everything passed".
     if (scoredResults.length === 0 && findings.length === 0) {
-        abstainPrCheck(prCheckSkipEntries(skipped, testUnits, barrelUnits, noiseResults.map((r) => r.unit.path)), opts.format, deps);
+        abstainPrCheck(prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits, noiseResults.map((r) => r.unit.path), typeOnlyUnits), opts.format, deps);
     }
     // SC-5 (PR half): resolve the requested tier against actual capability. No
     // agent runtime exists (default NoAgentProbe), so any `pr.tier > 0` drops to
@@ -966,6 +1037,22 @@ async function prCheckCmd(opts, deps) {
     // Compute the gate result once, up front: the emitted record carries it and it
     // is the process exit at the end (SC-4 -- emit never changes the exit logic).
     const exitCode = computeExitCode(findings, effectiveGate);
+    // #554: every surface below carries the coverage-input state, so a run that
+    // never saw a coverage report cannot present as one that checked and passed.
+    const gateMeta = {
+        checked: scoredResults.length,
+        abstained: false,
+        coverage,
+    };
+    const coverageNotice = coverageDegradedNotice(coverage);
+    if (coverageNotice) {
+        // `--format json` owns stdout: a `::warning::` line there would make the
+        // document unparseable, so the annotation goes to stderr on that path. Both
+        // streams are scanned for workflow commands, so CI still sees it.
+        const machineStdout = !opts.postComment && !opts.emitAnalysis && opts.format === 'json';
+        (machineStdout ? deps.err : deps.out)(degradationAnnotation(coverageNotice));
+        appendStepSummary(deps.env, coverageNotice);
+    }
     let commentPosted = false;
     if (opts.emitAnalysis) {
         // SC-10 producer half: write ONE record to the analyses channel. On an
@@ -981,6 +1068,7 @@ async function prCheckCmd(opts, deps) {
             exit_code: exitCode,
             checked: scoredResults.length,
             abstained: false, // an abstained run exits before emit (see plan)
+            coverage,
         });
         if (res.action === 'emitted') {
             deps.out(`guardian: wrote analysis record ${RIGHT_ARROW} ${res.path}`);
@@ -991,18 +1079,18 @@ async function prCheckCmd(opts, deps) {
             deps.out(degradationAnnotation(res.notice));
             appendStepSummary(deps.env, res.notice);
             deps.err(res.notice);
-            await postStickyComment(findings, resolution, deps);
+            await postStickyComment(findings, resolution, deps, gateMeta);
             commentPosted = true;
         }
     }
     if (opts.postComment && !commentPosted) {
         // Explicit `--post-comment`: post/upsert unless the SC-10 fallback already
         // posted this run.
-        await postStickyComment(findings, resolution, deps);
+        await postStickyComment(findings, resolution, deps, gateMeta);
     }
     else if (!opts.emitAnalysis && !opts.postComment) {
         // Local, non-posting default: render to stdout in `--format`.
-        deps.out(render(findings, opts.format, resolution.effective, resolution.degraded_notice, { checked: scoredResults.length, abstained: false }));
+        deps.out(render(findings, opts.format, resolution.effective, resolution.degraded_notice, gateMeta, blobBaseFromEnv(deps.env)));
     }
     throw new CliExit(exitCode);
 }
@@ -1016,8 +1104,17 @@ function buildGaps(diffText, config, coveragePath, graphMaxDepth) {
     const units = scopeDiff(diffText);
     const [keptSkip] = filterSkipped(units, config.skip_globs);
     const [keptTest] = filterTestUnits(keptSkip);
+    // #565: never hand the authoring tier a conftest/fixture module either -- a
+    // generated "test for the fixture" is exactly the inversion the gate exists
+    // to prevent, except it also writes a file (measured: this surface proposed
+    // `scripts/otel_bootstrap/test_conftest_otel.py`).
+    const [keptSupport] = filterTestSupportUnits(keptTest);
+    // #562: nor a type-only module -- measured, this surface proposed writing
+    // `src/ConfirmModal/types.test.ts` to test an interface, a file whose only
+    // possible content is an assertion about nothing.
+    const [keptTyped] = filterTypeOnlyUnits(keptSupport, '.');
     const reexportPaths = findReexportOnly(diffText);
-    const kept = keptTest.filter((u) => !reexportPaths.has(u.path));
+    const kept = keptTyped.filter((u) => !reexportPaths.has(u.path));
     if (kept.length === 0)
         return [];
     const results = resolveCoverage(kept, { coveragePath, graphMaxDepth });

package/dist/engine/guardian/coverage.js

@@ -594,8 +594,6 @@ function attrValue(attrs, name) {
 /** Read a report file as UTF-8, returning `null` on any read/decode failure. */
 function readReportText(reportPath) {
     try {
-        if (!existsSync(reportPath))
-            return null;
         const buf = readFileSync(reportPath);
         // Fatal decode: a non-UTF-8 report must fall through, never raise out of
         // the guardian gate (mirrors Python's UnicodeDecodeError → None).
@@ -614,9 +612,19 @@ function readReportText(reportPath) {
  * blocks).
  */
 export function resolveFromReport(units, reportPath) {
+    const { index } = readReportIndex(reportPath);
+    if (index === null)
+        return null;
+    return matchUnitsToIndex(units, index);
+}
+/** Read + parse a coverage report, reporting each step's outcome separately. */
+function readReportIndex(reportPath) {
+    if (!existsSync(reportPath))
+        return { found: false, index: null };
     const text = readReportText(reportPath);
+    // Present but unreadable/non-UTF-8 counts as found-and-unusable, not absent.
     if (text === null)
-        return null;
+        return { found: true, index: null };
     const name = basename(reportPath).toLowerCase();
     let index;
     if (name.endsWith('.json')) {
@@ -625,7 +633,7 @@ export function resolveFromReport(units, reportPath) {
             parsed = JSON.parse(text);
         }
         catch {
-            return null;
+            return { found: true, index: null };
         }
         index = parseCoverageJson(parsed);
     }
@@ -637,10 +645,15 @@ export function resolveFromReport(units, reportPath) {
     }
     else {
         // Unrecognized format → fall through to a lower fidelity tier.
-        return null;
+        return { found: true, index: null };
     }
-    if (index === null || Object.keys(index).length === 0)
-        return null;
+    if (index === null || Object.keys(index).length === 0) {
+        return { found: true, index: null };
+    }
+    return { found: true, index };
+}
+/** Resolve every unit the report index can speak to (COVERAGE_VERIFIED). */
+function matchUnitsToIndex(units, index) {
     const results = [];
     for (const unit of units) {
         const hits = matchHits(unit.path, index);
@@ -682,6 +695,207 @@ const TEST_PATH_RE = /(^|\/)tests?\/|(^|\/)test_[^/]*\.py$|\.test\.[^/]+$|\.spec
 export function isTestPath(path) {
     return TEST_PATH_RE.test(path);
 }
+/**
+ * Split a basename's stem into `-`/`_`/`.`-separated components (#565).
+ *
+ * `playwright-fixture.ts` → `['playwright', 'fixture']`;
+ * `user.fixtures.ts` → `['user', 'fixtures']`. The final extension is dropped
+ * first so it never appears as a component.
+ */
+function basenameComponents(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    const stem = dot > 0 ? base.slice(0, dot) : base;
+    return stem.split(/[-_.]/).filter((part) => part.length > 0);
+}
+/** Basename components that mark a file as test *support* rather than source. */
+const FIXTURE_COMPONENTS = new Set([
+    'fixture',
+    'fixtures',
+]);
+/**
+ * True if `path` is test *infrastructure* identified by filename idiom (#565).
+ *
+ * {@link isTestPath} recognises tests by directory (`tests/**`) or by the
+ * `*.test.*` / `*.spec.*` / `test_*.py` naming rules, and the skip layer
+ * recognises fixtures by the `fixtures/` *directory* convention. Neither
+ * catches a file that is test support by **name** while sitting in an ordinary
+ * source directory — the measured cases being a pytest `conftest_otel.py` and a
+ * Playwright `playwright-fixture.ts`, both under `scripts/otel_bootstrap/`.
+ *
+ * Such a file cannot host a test in the sense a coverage finding means: it *is*
+ * the harness the tests run inside. Asking it for a covering test inverts the
+ * relationship, so a reviewer's only correct response is 👎 — the precision
+ * cost #413 and #562 both describe.
+ *
+ * Two deliberate narrowings:
+ *
+ *   - **Components, not substrings.** `conftestimonial.py` and
+ *     `prefixtures.ts` are ordinary source and must survive. Matching on
+ *     `-`/`_`/`.`-separated components is what pytest's own name-based
+ *     resolution and the `*.fixtures.ts` idiom actually mean.
+ *   - **`conftest` is Python-only.** It is pytest's resolution rule
+ *     specifically; a `conftest.js` carries no framework meaning and is left as
+ *     source.
+ *
+ * Known over-match, accepted: a production module genuinely named
+ * `fixture-generator.ts` is suppressed. That trade is deliberate — a missed
+ * finding on a file named after fixtures costs far less than a finding no
+ * reviewer can ever act on, which is what drags `precision = TP / (TP + FP)`
+ * below the promotion bar.
+ *
+ * Kept separate from {@link isTestPath} on purpose: that predicate also decides
+ * what *confers* graph coverage, so widening it would let a conftest mark every
+ * module it imports as tested — a false negative in place of a false positive.
+ */
+export function isTestSupportPath(path) {
+    const components = basenameComponents(path);
+    if (path.endsWith('.py') && components.includes('conftest'))
+        return true;
+    return components.some((part) => FIXTURE_COMPONENTS.has(part));
+}
+/**
+ * Filenames/paths that plausibly hold nothing but type declarations (#562).
+ *
+ * A NAME GATE ONLY -- it decides which files are worth reading, never which
+ * are suppressed. {@link isTypeOnlyModule} always confirms against content,
+ * because a `types.ts` that also exports an enum or a const map is ordinary
+ * TypeScript and its findings are real.
+ */
+function isTypeModuleCandidate(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    if (base.endsWith('.d.ts'))
+        return true;
+    if (!/\.(ts|tsx|mts|cts)$/.test(base))
+        return false;
+    if (base === 'types.ts' || base.endsWith('.types.ts'))
+        return true;
+    return path.split('/').slice(0, -1).includes('types');
+}
+/**
+ * True if `path` is a module with no runtime content at all (#562).
+ *
+ * The false-positive class this closes is the one the heuristic-tier fix
+ * (#413) structurally cannot reach. {@link filterHeuristicNoise} is gated on
+ * `fidelity === HEURISTIC` on purpose -- a coverage-verified verdict rests on
+ * a real lcov row, so suppressing by path at that tier would discard
+ * evidence. A type-only module is the case that breaks the symmetry: the lcov
+ * row is accurate (39 lines, genuinely never executed) and the finding is
+ * still unsatisfiable, because an interface has no runtime existence for a
+ * test to reach. The evidence needed is therefore about the FILE, not the
+ * tier: prove there is nothing executable in it.
+ *
+ * Conservative in one direction on purpose. Every uncertainty -- an
+ * unreadable file, an unrecognised construct -- resolves to `false`, keeping
+ * the finding. A missed suppression costs one noisy finding; a wrong
+ * suppression hides untested code, which is the thing the guardian exists to
+ * catch.
+ */
+export function isTypeOnlyModule(path, repoRoot) {
+    if (!isTypeModuleCandidate(path))
+        return false;
+    let source;
+    try {
+        source = readFileSync(join(repoRoot, path), 'utf-8');
+    }
+    catch {
+        return false; // unreadable -> unproven -> keep the finding
+    }
+    return isTypeOnlySource(source);
+}
+/** Drop `//` and `/* *\/` comments so keywords inside prose never count. */
+function stripComments(source) {
+    const out = [];
+    let inBlock = false;
+    for (const line of splitLines(source)) {
+        let text = line;
+        if (inBlock) {
+            const end = text.indexOf('*/');
+            if (end === -1) {
+                out.push('');
+                continue;
+            }
+            text = text.slice(end + 2);
+            inBlock = false;
+        }
+        for (;;) {
+            const start = text.indexOf('/*');
+            if (start === -1)
+                break;
+            const end = text.indexOf('*/', start + 2);
+            if (end === -1) {
+                text = text.slice(0, start);
+                inBlock = true;
+                break;
+            }
+            text = text.slice(0, start) + text.slice(end + 2);
+        }
+        const line2 = text.indexOf('//');
+        out.push(line2 === -1 ? text : text.slice(0, line2));
+    }
+    return out.join('\n');
+}
+/**
+ * Top-level constructs TypeScript erases entirely at compile time (#562).
+ *
+ * An ALLOWLIST, not a denylist, and that is the load-bearing choice. A
+ * denylist of runtime keywords misses everything it did not enumerate -- a
+ * bare `register('widget')` declares nothing and still runs -- and every gap
+ * in it suppresses a real finding. An allowlist fails the other way: an
+ * unrecognised construct reads as runtime and the finding survives.
+ *
+ * Plain `import { X } from '...'` is allowed because TypeScript elides an
+ * import whose bindings are only used in type positions; if a binding were
+ * used as a value, the using statement itself would appear at top level and
+ * be rejected. A side-effect `import './x'` carries no binding, is never
+ * elided, and is therefore not matched.
+ */
+function isErasableTopLevelLine(line) {
+    if (line === '')
+        return true;
+    if (/^[})\];,]+$/.test(line))
+        return true;
+    if (/^import\s+type\b/.test(line))
+        return true;
+    if (/^import\b.*\sfrom\s/.test(line))
+        return true;
+    if (/^export\s+type\b/.test(line))
+        return true;
+    const bare = line.replace(/^(?:export\s+default\s+|export\s+|declare\s+)+/, '');
+    return /^(?:interface|type)\s/.test(bare);
+}
+/**
+ * True if every TOP-LEVEL statement in `source` is compile-time-only.
+ *
+ * Brace depth is tracked so an interface body is never mistaken for
+ * statements: only depth-0 lines are judged. An unbalanced file (depth does
+ * not return to zero) is treated as unproven rather than type-only -- brace
+ * counting is lexical, so a `{` inside a string literal could otherwise hide
+ * the rest of the file from inspection.
+ */
+function isTypeOnlySource(source) {
+    let depth = 0;
+    for (const raw of splitLines(stripComments(source))) {
+        const line = raw.trim();
+        if (depth === 0 && !isErasableTopLevelLine(line))
+            return false;
+        depth += bracketDelta(line);
+        if (depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Net nesting change across one line: openers minus closers. */
+function bracketDelta(line) {
+    let delta = 0;
+    for (const ch of line) {
+        if (ch === '{' || ch === '(' || ch === '[')
+            delta += 1;
+        else if (ch === '}' || ch === ')' || ch === ']')
+            delta -= 1;
+    }
+    return delta;
+}
 /**
  * Extensions that denote hand-authored, executable program source (#413).
  *
@@ -1112,18 +1326,86 @@ function escapeRe(s) {
  * is forwarded verbatim to {@link resolveFromGraph}.
  */
 export function resolveCoverage(units, options = {}) {
+    return resolveCoverageWithInput(units, options).results;
+}
+/** Classify a {@link CoverageInputState}. Zero matched is never `verified`. */
+export function coverageStatus(state) {
+    if (state.unitsTotal > 0 && state.unitsMatched === state.unitsTotal) {
+        return 'verified';
+    }
+    return state.unitsMatched > 0 ? 'partial' : 'unavailable';
+}
+const COVERAGE_EM_DASH = '\u{2014}';
+const FALLBACK_TIER = 'judged at graph/heuristic tier only';
+/**
+ * The human-readable degradation notice for a coverage run, or `null` when the
+ * report covered every changed unit (nothing was degraded, so nothing is said).
+ *
+ * A run that judged nothing (`unitsTotal === 0`) also returns `null` — it makes
+ * no coverage claim in either direction, and the abstention path reports it.
+ */
+export function coverageDegradedNotice(state) {
+    const { requested, found, parsed, filesInReport } = state;
+    const { unitsMatched: matched, unitsTotal: total } = state;
+    if (total === 0)
+        return null;
+    const status = coverageStatus(state);
+    if (status === 'verified')
+        return null;
+    const dash = ` ${COVERAGE_EM_DASH} `;
+    if (status === 'partial') {
+        return (`coverage partial${dash}report at '${requested}' matched ` +
+            `${matched} of ${total} changed file(s); the other ${total - matched} ` +
+            FALLBACK_TIER);
+    }
+    const head = `coverage unavailable${dash}`;
+    if (requested === null) {
+        return `${head}no coverage report was supplied; ${total} changed file(s) ${FALLBACK_TIER}`;
+    }
+    if (!found) {
+        return `${head}report not found at '${requested}'; ${total} changed file(s) ${FALLBACK_TIER}`;
+    }
+    if (!parsed) {
+        return (`${head}report at '${requested}' yielded no usable records; ` +
+            `${total} changed file(s) ${FALLBACK_TIER}`);
+    }
+    return (`${head}report at '${requested}' covers ${filesInReport} file(s) but ` +
+        `matched 0 of ${total} changed file(s); ${FALLBACK_TIER}`);
+}
+/**
+ * {@link resolveCoverage}, additionally reporting which mode the run was in.
+ *
+ * Identical ladder, identical results — the only addition is the
+ * {@link CoverageInputState} record, so a later reader can tell a clean result
+ * from a blind one (#554).
+ */
+export function resolveCoverageWithInput(units, options = {}) {
     const { coveragePath = null, graphPath = '.harness/graph/graph.json', repoRoot = '.', graphMaxDepth = null, } = options;
     // Reference-keyed map mirrors the Python `id(unit)` bookkeeping, so distinct
     // units that happen to share a path are still tracked independently.
     const resolved = new Map();
     let remaining = [...units];
+    const coverage = {
+        requested: coveragePath,
+        found: false,
+        parsed: false,
+        filesInReport: 0,
+        unitsMatched: 0,
+        unitsTotal: units.length,
+    };
     if (coveragePath !== null) {
-        const report = resolveFromReport(remaining, coveragePath);
+        const read = readReportIndex(coveragePath);
+        coverage.found = read.found;
+        coverage.parsed = read.index !== null;
+        coverage.filesInReport =
+            read.index === null ? 0 : Object.keys(read.index).length;
+        const report = read.index === null ? null : matchUnitsToIndex(remaining, read.index);
         // An empty array (no unit matched the report) is falsy-equivalent in the
         // Python `if report:` guard — fall through rather than lock in nothing.
         if (report !== null && report.length > 0) {
             for (const r of report)
                 resolved.set(r.unit, r);
+            coverage.unitsMatched = report.length;
             remaining = remaining.filter((u) => !resolved.has(u));
         }
     }
@@ -1140,6 +1422,6 @@ export function resolveCoverage(units, options = {}) {
             resolved.set(r.unit, r);
         }
     }
-    return units.map((unit) => resolved.get(unit));
+    return { results: units.map((unit) => resolved.get(unit)), coverage };
 }
 //# sourceMappingURL=coverage.js.map