testguard-cli 0.5.0 → 0.7.0

package/src/probe/pyimports.mjs

@@ -0,0 +1,287 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
+import { walk } from '../util/glob.mjs';
+
+/**
+ * Python import and patch analysis: the counterpart of the specifier
+ * resolution in `rank.mjs`, which understands only JavaScript.
+ *
+ * Without it every Python claim that declares no `defendedBy` resolves to no
+ * defender and reports `nocover` — not an error, not a warning, just a quiet
+ * and wrong answer about a suite that may defend the claim perfectly well.
+ *
+ * Python is matched on module names rather than on paths, because that is what
+ * Python itself matches on: a file at `src/pkg/mod.py` is imported as
+ * `pkg.mod` from anywhere on `sys.path`, and the test that reaches it by
+ * inserting `src/` into `sys.path` is indistinguishable, at the import site,
+ * from one that reaches it through an installed distribution.
+ */
+
+const PY = /\.py$/;
+const COMMENT = /^\s*#/;
+
+/**
+ * The dotted module name of a file, and the directory that name is relative
+ * to: walk up while each directory is a package (`__init__.py`), exactly as
+ * Python resolves a module to its package. `src/pkg/mod.py` with
+ * `src/pkg/__init__.py` present and no `src/__init__.py` is `pkg.mod` rooted
+ * at `src`.
+ *
+ * A package's own `__init__.py` is the package: `pkg/__init__.py` is `pkg`,
+ * not `pkg.__init__`, which is what makes `import pkg.anything` reach it.
+ */
+export function pyModuleName(projectDir, rel) {
+  const parts = [basename(rel).replace(PY, '')];
+  if (parts[0] === '__init__') parts.pop();
+  let dir = dirname(join(projectDir, rel));
+  for (let depth = 0; depth < 32; depth++) {
+    if (!existsSync(join(dir, '__init__.py'))) break;
+    parts.unshift(basename(dir));
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { dotted: parts.join('.'), isPackage: basename(rel) === '__init__.py' };
+}
+
+/**
+ * Logical import lines: `\` continuations joined, and a parenthesised
+ * `from x import (a, b)` collapsed onto one line so the names are visible.
+ */
+function logicalLines(source) {
+  const raw = source.split('\n');
+  const out = [];
+  for (let i = 0; i < raw.length; i++) {
+    let line = raw[i];
+    if (COMMENT.test(line)) continue;
+    while (/\\\s*$/.test(line) && i + 1 < raw.length) line = line.replace(/\\\s*$/, ' ') + raw[++i];
+    if (/^\s*from\s/.test(line) && line.includes('(') && !line.includes(')')) {
+      // Bounded: a malformed file must not make this loop to the end of a large source.
+      for (let n = 0; n < 200 && i + 1 < raw.length && !line.includes(')'); n++) line += ' ' + raw[++i];
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+/** The package a file lives in, as a dotted name ('' when it is not in a package). */
+function packageOf(projectDir, rel) {
+  const dir = dirname(rel);
+  if (dir === '.' || dir === '') return '';
+  return pyModuleName(projectDir, join(dir, '__init__.py')).dotted;
+}
+
+/**
+ * Every module path a source imports, as absolute dotted names.
+ *
+ * `from pkg import mod` is recorded as both `pkg` and `pkg.mod`, because
+ * Python cannot tell the two apart at the import site and neither can a
+ * reader: whether `mod` is a submodule or an attribute of `pkg` depends on
+ * what is on disk. Recording both is the pessimistic reading — it can only
+ * make a file count as a defender that might not be, never hide one that is.
+ */
+export function pyImports(source, selfPackage = '') {
+  const found = new Set();
+  const absolute = (level, module) => {
+    if (level === 0) return module;
+    const parts = selfPackage ? selfPackage.split('.') : [];
+    const base = parts.slice(0, Math.max(0, parts.length - (level - 1)));
+    return [...base, ...(module ? module.split('.') : [])].join('.');
+  };
+
+  for (const line of logicalLines(source)) {
+    const plain = /^\s*import\s+(.+?)\s*$/.exec(line);
+    if (plain && !/^\s*import\s*\(/.test(line)) {
+      for (const piece of plain[1].split(',')) {
+        const name = piece.trim().split(/\s+as\s+/)[0].trim();
+        if (/^[\w.]+$/.test(name)) found.add(name);
+      }
+      continue;
+    }
+    const rel = /^\s*from\s+(\.*)([\w.]*)\s+import\s+(.+?)\s*$/.exec(line);
+    if (rel) {
+      const base = absolute(rel[1].length, rel[2]);
+      if (base) found.add(base);
+      const names = rel[3].replace(/[()]/g, '');
+      if (!names.includes('*')) {
+        for (const piece of names.split(',')) {
+          const name = piece.trim().split(/\s+as\s+/)[0].trim();
+          if (/^\w+$/.test(name)) found.add(base ? `${base}.${name}` : name);
+        }
+      }
+    }
+  }
+  // `importlib.import_module('pkg.mod')` and `__import__('pkg.mod')`.
+  for (const m of source.matchAll(/(?:import_module|__import__)\s*\(\s*(['"])([\w.]+)\1/g)) found.add(m[2]);
+  return [...found];
+}
+
+/** Does `dotted` name the target module, or something inside it when the target is a package's `__init__.py`? */
+function hits(dotted, target) {
+  if (!target.dotted) return false;
+  return dotted === target.dotted || (target.isPackage && dotted.startsWith(target.dotted + '.'));
+}
+
+/** Does the Python file at `absFile` import `targetRel`? */
+export function pyFileImports(projectDir, absFile, targetRel, testRel) {
+  const target = pyModuleName(projectDir, targetRel);
+  if (!target.dotted) return false;
+  let source;
+  try {
+    source = readFileSync(absFile, 'utf8');
+  } catch {
+    return false;
+  }
+  return pyImports(source, packageOf(projectDir, testRel ?? absFile)).some((d) => hits(d, target));
+}
+
+/** Non-test Python files that import the target, by direct import only. */
+export function pyBlastRadius(projectDir, targetRel) {
+  const target = pyModuleName(projectDir, targetRel);
+  if (!target.dotted) return 0;
+  let count = 0;
+  for (const rel of walk(projectDir)) {
+    if (!PY.test(rel) || rel === targetRel || IS_PY_TEST.test(rel)) continue;
+    let source;
+    try {
+      source = readFileSync(join(projectDir, rel), 'utf8');
+    } catch {
+      continue;
+    }
+    if (pyImports(source, packageOf(projectDir, rel)).some((d) => hits(d, target))) count++;
+  }
+  return count;
+}
+
+export const IS_PY_TEST = /(^|\/)(test[^/]*\.py|[^/]*_test\.py)$/;
+
+const PATCH_STRING = /\b(?:mock\.|unittest\.mock\.|mocker\.|monkeypatch\.)?(?:patch|setattr|setitem|patch\.object|patch\.dict)\s*\(\s*(['"])([\w.]+)\1/g;
+// `.test()` on a global regex advances its lastIndex and carries that state to
+// the next call. The predicate gets its own non-global copy so line-by-line
+// scanning cannot silently start matching from the middle of a line.
+const PATCH_LINE = new RegExp(PATCH_STRING.source);
+const UNASSERTED = /unasserted:\s*(.+?)\s*$/;
+const ASSERT_LINE = /(^|[^\w.])assert(?:\s|_|\b)|\bself\.assert\w*\s*\(|\bassert\w*\s*\(/;
+
+/**
+ * Which parts of the target a test replaces.
+ *
+ * This is where Python and JavaScript genuinely differ, and copying the
+ * JavaScript rule would be wrong. `vi.mock('./mod')` replaces a whole module,
+ * so a file that calls it can detect nothing in that module and is never a
+ * defender. `patch('pkg.mod.fn')` replaces **one attribute**: a fault anywhere
+ * else in `pkg.mod` is still fully detectable, and excluding the file would
+ * turn a real verdict into `nocover` — the same silent wrong answer, pointing
+ * the other way.
+ *
+ * So only a patch of the module itself disqualifies a defender. An attribute
+ * patch leaves the file a defender and is reported as a signal, because it is
+ * still the cheapest available hint about where that test is blind.
+ */
+export function pyPatches(source, target) {
+  const whole = [];
+  const attributes = [];
+  for (const m of source.matchAll(PATCH_STRING)) {
+    const path = m[2];
+    if (!target.dotted) continue;
+    if (path === target.dotted) whole.push(path);
+    else if (path.startsWith(target.dotted + '.')) attributes.push(path);
+  }
+  return { whole, attributes };
+}
+
+/** Does any assertion in the file mention a name bound from the target? */
+function assertsOnTarget(source, bindings) {
+  if (bindings.length === 0) return false;
+  for (const line of source.split('\n')) {
+    if (COMMENT.test(line) || !ASSERT_LINE.test(line)) continue;
+    for (const b of bindings) if (new RegExp(`(^|[^\\w.])${b}(?![\\w])`).test(line)) return true;
+  }
+  return false;
+}
+
+/** Local names this source binds from the target module. */
+function bindingsFor(source, target, selfPackage) {
+  const names = new Set();
+  for (const line of logicalLines(source)) {
+    const rel = /^\s*from\s+(\.*)([\w.]*)\s+import\s+(.+?)\s*$/.exec(line);
+    if (rel) {
+      const parts = selfPackage ? selfPackage.split('.') : [];
+      const base = rel[1].length === 0 ? rel[2] : [...parts.slice(0, Math.max(0, parts.length - (rel[1].length - 1))), ...(rel[2] ? rel[2].split('.') : [])].join('.');
+      const list = rel[3].replace(/[()]/g, '');
+      for (const piece of list.split(',')) {
+        const [imported, alias] = piece.trim().split(/\s+as\s+/).map((x) => x && x.trim());
+        if (!imported || !/^\w+$/.test(imported)) continue;
+        if (base === target.dotted) names.add(alias || imported);              // from pkg.mod import fn
+        else if (`${base}.${imported}` === target.dotted) names.add(alias || imported); // from pkg import mod
+      }
+      continue;
+    }
+    const plain = /^\s*import\s+([\w.]+)(?:\s+as\s+(\w+))?\s*$/.exec(line);
+    if (plain && plain[1] === target.dotted) names.add(plain[2] || plain[1].split('.')[0]);
+  }
+  return [...names];
+}
+
+/**
+ * How one Python test file relates to one target: does it import it, does it
+ * replace the whole module, which attributes of it does it replace, does it
+ * ever assert on anything it took from it, and did the author annotate an
+ * unasserted patch with a reason (`# unasserted: <why>` on or above the line).
+ */
+export function analyzePyDefender(projectDir, testRel, targetRel) {
+  const target = pyModuleName(projectDir, targetRel);
+  let source;
+  try {
+    source = readFileSync(join(projectDir, testRel), 'utf8');
+  } catch {
+    return { file: testRel, imports: false, mocks: false, asserted: false, annotation: null, patchedAttributes: [] };
+  }
+  const selfPackage = packageOf(projectDir, testRel);
+  const imports = pyImports(source, selfPackage).some((d) => hits(d, target));
+  const { whole, attributes } = pyPatches(source, target);
+  const bindings = bindingsFor(source, target, selfPackage);
+  const asserted = assertsOnTarget(source, bindings);
+
+  let annotation = null;
+  if (whole.length || attributes.length) {
+    const lines = source.split('\n');
+    lines.forEach((text, i) => {
+      if (annotation || !PATCH_LINE.test(text)) return;
+      for (let j = i; j >= Math.max(0, i - 2) && !annotation; j--) {
+        const a = UNASSERTED.exec(lines[j]);
+        if (a) annotation = a[1];
+      }
+    });
+  }
+  return { file: testRel, imports, mocks: whole.length > 0, asserted, annotation, patchedAttributes: attributes };
+}
+
+/**
+ * The Python reading of the same question, which is deliberately not the
+ * JavaScript one.
+ *
+ * `vi.mock('./mod')` replaces a module; `patch('pkg.mod.fn')` replaces a single
+ * attribute of one. Applying the JavaScript rule to Python would drop every
+ * test that patches anything in the target — including tests that defend it
+ * perfectly — and report `nocover` for a claim that is in fact well covered.
+ * So only a patch of the module itself removes a defender. An attribute patch
+ * keeps it and raises `target-attribute-patched`, which names the attributes:
+ * a fault in one of them is the place that test is least likely to notice.
+ */
+export function classifyPythonDefenders(projectDir, targetRel, candidates) {
+  const canDetect = [];
+  const mocking = [];
+  const signals = [];
+  for (const file of candidates) {
+    const a = analyzePyDefender(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);
+      if (a.patchedAttributes.length) signals.push({ file, signal: 'target-attribute-patched', reason: a.patchedAttributes.slice(0, 8).join(', ') });
+    }
+  }
+  return { canDetect, mocking, signals };
+}

package/src/probe/rank.mjs

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join, resolve, extname } from 'node:path';
 import { walk } from '../util/glob.mjs';
+import { pyBlastRadius } from './pyimports.mjs';
 
 const aliasCache = new Map();
 
@@ -11,8 +12,10 @@ function parseJsonc(text) {
 
 /**
  * Alias rules for a project: tsconfig/jsconfig `compilerOptions.paths` (with
- * `baseUrl`, following a relative `extends` a few levels) and package.json
- * `imports`. Bare specifiers that match no rule are ignored, as documented.
+ * `baseUrl`, following a relative `extends` a few levels, and every
+ * `references[].path` — Vite projects keep `paths` in `tsconfig.app.json`),
+ * vite/vitest `resolve.alias` read as text, and package.json `imports`. Bare
+ * specifiers that match no rule are ignored, as documented.
  */
 export function loadAliases(projectDir) {
   if (aliasCache.has(projectDir)) return aliasCache.get(projectDir);
@@ -22,25 +25,69 @@ export function loadAliases(projectDir) {
     rules.push({ prefix, suffix, wildcard: pattern.includes('*'), targets: targets.map((t) => resolve(base, t)) });
   };
 
-  let cfgPath = ['tsconfig.json', 'jsconfig.json'].map((f) => join(projectDir, f)).find(existsSync);
-  let baseUrl;
-  let paths;
-  for (let hop = 0; cfgPath && hop < 5; hop++) {
+  // Every tsconfig in the chain: the root, what it extends, what it references.
+  const seen = new Set();
+  const queue = ['tsconfig.json', 'jsconfig.json'].map((f) => join(projectDir, f)).filter(existsSync).slice(0, 1);
+  while (queue.length && seen.size < 12) {
+    const cfgPath = queue.shift();
+    if (seen.has(cfgPath) || !existsSync(cfgPath)) continue;
+    seen.add(cfgPath);
     let cfg;
     try {
       cfg = parseJsonc(readFileSync(cfgPath, 'utf8'));
     } catch {
-      break;
+      continue;
     }
     const co = cfg.compilerOptions ?? {};
-    if (baseUrl === undefined && co.baseUrl !== undefined) baseUrl = resolve(dirname(cfgPath), co.baseUrl);
-    if (paths === undefined && co.paths !== undefined) paths = { dir: dirname(cfgPath), map: co.paths };
+    if (co.paths) {
+      const base = co.baseUrl !== undefined ? resolve(dirname(cfgPath), co.baseUrl) : dirname(cfgPath);
+      for (const [pattern, targets] of Object.entries(co.paths)) if (Array.isArray(targets)) toRule(pattern, targets, base);
+    }
     const ext = typeof cfg.extends === 'string' && cfg.extends.startsWith('.') ? cfg.extends : null;
-    cfgPath = ext ? resolve(dirname(cfgPath), ext.endsWith('.json') ? ext : ext + '.json') : null;
+    if (ext) queue.push(resolve(dirname(cfgPath), ext.endsWith('.json') ? ext : ext + '.json'));
+    for (const ref of Array.isArray(cfg.references) ? cfg.references : []) {
+      if (typeof ref?.path !== 'string') continue;
+      const p = resolve(dirname(cfgPath), ref.path);
+      queue.push(p.endsWith('.json') ? p : join(p, 'tsconfig.json'));
+    }
   }
-  if (paths) {
-    const base = baseUrl ?? paths.dir;
-    for (const [pattern, targets] of Object.entries(paths.map)) if (Array.isArray(targets)) toRule(pattern, targets, base);
+
+  // vite / vitest config: `resolve.alias` as `{ '@': path.resolve(__dirname, './src') }`,
+  // `{ '@': fileURLToPath(new URL('./src', import.meta.url)) }`, `{ '@': './src' }`
+  // or `[{ find: '@', replacement: … }]`. Read as text: the config may be TypeScript.
+  for (const f of ['vitest.config.ts', 'vitest.config.mts', 'vitest.config.js', 'vitest.config.mjs', 'vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs']) {
+    const path = join(projectDir, f);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, 'utf8');
+    const start = /\balias\s*:\s*([\[{])/.exec(text);
+    if (!start) continue;
+    // Take the balanced bracket block that follows `alias:`.
+    const open = start.index + start[0].length - 1;
+    const pairs = { '{': '}', '[': ']' };
+    let depth = 0;
+    let end = -1;
+    for (let i = open; i < text.length; i++) {
+      if (text[i] === '{' || text[i] === '[' || text[i] === '(') depth++;
+      else if (text[i] === '}' || text[i] === ']' || text[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
+    }
+    if (end === -1) continue;
+    const block = text.slice(open, end + 1);
+    const PATHLIKE = /(['"])(\.{1,2}\/[^'"]*|src(?:\/[^'"]*)?)\1/;
+    let entries;
+    if (start[1] === '[') {
+      entries = [...block.matchAll(/find\s*:\s*(['"])([^'"]+)\1([\s\S]*?)(?=find\s*:|\]$)/g)].map((m) => [m[2], m[3]]);
+    } else {
+      // key: <value up to the next top-level key>; the value may contain calls with their own commas
+      const keys = [...block.matchAll(/(['"]?)([@#~$\w./-]+)\1\s*:(?!\/)/g)];
+      entries = keys.map((k, i) => [k[2], block.slice(k.index + k[0].length, keys[i + 1]?.index ?? block.length)]);
+    }
+    for (const [key, value] of entries) {
+      const target = PATHLIKE.exec(value)?.[2];
+      if (!key || !target) continue;
+      const abs = resolve(projectDir, target);
+      rules.push({ prefix: key, suffix: '', wildcard: false, targets: [abs] });
+      rules.push({ prefix: key.endsWith('/') ? key : key + '/', suffix: '', wildcard: true, targets: [join(abs, '*')] });
+    }
   }
 
   const pkgPath = join(projectDir, 'package.json');
@@ -94,6 +141,14 @@ function resolvesTo(fromFile, specifier, targetAbs, aliases) {
   return bases.some((b) => expandBase(b).includes(targetAbs));
 }
 
+/** Does `specifier`, as written in `absFile`, resolve to `targetRel` (relative or alias-resolved)? */
+export function specifierResolvesTo(projectDir, absFile, specifier, targetRel) {
+  return resolvesTo(absFile, specifier, resolve(projectDir, targetRel), loadAliases(projectDir));
+}
+
+/** Clear the alias cache (tests create and delete projects at the same paths). */
+export const resetAliasCache = () => aliasCache.clear();
+
 /** Does the file at `absFile` import `targetRel` (relative or alias-resolved)? */
 export function fileImports(projectDir, absFile, targetRel) {
   const targetAbs = resolve(projectDir, targetRel);
@@ -114,6 +169,7 @@ export function fileImports(projectDir, absFile, targetRel) {
  * bare package specifiers are not. Direct imports only.
  */
 export function blastRadius(projectDir, targetRel) {
+  if (targetRel.endsWith('.py')) return pyBlastRadius(projectDir, targetRel);
   const targetAbs = resolve(projectDir, targetRel);
   const aliases = loadAliases(projectDir);
   let count = 0;
@@ -136,9 +192,13 @@ export function blastRadius(projectDir, targetRel) {
   return count;
 }
 
+// A kill whose defender was written in the same change as the code carries
+// less independent evidence. Ranking may read the signal; verdicts never do.
+const INDEPENDENCE_WEIGHT = { 'separate-change': 1, unknown: 0.95, 'co-authored': 0.85 };
+
 /** Additive ordering only. Never touches the verdict. */
-export function rank({ severity, sourceKind, blast }) {
-  const score = SEVERITY_WEIGHT[severity] * (SOURCE_WEIGHT[sourceKind] ?? 0.9) * (1 + Math.log2(1 + blast));
+export function rank({ severity, sourceKind, blast, independence }) {
+  const score = SEVERITY_WEIGHT[severity] * (SOURCE_WEIGHT[sourceKind] ?? 0.9) * (1 + Math.log2(1 + blast)) * (INDEPENDENCE_WEIGHT[independence] ?? 1);
   return { score: Number(score.toFixed(3)), blastRadius: blast, tier: severity };
 }
 

package/src/probe/runners/index.mjs

@@ -1,20 +1,91 @@
 import * as vitest from './vitest.mjs';
 import * as jest from './jest.mjs';
+import * as playwright from './playwright.mjs';
+import * as pythonRunner from './python.mjs';
 
-export const RUNNERS = { vitest, jest };
+export const RUNNERS = {
+  vitest,
+  jest,
+  playwright,
+  python: pythonRunner,
+  // The same adapter with its engine pinned: `--runner pytest` fails rather
+  // than falling back to unittest, because which engine ran changes what the
+  // evidence means.
+  pytest: pythonRunner.pinned('pytest'),
+  unittest: pythonRunner.pinned('unittest'),
+};
+
+export const RUNNER_NAMES = ['vitest', 'jest', 'playwright', 'python', 'pytest', 'unittest'];
+
+/**
+ * Runners that own files rather than projects: a defender under Playwright's
+ * testDir runs under Playwright, and a `.py` defender runs under Python,
+ * whatever the project runner is. That is what makes a repository holding
+ * both a JavaScript and a Python package probeable in one run. `auto` may
+ * still pick Python as the project runner when no JavaScript runner resolves;
+ * it never picks Playwright, which needs a config to mean anything.
+ */
+export const OWNED_RUNNERS = [playwright, pythonRunner];
 
 /**
- * Pick the runner: an explicit name, or the first of vitest, jest that is
- * resolvable from the project. Returns { runner, version } or { error }.
+ * Pick the project runner: an explicit name, or the first of vitest, jest,
+ * python that is resolvable from the project. Returns
+ * { runner, version, source, engine } or { error }. `engine` is set when the
+ * runner has more than one (Python: pytest or unittest) and names the one
+ * that will actually run — it, not the module name, is what the evidence
+ * records.
  */
-export async function selectRunner({ projectDir, name = 'auto' }) {
-  const candidates = name === 'auto' ? [vitest, jest] : [RUNNERS[name]];
-  if (!candidates[0]) return { error: `unknown runner "${name}"; use vitest, jest or auto` };
+export async function selectRunner({ projectDir, sourceDir, python, name = 'auto' }) {
+  const candidates = name === 'auto' ? [vitest, jest, pythonRunner] : [RUNNERS[name]];
+  if (!candidates[0]) return { error: `unknown runner "${name}"; use ${RUNNER_NAMES.join(', ')} or auto` };
   const messages = [];
   for (const r of candidates) {
-    const c = await r.check({ projectDir });
-    if (c.ok) return { runner: r, version: c.version };
+    const c = await r.check({ projectDir, sourceDir, python });
+    if (c.ok) return { runner: r, version: c.version, source: c.source, engine: c.engine };
     messages.push(`${r.name}: ${c.message}`);
   }
   return { error: messages.join('; ') };
 }
+
+/** What the evidence calls a runner: the engine that actually ran, else the module's name. */
+export const runnerLabel = (runner, engines) => engines?.get(runner) ?? runner.name;
+
+/** The runner a test file runs under: an owning runner if one claims it, else the project runner. */
+export function runnerFor(projectDir, file, primary) {
+  if (primary.owns?.(projectDir, file)) return primary;
+  return OWNED_RUNNERS.find((r) => r !== primary && r.owns(projectDir, file)) ?? primary;
+}
+
+/** Group files by the runner they run under, in a stable order (primary first). */
+export function partitionByRunner(projectDir, files, primary) {
+  const groups = new Map([[primary, []]]);
+  for (const f of files) {
+    const r = runnerFor(projectDir, f, primary);
+    if (!groups.has(r)) groups.set(r, []);
+    groups.get(r).push(f);
+  }
+  if (groups.get(primary).length === 0 && groups.size > 1) groups.delete(primary);
+  return groups;
+}
+
+/**
+ * Merge the runs of several runners into one testRun, pessimistically: any
+ * load error is an error, any timeout is a timeout, any failure is a failure.
+ * Counts add; failed test ids concatenate.
+ */
+export function mergeRuns(parts) {
+  if (parts.length === 1) return parts[0];
+  // Import provenance is per-target and never contradictory between runners:
+  // only the Python runner reports any, and only for its own targets.
+  const provenance = Object.assign({}, ...parts.map((p) => p.provenance ?? {}));
+  const runs = parts.map((p) => p.run);
+  const outcome = runs.some((r) => r.outcome === 'error') ? 'error' : runs.some((r) => r.outcome === 'timeout') ? 'timeout' : runs.some((r) => r.outcome === 'fail') ? 'fail' : 'pass';
+  const sum = (k) => runs.reduce((n, r) => n + (r.tests[k] ?? 0), 0);
+  return {
+    run: { outcome, tests: { total: sum('total'), passed: sum('passed'), failed: sum('failed') }, assertionFailures: runs.reduce((n, r) => n + r.assertionFailures, 0), durationMs: runs.reduce((n, r) => n + r.durationMs, 0) },
+    timeouts: parts.reduce((n, p) => n + (p.timeouts ?? 0), 0),
+    loadMessage: parts.find((p) => p.loadMessage)?.loadMessage,
+    failedTests: parts.flatMap((p) => p.failedTests ?? []),
+    provenance,
+  };
+}

package/src/probe/runners/jest.mjs

@@ -1,9 +1,21 @@
-import { TEST_GLOBS, npx, runProcess, checkBinary, listTestFiles } from './shared.mjs';
+import { TEST_GLOBS, runProcess, checkRunner, runnerArgv, listTestFiles } from './shared.mjs';
 
 export const name = 'jest';
 // jest's default testMatch also collects anything under __tests__/.
 export const testGlobs = [...TEST_GLOBS, '**/__tests__/**/*.js', '**/__tests__/**/*.mjs', '**/__tests__/**/*.cjs', '**/__tests__/**/*.ts', '**/__tests__/**/*.tsx', '**/__tests__/**/*.jsx'];
-export const check = (opts) => checkBinary({ ...opts, bin: 'jest' });
+export const check = (opts) => checkRunner({ ...opts, pkg: 'jest', bin: 'jest' });
 export const tests = (projectDir) => listTestFiles(projectDir, testGlobs);
 // --runTestsByPath: positionals are exact paths, not regexes — a path with `+` or `(` would otherwise silently match nothing.
-export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => [npx, 'jest', '--ci', '--json', `--outputFile=${outFile}`, '--runTestsByPath', ...files] });
+/** The command line, as data. Exported so it is falsifiable without spawning anything. */
+export const argvFor = (projectDir, files, outFile, { serial = false } = {}) =>
+  [...runnerArgv(projectDir, 'jest', 'jest'), '--ci', '--json', `--outputFile=${outFile}`, ...(serial ? ['--runInBand'] : []), '--runTestsByPath', ...files];
+export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => argvFor(opts.projectDir, files, outFile, opts) });
+
+/**
+ * The negative control's edit: content this runner's loader cannot possibly
+ * parse. Used to prove the defenders actually execute a file before a
+ * `survived` verdict about it is allowed to stand. An unterminated group is
+ * a syntax error at every JavaScript/TypeScript parser, whatever the file
+ * contained before.
+ */
+export const fatalEdit = () => '/* testguard negative control: this file must not parse */\n(\n';