canary-test-cli 6.6.0 → 6.7.0

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

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