tewip-ai 0.25.0 → 0.27.0

package/README.md

@@ -71,6 +71,13 @@ On every run, the action:
 - **Developers:** posts one diagnosis comment on the pull request and keeps it updated. For each failure it says whether the change likely caused it, why, and what to do next.
 - **SDETs:** writes the triage board into the job summary.
 - **DevOps:** collects environment failures (server errors, connection resets, outages) in **one** GitHub issue, and each new run adds a single grouped comment to it.
+- **The tests in the pull request:** on a PR it reads the test files the change touched and says which
+  of them could never fail - an unfinished expectation, a value compared with itself, a test that
+  discards its own failure, one that never runs. It says nothing when they are all sound, and it says
+  it **even on a green run**, because "all tests passed" is the exact sentence that needs qualifying
+  when one of them cannot fail. Needs `fetch-depth: 0` on `actions/checkout` so the diff can be read;
+  without it the section is skipped rather than guessed at. Any such test also enters the attestation
+  as a refusal, so a release decision taken from the bundle cannot rest on a test that proves nothing.
 - **Evidence, every run:** the Action writes an attestation into its artifact - the claims with
   their evidence and which layer decided each, what Tewip **refused** to decide, and what it did
   not check at all. Nothing enters it that Tewip did not verify itself, so a release decision can
@@ -496,6 +503,89 @@ Joins the test plans Tewip wrote to the tests that cover them and the runs that
 scenario counts as covered only when a real test can be named, and passing only when a real run
 attempted it; everything else says what is missing. No model, no cost.
 
+## Would your tests catch a bug? (Phase 23)
+
+```bash
+tewip prove src/pricing.js              # or --diff main...HEAD for what a change touched
+tewip prove src/pricing.js --strict     # exits non-zero when something goes unnoticed
+```
+
+Coverage says a line ran. It does not say anybody checked it. `prove` settles that by **execution**:
+it breaks your code in small, deliberate ways - a boundary moved by one, a condition inverted, an
+`and` that became an `or`, a returned flag flipped, a pattern loosened - runs the tests that reach
+that file, and reports every change **none of them noticed**.
+
+```
+4 change(s) were made to your code and the covering tests were run against each. 3 went unnoticed.
+
+- line 2: a boundary moved by one
+  - was:    if (total >= 100 && isMember) return 0.2;
+  - became: if (total > 100 && isMember) return 0.2;
+- line 9: a sign reversed
+  - was:    return total - total * off;
+  - became: return total + total * off;
+```
+
+Both of those are real: the tests used 150 and 10 and never the boundary itself, and the test calling
+`finalPrice` asserted nothing at all. Neither gap is visible in a coverage report, because both lines
+were covered.
+
+It refuses more often than it reports, and the refusals are the reason the reports are worth reading:
+
+- **Your file is put back exactly as it was**, byte for byte, line endings included, in a `finally` -
+  and the restore is verified, not assumed. A restore that did not work is an error, not a shrug.
+- **Nothing that can hang is touched.** Loop headers are never changed: a flipped comparison in a
+  `while` does not fail a test, it runs forever.
+- **A red suite proves nothing.** Every covering test is run untouched first. Ones that do not pass are
+  set aside by name, and if none pass, it says so and stops - a test that was already failing would
+  otherwise appear to "catch" every change.
+- **It checks that your tests actually load the file.** If breaking the file outright does not fail a
+  single test, they are reading an installed copy or a build output, and it says that instead of
+  reporting a page of holes that do not exist. This caught a real case on the first Python project it
+  met, where `import humanize` resolved to a different checkout entirely.
+- **Strings and comments are never changed**, because changing a message is not a bug a test should be
+  expected to catch.
+
+It follows imports, so a file reached *through* another module is still proved - in a layered codebase
+that is most of them. It needs a unit test framework (jest, vitest, mocha, `node --test`, pytest, go
+test, maven, gradle, dotnet), calls no model, and costs nothing but time. It is also an MCP tool, so a
+coding agent can ask whether the tests it is relying on would have stopped its own mistake.
+
+## Could these tests ever fail? (Phase 22)
+
+```bash
+tewip vouch tests/            # or a file, or the whole project
+tewip vouch tests/ --strict   # exits non-zero, for a merge gate
+```
+
+Most tests in a pull request are now written by an agent, and the question that decides whether they
+are worth anything goes unasked: **could this test ever fail?** Coverage counts a test that checks
+nothing. CI goes green on it. A reviewer skims something plausible and approves it.
+
+`vouch` reads tests somebody else wrote and answers per test, quoting the line it rests on. It finds
+tests that leave an expectation unfinished (`expect(value);` with no matcher - it reads exactly like a
+check), tests that compare a value with itself, tests that catch and discard their own failure, tests
+that never run, and tests that compare no value at all. No model, no cost.
+
+It is also an MCP tool, so a coding agent can ask about the tests it just wrote before claiming a
+change is covered.
+
+**Measured on 5,448 tests in 8 public projects across 5 languages** (express, axios, chalk, requests,
+click, gorilla/mux, cobra, gson): 19 tests were called unable to fail, and **all 19 were correct** when
+read against the files - one unconditional skip in psf/requests, eighteen `@Ignore` methods in gson.
+
+Two things it refuses to do, which is why the list is worth reading:
+
+- **It will not guess.** A test whose checking happens inside a helper it cannot follow is reported as
+  undecided, by name, never as worthless. A wrong accusation about somebody's test costs more than a
+  missed one.
+- **It will not overclaim.** A test with no assertion still fails when the code throws - in axios, a
+  test that compiles a TypeScript fixture and runs it asserts nothing *on purpose*. Those are reported
+  separately as "compares no value", not as broken, and they do not trip `--strict`.
+
+Honest limit, also printed at the bottom of every report: its **recall is unmeasured**. A clean report
+means nothing it found was wrong, not that every test in the file is worth something.
+
 ## A goal instead of a verb (Phases 19 and 21)
 
 ```bash
@@ -505,8 +595,9 @@ tewip pursue "keep the checkout flow green" --act
 
 Give Tewip a goal and it says what it would do next, and why, from what it can actually see. The
 order is fixed, published and testable - **not chosen by a model**: a real bug first, then the
-environment, then flakiness, then anything failing it cannot explain, then a coverage gap, and only
-then is the goal worth attesting. Deciding the same state twice gives the same answer.
+environment, then flakiness, then anything failing it cannot explain, then a test that cannot fail,
+then a coverage gap, and only then is the goal worth attesting. Deciding the same state twice gives
+the same answer.
 
 With `--act` it carries the decision out, and this is where the refusals matter most:
 

package/dist/cli/help.js

@@ -105,11 +105,28 @@ Usage:
                                     green" - and it says what it would do next and why, from what
                                     it can actually see. The order is fixed and written down: a
                                     real bug first, then the environment, then flakiness, then a
-                                    coverage gap. It decides; it does not act unless you ask. With
+                                    test that cannot fail, then a coverage gap. It decides; it does
+                                    not act unless you ask. With
                                     --act it carries out the two safe ones - writing a missing test,
                                     or attesting a green goal - by running the command that already
                                     proves them. It will not touch a real bug, and it writes what it
                                     did or refused to .tewip/actions.jsonl.
+  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,
+                                    an and that became an or - runs the tests that import that file,
+                                    and reports every change nobody noticed. The line was covered; it
+                                    was not checked, and no coverage number can tell you that. Every
+                                    file is put back exactly as it was. Slow by nature, and it needs
+                                    a unit test framework. No model, no cost.
+  tewip vouch [<paths>] [--strict] [--out vouch.md] [--json vouch.json]
+                                    Could these tests ever fail? Reads tests somebody else wrote -
+                                    an agent, a contractor, last year's team - and names the ones
+                                    that check nothing, compare a value with itself, leave an
+                                    expectation unfinished, swallow their own failure, or never run.
+                                    Where the checking is in a helper it cannot follow it says so
+                                    instead of accusing. --strict exits non-zero on a finding, for a
+                                    gate. No model, no cost.
   tewip trace [--only "<ticket or title>"] [--out trace.md]
                                     Is this requirement covered, and is it passing right now? Joins
                                     the plans Tewip wrote to the tests that cover them and the runs

package/dist/cli/tewip.js

@@ -185,6 +185,26 @@ async function main() {
             runPursue({ root: process.cwd(), goal, act: args.includes('--act'), name: flag(args, 'name'), out: flag(args, 'out') });
             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');
+            runProve({
+                root: process.cwd(),
+                files: paths,
+                diff: flag(args, 'diff'),
+                limit: Number(flag(args, 'limit') ?? '6'),
+                budgetSeconds: Number(flag(args, 'budget') ?? '600'),
+                out: flag(args, 'out'),
+                strict: args.includes('--strict'),
+            });
+            return;
+        }
+        case 'vouch': {
+            const paths = args.filter((a, i) => !a.startsWith('--') && !['--out', '--json'].includes(args[i - 1] ?? ''));
+            const { runVouch } = await import('../engine/vouch/run-vouch.js');
+            runVouch({ root: process.cwd(), paths: paths.length > 0 ? paths : ['.'], out: flag(args, 'out'), json: flag(args, 'json'), strict: args.includes('--strict') });
+            return;
+        }
         case 'trace': {
             const { runTrace } = await import('../engine/trace/trace-command.js');
             runTrace({ root: process.cwd(), only: flag(args, 'only'), name: flag(args, 'name'), out: flag(args, 'out') });

package/dist/engine/attest/attest.js

@@ -11,9 +11,12 @@ function evidenceOf(record) {
  * The bundle for one run. `records` and `run` are what Tewip itself wrote when it read the report,
  * so everything here is traceable; nothing is inferred and nothing is re-judged.
  */
-export function attestRun(project, run, records, { checked, notChecked, tool, engine }) {
+export function attestRun(project, run, records, { checked, notChecked, tool, engine, refusals: given = [], }) {
     const claims = [];
-    const refusals = [];
+    // Refusals the caller already established - a test in this change that cannot fail, for instance -
+    // belong here beside the ones the records produce. They are the same kind of statement: something
+    // this bundle will not vouch for.
+    const refusals = [...given];
     for (const record of records) {
         const diagnosis = record.diagnosis;
         const category = diagnosis?.category ?? 'UNKNOWN';

package/dist/engine/prove/mutants.js

@@ -0,0 +1,148 @@
+// Phase 23: small, deliberate breakages of real code, to find out what the tests would not notice.
+//
+// `vouch` reads a test and says whether it *could* fail. This asks the harder question, and answers
+// it by execution rather than by reading: break the code the test covers, run the test, and see. A
+// change nobody notices is a hole in the suite that no coverage percentage will ever show, because
+// the line was covered - it just was not checked.
+//
+// Three rules shape what may be changed, and all three exist to keep the answer trustworthy:
+//
+// 1. **Only code.** Strings and comments are skipped, reusing the same mask `vouch` uses. Changing a
+//    word in a message is not a bug a test should be expected to catch.
+// 2. **Nothing that can hang.** Loop headers are never touched. A flipped comparison in a `while`
+//    condition does not fail a test, it runs forever, and a tool that hangs a developer's machine
+//    gets uninstalled. This is the same lesson as the fork bomb in Phase 21, learned once.
+// 3. **One change at a time**, always restored. A mutant is a question, not an edit.
+import { textRanges } from '../vouch/tests-in.js';
+/** A line that could loop: never touched, because a wrong comparison there hangs instead of failing. */
+const COULD_LOOP = /\b(for|while|do|loop|repeat|until)\b\s*[({:]|\bfor\b.*\bin\b|\.\s*(forEach|map|filter|reduce|while)\s*\(/;
+/** A line that only reports, logs or types: changing it says nothing about behaviour. */
+const NOT_BEHAVIOUR = /^\s*(\/\/|#|\*|\/\*|@|import\b|from\b|export\s+(type|interface)\b|use\s|package\b|using\b|require\b|const\s+\w+\s*=\s*require)|console\s*\.|print\s*\(|println|log(ger)?\s*\.|process\.(stdout|stderr)|fmt\s*\.\s*Print/;
+/**
+ * The changes worth making, in the order they are worth making them. Each is a mistake a person or an
+ * agent really makes: a boundary off by one, a condition inverted, an `and` that should be an `or`, a
+ * 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: () => '>=' },
+    { kind: 'a comparison inverted', find: /===/, swap: () => '!==' },
+    { kind: 'a comparison inverted', find: /(?<![!=<>])==(?!=)/, swap: () => '!=' },
+    { kind: 'a comparison inverted', find: /!==/, swap: () => '===' },
+    { kind: 'a comparison inverted', find: /(?<![!=<>])!=(?!=)/, swap: () => '==' },
+    { kind: 'an "and" that became an "or"', find: /&&/, swap: () => '||' },
+    { kind: 'an "or" that became an "and"', find: /\|\|/, swap: () => '&&' },
+    { kind: 'a condition inverted', find: /\bif\s*\(\s*!/, swap: (m) => m.replace('!', '') },
+    { kind: 'a sign reversed', find: /(?<=[\w)\]]\s?)\+(?=\s?[\w(])/, swap: () => '-' },
+    { kind: 'a sign reversed', find: /(?<=[\w)\]]\s?)-(?=\s?[\w(])/, swap: () => '+' },
+    { kind: 'a returned flag flipped', find: /\breturn\s+true\b/, swap: () => 'return false' },
+    { kind: 'a returned flag flipped', find: /\breturn\s+false\b/, swap: () => 'return true' },
+    { kind: 'a returned value emptied', find: /\breturn\s+(?!null|undefined|None|nil|true|false|;|$)[\w.[\]]+\s*;?\s*$/, swap: (m) => (m.trimEnd().endsWith(';') ? 'return null;' : 'return null') },
+];
+/**
+ * Is this position inside a regular expression literal?
+ *
+ * Only a rough reading, and it only decides what a change is *called*, never whether it is safe: a
+ * slash that opens a pattern follows an operator, a bracket or a keyword, never a value, which is what
+ * separates `/re/` from division.
+ */
+function inPattern(line, at) {
+    let i = 0;
+    while (i < line.length) {
+        if (line[i] !== '/') {
+            i += 1;
+            continue;
+        }
+        const before = line.slice(0, i).trimEnd();
+        const opens = before === '' || /[=(,:[!&|?{;]$|\b(return|typeof|case|of|in|and|or|not)$/.test(before);
+        if (!opens) {
+            i += 1;
+            continue;
+        }
+        // Find the closing slash, ignoring one escaped by a backslash and one inside a character class.
+        let cls = false;
+        for (let j = i + 1; j < line.length; j += 1) {
+            const ch = line[j];
+            if (ch === String.fromCharCode(92)) {
+                j += 1;
+                continue;
+            }
+            if (ch === '[')
+                cls = true;
+            else if (ch === ']')
+                cls = false;
+            else if (ch === '/' && !cls) {
+                if (at > i && at < j)
+                    return true;
+                i = j + 1;
+                break;
+            }
+            if (j === line.length - 1)
+                return false; // never closed on this line
+        }
+        if (i < line.length && line[i] === '/')
+            i += 1;
+    }
+    return false;
+}
+/**
+ * The mutants worth trying for this file, spread over the file rather than taken from the top: five
+ * changes to one function say much less about a suite than five changes in five places.
+ */
+export function mutantsFor(text, limit = 6) {
+    const ranges = textRanges(text);
+    const lines = text.split(String.fromCharCode(10));
+    const offsets = [];
+    let seen = 0;
+    for (const line of lines) {
+        offsets.push(seen);
+        seen += line.length + 1;
+    }
+    const found = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.trim().length < 3 || COULD_LOOP.test(line) || NOT_BEHAVIOUR.test(line))
+            continue;
+        for (const operator of OPERATORS) {
+            const hit = operator.find.exec(line);
+            if (!hit)
+                continue;
+            const at = offsets[i] + (hit.index ?? 0);
+            // Inside a string or a comment: not behaviour, and often not even syntax once changed.
+            if (ranges.some(([from, to]) => at > from && at < to))
+                continue;
+            const now = line.slice(0, hit.index) + operator.swap(hit[0]) + line.slice((hit.index ?? 0) + hit[0].length);
+            if (now === line)
+                continue;
+            // A change inside a regular expression is worth making - loosening a pattern is exactly how one
+            // silently stops matching what it was written for - but it is not a boundary or a comparison, and
+            // calling it one makes an otherwise good finding look like a bug in the tool.
+            const kind = inPattern(line, hit.index ?? 0) ? 'a pattern loosened' : operator.kind;
+            found.push({ line: i + 1, was: line.trim(), now: now.trim(), kind });
+            break; // one change per line keeps each answer about one thing
+        }
+    }
+    return spread(found, limit);
+}
+/**
+ * Takes at most `limit`, as far apart in the file as they can be. A suite that catches everything in
+ * one function and nothing in the rest of the file should not look like a suite that catches
+ * everything, and taking the first six mutants in order is how that happens.
+ */
+function spread(all, limit) {
+    if (all.length <= limit)
+        return all;
+    const step = all.length / limit;
+    return Array.from({ length: limit }, (unused, i) => all[Math.floor(i * step)]);
+}
+/** The file with this one mutant applied, ready to be written and then put back. */
+export function applyMutant(text, mutant) {
+    const lines = text.split(String.fromCharCode(10));
+    const line = lines[mutant.line - 1];
+    if (line === undefined || line.trim() !== mutant.was)
+        throw new Error(`line ${mutant.line} is not what the mutant was made from, so nothing was written`);
+    lines[mutant.line - 1] = line.replace(mutant.was, mutant.now);
+    return lines.join(String.fromCharCode(10));
+}

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

@@ -0,0 +1,152 @@
+// `tewip prove <file>`: what your tests would not catch, shown by breaking the code and watching.
+//
+// The report is written for the reader who has to decide whether to trust a suite. It leads with what
+// went unnoticed, quotes the exact change, names the test that caught each one that was caught, and
+// says what the answer cost in seconds - because this is the one command here that is slow, and a
+// number somebody waited four minutes for should say how long it took.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { changeSummary } from '../quality/grounding.js';
+import { chooseFramework, detectFrameworks } from '../quality/frameworks.js';
+import { coverageFor, testFiles } from '../review/coverage.js';
+import { importingTests, proveFile } from './prove.js';
+import { testsReaching } from './reaches.js';
+const SOURCE = /\.(js|jsx|mjs|cjs|ts|tsx|mts|cts|py|java|kt|go|cs|rb|php)$/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;
+/** The source files to prove: the ones named, or the ones a change touched. */
+export function filesToProve(cmd) {
+    if (cmd.files.length > 0)
+        return cmd.files.map((f) => f.split('\\').join('/'));
+    if (!cmd.diff)
+        return [];
+    const change = changeSummary(cmd.root, cmd.diff);
+    if (!change)
+        return [];
+    return change.files.map((f) => f.split('\\').join('/')).filter((f) => SOURCE.test(f) && !IS_TEST.test(f) && existsSync(resolve(cmd.root, f)));
+}
+export function renderProof(proofs) {
+    const tried = proofs.flatMap((p) => p.tried);
+    const unnoticed = tried.filter((t) => t.fate === 'unnoticed');
+    const noticed = tried.filter((t) => t.fate === 'noticed');
+    const invalid = tried.filter((t) => t.fate === 'did-not-compile');
+    const broke = tried.filter((t) => t.fate === 'runner-broke');
+    const seconds = proofs.reduce((total, p) => total + p.seconds, 0);
+    const lines = [
+        '# What your tests would not catch',
+        '',
+        tried.length === 0
+            ? 'Nothing was tried. See below for why.'
+            : `${tried.length} change(s) were made to your code and the covering tests were run against each. **${unnoticed.length} went unnoticed.** ${noticed.length} were caught. Took ${seconds}s.`,
+        '',
+    ];
+    if (unnoticed.length > 0) {
+        lines.push(`## Unnoticed (${unnoticed.length})`, '', 'Each of these is a change to your code that every test covering it still passed. The line was', 'covered; it was not checked.', '');
+        for (const proof of proofs) {
+            const gaps = proof.tried.filter((t) => t.fate === 'unnoticed');
+            if (gaps.length === 0)
+                continue;
+            lines.push(`### ${proof.file}`, '');
+            for (const gap of gaps) {
+                lines.push(`- **line ${gap.mutant.line}: ${gap.mutant.kind}**`);
+                lines.push(`  - was: \`${gap.mutant.was.slice(0, 120)}\``);
+                lines.push(`  - became: \`${gap.mutant.now.slice(0, 120)}\``);
+            }
+            lines.push('', `Run by: ${proof.covering.join(', ')}`, '');
+        }
+    }
+    if (noticed.length > 0) {
+        lines.push(`## Caught (${noticed.length})`, '', 'These your tests would have stopped.', '');
+        for (const good of noticed)
+            lines.push(`- line ${good.mutant.line}: ${good.mutant.kind} — caught by \`${good.noticedBy}\``);
+        lines.push('');
+    }
+    const blocked = proofs.filter((p) => p.blocked);
+    if (blocked.length > 0) {
+        lines.push(`## Nothing could be proved here (${blocked.length})`, '');
+        for (const p of blocked)
+            lines.push(`- **${p.file}**: ${p.blocked}`);
+        lines.push('');
+    }
+    if (invalid.length > 0 || broke.length > 0 || proofs.some((p) => p.notTried > 0 || p.setAside.length > 0)) {
+        lines.push('## Not counted', '');
+        if (invalid.length > 0)
+            lines.push(`- ${invalid.length} change(s) did not compile, so they say nothing about the tests. That is Tewip's fault, not yours.`);
+        for (const p of proofs)
+            for (const aside of p.setAside)
+                lines.push(`- \`${aside.test}\` was set aside: ${aside.why}. It covers ${p.file}, so it may well notice things the tests above did not.`);
+        if (broke.length > 0)
+            lines.push(`- ${broke.length} run(s) broke in the environment rather than the tests.`);
+        const left = proofs.reduce((total, p) => total + p.notTried, 0);
+        if (left > 0)
+            lines.push(`- ${left} change(s) were never tried: the time budget ran out. Raise it with \`--budget <seconds>\`.`);
+        lines.push('');
+    }
+    lines.push('---', '', 'Every line above was proved by running your own tests against your own code, one small change at', 'a time, and every file was put back exactly as it was. No model was called.', '', 'What this does not say: that the unnoticed changes are bugs, or that the caught ones mean the', 'suite is good. It says only which of these particular mistakes your tests would have stopped -', 'which is more than a coverage percentage can tell you, and less than a proof that the code works.');
+    return lines.join(String.fromCharCode(10));
+}
+/**
+ * One file, proved, with nothing printed: what the MCP server and any other caller use. `runProve`
+ * prints as it goes because a person waiting minutes deserves to see progress; over a protocol that
+ * speaks on stdout, printing would corrupt the stream.
+ */
+export function proveOne(root, file, opts = {}) {
+    const framework = chooseFramework(detectFrameworks(root), undefined, false);
+    if (!framework)
+        return 'No unit test framework was found here (jest, vitest, mocha, node --test, pytest, go test, maven, gradle, dotnet). Proving works by running your tests, so it needs one.';
+    if (!existsSync(resolve(root, file)))
+        return `No such file here: ${file}`;
+    const covering = coveringTests(root, file, testFiles(root));
+    return renderProof([proveFile(root, file, covering.tests, framework, { limit: opts.limit, budgetSeconds: opts.budgetSeconds })]);
+}
+/** The tests that could notice a change here: the ones that import the file, else the ones that reach it. */
+function coveringTests(root, file, known) {
+    const direct = importingTests(root, coverageFor(root, [file], known), file);
+    if (direct.length > 0)
+        return { tests: direct, how: 'import it directly' };
+    const reached = testsReaching(root, file, known.map((t) => t.split(String.fromCharCode(92)).join('/')));
+    return { tests: reached.map((r) => r.testFile), how: reached.length > 0 ? `reach it through ${reached[0].steps} import(s), via ${reached[0].via}` : 'import it' };
+}
+export function runProve(cmd) {
+    const files = filesToProve(cmd);
+    if (files.length === 0) {
+        throw new Error('name a source file to prove, or pass --diff main...HEAD to prove what a change touched');
+    }
+    // A unit framework, never a browser one: proving needs dozens of runs, and a browser run costs
+    // minutes. Browser tests are where `tewip fix` and the drift lab work instead.
+    const framework = chooseFramework(detectFrameworks(cmd.root), undefined, false);
+    if (!framework) {
+        throw new Error('no unit test framework was found here (jest, vitest, mocha, pytest, go test, maven, gradle, dotnet). Proving needs one, because it works by running your tests.');
+    }
+    const known = testFiles(cmd.root);
+    const proofs = [];
+    for (const file of files) {
+        if (!existsSync(resolve(cmd.root, file))) {
+            proofs.push({ file, covering: [], tried: [], blocked: 'no such file here', setAside: [], notTried: 0, seconds: 0 });
+            continue;
+        }
+        // Nothing importing it by name is the normal case in a layered codebase, not the absence of
+        // tests, so the import chain is followed outwards before anything is concluded.
+        const { tests: covering, how } = coveringTests(cmd.root, file, known);
+        console.error(`${file}: ${covering.length} test file(s) ${how}`);
+        proofs.push(proveFile(cmd.root, file, covering, framework, {
+            limit: cmd.limit,
+            budgetSeconds: cmd.budgetSeconds,
+            onStep: (message) => console.error(`  ${message}`),
+        }));
+    }
+    const report = renderProof(proofs);
+    console.log(report);
+    if (cmd.out) {
+        mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+        writeFileSync(resolve(cmd.out), report + String.fromCharCode(10), 'utf8');
+    }
+    const unnoticed = proofs.flatMap((p) => p.tried).filter((t) => t.fate === 'unnoticed').length;
+    if (cmd.strict && unnoticed > 0) {
+        console.error(String.fromCharCode(10) + `${unnoticed} change(s) to your code went unnoticed by the tests covering it.`);
+        process.exitCode = 1;
+    }
+    return { proofs, unnoticed };
+}
+/** Kept so a caller that only wants the numbers does not have to parse the report. */
+export const readSource = (root, file) => readFileSync(resolve(root, file), 'utf8');
+export const shortName = (root, file) => relative(root, resolve(root, file)).split('\\').join('/');