testguard-cli 0.5.0 → 0.6.0

package/src/probe/probe.mjs

@@ -1,20 +1,32 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync as fsRealpathSync } from 'node:fs';
 import { git } from '../git.mjs';
 import { createRequire } from 'node:module';
-import { join, relative, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { repoRoot as gitRoot, headSha, isDirty, snapshotWorkingTree } from '../git.mjs';
-import { discoverDefenders } from './discover.mjs';
+import { discoverDefenders, discoverDefendersDetailed } from './discover.mjs';
+import { classifyDefenders } from './mocks.mjs';
+import { detectContention, contentionWarning } from './contention.mjs';
 import { createScratch, inPlace, PreconditionError } from './worktree.mjs';
 import { applyFault, locate } from './inject.mjs';
 import { resolveDefenders, parseCommandTemplate } from './runners/shared.mjs';
-import { selectRunner, RUNNERS } from './runners/index.mjs';
+import { selectRunner, RUNNERS, OWNED_RUNNERS, partitionByRunner, mergeRuns } from './runners/index.mjs';
 import { classify, shouldStopEarly } from './classify.mjs';
 import { blastRadius, rank } from './rank.mjs';
+import { classifyIndependence } from './independence.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { fingerprint } from '../../spec/lib/fingerprint.mjs';
 
 const isKill = (r) => r.outcome === 'fail' && r.assertionFailures > 0;
 
+/** realpath when the path still exists; the path itself otherwise. Never throws. */
+function realpathSync(p) {
+  try {
+    return fsRealpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
 function readRunnerVersion(projectDir, name = 'vitest') {
   try {
     return JSON.parse(readFileSync(createRequire(join(projectDir, 'noop.js')).resolve(`${name}/package.json`), 'utf8')).version;
@@ -33,6 +45,10 @@ export async function probe({
   confirmRuns = 3,
   mode = 'worktree',
   ref = 'HEAD',
+  refExplicit = false,
+  ignoreDirty = false,
+  serial = false,
+  onWarn = () => {},
   budgetMs = 120_000,
   runnerCommand,
   runnerName = 'auto',
@@ -69,11 +85,17 @@ export async function probe({
 
   // Worktree mode probes a commit, not the working tree. Uncommitted defender
   // or target edits would be silently absent — the same survivors, no hint why.
+  // Refused for the IMPLICIT HEAD, which is the silent-mismatch trap. With an
+  // explicit --ref the user has named the commit they mean (a pre-fix probe
+  // in a post-mortem is the most valuable run there is); with --ignore-dirty
+  // they have said they know. Both proceed with a warning that names the
+  // files, and the evidence records what was ignored.
   let snapshot;
+  let ignoredDirty = [];
   if (mode === 'worktree') {
     if (includeDirty) {
       if (isDirty(root)) snapshot = snapshotWorkingTree(root);
-    } else if (ref === 'HEAD') {
+    } else {
       const watched = new Set(targets);
       for (const claim of claims.claims) {
         if (selected && !selected.has(claim.id)) continue;
@@ -82,16 +104,28 @@ export async function probe({
         for (const g of claim.defendedBy ?? []) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
       }
       const dirty = git(['status', '--porcelain', '--', ...watched], root).split('\n').filter(Boolean).map((l) => l.replace(/^[ MADRCU?!]{1,2}\s+/, '').replace(/^.* -> /, ''));
+      if (dirty.length && !refExplicit && !ignoreDirty) {
+        throw new PreconditionError(`${dirty.length} defender/target file${dirty.length === 1 ? ' has' : 's have'} uncommitted changes (${dirty.join(', ')}); worktree mode probes HEAD (${head.slice(0, 7)}), so those changes would be silently ignored. Commit them, run with --include-dirty to probe the working tree, use --in-place, or --ignore-dirty if you mean HEAD as committed.`);
+      }
       if (dirty.length) {
-        throw new PreconditionError(`${dirty.length} defender/target file${dirty.length === 1 ? ' has' : 's have'} uncommitted changes (${dirty.join(', ')}); worktree mode probes HEAD (${head.slice(0, 7)}), so those changes would be silently ignored. Commit them, run with --include-dirty to probe the working tree, or use --in-place.`);
+        ignoredDirty = dirty.sort();
+        onWarn(`${dirty.length} defender/target file${dirty.length === 1 ? ' has' : 's have'} uncommitted changes (${dirty.join(', ')}); probing ${ref === 'HEAD' ? `HEAD (${head.slice(0, 7)})` : `${ref} (${head.slice(0, 7)})`} as committed — the working-tree versions are NOT what is being probed. Recorded in the evidence as repo.ignoredDirty.`);
       }
     }
   }
+  // Contention: name it before the first run, and record it, so a later
+  // reader of a TIMEOUT or FLAKY-DEFENDER knows the machine was loaded.
+  const contention = detectContention();
+  if (contention.detected) onWarn(contentionWarning(contention));
+
   const startedAt = new Date().toISOString();
   const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref: snapshot ?? ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
+  const isoReal = realpathSync(iso.projectDir);
   const records = [];
   let runnerVersion;
+  let runnerSource;
   let runner = RUNNERS[runnerName === 'auto' ? 'vitest' : runnerName];
+  const runnersUsed = new Map(); // every runner that ran defenders, beyond the project runner
   try {
     const commandTemplate = runnerCommand ? parseCommandTemplate(runnerCommand) : undefined;
     if (!commandTemplate) {
@@ -103,21 +137,60 @@ export async function probe({
       }
       runner = sel.runner;
       runnerVersion = sel.version;
+      runnerSource = sel.source;
     }
-    const allTests = runner.tests(iso.projectDir);
+    runnersUsed.set(runner.name, runnerVersion ?? readRunnerVersion(projectDir, runner.name));
+    // Files an owning runner (Playwright) claims run under it, whatever the
+    // project runner is; it must resolve before the first such defender runs.
+    const owned = OWNED_RUNNERS.filter((r) => r !== runner);
+    const ownedChecked = new Map();
+    const ensureOwned = async (r, file) => {
+      if (!ownedChecked.has(r)) ownedChecked.set(r, await r.check({ projectDir: iso.projectDir }));
+      const c = ownedChecked.get(r);
+      if (!c.ok) throw new PreconditionError(`${file} is a ${r.name} test (it lives under ${r.name}'s testDir) but ${r.name} is not resolvable in the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${c.message}).`);
+      runnersUsed.set(r.name, c.version);
+    };
+    const allTests = [...new Set([...runner.tests(iso.projectDir).filter((t) => !owned.some((r) => r.owns(iso.projectDir, t))), ...owned.flatMap((r) => r.tests(iso.projectDir))])].sort();
     const baselineCache = new Map();
     const prior = previous && previous.run.confirmRuns === confirmRuns
       ? new Map(previous.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]))
       : new Map();
-    const runDefenders = (files) => runner.run({ projectDir: iso.projectDir, files, budgetMs, commandTemplate });
+    const runDefenders = async (files) => {
+      if (commandTemplate) return runner.run({ projectDir: iso.projectDir, files, budgetMs, commandTemplate, serial });
+      const groups = partitionByRunner(iso.projectDir, files, runner);
+      const parts = [];
+      for (const [r, group] of groups) {
+        if (r !== runner) await ensureOwned(r, group[0]);
+        parts.push(await r.run({ projectDir: iso.projectDir, files: group, budgetMs, serial }));
+      }
+      return mergeRuns(parts);
+    };
+    /** Which runner each defender runs under, when more than the project runner is involved. */
+    const byRunner = (files) => {
+      const groups = partitionByRunner(iso.projectDir, files, runner);
+      if (groups.size <= 1) return undefined; // one runner ran them all, whichever it was
+      return Object.fromEntries([...groups].map(([r, group]) => [r.name, group]));
+    };
 
     for (const claim of claims.claims) {
       if (selected && !selected.has(claim.id)) continue;
       const declared = claim.defendedBy?.length ? resolveDefenders(iso.projectDir, claim.defendedBy) : null;
       for (const fault of claim.faults) {
-        const defenders = declared ?? discoverDefenders(iso.projectDir, fault.file);
+        // Mock-awareness: a discovered file that mocks the target is not a
+        // defender; a declared one that mocks it stays (the author named it)
+        // but is listed, because a declared defender that mocks the subject
+        // is a broken evidence chain the author should see.
+        const mockInfo = declared ? classifyDefenders(iso.projectDir, fault.file, declared) : discoverDefendersDetailed(iso.projectDir, fault.file);
+        const defenders = declared ?? mockInfo.canDetect;
         const stage = (name, i, n) => onStage({ claimId: claim.id, faultId: fault.id, stage: name, i, n });
-        const record = await probeOne({ claim, fault, defenders, discovered: declared === null, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, stage, prior: prior.get(`${claim.id}/${fault.id}`), priorRunId: previous?.run.id });
+        const record = await probeOne({ claim, fault, defenders, discovered: declared === null, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, stage, prior: prior.get(`${claim.id}/${fault.id}`), priorRunId: previous?.run.id, byRunner: byRunner(defenders), mocking: mockInfo.mocking, signals: mockInfo.signals,
+          historyRef: snapshot ?? (mode === 'worktree' ? head : 'HEAD'), historyDir: root,
+          // A path from the runner is absolute inside the SCRATCH worktree, or
+          // project-relative. Either way history is read from the real repository,
+          // so both must land on a repo-root-relative path. The runner reports
+          // realpaths (/private/var on macOS) while the worktree path may not be
+          // one — realpath both sides or every comparison silently misses.
+          toRepoPath: (p) => relative(root, join(projectDir, isAbsolute(p) ? relative(isoReal, realpathSync(p)) : p)) });
         records.push(record);
         onProgress(record);
       }
@@ -133,9 +206,12 @@ export async function probe({
       id: `run-${startedAt.replace(/[-:.]/g, '').slice(0, 15)}`,
       startedAt,
       finishedAt: new Date().toISOString(),
-      repo: { head, dirty: isDirty(root), ...(snapshot ? { snapshot } : {}) },
+      repo: { head, dirty: isDirty(root), ...(snapshot ? { snapshot } : {}), ...(ignoredDirty.length ? { ignoredDirty } : {}) },
       runner: { name: runner.name, ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}) },
+      ...(runnersUsed.size > 1 ? { runners: [...runnersUsed].map(([n, v]) => ({ name: n, ...(v ? { version: v } : {}) })) } : {}),
       confirmRuns,
+      ...(serial ? { serial: true } : {}),
+      ...(contention.detected ? { contention } : {}),
       ...(confirmRuns < 3 ? { provisional: true } : {}),
       mode,
     },
@@ -143,7 +219,7 @@ export async function probe({
   };
 }
 
-async function probeOne({ claim, fault, defenders, discovered, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, stage, prior, priorRunId }) {
+async function probeOne({ claim, fault, defenders, discovered, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, stage, prior, priorRunId, byRunner, mocking = [], signals = [], historyRef, historyDir, toRepoPath }) {
   const targetPath = join(iso.projectDir, fault.file);
   const targetExists = existsSync(targetPath);
   const inputs = {
@@ -177,10 +253,27 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, co
             break;
           }
         }
+        // The decision stops at the first non-green run — nothing about this
+        // fault can be trusted after it. But "failed once in three" and "fails
+        // every time" are different problems for whoever has to fix the
+        // defender, and the only way to tell them apart is to finish the runs.
+        // Paid once per defender set, and only when it is already broken.
+        if (runs.length < confirmRuns && runs[runs.length - 1].outcome === 'fail') {
+          for (let i = runs.length; i < confirmRuns; i++) {
+            stage('baseline-flake', i + 1, confirmRuns);
+            runs.push((await runDefenders(defenders)).run);
+          }
+        }
         baselineCache.set(key, { runs, loadMessage });
       }
       const baseline = baselineCache.get(key);
       detail.baselineRuns = baseline.runs;
+      // Observed instability of the defenders on UNMODIFIED source: `fail` is
+      // the tests running and disagreeing with themselves. A load error or a
+      // timeout is not flakiness — nothing was measured about stability — so
+      // neither is counted, on either side of the ratio.
+      const measured = baseline.runs.filter((r) => r.outcome === 'pass' || r.outcome === 'fail');
+      if (measured.length) detail.flakeRate = { runs: measured.length, failures: measured.filter((r) => r.outcome === 'fail').length };
       if (baseline.runs.some((r) => r.outcome === 'error')) {
         // The defenders did not load. That is not flakiness and not a verdict
         // about the fault; the claim cannot be probed until they do.
@@ -193,11 +286,11 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, co
           const probeRuns = rawProbeRuns;
           for (let i = 0; i < confirmRuns; i++) {
             stage('probe', i + 1, confirmRuns);
-            const { run, timeouts, loadMessage } = await runDefenders(defenders);
-            probeRuns.push({ ...run, timeouts, loadMessage });
+            const { run, timeouts, loadMessage, failedTests } = await runDefenders(defenders);
+            probeRuns.push({ ...run, timeouts, loadMessage, failedTests });
             if (shouldStopEarly(probeRuns)) break;
           }
-          detail.probeRuns = probeRuns.map(({ timeouts, loadMessage, ...run }) => run);
+          detail.probeRuns = probeRuns.map(({ timeouts, loadMessage, failedTests, ...run }) => run);
           const provisional = classify({ defenders, anchor, baselineRuns: detail.baselineRuns, probeRuns, confirmRuns });
 
           // Escalation: does anything *undeclared* catch it? A single run cannot
@@ -207,15 +300,21 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, co
           if (provisional.verdict === 'survived' && escalate && broader.length > 0) {
             const runs = [];
             let killers = null;
+            let stoppedEarly;
             for (let i = 0; i < confirmRuns; i++) {
               stage('escalation', i + 1, confirmRuns);
               const { run, failedTests } = await runDefenders(allTests);
               runs.push(run);
               killers = killers === null ? new Set(failedTests) : new Set(failedTests.filter((t) => killers.has(t)));
-              if (killers.size === 0) break;
+              // Attribution needs a test that failed in ALL N runs. Once the
+              // intersection is empty no further run can name a killer, so the
+              // remaining runs are wasted; stopping can only fail to NAME a
+              // killer, never upgrade a verdict, which is the pessimistic side.
+              if (killers.size === 0) { stoppedEarly = 'no-common-failure'; break; }
             }
             detail.escalated = true;
             detail.escalationRuns = runs;
+            if (stoppedEarly) detail.escalationStoppedEarly = stoppedEarly;
             if (killers.size > 0 && runs.length === confirmRuns && runs.every(isKill)) {
               detail.reason = 'killed-by-undeclared-tests';
               detail.undeclaredKillers = [...killers].sort();
@@ -234,15 +333,24 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, co
 
   const blast = targetExists ? blastRadius(iso.projectDir, fault.file) : 0;
 
+  // L3: a kill by a test written in the same change as the code it guards is
+  // weaker evidence than one written separately. Signal only — the verdict is
+  // already decided above, and ranking is the only consumer.
+  if (verdict === 'killed' && historyRef) {
+    // Only the tests that actually failed on the fault are its killers.
+    const killers = [...new Set(rawProbeRuns.flatMap((r) => r.failedTests ?? []).map((t) => t.split('::')[0]).filter(Boolean))];
+    detail.independence = classifyIndependence({ dir: historyDir, ref: historyRef, targetFile: toRepoPath(fault.file), defenders: (killers.length ? killers : defenders).map(toRepoPath) });
+  }
+
   return {
     fingerprint: fingerprint({ claimId: claim.id, subjectId: fault.id, file: fault.file, verdict }),
     claim: { id: claim.id, statement: claim.statement, severity: claim.severity, source: claim.source, producedBy: claim.producedBy },
     subject: { kind: 'fault', id: fault.id, description: fault.description, file: fault.file, faultClass: fault.faultClass, producedBy: fault.producedBy, contentHash: sha256(`${fault.find}\n${fault.replace}`) },
     verdict,
     detail,
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}) },
+    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
     inputs,
-    rank: rank({ severity: claim.severity, sourceKind: claim.source.kind, blast }),
+    rank: rank({ severity: claim.severity, sourceKind: claim.source.kind, blast, independence: detail.independence?.class }),
   };
 }
 

package/src/probe/rank.mjs

@@ -11,8 +11,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 +24,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 +140,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);
@@ -136,9 +190,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,64 @@
 import * as vitest from './vitest.mjs';
 import * as jest from './jest.mjs';
+import * as playwright from './playwright.mjs';
 
-export const RUNNERS = { vitest, jest };
+export const RUNNERS = { vitest, jest, playwright };
 
 /**
- * Pick the runner: an explicit name, or the first of vitest, jest that is
- * resolvable from the project. Returns { runner, version } or { error }.
+ * Runners that own files rather than projects: a defender under Playwright's
+ * testDir runs under Playwright whatever the project runner is. `auto` never
+ * picks one of these for the whole project; `--runner playwright` does.
+ */
+export const OWNED_RUNNERS = [playwright];
+
+/**
+ * Pick the project runner: an explicit name, or the first of vitest, jest that
+ * is resolvable from the project. Returns { runner, version } or { error }.
  */
 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` };
+  if (!candidates[0]) return { error: `unknown runner "${name}"; use vitest, jest, playwright or auto` };
   const messages = [];
   for (const r of candidates) {
     const c = await r.check({ projectDir });
-    if (c.ok) return { runner: r, version: c.version };
+    if (c.ok) return { runner: r, version: c.version, source: c.source };
     messages.push(`${r.name}: ${c.message}`);
   }
   return { error: messages.join('; ') };
 }
+
+/** 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];
+  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 ?? []),
+  };
+}

package/src/probe/runners/jest.mjs

@@ -1,9 +1,9 @@
-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] });
+export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => [...runnerArgv(opts.projectDir, 'jest', 'jest'), '--ci', '--json', `--outputFile=${outFile}`, ...(opts.serial ? ['--runInBand'] : []), '--runTestsByPath', ...files] });

package/src/probe/runners/playwright.mjs

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative, resolve, sep } from 'node:path';
+import { npx, runProcess, listTestFiles, firstInformativeLine } from './shared.mjs';
+import { globToRegExp } from '../../util/glob.mjs';
+
+/**
+ * Playwright runner. Selected **per file**, not per project: a defender that
+ * lives under Playwright's `testDir` runs here, everything else runs under
+ * the project runner (vitest/jest). One claim may list both kinds. Selected
+ * for the whole project only with `--runner playwright`.
+ *
+ * Report protocol: `--reporter=json` with the JSON written to a file we name
+ * (PLAYWRIGHT_JSON_OUTPUT_FILE; the older PLAYWRIGHT_JSON_OUTPUT_NAME is set
+ * too), never parsed from stdout. Playwright's test statuses map onto the
+ * spec's testRun as follows, and the mapping is the point of the adapter:
+ *
+ *   expected            → passed
+ *   unexpected/failed   → failed, counts toward assertionFailures (can kill)
+ *   unexpected/timedOut → failed, counts toward timeouts (never a kill)
+ *   flaky               → failed on an attempt and passed on retry: the run
+ *                         is NOT green. Counted as failed with neither an
+ *                         assertion failure nor a timeout, so a green-looking
+ *                         exit code becomes FLAKY-DEFENDER through the
+ *                         ordinary N-run rules, exactly as GATE-SEMANTICS says.
+ *   skipped             → neither passed nor failed
+ */
+
+export const name = 'playwright';
+
+const CONFIG_FILES = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+const SPEC_GLOBS = ['**/*.spec.js', '**/*.spec.mjs', '**/*.spec.cjs', '**/*.spec.ts', '**/*.spec.mts', '**/*.spec.tsx', '**/*.spec.jsx',
+  '**/*.test.js', '**/*.test.mjs', '**/*.test.cjs', '**/*.test.ts', '**/*.test.mts', '**/*.test.tsx', '**/*.test.jsx'];
+
+const configCache = new Map();
+
+/**
+ * The project's Playwright config, read as text (it may be TypeScript, so it
+ * is never imported): `{ path, testDir }` or null when there is none.
+ * `testDir` defaults to the config's own directory, as Playwright does.
+ */
+export function loadConfig(projectDir) {
+  if (configCache.has(projectDir)) return configCache.get(projectDir);
+  let out = null;
+  for (const f of CONFIG_FILES) {
+    const path = join(projectDir, f);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, 'utf8');
+    const m = /\btestDir\s*:\s*(['"`])([^'"`]+)\1/.exec(text);
+    const testDir = relative(projectDir, resolve(projectDir, m ? m[2] : '.')).split(sep).join('/') || '.';
+    out = { path: f, testDir };
+    break;
+  }
+  configCache.set(projectDir, out);
+  return out;
+}
+
+/** Clear the config cache (tests create and delete projects at the same paths). */
+export const resetConfigCache = () => configCache.clear();
+
+export const testGlobs = SPEC_GLOBS;
+const SPEC_RES = SPEC_GLOBS.map(globToRegExp);
+
+/** Does this test file belong to Playwright: is there a config, and does the file live under its testDir? */
+export function owns(projectDir, file) {
+  const cfg = loadConfig(projectDir);
+  if (!cfg) return false;
+  if (!SPEC_RES.some((re) => re.test(file))) return false;
+  return cfg.testDir === '.' ? true : file.startsWith(cfg.testDir + '/');
+}
+
+/**
+ * Resolvable = a config exists AND `@playwright/test` resolves from the
+ * project. Deliberately not `npx --no-install playwright --version`: the npx
+ * cache and a Python `playwright` on PATH both answer that from a project
+ * that has no Playwright at all, and `playwright test` would then run
+ * against nothing. The package `playwright test` needs is the precondition.
+ */
+export async function check({ projectDir }) {
+  const cfg = loadConfig(projectDir);
+  if (!cfg) return { ok: false, message: 'no playwright.config.* in the project' };
+  try {
+    const pkg = JSON.parse(readFileSync(createRequire(join(projectDir, 'noop.js')).resolve('@playwright/test/package.json'), 'utf8'));
+    return { ok: true, version: pkg.version };
+  } catch {
+    return { ok: false, message: '@playwright/test is not installed in the project (npm i -D @playwright/test)' };
+  }
+}
+
+export const tests = (projectDir) => listTestFiles(projectDir, SPEC_GLOBS).filter((f) => owns(projectDir, f));
+
+/**
+ * Playwright's JSON report → the spec's testRun. Pure; exported for the
+ * sample-driven tests. `durationMs` is the wall clock measured by the runner.
+ */
+export function parseReport(report, durationMs) {
+  const tests = [];
+  const walk = (suite) => {
+    for (const spec of suite.specs ?? []) {
+      for (const t of spec.tests ?? []) {
+        const results = t.results ?? [];
+        const last = results[results.length - 1];
+        tests.push({ id: `${suite.file ?? spec.file ?? ''}::${spec.title}`, status: t.status, finalResult: last?.status, error: results.find((r) => r.error)?.error?.message });
+      }
+    }
+    for (const s of suite.suites ?? []) walk(s);
+  };
+  for (const s of report.suites ?? []) walk(s);
+
+  const expected = tests.filter((t) => t.status === 'expected').length;
+  const unexpected = tests.filter((t) => t.status === 'unexpected');
+  const flaky = tests.filter((t) => t.status === 'flaky').length;
+  const timeouts = unexpected.filter((t) => t.finalResult === 'timedOut' || t.finalResult === 'interrupted').length;
+  const assertionFailures = unexpected.length - timeouts;
+  const failedTests = [...unexpected, ...tests.filter((t) => t.status === 'flaky')].map((t) => t.id);
+  const total = tests.length;
+  const summary = { total, passed: expected, failed: unexpected.length + flaky };
+
+  const globalErrors = report.errors ?? [];
+  let outcome;
+  if (total === 0) outcome = 'error';
+  else if (unexpected.length > 0 || flaky > 0) outcome = 'fail';
+  else outcome = 'pass';
+  const loadMessage = outcome === 'error'
+    ? (globalErrors.length ? firstInformativeLine(globalErrors.map((e) => e.message ?? '').join('\n')) : 'playwright found no tests')
+    : undefined;
+  return { run: { outcome, tests: summary, assertionFailures, durationMs }, timeouts, loadMessage, failedTests, flaky };
+}
+
+export const run = (opts) => {
+  const env = { PLAYWRIGHT_JSON_OUTPUT_FILE: '{out}', PLAYWRIGHT_JSON_OUTPUT_NAME: '{out}' };
+  return runProcess({ ...opts, env, parse: parseReport, argv: (files) => [npx, 'playwright', 'test', '--reporter=json', ...(opts.serial ? ['--workers=1'] : []), ...files] });
+};