tewip-ai 0.29.0 → 0.31.0

package/README.md

@@ -552,6 +552,104 @@ 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.
 
+## What will this migration do to a live database? (Phase 26)
+
+```bash
+tewip schema --diff main...HEAD      # or: tewip schema migrations/0002_drop_nickname.sql
+tewip schema --strict                # fails the build on a change that breaks the running version
+```
+
+The most expensive change in a pull request is usually not a test — it is a migration. A column dropped
+while the previous deployment is still selecting it. An index built without `CONCURRENTLY`, blocking every
+write to the busiest table. A `NOT NULL` added to a populated table. These are known, documented, and a
+tool can name every one of them from the text of the migration.
+
+```
+1 of 1 migration file(s) read. 1 change(s) would break the running version or destroy data
+
+## Breaks the version that is still running (1)
+- drops the column nickname from orders — migrations/0002_drop_nickname.sql:1
+  - Instead: deploy code that no longer selects or writes the column, then drop it in a later
+    migration. During a rolling deploy the old version is still running and will fail on a column
+    that is gone
+
+## Code that still uses what this takes away (1)
+- orders.nickname is still named in 1 file(s): app/orders.py
+```
+
+That last section is the part no SQL linter does: it searches your own code for what the migration takes
+away. "This drops `users.nickname`, and four files still read it" is a different sentence from "dropping a
+column is risky", and it is the one that stops the outage.
+
+It reads **SQL, Django, Rails and Alembic** migrations, judges **only the forward path** (a rollback step
+contains the mirror image of the change, so reading it says a migration that creates a table destroys
+one), and stays quiet when the team already did the safe thing — `atomic = False`, `algorithm:
+:concurrently`, `NOT VALID`, `postgresql_concurrently=True`. When it cannot read a migration it says so
+rather than passing it, and "read and nothing found" never looks like "not read".
+
+**Tried on real projects.** 200 Zulip migrations: 199 read, 19 changes that break the running version or
+destroy data, each sampled finding correct when read against the file — including a `DROP COLUMN` buried
+in raw SQL inside a Python data migration. 60 Mastodon migrations: it caught a `change_column` that
+rewrites a table, in a migration whose *name* says it only adds one.
+
+What it does not know, and says so: your table sizes and how busy the database is, so it reports what a
+statement **does** — rewrites the table, scans every row, blocks writes — and leaves the duration to the
+person who knows the data. In CI the findings go into the pull request comment, and anything that breaks
+the running version enters the evidence bundle as a refusal: a passing test suite does not verify a
+migration.
+
+## 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.
+
+**In CI**, `mode: pick` runs before your tests and hands the workflow the files to run:
+
+```yaml
+- id: pick
+  uses: hmamut39/tewip@main
+  with: { mode: pick }        # needs fetch-depth: 0 on actions/checkout
+- run: npx jest ${{ steps.pick.outputs.tests }}
+  if: steps.pick.outputs.narrowed == 'true'
+- run: npx jest
+  if: steps.pick.outputs.narrowed != 'true'
+```
+
+Whatever it leaves out is written into the job summary with the reason beside it, so "why did CI not run
+that test" is answered by the run itself. When it will not narrow safely, `narrowed` is `false` and
+`tests` is empty - so a workflow that ignores the flag still runs everything, which is the safe default.
+
 ## Would your tests catch a bug? (Phase 23)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,22 @@ 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 schema [<files>] [--diff main...HEAD] [--strict] [--out schema.md]
+                                    What will this migration do to a live database? Names the changes
+                                    that break the version still running during a deploy, destroy data,
+                                    block writes while they run, or cannot be undone - and searches your
+                                    code for what still uses the column it takes away. Reads SQL, Django,
+                                    Rails and Alembic migrations, and says so when it cannot read one.
+                                    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,30 @@ async function main() {
             });
             return;
         }
+        case 'schema': {
+            const { runSchema } = await import('../engine/schema/schema-command.js');
+            runSchema({
+                root: process.cwd(),
+                diff: flag(args, 'diff') ?? 'main...HEAD',
+                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out'),
+                out: flag(args, 'out'),
+                strict: args.includes('--strict'),
+            });
+            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) {