tewip-ai 0.29.0 → 0.30.0

package/README.md

@@ -552,6 +552,42 @@ With `--json` the verdict is **sealed**: editing `not-ready` to `ready` in the f
 fail, so a verdict that travels into a ticket or a release note can be checked rather than trusted. It is
 also an MCP tool, so an agent can ask whether its own work is done before saying that it is.
 
+## Run only the tests that could notice this change (Phase 25)
+
+```bash
+tewip pick --diff main...HEAD     # or: tewip pick src/pricing.js
+tewip pick --list                 # just the files, for piping into your runner
+```
+
+A forty-minute suite is a suite people stop running. Vendors sell this as a prediction - a model guesses
+which tests matter - and a guess is the wrong shape for the job, because the cost of being wrong is a bug
+reaching production and nobody can audit a guess.
+
+Here, **skipping a test is a claim that it could not have noticed the change**, and a claim needs
+evidence. A test runs when it imports a changed file, reaches one through another module, is edited by the
+change itself, reads the repository at run time (a guard that scans every source file can be broken by any
+file), or has failed recently — an unknown is never a skip. Everything else is left out with the reason
+printed beside it.
+
+**It refuses to narrow at all** when the change touches dependencies, build or test configuration, shared
+setup or fixtures; when the suite drives a browser, because what a browser test exercises is not written
+in its imports; or when a changed file cannot be traced to any test, since code is reachable in ways an
+import does not show.
+
+**Measured by breaking the code** (`eval/pick-safety.ts`): make a real mutation, ask `pick` what could
+notice it, then run the **whole** suite to find out which tests really catch it. A failure is dropping a
+catching test.
+
+| Project | Judged cases | Catching test lost | Suite selected |
+| --- | --- | --- | --- |
+| This repository (node --test, 76 test files) | 8 | **0** | 7–9% |
+| expressjs/express (Mocha, 88 test files) | 2 | **0** | refused to narrow — every test reaches the change |
+
+Those two rows are the point. On a layered codebase it runs under a tenth of the suite and keeps every
+test that would have caught the bug; on a monolith where every test imports the package front door it says
+there is nothing to skip, rather than inventing a saving. It is also an MCP tool, so an agent can ask what
+to run before running anything.
+
 ## Would your tests catch a bug? (Phase 23)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,15 @@ Usage:
                                     is what was asked for covered. Answers ready, not ready, or cannot
                                     say - and cannot say is never rounded up to ready. --json writes a
                                     sealed verdict that can be checked later. No model, no cost.
+  tewip pick [--diff main...HEAD] [--list] [--out picked.md]
+                                    Which tests could notice this change? Narrows a test run using
+                                    facts rather than a prediction: a test runs when it imports a
+                                    changed file or reaches one through another module, when the change
+                                    edits the test itself, or when it failed recently - an unknown is
+                                    never a skip. It runs the whole suite when the change touches
+                                    dependencies, build or test configuration, shared setup or
+                                    fixtures, or when a changed file cannot be traced to any test.
+                                    --list prints the files for piping. No model, no cost.
   tewip prove <file> [--diff main...HEAD] [--limit 6] [--budget 600] [--strict]
                                     What would your tests NOT catch? Breaks your code in small,
                                     deliberate ways - a boundary moved by one, a condition inverted,

package/dist/cli/tewip.js

@@ -199,6 +199,19 @@ async function main() {
             });
             return;
         }
+        case 'pick': {
+            const { runPick } = await import('../engine/pick/pick-command.js');
+            runPick({
+                root: process.cwd(),
+                diff: flag(args, 'diff') ?? 'main...HEAD',
+                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out' && args[i - 1] !== '--recent' && args[i - 1] !== '--name'),
+                out: flag(args, 'out'),
+                list: args.includes('--list'),
+                recentRuns: Number(flag(args, 'recent') ?? '5'),
+                name: flag(args, 'name'),
+            });
+            return;
+        }
         case 'prove': {
             const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--diff', '--limit', '--budget'].includes(args[i - 1] ?? ''));
             const { runProve } = await import('../engine/prove/prove-command.js');

package/dist/engine/pick/pick-command.js

@@ -0,0 +1,198 @@
+// `tewip pick --diff main...HEAD`: the tests that could notice a change, and the command that runs them.
+//
+// Everything here is a fact read from the project: the diff from git, the test files on disk, the import
+// graph followed outwards from each changed file, and the failures Tewip has kept. Nothing is predicted.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { chooseFramework, detectFrameworks } from '../quality/frameworks.js';
+import { changeSummary } from '../quality/grounding.js';
+import { coverageFor, testFiles } from '../review/coverage.js';
+import { importingTests } from '../prove/prove.js';
+import { allTestsReaching } from '../prove/reaches.js';
+import { datasetFiles, readJsonl, readTriageRecords } from '../../reporters/store.js';
+import { pick, renderPick } from './pick.js';
+const slash = (p) => p.split(String.fromCharCode(92)).join('/');
+/** Tests that failed in the most recent runs, by the file they live in. */
+function recentFailures(root, only, howMany) {
+    const dir = join(root, '.tewip', 'history');
+    const byFile = new Map();
+    if (!existsSync(dir))
+        return { byFile, noHistory: true };
+    const runs = [];
+    const records = [];
+    for (const project of only ? [only] : readdirSync(dir)) {
+        const where = join(dir, project);
+        if (!existsSync(where))
+            continue;
+        runs.push(...readJsonl(datasetFiles(where).runs));
+        records.push(...readTriageRecords(datasetFiles(where).triage));
+    }
+    if (runs.length === 0)
+        return { byFile, noHistory: true };
+    const recent = new Set(runs
+        .slice()
+        .sort((a, b) => (a.finishedAt > b.finishedAt ? -1 : 1))
+        .slice(0, howMany)
+        .map((r) => r.runId));
+    for (const record of records) {
+        if (!recent.has(record.runId))
+            continue;
+        const file = slash(String(record.file ?? ''));
+        if (!file)
+            continue;
+        byFile.set(file, [...(byFile.get(file) ?? []), record.testId]);
+    }
+    return { byFile, noHistory: false };
+}
+/** A test file's path as the history records it, which may be a bare name rather than a full path. */
+const sameTest = (testFile, recorded) => testFile === recorded || testFile.endsWith(`/${recorded}`) || recorded.endsWith(`/${testFile}`);
+/**
+ * Does this test walk the repository at run time?
+ *
+ * Such a test - a guard that scans every source file, a check on licence headers, a snapshot of the
+ * public API - can be broken by any file in the project, so it must never be skipped. This is not a
+ * guess at coverage: it is a statement about what the test reads. Found the hard way, by a safety
+ * measurement that caught this project's own control-character guard failing over a change to a module
+ * it does not import.
+ */
+function readsTheRepo(root, testFile) {
+    try {
+        const text = readFileSync(resolve(root, testFile), 'utf8');
+        const walks = /\breaddirSync\b|\bglob(?:Sync)?\s*\(|\bwalk\s*\(|os\.walk|Files\.walk|filepath\.Walk/.test(text);
+        const reads = /\breadFileSync\b|\bopen\s*\(|readFile\b/.test(text);
+        return walks && reads;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One command rather than a chain of them. Runners take several files at once, and a line of forty
+ * `&&`-joined invocations pays the start-up cost forty times - which is most of the saving the selection
+ * was for. The shared prefix is taken from the framework's own command for two files, so nothing is
+ * assumed about how it is spelled.
+ */
+function oneCommand(root, picked, framework) {
+    if (!framework)
+        return 'your test command';
+    if (picked.mustRun.length === 0)
+        return framework.suite;
+    const paths = picked.mustRun.map((m) => resolve(root, m.testFile));
+    const first = framework.command(paths[0]);
+    if (paths.length === 1)
+        return withCwd(root, framework.cwd, first);
+    // Everything before the first quoted argument is the runner. A longest-common-prefix of two commands
+    // looked cleverer and cut inside the first file name, producing `node --test "test/ "test/a.ts"`.
+    const quote = first.indexOf('"');
+    const prefix = quote > 0 ? first.slice(0, quote).trimEnd() : '';
+    if (!prefix)
+        return withCwd(root, framework.cwd, picked.mustRun.map((m) => framework.command(resolve(root, m.testFile))).join(' && '));
+    const quoted = paths.map((p) => JSON.stringify(relative(framework.cwd, p).split(String.fromCharCode(92)).join('/'))).join(' ');
+    return withCwd(root, framework.cwd, `${prefix} ${quoted}`);
+}
+/** Says where to run it, when that is not the project root. */
+const withCwd = (root, cwd, command) => (resolve(cwd) === resolve(root) ? command : `cd ${JSON.stringify(relative(root, cwd).split(String.fromCharCode(92)).join('/'))} && ${command}`);
+/** Test files that mention this file by path or by name, which is weaker than an import but not nothing. */
+function mentionsOf(root, file, tests) {
+    // The name **with its extension**, or the path. Matching the bare stem was useless: for `cli/tewip.ts`
+    // the stem is "tewip", which appears in nearly every file of this project, so 28 test files were
+    // selected on the grounds that they had mentioned the product's own name.
+    const named = file.split('/').pop() ?? '';
+    if (named.length < 5)
+        return [];
+    const out = [];
+    for (const test of tests) {
+        try {
+            const text = readFileSync(resolve(root, test), 'utf8');
+            if (text.includes(file) || text.includes(named))
+                out.push(test);
+        }
+        catch {
+            // Unreadable: it cannot be shown to mention anything.
+        }
+    }
+    return out;
+}
+/** Does anything at all in the project refer to this file? Used only to tell "unknown" from "unreachable". */
+function mentionedAnywhere(root, file) {
+    const named = file.split('/').pop() ?? '';
+    const where = spawnSync('git', ['grep', '-l', '--', named], { cwd: root, encoding: 'utf8', timeout: 60_000 });
+    const hits = (where.stdout ?? '')
+        .split(String.fromCharCode(10))
+        .map((l) => l.trim())
+        .filter((l) => l && l.split(String.fromCharCode(92)).join('/') !== file);
+    return hits.length > 0;
+}
+export function choose(cmd) {
+    const change = cmd.files && cmd.files.length > 0 ? { files: cmd.files } : changeSummary(cmd.root, cmd.diff);
+    if (!change)
+        return null;
+    const changed = change.files.map(slash);
+    const known = testFiles(cmd.root).map(slash);
+    const relative = known.map((t) => slash(t).replace(`${slash(cmd.root)}/`, ''));
+    const { byFile, noHistory } = recentFailures(cmd.root, cmd.name, cmd.recentRuns ?? 5);
+    const candidates = relative.map((testFile) => {
+        const failed = [];
+        for (const [file, ids] of byFile)
+            if (sameTest(testFile, file))
+                failed.push(...ids);
+        return { testFile, recentlyFailed: failed, readsTheRepo: readsTheRepo(cmd.root, testFile) };
+    });
+    // The import graph, followed outwards from each changed source file.
+    const reaching = new Map();
+    const sources = changed.filter((f) => existsSync(resolve(cmd.root, f)));
+    for (const file of sources) {
+        // Both kinds, together: a test may import the file itself and others reach it through the package.
+        // Taking only the direct importers when there are any is how a selection quietly drops the tests
+        // that exercise the code through the application's own front door.
+        const direct = importingTests(cmd.root, coverageFor(cmd.root, [file], testFiles(cmd.root)), file);
+        const reached = allTestsReaching(cmd.root, file, relative);
+        const byFile = new Map();
+        for (const r of reached)
+            byFile.set(slash(r.testFile), { testFile: slash(r.testFile), how: `reaches, through ${r.steps} import(s),` });
+        for (const testFile of direct)
+            byFile.set(slash(testFile), { testFile: slash(testFile), how: 'imports' });
+        reaching.set(file, [...byFile.values()]);
+    }
+    // A file nothing imports may still be named somewhere - a test that reads it as text, a path in a
+    // script, a dynamic import. A mention is not proof that a test exercises it, so a test that mentions
+    // it runs; and when nothing in the project mentions it at all, nothing can notice it.
+    const unreferenced = [];
+    for (const [file, reaches] of reaching) {
+        if (reaches.length > 0)
+            continue;
+        const named = mentionsOf(cmd.root, file, relative);
+        if (named.length > 0)
+            reaching.set(file, named.map((testFile) => ({ testFile, how: 'names' })));
+        else if (!mentionedAnywhere(cmd.root, file))
+            unreferenced.push(file);
+    }
+    const framework = chooseFramework(detectFrameworks(cmd.root), undefined, false) ?? detectFrameworks(cmd.root)[0] ?? null;
+    const picked = pick({ changed, tests: candidates, reaching, browserTests: Boolean(framework?.browser), noHistory, unreferenced });
+    const command = oneCommand(cmd.root, picked, framework);
+    return { picked, total: candidates.length, command, noHistory };
+}
+export function runPick(cmd) {
+    const chosen = choose(cmd);
+    if (!chosen)
+        throw new Error(`could not read the change "${cmd.diff}". Is this a git checkout, and does that range exist? (try --diff main...HEAD)`);
+    if (cmd.list) {
+        // For piping into a runner: the files, and nothing else. A run-everything decision prints nothing,
+        // so a script that pipes this cannot mistake "cannot narrow" for "no tests to run".
+        if (chosen.picked.runEverything) {
+            console.error(`tewip pick: ${chosen.picked.runEverything}. Run the whole suite.`);
+            process.exitCode = 2;
+            return;
+        }
+        for (const must of chosen.picked.mustRun)
+            console.log(must.testFile);
+        return;
+    }
+    const report = renderPick(chosen.picked, chosen.total, chosen.command, chosen.noHistory);
+    console.log(report);
+    if (cmd.out) {
+        mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+        writeFileSync(resolve(cmd.out), report + String.fromCharCode(10), 'utf8');
+    }
+}

package/dist/engine/pick/pick.js

@@ -0,0 +1,117 @@
+/** A changed file that can affect anything, so no test can be ruled out because of it. */
+const GLOBAL = [
+    { match: /(^|\/)(package|package-lock|yarn|pnpm-lock|bun\.lock|requirements|pyproject|poetry\.lock|go\.mod|go\.sum|pom\.xml|build\.gradle|Gemfile|composer\.json|Cargo\.toml)/i, why: 'it changes the dependencies, which every test runs against' },
+    { match: /(^|\/)(\.github|\.gitlab-ci|Jenkinsfile|azure-pipelines|\.circleci|Dockerfile|docker-compose|Makefile)/i, why: 'it changes how the suite is built or run' },
+    { match: /(^|\/)(jest|vitest|playwright|cypress|karma|babel|tsconfig|webpack|vite|rollup|eslint|tox|pytest|conftest)\b[\w.]*\.(json|js|ts|cjs|mjs|ini|cfg|toml|yaml|yml)$/i, why: 'it is test or build configuration, which applies to the whole suite' },
+    { match: /(^|\/)(conftest\.py|setup\.(js|ts|py)|global-setup\.[jt]s|jest\.setup\.[jt]s|test-setup\.[jt]s)$/i, why: 'it is shared setup, which runs before every test' },
+    { match: /(^|\/)(fixtures?|helpers?|support|mocks?|__mocks__|testdata|factories)\//i, why: 'it is shared test support, which any test may use' },
+];
+const SOURCE = /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts|py|java|kt|go|cs|rb|php|vue|svelte|scala|swift)$/i;
+const IS_TEST = /(^|\/)(tests?|spec|specs|__tests__|e2e)\/|[._-](test|tests|spec|specs)\.[a-z]+$|(^|\/)test_[^/]+\.py$|_test\.(go|py|rb)$|Tests?\.(java|kt|cs)$/i;
+/** Documentation and assets: a test cannot notice these, so they never widen the run. */
+const INERT = /\.(md|mdx|txt|rst|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|eot|mp4|pdf|lock|csv)$|(^|\/)(LICENSE|CODEOWNERS|\.gitignore|\.editorconfig|\.prettierrc)/i;
+export function pick(input) {
+    // Global first, then inert. The other order called `requirements.txt` documentation because of its
+    // extension and then reported that a dependency change could not affect any test.
+    const changed = input.changed.filter((f) => GLOBAL.some((g) => g.match.test(f)) || !INERT.test(f));
+    const picked = { mustRun: [], skipped: [], runEverything: '', opaque: [] };
+    if (changed.length === 0) {
+        return { ...picked, runEverything: 'nothing in this change can affect a test result - only documentation, assets or lockless files were touched. Running nothing is also an option.' };
+    }
+    // Anything global stops selection outright, and names the file that did it.
+    for (const file of changed) {
+        const global = GLOBAL.find((g) => g.match.test(file));
+        if (global)
+            return { ...picked, runEverything: `${file} cannot be narrowed around: ${global.why}` };
+    }
+    const changedSource = changed.filter((f) => SOURCE.test(f) && !IS_TEST.test(f));
+    const changedTests = changed.filter((f) => IS_TEST.test(f));
+    // A changed file nothing can be traced from. For a browser suite this is the normal case rather than a
+    // gap - the test reaches the code through the running application - so the honest answer is to run
+    // everything and say why, not to claim the tests are unrelated.
+    // A file no test imports may still be reachable in a way imports do not show. But a file that nothing
+    // in the project refers to **at all** - not imported, not named in any source or test - cannot be
+    // noticed by any test, and treating that as "cannot tell" made the command useless: in this very
+    // repository a change to the command-line dispatcher, which tests only read as text, forced the whole
+    // suite. So the two cases are separated, and only a genuine unknown stops selection.
+    picked.opaque = changedSource.filter((f) => (input.reaching.get(f) ?? []).length === 0 && !input.unreferenced.includes(f));
+    if (picked.opaque.length > 0) {
+        return {
+            ...picked,
+            runEverything: input.browserTests
+                ? `these tests drive a browser, so what a test exercises is not written in its imports: ${picked.opaque.slice(0, 3).join(', ')} cannot be traced to any test, and skipping on that basis would be a guess`
+                : `no test can be traced to ${picked.opaque.slice(0, 3).join(', ')}${picked.opaque.length > 3 ? ` and ${picked.opaque.length - 3} more` : ''}. Tewip will not take that as proof the suite is unaffected - code can be reached in ways an import does not show (dependency injection, a plugin registry, a dynamic import)`,
+        };
+    }
+    const why = new Map();
+    const add = (testFile, reason) => {
+        if (!why.has(testFile))
+            why.set(testFile, reason);
+    };
+    // A test the change itself edited always runs: whatever it now checks, nobody has seen it run yet.
+    for (const file of changedTests)
+        add(file, 'this change edits it');
+    for (const [file, reaches] of input.reaching) {
+        if (!changedSource.includes(file))
+            continue;
+        for (const reach of reaches)
+            add(reach.testFile, `it ${reach.how} ${file}`);
+    }
+    // A test that walks the repository can be broken by any file in it, so it always runs.
+    for (const test of input.tests) {
+        if (test.readsTheRepo)
+            add(test.testFile, 'it reads the repository itself, so any changed file can break it');
+    }
+    // An unknown is not a skip. A test that has been failing or flaking lately gets another run, because
+    // "it is unrelated to this change" and "it is broken for another reason" are different statements and
+    // only the first is a reason to skip.
+    for (const test of input.tests) {
+        if (test.recentlyFailed.length > 0)
+            add(test.testFile, `it failed recently (${test.recentlyFailed.length} time(s)), so its state is unknown rather than unrelated`);
+    }
+    picked.mustRun = [...why.entries()].map(([testFile, reason]) => ({ testFile, why: reason })).sort((a, b) => a.testFile.localeCompare(b.testFile));
+    picked.skipped = input.tests
+        .filter((t) => !why.has(t.testFile))
+        .map((t) => ({ testFile: t.testFile, why: 'nothing it imports, directly or through another module, reaches anything this change touched' }))
+        .sort((a, b) => a.testFile.localeCompare(b.testFile));
+    if (picked.mustRun.length === 0) {
+        return {
+            ...picked,
+            runEverything: `nothing in this project refers to ${changed.slice(0, 3).join(', ')}, so no test can notice the change. Running nothing is defensible; running the suite costs nothing but time.`,
+        };
+    }
+    // Selecting everything is not a failure, but it should be said plainly rather than dressed up as a saving.
+    if (picked.skipped.length === 0 && picked.mustRun.length > 0) {
+        picked.runEverything = 'every test in the project reaches something this change touched, so there is nothing to skip';
+    }
+    if (input.noHistory && picked.skipped.length > 0) {
+        picked.runEverything = picked.runEverything || '';
+    }
+    return picked;
+}
+/** What the selection is worth, and what it rests on. */
+export function renderPick(picked, total, command, noHistory) {
+    const lines = ['# Which tests could notice this change?', ''];
+    if (picked.runEverything) {
+        lines.push(`**Run the whole suite.** ${picked.runEverything}.`, '', 'Tewip narrows a test run only when it can show that the tests it leaves out could not have noticed', 'the change. It cannot show that here, so it is not asking you to take the risk.', '');
+        if (picked.opaque.length > 0) {
+            lines.push('Changed files nothing could be traced from:', '', ...picked.opaque.slice(0, 10).map((f) => `- ${f}`), '');
+        }
+        return lines.concat(tail(noHistory)).join(String.fromCharCode(10));
+    }
+    const kept = picked.mustRun.length;
+    const share = total > 0 ? Math.round((kept / total) * 100) : 100;
+    lines.push(`**${kept} of ${total} test file(s)** could notice it - ${share}% of the suite. ${picked.skipped.length} can be left out.`, '', '```', command, '```', '', `## Why these ${kept} run`, '', ...picked.mustRun.slice(0, 30).map((m) => `- \`${m.testFile}\` — ${m.why}`), ...(picked.mustRun.length > 30 ? [`- …and ${picked.mustRun.length - 30} more`] : []), '', `## What you are giving up (${picked.skipped.length})`, '', 'Each of these is left out because of a fact about the source, not a prediction:', '', ...picked.skipped.slice(0, 15).map((s) => `- \`${s.testFile}\``), ...(picked.skipped.length > 15 ? [`- …and ${picked.skipped.length - 15} more`] : []), '');
+    return lines.concat(tail(noHistory)).join(String.fromCharCode(10));
+}
+const tail = (noHistory) => [
+    '---',
+    '',
+    'How this decides: a test runs when it imports a changed file, or reaches one through another module,',
+    'or when the change edits the test itself, or when it has failed recently - an unknown is never a skip.',
+    'It runs everything when the change touches dependencies, build or test configuration, shared setup or',
+    'shared fixtures, or when a changed file cannot be traced to any test at all. No model is called.',
+    ...(noHistory
+        ? ['', 'This project keeps no run history, so "it has not failed lately" could not be checked for any test.', 'Run `tewip explain` on your CI reports and the next selection will know more.']
+        : []),
+];

package/dist/engine/prove/mutants.js

@@ -24,10 +24,14 @@ const NOT_BEHAVIOUR = /^\s*(\/\/|#|\*|\/\*|@|import\b|from\b|export\s+(type|inte
  * sign the wrong way round, a flag returned the wrong way.
  */
 const OPERATORS = [
-    { kind: 'a boundary moved by one', find: /(?<![<>=!])<=(?!=)/, swap: () => '<' },
-    { kind: 'a boundary moved by one', find: /(?<![<>=!])>=(?!=)/, swap: () => '>' },
-    { kind: 'a boundary moved by one', find: /(?<![<>=!+-])<(?![<=])/, swap: () => '<=' },
-    { kind: 'a boundary moved by one', find: /(?<![<>=!+-])>(?![>=])/, swap: () => '>=' },
+    // Whitespace on both sides, which is what separates a comparison from a generic type. Without it,
+    // `Array<{ id: string }>` was read as a comparison and mutated into `Array<={ … }>`: the file stopped
+    // compiling, the whole suite failed to load, and the measurement counted a mutant nothing caught.
+    // A codebase that writes `a<b` loses a few mutants; one that breaks its build loses the answer.
+    { kind: 'a boundary moved by one', find: /(?<=\s)<=(?=\s)/, swap: () => '<' },
+    { kind: 'a boundary moved by one', find: /(?<=\s)>=(?=\s)/, swap: () => '>' },
+    { kind: 'a boundary moved by one', find: /(?<=\s)<(?=\s)/, swap: () => '<=' },
+    { kind: 'a boundary moved by one', find: /(?<=\s)>(?=\s)/, swap: () => '>=' },
     { kind: 'a comparison inverted', find: /===/, swap: () => '!==' },
     { kind: 'a comparison inverted', find: /(?<![!=<>])==(?!=)/, swap: () => '!=' },
     { kind: 'a comparison inverted', find: /!==/, swap: () => '===' },

package/dist/engine/prove/prove.js

@@ -80,10 +80,11 @@ export function proveFile(root, file, covering, framework, opts = {}) {
         return finish(proof, started);
     }
     const original = readFileSync(full, 'utf8');
+    const stopGuarding = guardAgainstBeingKilled(full, original);
     const mutants = mutantsFor(original, limit);
     if (mutants.length === 0) {
         proof.blocked = 'nothing in this file could be changed in a way a test should be expected to catch - no comparison, no condition, no returned value outside of strings and comments';
-        return finish(proof, started);
+        return finish(proof, started, stopGuarding);
     }
     // A test has to pass before it can be asked to notice anything, or a red suite turns into "your
     // tests catch nothing", which is the worst kind of lie this command could tell.
@@ -103,7 +104,7 @@ export function proveFile(root, file, covering, framework, opts = {}) {
     }
     if (usable.length === 0) {
         proof.blocked = `none of the ${covering.length} test file(s) covering this pass as they are, so none can be asked whether they would notice a change. Fix the run first.`;
-        return finish(proof, started);
+        return finish(proof, started, stopGuarding);
     }
     proof.covering = usable;
     // The control: break the file outright and check that a covering test notices. Without this, a file
@@ -111,7 +112,7 @@ export function proveFile(root, file, covering, framework, opts = {}) {
     say('checking the tests really load this file');
     if (!testsLoadIt(root, full, original, usable[0], framework, runMs)) {
         proof.blocked = `${usable[0]} passes even when this file is made unusable, so the tests are not loading the file that was edited - they are reading an installed copy or a build output. Nothing here can be proved until they run against this source (for a Python src layout, install it in editable mode: pip install -e .).`;
-        return finish(proof, started);
+        return finish(proof, started, stopGuarding);
     }
     // Only the tests that pass may judge a mutant. A test that is already failing fails for every
     // change too, which would have it "catch" everything - the exact false confidence this command
@@ -156,7 +157,7 @@ export function proveFile(root, file, covering, framework, opts = {}) {
         }
         proof.tried.push({ mutant, fate, noticedBy, seconds: Math.round((Date.now() - at) / 100) / 10 });
     }
-    return finish(proof, started);
+    return finish(proof, started, stopGuarding);
 }
 /**
  * Puts the file back and checks that it really went back. Anything less would mean this command can
@@ -168,7 +169,43 @@ function restore(full, original) {
         throw new Error(`${full} could not be put back as it was. Check it before doing anything else: git checkout -- "${full}"`);
     }
 }
-const finish = (proof, started) => ({ ...proof, seconds: Math.round((Date.now() - started) / 1000) });
+/**
+ * Put the file back even when the process is killed.
+ *
+ * `finally` does not run for SIGINT or SIGTERM, so a developer pressing Ctrl-C during a run - which they
+ * will, because this is the slow command - was left with a mutated source file and no idea why their
+ * code had stopped working. Found by killing one of these runs during development and finding a flipped
+ * comparison still sitting in the repository.
+ */
+function guardAgainstBeingKilled(full, original) {
+    const putBack = (signal) => () => {
+        try {
+            restore(full, original);
+            process.stderr.write(`${String.fromCharCode(10)}${signal}: ${full} was put back as it was.${String.fromCharCode(10)}`);
+        }
+        catch {
+            process.stderr.write(`${String.fromCharCode(10)}${signal}: could not put ${full} back. Run: git checkout -- "${full}"${String.fromCharCode(10)}`);
+        }
+        process.exit(130);
+    };
+    const handlers = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK'].map((signal) => [signal, putBack(signal)]);
+    for (const [signal, handler] of handlers) {
+        try {
+            process.on(signal, handler);
+        }
+        catch {
+            // Not every signal exists on every platform.
+        }
+    }
+    return () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+    };
+}
+const finish = (proof, started, stopGuarding) => {
+    stopGuarding?.();
+    return { ...proof, seconds: Math.round((Date.now() - started) / 1000) };
+};
 const firstLine = (output) => output.split(String.fromCharCode(10)).map((l) => l.trim()).find(Boolean)?.slice(0, 160) ?? '';
 /** Which of the tests that cover a file really import it, and so could notice a change. */
 export function importingTests(root, coverage, file) {

package/dist/engine/prove/reaches.js

@@ -9,7 +9,7 @@
 // The chain is followed outwards from the file, not inwards from the tests, because the answer needed
 // is "who would notice if this changed" and that is what a reverse import graph gives.
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { importNames, importsIt } from '../review/coverage.js';
 const SKIP_DIR = new Set(['node_modules', '.git', 'dist', 'build', 'out', 'coverage', 'target', 'vendor', '__pycache__', '.venv', 'venv', '.tewip', '.next']);
 const SOURCE = /\.(?:[cm]?[jt]sx?|py|go|java|kt|cs|rb)$/i;
@@ -46,6 +46,116 @@ function sourceFiles(root, limit = 6000) {
     walk(root);
     return out;
 }
+/**
+ * The package's front door: the files a test means when it writes `require('..')`.
+ *
+ * This matters for selection and nothing else. express's tests all do `require('..')`, which resolves
+ * through `index.js` to `lib/express.js` and from there to every part of the library - so a change to
+ * `lib/response.js` really is reachable from almost every test in the project. Without this, selection
+ * followed the chain as far as `index.js`, found that no test imports *that* by name, and cheerfully
+ * declared 86 of express's 88 test files unaffected by a change to the response code.
+ */
+function frontDoor(root) {
+    const files = new Set();
+    try {
+        const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+        if (manifest.main)
+            files.add(resolve(root, manifest.main));
+    }
+    catch {
+        // No manifest: the conventional entry points below still apply.
+    }
+    for (const entry of ['index.js', 'index.ts', 'index.mjs', 'index.cjs', 'index.tsx', '__init__.py', 'src/index.js', 'src/index.ts']) {
+        if (existsSync(resolve(root, entry)))
+            files.add(resolve(root, entry));
+    }
+    return files;
+}
+/** Every path this file imports, as written. */
+const importedPaths = (text) => [...text.matchAll(/(?:from|require\s*\(|import)\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+/**
+ * Does this file import the package's front door?
+ *
+ * Decided by **resolving** each import against the file's own directory, not by recognising spellings.
+ * Guessing at spellings had already missed one: express's `test/res.status.js` imports `require('../.')`,
+ * which is the package root written a slightly unusual way, and the selection declared that file
+ * unaffected by a change to the very module `res.status` lives in. A false skip is the one failure this
+ * command must not have, so the question is answered by path resolution, which cannot be spelled around.
+ */
+function importsFrontDoor(root, file, text, doors) {
+    const here = dirname(resolve(root, file));
+    for (const spec of importedPaths(text)) {
+        if (!spec.startsWith('.'))
+            continue;
+        const target = resolve(here, spec);
+        if (target === resolve(root))
+            return true; // the package root itself
+        for (const ending of ['', '.js', '.ts', '.mjs', '.cjs', '.tsx', '/index.js', '/index.ts', '/index.mjs', '/index.cjs', '/index.tsx', '/__init__.py']) {
+            if (doors.has(resolve(`${target}${ending}`)))
+                return true;
+        }
+    }
+    return false;
+}
+export function allTestsReaching(root, file, tests, depth = 6) {
+    const all = sourceFiles(root);
+    const text = new Map();
+    const read = (path) => {
+        if (!text.has(path)) {
+            try {
+                text.set(path, readFileSync(path, 'utf8'));
+            }
+            catch {
+                text.set(path, '');
+            }
+        }
+        return text.get(path);
+    };
+    const rel = (path) => relative(root, path).split(String.fromCharCode(92)).join('/');
+    const testSet = new Set(tests.map((t) => rel(resolve(root, t))));
+    const found = new Map();
+    const seen = new Set([rel(resolve(root, file))]);
+    const doors = frontDoor(root);
+    let layer = [file];
+    for (let step = 1; step <= depth && layer.length > 0; step += 1) {
+        // Reached the package's own entry point. Everything that imports the package now reaches the change -
+        // and that includes modules, not only tests: express's acceptance tests import an example app, which
+        // imports the package, so stopping at tests here left nineteen of them looking unaffected.
+        if (layer.some((f) => doors.has(resolve(root, f)))) {
+            const throughDoor = [];
+            for (const path of all) {
+                const where = rel(path);
+                if (seen.has(where) || !importsFrontDoor(root, where, read(path), doors))
+                    continue;
+                seen.add(where);
+                if (testSet.has(where))
+                    found.set(where, { testFile: where, steps: step, via: 'the package itself' });
+                else
+                    throughDoor.push(where);
+            }
+            layer = [...layer, ...throughDoor];
+        }
+        const names = layer.flatMap((f) => (existsSync(resolve(root, f)) ? importNames(root, f) : []));
+        if (names.length === 0)
+            break;
+        const next = [];
+        for (const path of all) {
+            const where = rel(path);
+            if (seen.has(where))
+                continue;
+            if (!importsIt(read(path), names))
+                continue;
+            seen.add(where);
+            if (testSet.has(where))
+                found.set(where, { testFile: where, steps: step, via: layer[0] });
+            // A module that imports the change is itself a way in, whether or not it is a test, so the walk
+            // continues through it. This is what reaches a test that only imports the package front door.
+            next.push(where);
+        }
+        layer = next;
+    }
+    return [...found.values()];
+}
 /**
  * The tests that reach `file`, directly or through up to `depth` modules.
  *

package/dist/mcp/server.js

@@ -176,4 +176,25 @@ server.registerTool('is_the_work_done', {
         return `Nothing changed in ${range}, or that range could not be read here.`;
     return renderDecision(range, decide(gathered.evidence));
 }));
+server.registerTool('which_tests_to_run', {
+    title: 'Which tests could notice this change?',
+    description: "Narrows a test run to the tests that could notice a change, from facts in the source rather than a prediction: a test runs when it imports a changed file, reaches one through another module, is itself edited by the change, reads the repository at run time, or has failed recently. It refuses to narrow at all - and says why - when the change touches dependencies, build or test configuration, shared setup or fixtures, when the suite drives a browser, or when a changed file cannot be traced to any test. Use it to run the right tests quickly; what it leaves out, it leaves out for a stated reason.",
+    inputSchema: {
+        project,
+        diff: z.string().optional().describe('A git range, e.g. main...HEAD (the default)'),
+        files: z.array(z.string()).optional().describe('The changed files, when they do not come from a git range'),
+    },
+    annotations: readOnly,
+}, ({ project: root, diff, files }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    // choose/renderPick are pure; runPick prints, which would corrupt the protocol.
+    const { choose } = await import('../engine/pick/pick-command.js');
+    const { renderPick } = await import('../engine/pick/pick.js');
+    const range = diff ?? 'main...HEAD';
+    const chosen = choose({ root, diff: range, files });
+    if (!chosen)
+        return `Nothing changed in ${range}, or that range could not be read here.`;
+    return renderPick(chosen.picked, chosen.total, chosen.command, chosen.noHistory);
+}));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",