testguard-cli 0.5.0 → 0.7.0

package/src/commands/brief.mjs

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
-import { buildBrief, buildUnclaimedBrief } from '../brief/brief.mjs';
+import { buildBrief, buildUnclaimedBrief, renderBriefMarkdown, renderUnclaimedMarkdown } from '../brief/brief.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { evidencePath, baselinePath } from './probe.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
@@ -13,15 +13,18 @@ export async function briefCommand({ projectDir, values, version }, io) {
     // A detected base that does not resolve is silent here: the brief is a
     // session-start hook's output and must never add noise; `status` and
     // `gate` are where that warning is printed.
-    status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }));
+    status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: values.evidence ? evPath : undefined }));
   } catch {
     status = undefined; // a brief must never fail because status could not be computed
   }
   if (!existsSync(evPath)) {
     // A missing brief must never break an agent's session start — but unclaimed
     // changes are still said, because the claim comes before the probe.
-    if (values.text) {
-      if (status?.changes?.uncovered?.length) io.out(buildUnclaimedBrief({ tool: { name: 'testguard', version }, next: status.next, changes: status.changes }).text.trimEnd());
+    if (values.text || values.markdown) {
+      if (status?.changes?.uncovered?.length) {
+        const args = { tool: { name: 'testguard', version }, next: status.next, changes: status.changes };
+        io.out((values.markdown ? renderUnclaimedMarkdown(args) : buildUnclaimedBrief(args).text).trimEnd());
+      }
       return 0;
     }
     io.err(`no evidence at ${evPath}; run \`testguard probe\` first`);
@@ -35,8 +38,11 @@ export async function briefCommand({ projectDir, values, version }, io) {
     io.err('--max must be an integer from 1 to 50');
     return 3;
   }
-  const brief = buildBrief(evidence, baseline, { max, next: status?.next, changes: status?.changes });
-  if (!values.text) writeSpecDoc('brief', values.out ? resolve(values.out) : join(projectDir, '.testguard', 'brief.json'), brief);
-  io.out(values.json ? JSON.stringify(brief, null, 2) : brief.text.trimEnd());
+  // Where this binary came from, so a stale install is visible in the session-start context.
+  const install = /[\\/]node_modules[\\/]/.test(process.argv[1] ?? '') ? 'local install' : 'global';
+  const brief = buildBrief(evidence, baseline, { max, next: status?.next, changes: status?.changes, install });
+  if (!values.text && !values.markdown) writeSpecDoc('brief', values.out ? resolve(values.out) : join(projectDir, '.testguard', 'brief.json'), brief);
+  if (values.markdown) io.out(renderBriefMarkdown({ ...brief, provisional: Boolean(evidence.run.provisional) }, { hasBaseline: Boolean(baseline), total: evidence.records.length, install }).trimEnd());
+  else io.out(values.json ? JSON.stringify(brief, null, 2) : brief.text.trimEnd());
   return 0;
 }

package/src/commands/claims.mjs

@@ -2,29 +2,78 @@ import { resolve } from 'node:path';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { scanAnnotations, reconcile } from '../claims/annotations.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
-import { discoverDefenders } from '../probe/discover.mjs';
+import { discoverDefendersDetailed } from '../probe/discover.mjs';
+import { classifyDefenders } from '../probe/mocks.mjs';
+import { computeRemovedClaims, renderRemoved } from '../claims/removed.mjs';
+import { evidencePath } from './probe.mjs';
+import { costReport, renderCost } from '../probe/cost.mjs';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { existsSync } from 'node:fs';
 
-export async function claimsCommand({ projectDir, values }, io) {
+export async function claimsCommand({ projectDir, values, version }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
   const claims = loadClaims(path);
   const annotations = scanAnnotations(projectDir);
   const drift = reconcile(claims, annotations);
 
+  // A claim that disappeared is invisible to every other command; compare
+  // identities against a reference when one is given.
+  const removed = values.since
+    ? computeRemovedClaims({ projectDir, ref: values.since, claimsPath: path, current: claims, ignorePath: values.ignore ? resolve(values.ignore) : undefined, evidencePath: evidencePath(projectDir), toolVersion: version })
+    : undefined;
+
+  // Cost is read back out of evidence the probe already wrote; it never runs a test.
+  let cost;
+  if (values.cost) {
+    const ev = values.evidence ? resolve(values.evidence) : evidencePath(projectDir);
+    cost = existsSync(ev) ? costReport(readSpecDoc('evidence', ev).records) : undefined;
+    if (!cost && !values.json) io.err(`no evidence at ${ev} — run \`testguard probe\` first; cost is derived from the run durations it records`);
+  }
+
   if (values.json) {
-    io.out(JSON.stringify({ path, claims, annotations, drift }, null, 2));
+    io.out(JSON.stringify({ path, claims, annotations, drift, ...(removed ? { removed } : {}), ...(cost ? { cost } : {}) }, null, 2));
   } else {
     const annotated = new Set(drift.annotated);
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
     io.out('');
+    const signalLines = [];
     for (const c of claims.claims) {
       const declared = c.defendedBy?.length > 0;
-      const defenders = declared ? resolveDefenders(projectDir, c.defendedBy) : [...new Set(c.faults.flatMap((f) => discoverDefenders(projectDir, f.file)))];
-      const cover = defenders.length ? `${defenders.length} ${declared ? 'defender' : 'discovered'}${defenders.length === 1 ? '' : 's'}` : 'NO DEFENDER';
+      const targets = [...new Set(c.faults.map((f) => f.file))];
+      let cover;
+      if (declared) {
+        const defenders = resolveDefenders(projectDir, c.defendedBy);
+        const mocking = new Set();
+        for (const t of targets) { const m = classifyDefenders(projectDir, t, defenders); m.mocking.forEach((f) => mocking.add(f)); for (const s of m.signals) signalLines.push({ claim: c.id, target: t, ...s }); }
+        cover = defenders.length ? `${defenders.length} defender${defenders.length === 1 ? '' : 's'}${mocking.size ? ` (${mocking.size} mock the target)` : ''}` : 'NO DEFENDER';
+      } else {
+        const importing = new Set(); const mocking = new Set(); const can = new Set();
+        for (const t of targets) { const d = discoverDefendersDetailed(projectDir, t); d.importing.forEach((f) => importing.add(f)); d.mocking.forEach((f) => mocking.add(f)); d.canDetect.forEach((f) => can.add(f)); for (const s of d.signals) signalLines.push({ claim: c.id, target: t, ...s }); }
+        cover = can.size ? `${importing.size} import · ${mocking.size} mock · ${can.size} can detect` : importing.size ? `NO DEFENDER (${importing.size} import, all mock the target)` : 'NO DEFENDER';
+      }
       io.out(`${annotated.has(c.id) ? '@ ' : '  '}${c.id.padEnd(14)} ${c.severity.padEnd(8)} ${c.source.kind.padEnd(10)} ${String(c.faults.length).padStart(2)} fault${c.faults.length === 1 ? ' ' : 's'}  ${cover.padEnd(12)}  ${c.statement}`);
     }
+    if (signalLines.length) io.out('');
+    for (const s of signalLines) {
+      // The annotation's comment marker is the probed file's, not JavaScript's.
+      const marker = s.file.endsWith('.py') ? '#' : '//';
+      if (s.signal === 'mocked-never-asserted') io.out(`MOCKED-NEVER-ASSERTED  ${s.file} mocks ${s.target} and never asserts on it (${s.claim}) — assert on the mocked call, drive the real module, or annotate the mock \`${marker} unasserted: <why>\``);
+      // An attribute patch does not remove a defender; saying it "mocks" the
+      // module would tell the author the opposite of what happened.
+      else if (s.signal === 'target-attribute-patched') io.out(`attribute-patched  ${s.file} defends ${s.target} but replaces ${s.reason} (${s.claim}) — a fault in those attributes is where it is least likely to notice`);
+      else io.out(`unasserted (annotated)  ${s.file} mocks ${s.target}: ${s.reason} (${s.claim})`);
+    }
     if (drift.undeclared.length || drift.stale.length) io.out('');
     for (const a of drift.undeclared) io.out(`UNDECLARED   @claim ${a.id} at ${a.file}:${a.line} has no entry in the claims file — a claim with no fault model`);
     for (const c of drift.stale) io.out(`STALE        ${c.id} is annotation-sourced but no source file carries @claim ${c.id}`);
+    if (removed) {
+      io.out('');
+      io.out(renderRemoved(removed));
+    }
+    if (cost) {
+      io.out('');
+      io.out(renderCost(cost));
+    }
   }
-  return drift.undeclared.length || drift.stale.length ? 1 : 0;
+  return drift.undeclared.length || drift.stale.length || (removed?.removed.length ?? 0) > 0 ? 1 : 0;
 }

package/src/commands/init.mjs

@@ -1,15 +1,28 @@
 import { initProject } from '../init/init.mjs';
 
 export async function initCommand({ projectDir, values }, io) {
-  const { done, skipped } = initProject({ projectDir, force: values.force });
+  const r = initProject({ projectDir, force: values.force, here: values.here, ciEvidence: values['ci-evidence'], mcp: values.mcp });
+  const { done, skipped, warnings, agentRoot, dir, mcpConfig } = r;
   if (values.json) {
-    io.out(JSON.stringify({ done, skipped }, null, 2));
-    return 0;
+    io.out(JSON.stringify({ done, skipped, warnings, agentRoot, dir, ...(mcpConfig ? { mcpConfig } : {}) }, null, 2));
+    return warnings.length ? 1 : 0;
   }
   for (const d of done) io.out(`+ ${d}`);
   for (const s of skipped) io.out(`= ${s}`);
+  for (const w of warnings) io.out(`! ${w}`);
   io.out('');
-  io.out('Agents in this project now start with the blind-spot brief and can run `testguard status --json` to learn what to do next.');
-  io.out(done.length ? 'Commit these files.' : 'Nothing to change.');
-  return 0;
+  if (dir !== '.') io.out(`Agent layer (skill, session-start hook, AGENTS.md section) installed at the git root ${agentRoot}, where agent sessions run; the project layer stays in ${dir}/. Use --here to keep everything in ${dir}/.`);
+  io.out(`Agents now start with the blind-spot brief and can run \`testguard status --json${dir === '.' ? '' : ` ${dir}`}\` to learn what to do next. The hook prefers a local install and never fetches from the network.`);
+  io.out(warnings.length ? 'Some written files are ignored by git — fix that before committing.' : done.length ? 'Commit these files.' : 'Nothing to change.');
+  if (mcpConfig) {
+    io.out('');
+    io.out('MCP — five READ-ONLY tools (status, brief, claims, evidence, next_command), so the loop survives a change of harness. Nothing there runs a probe. Add ONE of these:');
+    for (const [where, snippet] of Object.entries(mcpConfig)) {
+      io.out('');
+      io.out(`  ${where}`);
+      const text = typeof snippet === 'string' ? snippet : JSON.stringify(snippet, null, 2);
+      for (const line of text.split('\n')) io.out(`    ${line}`);
+    }
+  }
+  return warnings.length ? 1 : 0;
 }

package/src/commands/mcp.mjs

@@ -0,0 +1,12 @@
+import { serve } from '../mcp/server.mjs';
+
+export async function mcpCommand({ values, version }, io) {
+  if (values.json) {
+    // Not a JSON command: it is a long-lived server on stdio, and printing
+    // anything to stdout would corrupt the protocol stream.
+    io.err('mcp speaks JSON-RPC on stdin/stdout; there is no --json mode');
+    return 3;
+  }
+  await serve({ version });
+  return 0;
+}

package/src/commands/probe.mjs

@@ -7,6 +7,8 @@ import { gate } from '../baseline/baseline.mjs';
 import { renderRecord, renderSummary, sortForReport, PROVISIONAL_WARNING } from '../render.mjs';
 import { computeStatus } from '../status/status.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
+import { costReport, renderCost } from '../probe/cost.mjs';
+import { progressMode, stageReporter, clearStageLine, recordEvent, isProgressMode, progressStream } from '../probe/progress.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -19,6 +21,14 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.err('--confirm must be a positive integer and --budget at least 1000');
     return 3;
   }
+  if (values.progress && !isProgressMode(values.progress)) {
+    io.err(`--progress must be one of auto, tty, plain, ndjson, none (got ${values.progress})`);
+    return 3;
+  }
+  // Progress always goes to stderr, so --json keeps stdout parseable.
+  const progress = progressMode({ explicit: values.progress, isTTY: process.stderr.isTTY, quiet: values.quiet, json: values.json });
+  const progressTo = progressStream(process);
+  const stageOut = stageReporter(progress, (s) => progressTo.write(s));
   const claims = loadClaims(values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir));
   if (claims.claims.length === 0) {
     io.err('claims file declares no claims; nothing to verify');
@@ -30,6 +40,7 @@ export async function probeCommand({ projectDir, values, version }, io) {
   // Provisional and partial runs never overwrite the canonical evidence: only confirmed, complete runs may feed a baseline.
   const outPath = values.out ? resolve(values.out) : only ? join(projectDir, '.testguard', 'evidence-partial.json') : provisional ? provisionalEvidencePath(projectDir) : evidencePath(projectDir);
   if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
+  const discoveryNoted = new Set();
   const previous = !values['no-reuse'] && existsSync(outPath) ? readSpecDoc('evidence', outPath) : undefined;
   const basePath = values.baseline ? resolve(values.baseline) : baselinePath(projectDir);
   const baseline = existsSync(basePath) ? readSpecDoc('baseline', basePath) : undefined;
@@ -41,26 +52,38 @@ export async function probeCommand({ projectDir, values, version }, io) {
     confirmRuns,
     budgetMs,
     mode: values['in-place'] ? 'in-place' : 'worktree',
-    ref: values.ref,
+    ref: values.ref ?? 'HEAD',
+    refExplicit: values.ref !== undefined,
+    ignoreDirty: values['ignore-dirty'],
+    serial: values.serial,
+    onWarn: (m) => io.err(`warning: ${m}`),
     runnerCommand: values['runner-cmd'],
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    python: values.python ? resolve(values.python) : undefined,
     only,
     escalate: !values['no-escalate'],
     toolVersion: version,
     includeDirty: values['include-dirty'],
-    onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`) : undefined,
-    onProgress: values.quiet || values.json ? undefined : (r) => {
-      if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
-      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r, { provisional }) + (r.reusedFrom ? '  (reused)' : ''));
+    onStage: stageOut,
+    onProgress: (r) => {
+      // ndjson streams verdicts as they land; a watcher sees them without
+      // waiting for the document at the end.
+      if (progress === 'ndjson') progressTo.write(recordEvent(r));
+      if (values.quiet || values.json) return;
+      progressTo.write(clearStageLine(progress));
+      // The discovery note is a property of the claim, not of each fault: say it once.
+      const firstOfClaim = !discoveryNoted.has(r.claim.id);
+      if (r.defenders.discovered) discoveryNoted.add(r.claim.id);
+      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r, { provisional, showDiscovered: firstOfClaim }) + (r.reusedFrom ? '  (reused)' : ''));
     },
   });
   writeSpecDoc('evidence', outPath, evidence);
 
   const g = gate(evidence.records, baseline, { severityFloor: values.severity });
   if (values.json) {
-    const status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }), io.err);
-    io.out(JSON.stringify({ ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0 } }, null, 2));
+    const status = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence: outPath }), io.err);
+    io.out(JSON.stringify({ ...status, run: { id: evidence.run.id, evidence: outPath, provisional, records: evidence.records.length, newSinceBaseline: g.new.length, exitCode: g.new.length > 0 ? 1 : 0 }, ...(values.cost ? { cost: costReport(evidence.records) } : {}) }, null, 2));
     return g.new.length > 0 ? 1 : 0;
   }
   if (!values.quiet && baseline) {
@@ -74,6 +97,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     if (killed) io.out(`  ${killed} killed (not listed; --verbose to see them)`);
   }
   io.out(renderSummary(evidence.records, evidence.run) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
+  if (values.cost) {
+    io.out('');
+    io.out(renderCost(costReport(evidence.records)));
+    io.out('');
+  }
   io.out(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : provisional ? ' (provisional; not the canonical evidence file)' : ''}`);
   if (provisional && !values.quiet) io.err(PROVISIONAL_WARNING(confirmRuns));
   return g.new.length > 0 ? 1 : 0;

package/src/commands/replay.mjs

@@ -0,0 +1,63 @@
+import { dirname, join, resolve } from 'node:path';
+import { replay, calibrationFrom, renderReplay } from '../replay/replay.mjs';
+import { writeSpecDoc } from '../evidence/writer.mjs';
+
+export const replayPath = (projectDir) => join(projectDir, '.testguard', 'replay.json');
+export const calibrationPath = (projectDir) => join(projectDir, '.testguard', 'calibration.json');
+
+export async function replayCommand({ projectDir, values, version }, io) {
+  const range = values.since ?? values.changed;
+  if (!range) {
+    io.err('usage: testguard replay [dir] --since <range>   (e.g. --since HEAD~50..HEAD, or a tag)');
+    return 3;
+  }
+  const confirmRuns = Number(values.confirm);
+  const budgetMs = Number(values.budget);
+  const limit = values.max ? Number(values.max) : undefined;
+  if (!Number.isInteger(confirmRuns) || confirmRuns < 1 || !Number.isInteger(budgetMs) || budgetMs < 1000) {
+    io.err('--confirm must be a positive integer and --budget at least 1000');
+    return 3;
+  }
+
+  const doc = await replay({
+    projectDir,
+    range,
+    confirmRuns,
+    budgetMs,
+    runnerCommand: values['runner-cmd'],
+    runnerName: values.runner,
+    nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    limit,
+    toolVersion: version,
+    onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ commit, i, n, stage }) => process.stderr.write(`\r\x1b[K  … ${commit.slice(0, 9)} (${i}/${n}) ${stage}`) : undefined,
+    onProgress: values.quiet || values.json ? undefined : () => {
+      if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
+    },
+  });
+
+  const outPath = values.out ? resolve(values.out) : replayPath(projectDir);
+  writeSpecDoc('replay', outPath, doc);
+  const calibration = calibrationFrom(doc, { toolVersion: version });
+  // Beside the replay document, whatever --out says: the two are one result,
+  // and splitting them across directories loses the pairing — and leaves a
+  // file behind in a repository the run is only meant to read.
+  const calPath = values.baseline ? resolve(values.baseline) : values.out ? join(dirname(outPath), 'calibration.json') : calibrationPath(projectDir);
+  writeSpecDoc('calibration', calPath, calibration);
+
+  if (values.json) {
+    io.out(JSON.stringify({ replay: doc, calibration, paths: { replay: outPath, calibration: calPath } }, null, 2));
+  } else {
+    io.out(renderReplay(doc));
+    io.out('');
+    for (const [cls, b] of Object.entries(calibration.buckets).sort((a, b2) => b2[1].n - a[1].n)) {
+      io.out(`  ${cls.padEnd(22)} blind ${String(b.positives).padStart(3)}/${String(b.n).padEnd(3)}  p=${b.p.toFixed(2)}  ci [${b.ci[0].toFixed(2)}, ${b.ci[1].toFixed(2)}]`);
+    }
+    if (Object.keys(calibration.buckets).length === 0) io.out('  no measurable bug in this range: nothing to calibrate from yet.');
+    io.out('');
+    io.out(`replay: ${outPath}`);
+    io.out(`calibration: ${calPath}`);
+  }
+  // Replay reports; it never gates. A bug that escaped is history, not a
+  // regression in this change, and a gate on history is a gate nobody can pass.
+  return 0;
+}

package/src/commands/status.mjs

@@ -1,9 +1,11 @@
+import { resolve } from 'node:path';
 import { computeStatus, renderStatus } from '../status/status.mjs';
 import { validate } from '../../spec/lib/validate.mjs';
 import { resolveChangedRef, withChangedRef } from '../gate/changed.mjs';
 
 export async function statusCommand({ projectDir, values, version }, io) {
-  const doc = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'] }), io.err);
+  const evidence = values.evidence ? resolve(values.evidence) : undefined;
+  const doc = withChangedRef(resolveChangedRef({ explicit: values.changed }), (changedRef) => computeStatus({ projectDir, toolVersion: version, changedRef, includeDirty: values['include-dirty'], evidence }), io.err);
   const result = validate('status', doc);
   if (!result.ok) throw new Error(`status document does not conform: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
   io.out(values.json ? JSON.stringify(doc, null, 2) : renderStatus(doc));

package/src/gate/changed.mjs

@@ -5,6 +5,7 @@ import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { readSpecDoc } from '../evidence/writer.mjs';
 import { resolveDefenders } from '../probe/runners/shared.mjs';
 import { discoverDefenders } from '../probe/discover.mjs';
+import { IS_PY_TEST } from '../probe/pyimports.mjs';
 import { globToRegExp } from '../util/glob.mjs';
 
 /**
@@ -20,8 +21,14 @@ import { globToRegExp } from '../util/glob.mjs';
  * the smallest unit the rest of the contract already understands.
  */
 
-export const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']);
+// `.py` belongs here for the same reason every other extension does: a file
+// the gate does not recognise as source is excluded as `non-source`, which
+// means a changed Python file could never be reported as uncovered and the
+// gate would pass while saying nothing.
+export const SOURCE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
 const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+// Python names tests by file, not by a dotted suffix: `test_foo.py`, `foo_test.py`.
+const isTestFile = (f) => TEST_RE.test(f) || IS_PY_TEST.test(f);
 
 /** Files that are source by extension but never carry claims. Printed by --explain. */
 export const DEFAULT_EXCLUDES = Object.freeze([
@@ -163,7 +170,7 @@ export function computeChangedGate({ projectDir, ref, includeDirty = false, excl
     const dx = defaultExcludes.find((x) => x.re.test(file));
     if (dx) { excluded.push({ file, by: `default:${dx.glob}` }); continue; }
 
-    const isTest = TEST_RE.test(file);
+    const isTest = isTestFile(file);
     if (faultFiles.has(file)) { covered.push({ file, by: 'fault', claimIds: faultFiles.get(file) }); continue; }
     if (isTest && defenderFiles.has(file)) { covered.push({ file, by: 'defender', claimIds: defenderFiles.get(file) }); continue; }
     const active = pathEntries.find((p) => !p.expired && p.re.test(file));

package/src/git.mjs

@@ -23,6 +23,11 @@ export function headSha(dir, ref = 'HEAD') {
   }
 }
 
+/** Is `ancestor` reachable from `ref`? False when either does not resolve. */
+export function isAncestor(dir, ancestor, ref = 'HEAD') {
+  return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, ref], { cwd: dir }).status === 0;
+}
+
 /** True when any of `paths` (repo-relative; empty = whole tree) has uncommitted changes. */
 export const isDirty = (dir, paths = []) => git(['status', '--porcelain', '--', ...paths], dir).length > 0;