testguard-cli 0.5.0 → 0.7.0

package/src/probe/classify.mjs

@@ -6,8 +6,13 @@
  * encodes GATE-SEMANTICS.md: nothing to run → nocover; nothing to apply →
  * unverifiable; defenders not green → flaky-defender; then, and only then,
  * does the fault's own result count.
+ *
+ * `subjectReached` is the negative control's answer and is consulted at one
+ * point only: a would-be `survived`. It is never asked about a kill — a kill
+ * already proves the defenders reached the code — and `undefined` (the control
+ * was not run) never changes a verdict.
  */
-export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRuns }) {
+export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRuns, subjectReached }) {
   if (defenders.length === 0) return { verdict: 'nocover' };
   if (anchor && anchor.status !== 'ok') return { verdict: 'unverifiable', reason: anchor.status };
   if (baselineRuns.length === 0 || baselineRuns.some((r) => r.outcome !== 'pass')) {
@@ -24,7 +29,18 @@ export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRu
   const killedRuns = probeRuns.filter((r) => r.outcome === 'fail' && r.assertionFailures > 0);
   const passedRuns = probeRuns.filter((r) => r.outcome === 'pass');
   if (probeRuns.length === confirmRuns && killedRuns.length === confirmRuns) return { verdict: 'killed' };
-  if (probeRuns.length === confirmRuns && passedRuns.length === confirmRuns) return { verdict: 'survived' };
+  if (probeRuns.length === confirmRuns && passedRuns.length === confirmRuns) {
+    // The negative control. A green baseline proves the defenders can PASS; it
+    // says nothing about whether they can fail because of THIS file. If the
+    // subject was replaced with something that cannot compile and the
+    // defenders still went green, they never execute it — and then `survived`
+    // is a statement about their reach, not their assertions, and reads as a
+    // devastating audit finding while being entirely false.
+    // `undefined` means the control was not run, which is not evidence either
+    // way and leaves the verdict alone.
+    if (subjectReached === false) return { verdict: 'unverifiable', reason: 'subject-not-executed' };
+    return { verdict: 'survived' };
+  }
   // Some runs killed, some passed: the defenders' response to this fault is
   // nondeterministic. Reporting it as killed would be the optimistic bias
   // the research warned about; reporting survived would be a lie the other way.

package/src/probe/contention.mjs

@@ -0,0 +1,60 @@
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Concurrent test runners (issue #26).
+ *
+ * A probe runs the defenders 3× clean and 3× with each fault applied. Heavy
+ * suites time out under parallel CPU load, and a timeout is a verdict —
+ * `TIMEOUT` or `FLAKY-DEFENDER` — that says nothing about the claim. A field
+ * report serialised everything by hand for exactly this reason. We cannot
+ * prevent the contention, but we can name it: warn before the first run, and
+ * record it on the evidence so a later reader of a flaky verdict knows the
+ * run was contended.
+ *
+ * Best effort by design: the detector never fails a probe, and a process list
+ * it cannot read is simply no detection.
+ */
+
+const RUNNER_RE = /\b(vitest|jest|playwright|mocha|ava|karma|cypress)\b/i;
+// Our own child processes and this process are not contention.
+const SELF_RE = /testguard/i;
+
+/** Rows of the process table as `{ pid, command }`, or [] when it cannot be read. */
+export function processList({ platform = process.platform, run = spawnSync } = {}) {
+  try {
+    const r = platform === 'win32'
+      ? run('wmic', ['process', 'get', 'ProcessId,CommandLine', '/format:csv'], { encoding: 'utf8', timeout: 5000 })
+      : run('ps', ['-Ao', 'pid=,args='], { encoding: 'utf8', timeout: 5000 });
+    if (r.status !== 0 || !r.stdout) return [];
+    return r.stdout.split('\n').map((line) => {
+      const m = platform === 'win32' ? /^[^,]*,(.*),(\d+)\s*$/.exec(line) : /^\s*(\d+)\s+(.*)$/.exec(line);
+      if (!m) return null;
+      const [pid, command] = platform === 'win32' ? [m[2], m[1]] : [m[1], m[2]];
+      return { pid: Number(pid), command: command.trim() };
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Test runners already running, other than ours. Returns
+ * `{ detected, runners: [{ pid, command }] }`; `detected` is false when
+ * nothing was found or the process list could not be read.
+ */
+export function detectContention({ self = process.pid, ...opts } = {}) {
+  const rows = processList(opts);
+  const runners = rows
+    .filter((p) => p.pid !== self && RUNNER_RE.test(p.command) && !SELF_RE.test(p.command))
+    // `ps` lists the grep/ps itself and any shell wrapper; a runner's command
+    // line always names its own binary, so require it to look like an exec.
+    .filter((p) => !/^\s*(ps|grep|wmic)\b/.test(p.command))
+    .map((p) => ({ pid: p.pid, command: p.command.length > 200 ? p.command.slice(0, 197) + '…' : p.command }));
+  return { detected: runners.length > 0, runners };
+}
+
+/** One line for the operator: what is running, and what it costs. */
+export const contentionWarning = (c) =>
+  `${c.runners.length} test runner${c.runners.length === 1 ? ' is' : 's are'} already running (${c.runners.map((r) => `pid ${r.pid}`).join(', ')}); ` +
+  'defenders run N times each here, and a suite that times out under parallel load yields TIMEOUT or FLAKY-DEFENDER — verdicts about the load, not the claim. ' +
+  'Wait for it to finish, or pass --serial to run one test file at a time.';

package/src/probe/cost.mjs

@@ -0,0 +1,145 @@
+/**
+ * What a probe costs, derived from evidence that already exists (issue #67).
+ *
+ * A probe's wall clock is not a function of how many claims there are. It is
+ * `(baseline runs + faults × confirm runs) × the cost of the claim's defender
+ * SET`, per claim. One slow acceptance test named as a defender by five claims
+ * is therefore paid for thirty times, and nothing in the output says so — the
+ * only symptom is that the gate takes twenty-four minutes and nobody knows
+ * which line to blame.
+ *
+ * Every number here is read back out of `durationMs` on the runs the probe
+ * already recorded. Nothing re-measures, nothing spawns, nothing guesses: a
+ * cost report costs the price of reading one JSON file.
+ *
+ * ATTRIBUTION, HONESTLY. Runs execute a claim's whole defender set together,
+ * so the runner never says how much of a run belonged to which file. Per-file
+ * `ms` is therefore the time of every run that *included* that file: an upper
+ * bound on what removing it could save, and, when a claim names several
+ * defenders, a number that overlaps with its siblings. The per-file figures do
+ * not sum to the total, by construction. `totalMs` is the only additive one.
+ */
+
+/** Every run a record paid for, in the order the probe made them. */
+export const runsOf = (record) => [
+  ...(record.detail?.baselineRuns ?? []),
+  ...(record.detail?.probeRuns ?? []),
+  ...(record.detail?.escalationRuns ?? []),
+];
+
+/**
+ * What one record cost. A reused record reports the duration of the runs it
+ * reused, which is the right number for planning — it is what the record costs
+ * whenever reuse does not apply — and `reused` marks it so a reader does not
+ * read it as wall clock just spent.
+ */
+export function recordCost(record) {
+  const runs = runsOf(record);
+  return {
+    ms: runs.reduce((a, r) => a + (r.durationMs ?? 0), 0),
+    runs: runs.length,
+    reused: Boolean(record.reusedFrom),
+  };
+}
+
+/** Per claim: what its faults cost in total, most expensive first. */
+export function claimCosts(records) {
+  const by = new Map();
+  for (const r of records) {
+    const c = recordCost(r);
+    const e = by.get(r.claim.id) ?? { claimId: r.claim.id, ms: 0, runs: 0, faults: 0, reused: 0, defenders: new Set() };
+    e.ms += c.ms;
+    e.runs += c.runs;
+    e.faults += 1;
+    if (c.reused) e.reused += 1;
+    for (const d of r.defenders?.resolved ?? []) e.defenders.add(d);
+    by.set(r.claim.id, e);
+  }
+  return [...by.values()]
+    .map((e) => ({ ...e, defenders: [...e.defenders].sort() }))
+    .sort((a, b) => b.ms - a.ms || a.claimId.localeCompare(b.claimId));
+}
+
+/**
+ * Per defender file: the time of every run that included it, and the claims
+ * that named it. See the attribution note above — this is a ceiling, not a
+ * share, and the figures overlap.
+ */
+export function defenderCosts(records) {
+  const by = new Map();
+  for (const r of records) {
+    const c = recordCost(r);
+    for (const file of r.defenders?.resolved ?? []) {
+      const e = by.get(file) ?? { file, ms: 0, runs: 0, claims: new Set() };
+      e.ms += c.ms;
+      e.runs += c.runs;
+      e.claims.add(r.claim.id);
+      by.set(file, e);
+    }
+  }
+  return [...by.values()]
+    .map((e) => ({ ...e, claims: [...e.claims].sort() }))
+    .sort((a, b) => b.ms - a.ms || a.file.localeCompare(b.file));
+}
+
+/**
+ * The whole cost model for one evidence document.
+ *
+ * `sharedDefenders` is the actionable part: a file named by more than one
+ * claim, whose cost is multiplied by every claim that names it. Splitting the
+ * behaviour it defends into a unit test that runs in milliseconds is what
+ * turns a twenty-four-minute gate into a one-minute one, and until a report
+ * names the file nobody knows which test to split.
+ */
+export function costReport(records) {
+  const claims = claimCosts(records);
+  const defenders = defenderCosts(records);
+  return {
+    totalMs: claims.reduce((a, c) => a + c.ms, 0),
+    totalRuns: claims.reduce((a, c) => a + c.runs, 0),
+    reusedRecords: records.filter((r) => r.reusedFrom).length,
+    records: records.length,
+    claims,
+    defenders,
+    sharedDefenders: defenders.filter((d) => d.claims.length > 1),
+  };
+}
+
+const secs = (ms) => (ms >= 10_000 ? `${Math.round(ms / 1000)}s` : ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`);
+/** Exported so a caller can format a duration the same way the report does. */
+export const formatMs = secs;
+
+/**
+ * The cost report as text. `limit` caps each list; the totals always describe
+ * everything, so a truncated list never misrepresents the whole.
+ */
+export function renderCost(report, { limit = 10 } = {}) {
+  const out = [];
+  if (!report.records) return 'no evidence records — run `testguard probe` first; cost is read back from the runs it records.';
+  out.push(`${report.records} fault record${report.records === 1 ? '' : 's'} cost ${secs(report.totalMs)} across ${report.totalRuns} defender runs${report.reusedRecords ? ` (${report.reusedRecords} reused; their runs are what they cost when reuse does not apply)` : ''}.`);
+  out.push('');
+  out.push('most expensive claims');
+  for (const c of report.claims.slice(0, limit)) {
+    out.push(`  ${secs(c.ms).padStart(7)}  ${c.claimId.padEnd(34)} ${c.faults} fault${c.faults === 1 ? ' ' : 's'} · ${c.runs} runs${c.reused ? ` · ${c.reused} reused` : ''}`);
+  }
+  if (report.claims.length > limit) out.push(`  … ${report.claims.length - limit} more`);
+  out.push('');
+  out.push('defender files, by the time of the runs that included them');
+  out.push('  (a claim runs its whole defender set at once, so these overlap and do not sum to the total)');
+  for (const d of report.defenders.slice(0, limit)) {
+    out.push(`  ${secs(d.ms).padStart(7)}  ${d.file.padEnd(44)} ${d.claims.length} claim${d.claims.length === 1 ? '' : 's'}`);
+  }
+  if (report.defenders.length > limit) out.push(`  … ${report.defenders.length - limit} more`);
+  if (report.sharedDefenders.length) {
+    out.push('');
+    out.push('shared defenders — each claim pays the file\'s full cost again');
+    for (const d of report.sharedDefenders.slice(0, limit)) {
+      out.push(`  ${secs(d.ms).padStart(7)}  ${d.file}`);
+      out.push(`           named by ${d.claims.join(', ')}`);
+    }
+    out.push('');
+    out.push('  To make a probe cheaper, split the behaviour a shared defender proves into a');
+    out.push('  test that does not need the expensive setup, and point the claim at that.');
+  }
+  return out.join('\n');
+}

package/src/probe/discover.mjs

@@ -1,12 +1,29 @@
 import { join } from 'node:path';
 import { listTestFiles } from './runners/shared.mjs';
+import { testGlobs as PY_TEST_GLOBS } from './runners/python.mjs';
 import { fileImports } from './rank.mjs';
+import { pyFileImports } from './pyimports.mjs';
+import { classifyDefenders } from './mocks.mjs';
+
+/** A target's language decides how its importers are found. Nothing else about it matters here. */
+export const isPython = (rel) => rel.endsWith('.py');
 
 /**
  * When a claim declares no defenders: the test files that import the fault's
- * target file, directly, by relative path or through a resolved alias. This
- * is what `nocover` measures against — no test file even imports the source.
+ * target file — directly, by relative path or through a resolved alias in
+ * JavaScript, by module name in Python — and do NOT replace it wholesale. A
+ * file that mocks the target cannot detect any fault in it; counting it would
+ * make `nocover` under-report and waste probe runs on files that cannot fail.
+ * `nocover` therefore means exactly "no test file imports this source without
+ * mocking it".
  */
+export function discoverDefendersDetailed(projectDir, targetRel) {
+  const importing = isPython(targetRel)
+    ? listTestFiles(projectDir, PY_TEST_GLOBS).filter((t) => pyFileImports(projectDir, join(projectDir, t), targetRel, t))
+    : listTestFiles(projectDir).filter((t) => fileImports(projectDir, join(projectDir, t), targetRel));
+  return { importing, ...classifyDefenders(projectDir, targetRel, importing) };
+}
+
 export function discoverDefenders(projectDir, targetRel) {
-  return listTestFiles(projectDir).filter((t) => fileImports(projectDir, join(projectDir, t), targetRel));
+  return discoverDefendersDetailed(projectDir, targetRel).canDetect;
 }

package/src/probe/independence.mjs

@@ -0,0 +1,59 @@
+import { git, GitError } from '../git.mjs';
+
+/**
+ * Maturity-ladder L3: independence.
+ *
+ * `probe` measures POWER — would this test notice if the code were wrong.
+ * It says nothing about who wrote the test. An agent that writes the code and
+ * its defender in one change encodes whatever it believed, and a kill by such
+ * a test is weaker evidence than a kill by a test written separately
+ * (SpecBench: agents saturate the tests they can see).
+ *
+ * This is a SIGNAL, never a verdict. A co-authored kill is legitimate — a bug
+ * fix *should* ship with its regression test — but a repository where every
+ * kill is co-authored has no independent verification, whatever its claim
+ * verification rate says. Ranking may read it; `classify()` never does.
+ */
+const CLASSES = ['co-authored', 'separate-change', 'unknown'];
+
+/** `git log -1` for one path at a commit → {commit, author} or null when there is no history for it. */
+function lastCommit(dir, ref, path) {
+  try {
+    const out = git(['log', '-1', '--format=%H%x09%ae', ref, '--', path], dir);
+    if (!out) return null;
+    const [commit, author] = out.split('\t');
+    return commit && author ? { commit, author } : null;
+  } catch (e) {
+    if (e instanceof GitError) return null;
+    throw e;
+  }
+}
+
+/**
+ * Was the killing defender last touched by the same change as the fault's
+ * target? `defenders` are the files whose tests failed on the fault.
+ *
+ * `co-authored`     — same commit, or the same author identity within the
+ *                     commits the caller considers one change (`range`).
+ * `separate-change` — different commits by different identities.
+ * `unknown`         — no history for one of them: a working-tree snapshot of
+ *                     untracked files, a shallow clone, or no commits.
+ */
+export function classifyIndependence({ dir, ref = 'HEAD', targetFile, defenders = [] }) {
+  const target = lastCommit(dir, ref, targetFile);
+  if (!target || defenders.length === 0) return { class: 'unknown' };
+
+  let sameAuthor = false;
+  let worst = null; // the most independent defender decides: one separate author is independence
+  for (const d of defenders) {
+    const def = lastCommit(dir, ref, d);
+    if (!def) return { class: 'unknown', targetCommit: target.commit };
+    const co = def.commit === target.commit || def.author === target.author;
+    if (def.author === target.author) sameAuthor = true;
+    if (!co) return { class: 'separate-change', defenderCommit: def.commit, targetCommit: target.commit, sameAuthor: false };
+    worst ??= def;
+  }
+  return { class: 'co-authored', defenderCommit: worst.commit, targetCommit: target.commit, sameAuthor };
+}
+
+export { CLASSES as INDEPENDENCE_CLASSES };

package/src/probe/inject.mjs

@@ -63,24 +63,56 @@ export function mutate(source, fault) {
 }
 
 /**
- * Apply a fault to a file on disk. Returns a handle whose `restore()` puts the
- * original back; restore is idempotent and also runs on process exit/signal.
+ * Replace a file's contents on disk. Returns a handle whose `restore()` puts
+ * the original back; restore is idempotent and also runs on process
+ * exit/signal. `content` is the new text, or a function of the original.
+ *
+ * `inPlace` decides what a *missing* target means at restore time, and the two
+ * modes are opposites. In worktree mode the mutation only ever existed inside a
+ * scratch worktree that is discarded at the end of the run, so a target that has
+ * vanished is already restored in every sense that matters — a parallel session
+ * pruning its own leaked worktrees is enough to cause it, and throwing there
+ * converts a harmless cleanup race into a probe that dies with no evidence at
+ * all. In `--in-place` mode the same condition means the user's own file is
+ * gone, and silence would be the worst possible answer.
  */
-export function applyFault(projectDir, fault) {
+export function applyContent(projectDir, file, content, { inPlace = false } = {}) {
   installHandlers();
-  const path = join(projectDir, fault.file);
+  const path = join(projectDir, file);
   const original = readFileSync(path, 'utf8');
-  const anchor = locate(original, fault);
-  if (anchor.status !== 'ok') return { anchor, applied: false, restore: () => {} };
 
   let restored = false;
+  const handle = { applied: true, restore: null };
   const restore = () => {
     if (restored) return;
     restored = true;
     live.delete(restore);
-    writeFileSync(path, original);
+    try {
+      writeFileSync(path, original);
+    } catch (err) {
+      // Only a target that is no longer there. A permission failure or a
+      // directory where a file should be can still mean a mutated file left on
+      // disk, and those must stay loud in either mode.
+      if (inPlace || err.code !== 'ENOENT') throw err;
+      handle.restoreSkipped = 'target-missing';
+    }
   };
+  handle.restore = restore;
   live.add(restore);
-  writeFileSync(path, mutate(original, fault));
-  return { anchor, applied: true, restore };
+  writeFileSync(path, typeof content === 'function' ? content(original) : content);
+  return handle;
+}
+
+/**
+ * Apply a fault to a file on disk. Returns a handle whose `restore()` puts the
+ * original back; `applied` is false and nothing is written when the anchor does
+ * not hit exactly as declared.
+ */
+export function applyFault(projectDir, fault, opts = {}) {
+  const anchor = locate(readFileSync(join(projectDir, fault.file), 'utf8'), fault);
+  if (anchor.status !== 'ok') return { anchor, applied: false, restore: () => {} };
+  // The same object, never a spread: `restoreSkipped` is set on it later.
+  const handle = applyContent(projectDir, fault.file, (src) => mutate(src, fault), opts);
+  handle.anchor = anchor;
+  return handle;
 }

package/src/probe/mocks.mjs

@@ -0,0 +1,122 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { specifierResolvesTo } from './rank.mjs';
+import { classifyPythonDefenders } from './pyimports.mjs';
+
+/**
+ * Mock-awareness for defenders (issues #20, #21).
+ *
+ * A test file that `vi.mock`s / `jest.mock`s the target cannot detect any
+ * fault in it, yet it imports the target, so the import rule would count it
+ * as a defender. Two consequences the field reports measured: `nocover`
+ * under-reports (a module with eighteen "defenders" that is effectively
+ * uncovered) and every probe wastes runs on files that cannot fail. The
+ * mocked count is itself the strongest blindness signal.
+ *
+ * And the cheapest static signal of all: a file that mocks the target and
+ * never `expect(...)`s anything from it. That single fact explained the
+ * seam behind an escaped bug without injecting anything.
+ */
+
+const MOCK_CALL = /\b(?:vi|jest)\.(?:mock|doMock|unstable_mockModule)\(\s*(['"])([^'"]+)\1/g;
+const IMPORT_STMT = /import\s+([^'";]+?)\s+from\s*(['"])([^'"]+)\2|import\s*(['"])([^'"]+)\4|(?:const|let|var)\s+([^=;]+?)\s*=\s*(?:await\s+)?(?:require|import)\(\s*(['"])([^'"]+)\7\s*\)/g;
+const UNASSERTED = /unasserted:\s*(.+?)\s*(?:\*\/)?\s*$/;
+
+/** The specifiers this source mocks, with their line numbers. */
+export function mockSpecifiers(source) {
+  const out = [];
+  const lines = source.split('\n');
+  lines.forEach((text, i) => {
+    for (const m of text.matchAll(MOCK_CALL)) out.push({ specifier: m[2], line: i + 1 });
+  });
+  return out;
+}
+
+/** Local names bound to a module specifier by import/require statements. `*` marks a namespace/default object binding. */
+function bindingsFor(source, matchesTarget) {
+  const names = [];
+  for (const m of source.matchAll(IMPORT_STMT)) {
+    const spec = m[3] ?? m[5] ?? m[8];
+    if (!spec || !matchesTarget(spec)) continue;
+    const clause = (m[1] ?? m[6] ?? '').trim();
+    if (!clause) continue; // side-effect import
+    const ns = /\*\s+as\s+([\w$]+)/.exec(clause);
+    if (ns) names.push(ns[1]);
+    const braces = /\{([^}]*)\}/.exec(clause);
+    if (braces) for (const part of braces[1].split(',')) { const local = part.trim().split(/\s+as\s+|\s*:\s*/).pop()?.trim(); if (local && /^[\w$]+$/.test(local)) names.push(local); }
+    const def = clause.replace(/\{[^}]*\}/, '').replace(/\*\s+as\s+[\w$]+/, '').replace(/,/g, '').trim();
+    if (def && /^[\w$]+$/.test(def)) names.push(def);
+  }
+  return [...new Set(names)];
+}
+
+/** Does any `expect(...)` argument mention one of the bindings (as an identifier or a member root)? */
+function expectMentions(source, bindings) {
+  if (bindings.length === 0) return false;
+  const re = /\bexpect\s*\(((?:[^()]|\((?:[^()]|\([^()]*\))*\))*)\)/g;
+  for (const m of source.matchAll(re)) {
+    const arg = m[1];
+    for (const b of bindings) if (new RegExp(`(^|[^\\w$.])${b.replace(/\$/g, '\\$')}(?![\\w$])`).test(arg)) return true;
+  }
+  return false;
+}
+
+/**
+ * How one test file relates to one target: does it import it, does it mock it,
+ * does it ever assert on what it imported from it, and did the author annotate
+ * an unasserted mock with a reason (`// unasserted: <why>` on or above the
+ * mock line).
+ */
+export function analyzeDefender(projectDir, testRel, targetRel) {
+  const abs = join(projectDir, testRel);
+  let source;
+  try {
+    source = readFileSync(abs, 'utf8');
+  } catch {
+    return { file: testRel, imports: false, mocks: false, asserted: false, annotation: null };
+  }
+  const matchesTarget = (spec) => specifierResolvesTo(projectDir, abs, spec, targetRel);
+  const mocks = mockSpecifiers(source).filter((m) => matchesTarget(m.specifier));
+  const bindings = bindingsFor(source, matchesTarget);
+  const asserted = expectMentions(source, bindings);
+  let annotation = null;
+  if (mocks.length) {
+    const lines = source.split('\n');
+    for (const m of mocks) {
+      for (let i = m.line - 1; i >= Math.max(0, m.line - 3) && !annotation; i--) {
+        const a = UNASSERTED.exec(lines[i]);
+        if (a) annotation = a[1];
+      }
+    }
+  }
+  return { file: testRel, imports: bindings.length > 0 || matchesTargetAnyImport(source, matchesTarget), mocks: mocks.length > 0, asserted, annotation };
+}
+
+function matchesTargetAnyImport(source, matchesTarget) {
+  for (const m of source.matchAll(/(?:from\s*|import\s*\(?\s*|require\s*\(\s*)['"]([^'"]+)['"]/g)) if (matchesTarget(m[1])) return true;
+  return false;
+}
+
+/**
+ * Split candidate test files for one target into the ones that can detect a
+ * fault in it and the ones that mock it, plus the static signals. A file that
+ * mocks the target is never a defender; a mocking file that never asserts on
+ * the target carries `mocked-never-asserted`, unless annotated, in which case
+ * the annotation is recorded (`unasserted-annotated`) — silenced, never hidden.
+ */
+export function classifyDefenders(projectDir, targetRel, candidates) {
+  if (targetRel.endsWith('.py')) return classifyPythonDefenders(projectDir, targetRel, candidates);
+  const canDetect = [];
+  const mocking = [];
+  const signals = [];
+  for (const file of candidates) {
+    const a = analyzeDefender(projectDir, file, targetRel);
+    if (a.mocks) {
+      mocking.push(file);
+      if (!a.asserted) signals.push(a.annotation ? { file, signal: 'unasserted-annotated', reason: a.annotation } : { file, signal: 'mocked-never-asserted' });
+    } else {
+      canDetect.push(file);
+    }
+  }
+  return { canDetect, mocking, signals };
+}