canary-test-cli 6.1.0 → 6.3.0

package/dist/engine/guardian/cli.js

@@ -55,7 +55,7 @@ import { buildApiDelta, writeApiDelta } from './delta-emitter.js';
 import { extractApiDiff } from './diff-extractor.js';
 import { HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
 import { mapImpact } from './impact-mapper.js';
-import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterSkipped, filterTestUnits, findReexportOnly, loadGuardianConfig, render, scopeDiff, } from './pr-check.js';
+import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestUnits, 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';
@@ -258,22 +258,206 @@ const AUTHORED_SENTINEL_NAME = 'canary-guardian-authored';
 function authoredSentinelPath(deps, root) {
     return join(gitDir(deps, root), AUTHORED_SENTINEL_NAME);
 }
+// The sentinel's FIRST line stamps the HEAD the guardian authored at:
+// `HEAD <sha>`. Every line after it is one authored path. Anchored at the start
+// of the body and hex-only, with a trailing `[ \t\r]*` so a CRLF-written file
+// still parses -- anything else reads as malformed, which fails OPEN.
+const SENTINEL_HEAD_RE = /^HEAD ([0-9a-fA-F]{7,64})[ \t\r]*(?:\n|$)/;
+/**
+ * Parse the `HEAD <sha>` stamp off a sentinel body; `null` when malformed.
+ *
+ * Malformed covers empty, headerless (the pre-#456 paths-only format), and any
+ * unparseable first line. Callers MUST treat `null` as "cannot verify" and fail
+ * OPEN -- an unreadable sentinel must never wedge authoring off (#456).
+ */
+function sentinelHeadStamp(text) {
+    const match = SENTINEL_HEAD_RE.exec(text);
+    return match === null ? null : match[1].toLowerCase();
+}
+/** Current `HEAD` sha for `root`, or `null` when git/HEAD is unavailable. */
+function headSha(deps, root) {
+    const res = deps.runGit(['rev-parse', 'HEAD'], root);
+    if (res === null || res.code !== 0)
+        return null; // no git / no commits
+    return res.stdout.trim().toLowerCase() || null;
+}
+/**
+ * Is the loop guard live -- i.e. does a sentinel stamped at the CURRENT `HEAD`
+ * exist?
+ *
+ * This is the surviving half of the stage-and-block-once contract (#456). The
+ * component that CLEARED the sentinel on the next commit
+ * (`hooks/guardian_precommit.py`) was deleted as dead code in #449, which left
+ * `author-plan` fail-closed forever: author once in a clone and Tier-2 authoring
+ * never ran again. Stamping HEAD makes the guard self-expiring -- once the human
+ * reviews and commits the staged tests, `HEAD` moves, the stamp stops matching,
+ * and authoring re-enables itself with no manual step and no hook.
+ *
+ * Every unverifiable state FAILS OPEN (returns `false`, authoring allowed):
+ * missing or unreadable sentinel, a malformed/absent `HEAD` header, or a `HEAD`
+ * we cannot resolve. Fail-closed here is exactly the bug being fixed.
+ */
+function authoredSentinelActive(deps, root) {
+    let body;
+    try {
+        body = readFileSync(authoredSentinelPath(deps, root), 'utf-8');
+    }
+    catch {
+        return false; // absent or unreadable -> fail open
+    }
+    const stamp = sentinelHeadStamp(body);
+    if (stamp === null)
+        return false; // malformed -> fail open
+    const head = headSha(deps, root);
+    if (head === null)
+        return false; // unverifiable -> fail open
+    return head === stamp;
+}
 /**
  * Return raw unified-diff text from a source.
  *
  * `source === '-'` reads stdin; a path reads that file; `null` runs `git diff`
  * and falls back to `git diff --staged` when the worktree is clean.
+ *
+ * This is the AT-DESK resolution: the working tree is the subject. `pr-check`
+ * uses {@link readPrDiff} instead, which prefers the PR diff in CI (#369).
  */
 function readDiff(source, deps) {
     if (source === '-')
         return deps.readStdin();
     if (source !== null)
         return readFileSync(source, 'utf-8');
+    return readWorktreeDiff(deps);
+}
+/** `git diff`, falling back to `git diff --staged` on a clean worktree. */
+function readWorktreeDiff(deps) {
     const unstaged = deps.runGit(['diff'])?.stdout ?? '';
     if (unstaged.trim())
         return unstaged;
     return deps.runGit(['diff', '--staged'])?.stdout ?? '';
 }
+/** True when the process looks like a CI runner rather than a dev worktree. */
+function isCiContext(env) {
+    return Boolean(env['GITHUB_ACTIONS'] || env['CI']);
+}
+/**
+ * Read `pull_request.base.sha` from the Actions event payload, if present.
+ *
+ * Optional chaining over a narrow interface (rather than an `unknown` +
+ * `typeof` ladder) keeps this at one branch per real failure mode: unreadable
+ * file, unparseable JSON, or a payload without a usable sha.
+ */
+function eventBaseSha(env) {
+    const eventPath = env['GITHUB_EVENT_PATH'];
+    if (!eventPath)
+        return null;
+    let sha;
+    try {
+        const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+        sha = event?.pull_request?.base?.sha;
+    }
+    catch {
+        return null;
+    }
+    return typeof sha === 'string' && sha.trim() ? sha.trim() : null;
+}
+/**
+ * Base-rev candidates for the PR diff, most-preferred first.
+ *
+ * `origin/<ref>` leads because `actions/checkout` fetches the base branch under
+ * the remote namespace and usually does NOT create a local branch for it; the
+ * bare `<ref>` covers checkouts that do. The event payload's `base.sha` is the
+ * last resort — exact, but only present on `pull_request` events.
+ */
+function baseRefCandidates(env) {
+    const candidates = [];
+    const baseRef = env['GITHUB_BASE_REF']?.trim();
+    if (baseRef)
+        candidates.push(`origin/${baseRef}`, baseRef);
+    const sha = eventBaseSha(env);
+    if (sha)
+        candidates.push(sha);
+    return candidates;
+}
+/**
+ * Return the first base candidate that actually resolves to a commit locally.
+ *
+ * A shallow clone (`fetch-depth: 1`, the `actions/checkout` default) will NOT
+ * have the base commit, so every candidate fails `rev-parse` and we return
+ * `null` — the caller then falls back to the worktree diff and warns.
+ */
+function resolveBaseRev(deps) {
+    for (const candidate of baseRefCandidates(deps.env)) {
+        const res = deps.runGit([
+            'rev-parse',
+            '--verify',
+            '--quiet',
+            `${candidate}^{commit}`,
+        ]);
+        if (res !== null && res.code === 0 && res.stdout.trim())
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Resolve the diff `pr-check` should scope, preferring the PR diff in CI (#369).
+ *
+ * An explicit `--diff` (stdin or file) always wins and never shells out. With
+ * `--diff` omitted:
+ *
+ *   - **In CI** with a resolvable base rev → `git diff <base>...HEAD`. The
+ *     TRIPLE-dot form diffs against the merge base, so commits that land on the
+ *     base branch mid-PR never appear as part of this PR's changed surface.
+ *   - **Otherwise** → the at-desk working-tree diff ({@link readWorktreeDiff}).
+ *
+ * The legacy behavior was the working-tree diff unconditionally, which is empty
+ * on a clean CI checkout — the gate then scoped zero paths and exited 0, so an
+ * adopting repo could not tell a working gate from a broken one.
+ */
+export function readPrDiff(source, deps) {
+    if (source === '-') {
+        return { text: deps.readStdin(), origin: 'stdin', base: null };
+    }
+    if (source !== null) {
+        return { text: readFileSync(source, 'utf-8'), origin: 'file', base: null };
+    }
+    if (isCiContext(deps.env)) {
+        const base = resolveBaseRev(deps);
+        if (base !== null) {
+            const res = deps.runGit(['diff', `${base}...HEAD`]);
+            if (res !== null && res.code === 0) {
+                return { text: res.stdout, origin: 'ci-base', base };
+            }
+        }
+    }
+    return { text: readWorktreeDiff(deps), origin: 'worktree', base: null };
+}
+const EMPTY_CI_DIFF_NOTICE = 'guardian: 0 changed paths — fell back to a working-tree `git diff`, which ' +
+    'is empty on a clean CI checkout, so NOTHING was verified. Pass ' +
+    '`--diff <base>...<head>`, or checkout with `fetch-depth: 0` so the PR base ' +
+    'ref resolves automatically.';
+/**
+ * Warn LOUDLY when a CI run scoped zero paths off the worktree fallback (#369).
+ *
+ * Fires only for the exact broken shape — `--diff` omitted, CI detected, base
+ * rev unresolvable, and zero changed paths. A diff that DID carry paths which
+ * were then all skipped is a legitimate no-op and stays quiet.
+ *
+ * Deliberately non-blocking: it annotates (`::warning::` + step summary +
+ * stderr) rather than exiting non-zero, so adopting an engine upgrade never
+ * flips a green build red — but a silent green no-op becomes impossible.
+ */
+function warnIfEmptyCiDiff(resolved, unitCount, deps) {
+    if (resolved.origin !== 'worktree')
+        return;
+    if (unitCount > 0)
+        return;
+    if (!isCiContext(deps.env))
+        return;
+    deps.out(degradationAnnotation(EMPTY_CI_DIFF_NOTICE));
+    appendStepSummary(deps.env, EMPTY_CI_DIFF_NOTICE);
+    deps.err(EMPTY_CI_DIFF_NOTICE);
+}
 // --- analyze ------------------------------------------------------------------
 function loadSpec(path, deps) {
     if (!existsSync(path)) {
@@ -494,6 +678,10 @@ async function postStickyComment(findings, resolution, deps) {
         appendStepSummary(deps.env, res.notice);
     }
 }
+/** The gate's no-op line, shared by the pre- and post-filter exits. */
+function nothingToVerify(skippedCount) {
+    return `guardian: nothing to verify (${skippedCount} path(s) skipped).`;
+}
 async function prCheckCmd(opts, deps) {
     const [config, warning] = loadGuardianConfig(opts.config);
     if (warning !== null) {
@@ -507,8 +695,12 @@ async function prCheckCmd(opts, deps) {
         throw new CliExit(0);
     }
     const effectiveGate = opts.gate ?? config.pr_gate;
-    const diffText = readDiff(opts.diff ?? null, deps);
+    // #369: in CI an omitted `--diff` resolves the PR diff from the base ref;
+    // the working-tree fallback is empty on a clean checkout.
+    const resolvedDiff = readPrDiff(opts.diff ?? null, deps);
+    const diffText = resolvedDiff.text;
     const units = scopeDiff(diffText);
+    warnIfEmptyCiDiff(resolvedDiff, units.length, deps);
     // SC-2: drop docs/config-only units matching skipGlobs.
     const [keptSkip, skipped] = filterSkipped(units, config.skip_globs);
     // FIX A: drop test-path units -- a test does not itself need a test.
@@ -521,9 +713,9 @@ async function prCheckCmd(opts, deps) {
     const weakFindings = config.weak_tests
         ? buildWeakTestFindings(testUnits, diffText)
         : [];
+    const preFilterSkipped = skipped.length + testUnits.length + barrelUnits.length;
     if (kept.length === 0 && weakFindings.length === 0) {
-        deps.out(`guardian: nothing to verify ` +
-            `(${skipped.length + testUnits.length + barrelUnits.length} path(s) skipped).`);
+        deps.out(nothingToVerify(preFilterSkipped));
         throw new CliExit(0);
     }
     const results = resolveCoverage(kept, {
@@ -532,10 +724,21 @@ async function prCheckCmd(opts, deps) {
         // (depth 1); soft stays unbounded. An explicit config value wins.
         graphMaxDepth: effectiveGraphDepth(config, effectiveGate),
     });
+    // #413: drop uncovered HEURISTIC verdicts on paths a naming heuristic can
+    // never judge (non-source, or an excluded glob). Coverage/graph-verified
+    // verdicts on the same paths are real evidence and survive.
+    const [scoredResults, noiseResults] = filterHeuristicNoise(results, opts.heuristicExclude ?? config.heuristic_exclude);
     const findings = [
-        ...applySuppressions(buildFindings(results)),
+        ...applySuppressions(buildFindings(scoredResults)),
         ...weakFindings,
     ];
+    // #413: if the heuristic filter consumed every scorable unit, report it as a
+    // 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) {
+        deps.out(nothingToVerify(preFilterSkipped + noiseResults.length));
+        throw new CliExit(0);
+    }
     // SC-5 (PR half): resolve the requested tier against actual capability. No
     // agent runtime exists (default NoAgentProbe), so any `pr.tier > 0` drops to
     // tier 0 with a LOUD degradation notice.
@@ -602,7 +805,10 @@ function buildGaps(diffText, config, coveragePath, graphMaxDepth) {
     if (kept.length === 0)
         return [];
     const results = resolveCoverage(kept, { coveragePath, graphMaxDepth });
-    return applySuppressions(buildFindings(results));
+    // #413: never hand the authoring tier a heuristic FP -- a generated "test" for
+    // a config dotfile is worse noise than the finding was.
+    const [scored] = filterHeuristicNoise(results, config.heuristic_exclude);
+    return applySuppressions(buildFindings(scored));
 }
 /** Serialize a {@link GeneratedTest} intent for the SKILL (JSON-safe). */
 function intentDict(intent) {
@@ -634,7 +840,8 @@ function authorPlanCmd(opts, deps) {
     const ctx = new AuthoringContext(config.precommit_author_tests, effective, {
         is_fork: isForkContext(deps.env),
         repo_root: repoRoot,
-        authored_sentinel_present: existsSync(authoredSentinelPath(deps, repoRoot)),
+        // #456: HEAD-stamped, so the guard expires on the next commit by itself.
+        authored_sentinel_present: authoredSentinelActive(deps, repoRoot),
     });
     const results = deps.makeAgentTier().author_tests(gaps, ctx);
     const decision = decideBlock(results);
@@ -648,11 +855,23 @@ function authorPlanCmd(opts, deps) {
     };
     deps.out(ensureAscii(JSON.stringify(payload, null, 2)));
 }
+/**
+ * Record the authored paths in the loop-guard sentinel, stamped with the HEAD
+ * they were authored at (#456).
+ *
+ * The `HEAD <sha>` header is what makes the guard self-expiring: `author-plan`
+ * honors it only while `HEAD` still matches, so the human's review commit clears
+ * it implicitly. When `HEAD` cannot be resolved (a repo with no commits, or no
+ * git at all) the header is omitted -- an unstamped sentinel reads as malformed
+ * and FAILS OPEN, which is the safe direction.
+ */
 function markAuthoredCmd(opts, deps) {
     const root = gitToplevel(deps);
     const sentinel = authoredSentinelPath(deps, root);
     mkdirSync(dirname(sentinel), { recursive: true });
-    const body = opts.path.map((p) => `${p}\n`).join('');
+    const head = headSha(deps, root);
+    const header = head === null ? '' : `HEAD ${head}\n`;
+    const body = header + opts.path.map((p) => `${p}\n`).join('');
     writeFileSync(sentinel, body, 'utf-8');
     deps.out(`guardian: recorded ${opts.path.length} authored path(s) ${RIGHT_ARROW} ${sentinel}`);
 }
@@ -729,11 +948,15 @@ export function createGuardianCommand(depsInit = {}) {
     program
         .command('pr-check')
         .description('Tier 0 deterministic PR guardian: scope, resolve, gate.')
-        .option('--diff <diff>', "Diff file, '-' for stdin, or omit to use `git diff`.")
+        .option('--diff <diff>', "Diff file, '-' for stdin, or omit to auto-resolve: the PR diff " +
+        '(`<base>...HEAD`) in CI, else the local working-tree `git diff`.')
         .option('--coverage <path>', 'Coverage report path (lcov/json).')
         .addOption(new Option('--format <fmt>', 'comment|json|text').default('comment'))
         .addOption(new Option('--config <path>').default('harness.config.json'))
         .option('--gate <gate>', 'Override config gate: soft|hard')
+        .option('--heuristic-exclude <glob>', 'Glob whose paths never produce a heuristic-tier finding (repeatable). ' +
+        'Replaces canary.guardian.pr.heuristicExclude for this run. ' +
+        'Coverage/graph-verified findings are unaffected.', (value, previous) => [...(previous ?? []), value])
         .option('--post-comment', 'Post/update the sticky PR comment via the GitHub API (CI).')
         .option('--emit-analysis', 'Write the finding record to the .harness/analyses/ channel ' +
         '(harness handoff, #899); falls back LOUDLY to the sticky comment ' +

package/dist/engine/guardian/coverage.js

@@ -682,6 +682,96 @@ const TEST_PATH_RE = /(^|\/)tests?\/|(^|\/)test_[^/]*\.py$|\.test\.[^/]+$|\.spec
 export function isTestPath(path) {
     return TEST_PATH_RE.test(path);
 }
+/**
+ * Extensions that denote hand-authored, executable program source (#413).
+ *
+ * The membership rule is deliberately simple and defensible: **a programming
+ * language belongs; data, config, markup, and style do not.** `.sh` is in (it is
+ * executable logic — bats/shunit2 exist); `.json`, `.yaml`, `.sql`, `.css`, and
+ * `.html` are out (nothing a naming heuristic could meaningfully judge).
+ *
+ * A repo that disagrees at the margins tunes the glob layer
+ * (`canary.guardian.pr.heuristicExclude`) rather than this list.
+ */
+const SOURCE_EXTENSIONS = new Set([
+    // TS/JS + component dialects.
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.vue',
+    '.svelte',
+    '.astro',
+    // Python / Ruby / PHP / Perl / Lua.
+    '.py',
+    '.pyi',
+    '.rb',
+    '.php',
+    '.pl',
+    '.pm',
+    '.lua',
+    // JVM + .NET.
+    '.java',
+    '.kt',
+    '.kts',
+    '.scala',
+    '.groovy',
+    '.clj',
+    '.cljs',
+    '.cs',
+    '.fs',
+    '.vb',
+    // Systems.
+    '.go',
+    '.rs',
+    '.c',
+    '.h',
+    '.cc',
+    '.cpp',
+    '.cxx',
+    '.hpp',
+    '.hh',
+    '.m',
+    '.mm',
+    '.swift',
+    // Functional / scientific / other.
+    '.ex',
+    '.exs',
+    '.erl',
+    '.dart',
+    '.r',
+    '.jl',
+    // Shell.
+    '.sh',
+    '.bash',
+    '.zsh',
+    '.ps1',
+    '.psm1',
+]);
+/**
+ * True if `path` looks like hand-authored program source (#413).
+ *
+ * Used to gate the Tier-3 naming heuristic. That heuristic asks "does any test
+ * file reference this file's stem or a top-level symbol?" — for a config
+ * dotfile, a lockfile, or a data blob there are no symbols and no test will
+ * ever name it, so the verdict is structurally always "uncovered": a guaranteed
+ * false positive rather than a signal. An extension-less file (`Makefile`,
+ * `Dockerfile`) and a bare dotfile (`.eslintrc`) are both non-source.
+ */
+export function isSourcePath(path) {
+    const base = basename(path);
+    // `.eslintrc` — `extname` calls this '' already, but a dotfile WITH a real
+    // extension (`.eslintrc.json`) must be judged on that extension, which the
+    // normal path handles.
+    const ext = extname(base).toLowerCase();
+    if (!ext)
+        return false;
+    return SOURCE_EXTENSIONS.has(ext);
+}
 /**
  * Tier 2: derive coverage from the harness knowledge graph (`GRAPH_VERIFIED`).
  *