canary-test-cli 6.8.1 → 7.1.0

package/dist/engine/guardian/diff-coverage/report-tier.js

@@ -0,0 +1,153 @@
+/**
+ * Tier 1 — coverage resolved from an explicit report (`COVERAGE_VERIFIED`).
+ *
+ * Owns the lcov reader, the format dispatch (which report shape is this file?),
+ * and the per-unit matching that turns a report index into verdicts.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { parseCobertura } from './formats/cobertura.js';
+import { parseCoverageJson } from './formats/coverage-json.js';
+import { expandRanges, makeResult, matchFile, rangesStr, selfDescribing, splitLines, pyInt, Fidelity, } from './types.js';
+/**
+ * Parse `lcov.info` into `{path: {line: hits}}`.
+ *
+ * Every `DA:` record is a line the instrumenter measured, so the recorded lines
+ * are exactly the coverable set — see `FileCoverage`.
+ */
+function parseLcov(text) {
+    const byPath = {};
+    let current = null;
+    for (const line of splitLines(text)) {
+        if (line.startsWith('SF:')) {
+            current = line.slice(3).trim();
+            if (!(current in byPath))
+                byPath[current] = {};
+        }
+        else if (line.startsWith('DA:') && current !== null) {
+            recordDa(byPath[current], line.slice(3).trim());
+        }
+        else if (line.trim() === 'end_of_record') {
+            current = null;
+        }
+    }
+    const index = {};
+    for (const [path, hits] of Object.entries(byPath)) {
+        index[path] = selfDescribing(hits);
+    }
+    return index;
+}
+/** Fold one `DA:<line>,<hits>` body into a file's hit map, skipping junk. */
+function recordDa(hits, body) {
+    const parts = body.split(',');
+    if (parts.length < 2)
+        return;
+    const lineno = pyInt(parts[0]);
+    const count = pyInt(parts[1]);
+    if (lineno === null || count === null)
+        return;
+    hits[lineno] = count;
+}
+/** Read a report file as UTF-8, returning `null` on any read/decode failure. */
+function readReportText(reportPath) {
+    try {
+        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).
+        return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Tier 1: resolve coverage from an explicit report (`COVERAGE_VERIFIED`).
+ *
+ * Supports `lcov.info` (`DA:<line>,<hits>`), the canary coverage-json shape,
+ * and Cobertura `coverage.xml` (line-level). Unrecognized/empty/unreadable →
+ * `null` (caller falls through to a lower fidelity tier — absence never
+ * 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. */
+export function readReportIndex(reportPath) {
+    const unusable = (found) => ({ found, index: null });
+    if (!existsSync(reportPath))
+        return unusable(false);
+    const text = readReportText(reportPath);
+    // Present but unreadable/non-UTF-8 counts as found-and-unusable, not absent.
+    if (text === null)
+        return unusable(true);
+    const index = parseByFormat(basename(reportPath).toLowerCase(), text);
+    if (index === null || Object.keys(index).length === 0)
+        return unusable(true);
+    return { found: true, index };
+}
+/** Pick the reader by report filename; `null` for a format we don't know. */
+function parseByFormat(name, text) {
+    if (name.endsWith('.json')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        return parseCoverageJson(parsed);
+    }
+    if (name.endsWith('.info') || name.includes('lcov'))
+        return parseLcov(text);
+    if (name.endsWith('.xml'))
+        return parseCobertura(text);
+    // Unrecognized format → fall through to a lower fidelity tier.
+    return null;
+}
+/** Resolve every unit the report index can speak to (COVERAGE_VERIFIED). */
+export function matchUnitsToIndex(units, index) {
+    const results = [];
+    for (const unit of units) {
+        const file = matchFile(unit.path, index);
+        if (file === null) {
+            // Unit path is nowhere in the report index → "not instrumented", which is
+            // NOT the same as "instrumented and unhit". Emit no COVERAGE_VERIFIED
+            // result so the orchestrator falls through to a lower-fidelity tier for
+            // this unit (FIX 2).
+            continue;
+        }
+        const { hits, coverable: measured } = file;
+        const added = expandRanges(unit.added_ranges);
+        // The per-line form of the check above (#655/#657): where the report says
+        // which lines it instrumented, a changed line outside that set could not
+        // have been executed and is scored by neither side. Where it does not say,
+        // every changed line counts and absence means uncovered.
+        const coverable = measured === null ? added : added.filter((ln) => measured.has(ln));
+        if (coverable.length === 0) {
+            // Every changed line is non-coverable, so this report has nothing to say
+            // about the unit. An abstention — never a clean pass, never a finding.
+            // Falls through to the graph/heuristic tier exactly as an absent path does.
+            continue;
+        }
+        const uncovered = coverable.filter((ln) => (hits[ln] ?? 0) <= 0);
+        const covered = uncovered.length === 0;
+        // State the denominator: "all covered" over 20 changed lines and over the 3
+        // of them that were coverable are very different claims (#508).
+        const evidence = covered
+            ? `lines ${rangesStr(unit.added_ranges)}: all ${coverable.length} coverable line(s) covered`
+            : `lines ${rangesStr(unit.added_ranges)}: ${uncovered.length} of ${coverable.length} coverable line(s) uncovered`;
+        results.push(makeResult({
+            unit,
+            covered,
+            fidelity: Fidelity.CoverageVerified,
+            evidence,
+            uncovered_lines: uncovered,
+            coverable_lines: coverable.length,
+        }));
+    }
+    return results;
+}
+//# sourceMappingURL=report-tier.js.map

package/dist/engine/guardian/diff-coverage/type-only.js

@@ -0,0 +1,150 @@
+/**
+ * Proof that a module has no runtime content at all (#562) — the one
+ * suppression that is about the FILE rather than the fidelity tier.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { splitLines } from './types.js';
+/**
+ * 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. `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;
+}
+//# sourceMappingURL=type-only.js.map

package/dist/engine/guardian/diff-coverage/types.js

@@ -0,0 +1,115 @@
+/**
+ * The coverage resolver's shared shapes, plus the small primitives every tier
+ * needs to speak about them (line arithmetic, Python-parity parsing, path
+ * matching). Leaf module: it imports nothing from the rest of the resolver.
+ */
+import { basename, extname } from 'node:path';
+/** Confidence tier of a coverage signal (lower rank == higher fidelity). */
+export var Fidelity;
+(function (Fidelity) {
+    Fidelity["CoverageVerified"] = "coverage-verified";
+    Fidelity["GraphVerified"] = "graph-verified";
+    Fidelity["Heuristic"] = "heuristic";
+})(Fidelity || (Fidelity = {}));
+const FIDELITY_RANK = {
+    [Fidelity.CoverageVerified]: 0,
+    [Fidelity.GraphVerified]: 1,
+    [Fidelity.Heuristic]: 2,
+};
+/** 0=coverage, 1=graph, 2=heuristic. Lower means higher fidelity. */
+export function fidelityRank(fidelity) {
+    return FIDELITY_RANK[fidelity];
+}
+/**
+ * Build a {@link CoverageResult}, defaulting `uncovered_lines` to `[]`. Stands
+ * in for the Python dataclass's `field(default_factory=list)` — the graph and
+ * heuristic tiers never populate uncovered lines and rely on that default.
+ */
+export function makeResult(fields) {
+    return { ...fields, uncovered_lines: fields.uncovered_lines ?? [] };
+}
+/** Every line the report recorded is a line it could measure (lcov/Cobertura). */
+export function selfDescribing(hits) {
+    return { hits, coverable: recordedLines(hits) };
+}
+/** The line numbers a hit map has records for. */
+export function recordedLines(hits) {
+    return new Set(Object.keys(hits).map(Number));
+}
+/** Split like Python's `str.splitlines()` for the common line endings. */
+export function splitLines(text) {
+    return text.split(/\r\n|\r|\n/);
+}
+/**
+ * Parse an integer the way Python's `int(str)` does for our inputs: optional
+ * surrounding whitespace and sign, digits only. Returns `null` on failure
+ * (Python would raise `ValueError`, which the callers catch-and-skip).
+ */
+export function pyInt(value) {
+    const trimmed = value.trim();
+    if (!/^[+-]?\d+$/.test(trimmed))
+        return null;
+    return Number.parseInt(trimmed, 10);
+}
+/** bool is excluded (a JSON true/false is not a valid line/hit count). */
+export function isInt(value) {
+    // typeof boolean !== 'number', so booleans are already excluded here — the
+    // JS analog of Python's explicit `not isinstance(value, bool)` guard.
+    return typeof value === 'number' && Number.isInteger(value);
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Flatten inclusive `[start, end]` ranges into a sorted, de-duped line list. */
+export function expandRanges(ranges) {
+    const lines = new Set();
+    for (const [start, end] of ranges) {
+        for (let ln = start; ln <= end; ln++)
+            lines.add(ln);
+    }
+    return [...lines].sort((a, b) => a - b);
+}
+/** Python's `Path(p).stem`: basename minus its final extension. */
+export function stem(path) {
+    const base = basename(path);
+    const ext = extname(base);
+    return ext ? base.slice(0, -ext.length) : base;
+}
+/**
+ * True iff `candidate` and `target` name the same file path suffix.
+ *
+ * Exact match, or one is a suffix of the other on a **path-separator boundary**
+ * (`a/b/foo.py` vs `foo.py`). Rejects loose substring collisions such as
+ * `foobar.py` vs `bar.py` and `usermodels.py` vs `models.py` (FIX 6).
+ */
+export function pathBoundaryMatch(candidate, target) {
+    return (candidate === target ||
+        candidate.endsWith('/' + target) ||
+        target.endsWith('/' + candidate));
+}
+/**
+ * Look up one file's coverage for `path` in a report index.
+ *
+ * Prefers an EXACT path match. Otherwise falls back to a **boundary** suffix
+ * match (report paths may be absolute, `./`-prefixed, or repo-relative). On
+ * multiple boundary matches (duplicate basenames) the lookup is ambiguous and
+ * returns `null` — the unit is then skipped and falls through rather than
+ * binding to an arbitrary first match (FIX 6).
+ */
+export function matchFile(path, index) {
+    if (path in index)
+        return index[path];
+    const matches = [];
+    for (const [reportPath, file] of Object.entries(index)) {
+        if (pathBoundaryMatch(reportPath, path))
+            matches.push(file);
+    }
+    return matches.length === 1 ? matches[0] : null;
+}
+/** Render ranges compactly, e.g. `[[12, 28], [30, 30]]` → `"12-28, 30"`. */
+export function rangesStr(ranges) {
+    return ranges
+        .map(([start, end]) => (start === end ? `${start}` : `${start}-${end}`))
+        .join(', ');
+}
+//# sourceMappingURL=types.js.map

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

@@ -30,6 +30,7 @@ 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 { Severity, severitySortKey } from './impact-mapper.js';
+import { ensureAscii } from '../util/ensure-ascii.js';
 const HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
 // Suppression annotation: `// canary:allow-untested <reason>` or the `#`
 // variant. A comment leader (`//` or `#`) is REQUIRED immediately before the
@@ -470,7 +471,7 @@ export function filterHeuristicNoise(results, excludeGlobs) {
  * concern). `severity` reuses {@link Severity}; `fidelity` carries the
  * confidence tier from the underlying coverage signal.
  */
-export class Finding {
+export class GuardianFinding {
     path;
     unit;
     kind;
@@ -585,7 +586,7 @@ function uncoveredShare(result, uncovered) {
  * 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
+ * (see the `uncovered_lines` comment on {@link GuardianFinding}). 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
@@ -642,7 +643,7 @@ export function buildFindings(results) {
             severity = Severity.HIGH;
         const unit = result.unit;
         const uncovered = [...(result.uncovered_lines ?? [])];
-        findings.push(new Finding({
+        findings.push(new GuardianFinding({
             path: unit.path,
             unit: unit.symbol || unit.path,
             fidelity: result.fidelity,
@@ -724,7 +725,7 @@ export function buildWeakTestFindings(testUnits, diffText) {
         const code = added.join('\n');
         const framework = frameworkForTestPath(unit.path);
         if (isAssertionFreeTest(code, framework)) {
-            findings.push(new Finding({
+            findings.push(new GuardianFinding({
                 path: unit.path,
                 unit: unit.path,
                 kind: 'weak-test',
@@ -859,9 +860,9 @@ const STICKY_MARKER = '<!-- canary-pr-guardian -->';
  * 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 `render`
- * (degradation annotations, upsert wrappers) without inviting a body that only
- * *just* fits and then breaks when a filename grows.
+ * 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.
@@ -893,18 +894,7 @@ const SEVERITY_ICON = {
     [Severity.MEDIUM]: YELLOW_CIRCLE,
     [Severity.LOW]: WHITE_CIRCLE,
 };
-/**
- * Escape every non-ASCII (>= U+0080) code unit to a `\uXXXX` sequence, matching
- * Python's `json.dumps(..., ensure_ascii=True)` (the library default). `JSON`
- * `.stringify` emits raw UTF-8 for these, so a finding whose evidence carries an
- * em-dash (`—`, U+2014) would otherwise diverge byte-for-byte from the Python
- * oracle. Only touches the >= 0x80 range, so the ASCII escapes JSON.stringify
- * already produced (`\"`, `\\`, control chars) are left intact.
- */
-function ensureAscii(json) {
-    return json.replace(/[€-￿]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
-}
-/** Serialize a {@link Finding} to a stable JSON-friendly object. */
+/** Serialize a {@link GuardianFinding} to a stable JSON-friendly object. */
 function findingDict(finding) {
     return {
         path: finding.path,
@@ -955,7 +945,7 @@ function noGapsLines(coverageState, suppressedCount) {
     }
     return lines;
 }
-export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta = null, blobBase = null) {
+export function renderFindings(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;

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

@@ -32,9 +32,10 @@
  *     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.
+// Single source of truth for the sticky-comment marker.
+// `pr_check.renderFindings` emits the identical literal at the head of a
+// `comment`-format body so `findSticky` can locate the guardian comment for
+// in-place upsert.
 export const STICKY_MARKER = '<!-- canary-pr-guardian -->';
 /**
  * A client cannot write (fork read-only token → HTTP 403).