@rigour-labs/core 6.6.4 → 6.6.6

package/dist/review/reviewer.test.js

@@ -4,18 +4,22 @@ import os from 'os';
 import path from 'path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { ConfigSchema } from '../types/index.js';
-import { parseVerdict, reviewerBlocks, runReviewer } from './reviewer.js';
+import { reviewerBlocks, runReviewer } from './reviewer.js';
+import { selectReviewers, vendorsOf } from './reviewer/adapters.js';
+import { account, carryResolved, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
 let repo;
-const config = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account' } });
-const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
+const config = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor'] } } });
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const PR = { number: 42, state: 'OPEN', isDraft: false, author: { login: 'author' }, body: 'Every read is bounded at both ends.' };
 const REVIEWS = [
-    { id: 1, user: { login: 'ci-bot', type: 'Bot' }, body: 'automated', state: 'COMMENTED', submitted_at: '2026-10-01' },
-    { id: 2, user: { login: 'author', type: 'User' }, body: 'self note', state: 'COMMENTED', submitted_at: '2026-10-02' },
-    { id: 3, user: { login: 'senior', type: 'User' }, body: 'Two blocking points.', state: 'CHANGES_REQUESTED', submitted_at: '2026-10-03' },
+    { id: 1, user: { login: 'ci-bot', type: 'Bot' }, body: 'automated', state: 'COMMENTED', submitted_at: '2026-10-01', commit_id: 'aaaaaaaaa' },
+    { id: 2, user: { login: 'author', type: 'User' }, body: 'self note', state: 'COMMENTED', submitted_at: '2026-10-02', commit_id: 'aaaaaaaaa' },
+    { id: 3, user: { login: 'senior', type: 'User' }, body: 'Two blocking points.', state: 'CHANGES_REQUESTED', submitted_at: '2026-10-03', commit_id: 'aaaaaaaaa' },
 ];
-const INLINE = [{ path: 'src/job.ts', line: 12, body: 'Check the lock before the first read.' }];
-/** Real git; scripted gh; a reviewer that records what it was shown and answers `answer`. */
-function fakes(answer, seen) {
+const INLINE = [{ id: 7, user: { login: 'senior', type: 'User' }, path: 'src/job.ts', line: 12, body: 'Check the lock before the first read.', created_at: '2026-10-03', updated_at: '2026-10-03' }];
+const EMPTY = { prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: true, evidence: 'a.ts:1' }], redundant: [], reads: [], scans: [], merge_impact: [], findings: [], carried: [], resolved_previous: [] };
+/** Real git; scripted gh; agent CLIs that record what they were shown and answer `answer` (a function of the reviewer's name). */
+function fakes(answer, seen, pr = PR) {
     return async (command, args, options) => {
         if (command === 'git') {
             try {
@@ -26,23 +30,49 @@ function fakes(answer, seen) {
             }
         }
         if (command === 'gh') {
+            seen.ghArgs.push(args);
             if (args[0] === 'auth')
                 return { exitCode: 0, stdout: 'token-for-account\n', stderr: '' };
             seen.ghToken = options.env?.GH_TOKEN;
             if (args[0] === 'pr')
-                return { exitCode: 0, stdout: `42\tauthor\t${Buffer.from('Every read is bounded at both ends.').toString('base64')}\n`, stderr: '' };
+                return pr ? { exitCode: 0, stdout: JSON.stringify(pr), stderr: '' } : { exitCode: 1, stdout: '', stderr: 'no pull requests found for branch "feature"' };
             if (args[1].endsWith('/reviews'))
                 return { exitCode: 0, stdout: JSON.stringify(REVIEWS), stderr: '' };
-            return { exitCode: 0, stdout: JSON.stringify(INLINE), stderr: '' };
+            if (args[1].endsWith('/comments'))
+                return { exitCode: 0, stdout: JSON.stringify(INLINE), stderr: '' };
+            return { exitCode: 1, stdout: '', stderr: 'unexpected gh call' };
         }
-        const prompt = args[args.indexOf('-p') + 1];
+        const binary = path.basename(command).replace(/\.(cmd|exe)$/, '');
+        if (args[0] === '--version')
+            return (seen.installed ?? ['claude', 'cursor-agent']).includes(binary) ? { exitCode: 0, stdout: `${seen.versions?.[command] ?? '1.0.0'}\n`, stderr: '' } : { exitCode: 127, stdout: '', stderr: 'not found' };
+        seen.ran.push(command);
+        const name = binary === 'claude' ? 'claude' : binary === 'cursor-agent' ? 'cursor' : 'codex';
+        const prompt = binary === 'cursor-agent' ? args[args.length - 1] : args[args.indexOf('-p') + 1];
         seen.prompts.push(prompt);
-        seen.review = fs.readFileSync(prompt.match(/inline comments: (\S+)/)[1], 'utf8');
-        seen.description = fs.readFileSync(prompt.match(/description: (\S+)/)[1], 'utf8');
-        return { exitCode: 0, stdout: JSON.stringify({ result: answer }), stderr: '' };
+        // Paths as the prompt names them, on either separator (Windows writes `D:\...`).
+        for (const match of prompt.matchAll(/(\S+(?:previous-reviews\.md|pr-description\.md|full\.diff|hints\.txt|previous-open\.json|delta\.diff|previous-resolved\.json))/g)) {
+            seen.files[path.basename(match[1])] = fs.readFileSync(match[1], 'utf8');
+        }
+        const reply = answer(name);
+        if (typeof reply !== 'string')
+            return reply;
+        return { exitCode: 0, stdout: binary === 'claude' ? JSON.stringify({ result: reply, total_cost_usd: 1.5 }) : JSON.stringify({ result: reply }), stderr: '' };
     };
 }
+const seenNow = () => ({ prompts: [], files: {}, ghArgs: [], ran: [] });
+/** A PATH of our own, so the test sees only the agent CLIs it creates (the fake exec answers for them by name). */
+let bins;
+const originalPath = process.env.PATH;
+function installFake(dir, name) {
+    const file = path.join(dir, process.platform === 'win32' ? `${name}.cmd` : name);
+    fs.writeFileSync(file, '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+    return file;
+}
 beforeEach(() => {
+    bins = [fs.mkdtempSync(path.join(os.tmpdir(), 'bin-a-')), fs.mkdtempSync(path.join(os.tmpdir(), 'bin-b-'))];
+    for (const name of ['claude', 'cursor-agent'])
+        installFake(bins[0], name);
+    process.env.PATH = [...bins, originalPath ?? ''].join(path.delimiter);
     repo = fs.mkdtempSync(path.join(os.tmpdir(), 'reviewer-'));
     git('init', '-q', '-b', 'main');
     git('config', 'user.email', 't@example.com');
@@ -51,49 +81,170 @@ beforeEach(() => {
     fs.writeFileSync(path.join(repo, 'a.ts'), 'export const a = 1;\n');
     git('add', '-A');
     git('commit', '-qm', 'init');
+    git('checkout', '-qb', 'feature');
+    fs.mkdirSync(path.join(repo, 'src'));
+    fs.writeFileSync(path.join(repo, 'src/job.ts'), 'export function job() {\n    return 1;\n}\n');
+    git('add', '-A');
+    git('commit', '-qm', 'job');
+});
+afterEach(() => {
+    process.env.PATH = originalPath;
+    for (const dir of [repo, ...bins])
+        fs.rmSync(dir, { recursive: true, force: true });
 });
-afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
 describe('the reviewer', () => {
-    it("works from the latest person's review with its inline comments, and blocks on an open point", async () => {
-        const seen = { prompts: [] };
-        const answer = JSON.stringify({ prior_points: [{ point: 'lock before read', resolved: false, evidence: 'src/job.ts:12' }], blocking: [], non_blocking: [] });
-        const result = await runReviewer(repo, 'main', config, fakes(answer, seen), () => undefined);
-        expect(seen.review).toContain('Reviewer: senior');
-        expect(seen.review).toContain('- src/job.ts:12: Check the lock before the first read.');
-        expect(seen.review).not.toContain('automated');
-        expect(seen.review).not.toContain('self note');
+    it('works from every human review with inline comments and the description, written to files, and blocks on an open point', async () => {
+        const seen = seenNow();
+        const answer = JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: false, evidence: 'src/job.ts:2' }] });
+        const result = await runReviewer(repo, 'main', config, fakes(() => answer, seen), () => undefined);
+        expect(seen.files['previous-reviews.md']).toContain('Review by senior');
+        expect(seen.files['previous-reviews.md']).toContain('- 2026-10-03 src/job.ts:12: Check the lock before the first read.');
+        expect(seen.files['previous-reviews.md']).not.toContain('automated');
+        expect(seen.files['previous-reviews.md']).not.toContain('self note');
+        expect(seen.files['pr-description.md']).toBe('Every read is bounded at both ends.');
+        expect(seen.files['full.diff']).toContain('+export function job()');
         expect(seen.ghToken).toBe('token-for-account');
-        expect(seen.description).toBe('Every read is bounded at both ends.');
-        expect(result).toMatchObject({ cached: false, previousReview: 'senior, 2026-10-03 (1 review)' });
+        expect(seen.ghArgs[1].slice(0, 3)).toEqual(['pr', 'view', 'feature']); // by branch: the commit is not on the forge yet
+        expect(result).toMatchObject({ outcome: 'findings', reviewers: ['claude'], scope: 'full', cached: false, previousReview: 'senior, 2026-10-03 (1 review)', pr: 42, costUsd: 1.5 });
+        expect(result.items).toEqual([expect.objectContaining({ kind: 'prior', issue: 'lock before read', evidence: 'src/job.ts:2', reviewer: 'claude' })]);
         expect(reviewerBlocks(result)).toBe(true);
     });
-    it('caches the verdict per commit and review, so the same push is free', async () => {
-        const seen = { prompts: [] };
-        const answer = JSON.stringify({ prior_points: [{ point: 'p', resolved: true }], blocking: [] });
-        await runReviewer(repo, 'main', config, fakes(answer, seen), () => undefined);
-        const again = await runReviewer(repo, 'main', config, fakes(answer, seen), () => undefined);
+    it('caches the verdict per commit and inputs, so the same push is free, and the next commit gets a delta review that carries what is not accounted for', async () => {
+        const seen = seenNow();
+        const open = JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', why: 'x' }] });
+        const first = await runReviewer(repo, 'main', config, fakes(() => open, seen), () => undefined);
+        expect(first.items).toHaveLength(1);
+        const again = await runReviewer(repo, 'main', config, fakes(() => open, seen), () => undefined);
         expect(again.cached).toBe(true);
         expect(seen.prompts).toHaveLength(1);
-        expect(reviewerBlocks(again)).toBe(false);
-        expect(fs.readdirSync(repo)).toEqual(['.git', 'a.ts']); // nothing written to the working tree
+        expect(fs.readdirSync(repo).sort()).toEqual(['.git', 'a.ts', 'src']); // nothing written to the working tree
+        fs.writeFileSync(path.join(repo, 'src/job.ts'), 'export function job() {\n    return 2;\n}\n');
+        git('commit', '-qam', 'tweak');
+        const delta = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [], carried: [], resolved_previous: [] }), seen), () => undefined);
+        expect(delta.scope).toBe('delta');
+        expect(seen.prompts[1]).toContain('DELTA MODE');
+        expect(seen.files['delta.diff']).toContain('-    return 1;');
+        expect(JSON.parse(seen.files['previous-open.json'])).toHaveLength(1);
+        expect(delta.items).toEqual([expect.objectContaining({ issue: 'returns before the lock', status: 'not accounted for' })]);
+        expect(delta.outcome).toBe('findings');
+        // The human point the previous verdict resolved (a.ts untouched) was carried, not judged again.
+        expect(JSON.parse(seen.files['previous-resolved.json'])).toEqual([expect.objectContaining({ point: 'lock before read', resolved: true })]);
+        expect(delta.answerInReply).toEqual([]);
+    });
+    it('resolves a previous item only with evidence, and never blocks on an item that names code the checkout does not have', async () => {
+        const seen = seenNow();
+        const first = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock' }, { class: 'dead-code', file: 'src/ghost.ts', line: 1, issue: 'unused' }, { class: 'dead-code', file: '', issue: 'somewhere, no file named' }] }), seen), () => undefined);
+        expect(first.items.map(i => i.file)).toEqual(['src/job.ts']);
+        expect(first.unverified.map(i => i.file)).toEqual(['src/ghost.ts', '']); // a slip and a finding with no place to check: shown, never a block
+        const id = first.items[0].id;
+        fs.writeFileSync(path.join(repo, 'src/job.ts'), 'export function job() {\n    return 2;\n}\n');
+        git('commit', '-qam', 'fix');
+        const delta = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [], resolved_previous: [{ id, evidence: 'src/job.ts:2 the lock comes first now' }] }), seen), () => undefined);
+        expect(delta.outcome).toBe('passed');
+        expect(delta.resolved).toEqual([{ item: expect.objectContaining({ id }), evidence: 'src/job.ts:2 the lock comes first now' }]);
+    });
+    it('at push, asks a model only when someone will read the push: an open, non-draft pull request', async () => {
+        const seen = seenNow();
+        const none = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify(EMPTY), seen, null), () => undefined, { trigger: 'push' });
+        expect(none).toMatchObject({ outcome: 'skipped', reason: expect.stringContaining('no pull request for feature') });
+        expect(reviewerBlocks(none)).toBe(false);
+        expect(seen.prompts).toHaveLength(0);
+        const draft = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify(EMPTY), seen, { ...PR, isDraft: true }), () => undefined, { trigger: 'push' });
+        expect(draft.reason).toContain('is a draft');
+        const asked = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify(EMPTY), seen, null), () => undefined, { trigger: 'review' });
+        expect(asked.outcome).toBe('passed'); // on request it reviews without a pull request
+        expect(seen.prompts).toHaveLength(1);
+    });
+    it('for a backtest, reads the named pull request and hides every review and comment from the reviewed moment on', async () => {
+        const seen = seenNow();
+        const hidden = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [] }), seen), () => undefined, { pr: 42, reviewsBefore: '2026-10-03', force: true });
+        expect(seen.ghArgs.find(a => a[0] === 'pr')?.slice(0, 3)).toEqual(['pr', 'view', '42']);
+        expect(seen.files['previous-reviews.md']).toBe('none\n');
+        expect(hidden.outcome).toBe('passed');
+        const shown = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [] }), seen), () => undefined, { pr: 42, reviewsBefore: '2026-10-04', force: true });
+        expect(seen.files['previous-reviews.md']).toContain('Review by senior');
+        expect(shown).toMatchObject({ outcome: 'unavailable', reason: 'claude did not report on the human reviews' });
     });
-    it('finds the verdict when the reviewer wraps it in a summary or a code fence', () => {
-        const verdict = '{"prior_points":[{"point":"p","resolved":false}],"blocking":[]}';
-        for (const result of [`## Summary\nAll checked.\n\n\`\`\`json\n${verdict}\n\`\`\`\nDone.`, `Notes first.\n${verdict}\nThat is all {see above}.`]) {
-            const parsed = parseVerdict({ exitCode: 0, stdout: JSON.stringify({ result }), stderr: '' }, true);
-            expect(parsed).toMatchObject({ verdict: { prior_points: [{ point: 'p', resolved: false }] } });
+    it('never passes without a verdict: a crash, a malformed answer, an unreadable pull request or no installed reviewer', async () => {
+        const crashed = await runReviewer(repo, 'main', config, fakes(() => ({ exitCode: 1, stdout: '', stderr: 'API error' }), seenNow()), () => undefined);
+        expect(crashed).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('claude: no answer (exit 1)') });
+        const prose = await runReviewer(repo, 'main', config, fakes(() => 'Looks good to me!', seenNow()), () => undefined);
+        expect(prose).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no valid verdict') });
+        const broken = async (command, args, options) => command === 'gh' && args[0] === 'pr' ? { exitCode: 1, stdout: '', stderr: 'HTTP 500' } : fakes(() => '', seenNow())(command, args, options);
+        expect(await runReviewer(repo, 'main', config, broken, () => undefined)).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('could not read the pull request') });
+        const seen = { ...seenNow(), installed: [] };
+        expect(await runReviewer(repo, 'main', config, fakes(() => '', seen), () => undefined)).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no reviewer installed') });
+        for (const result of [crashed, prose])
+            expect(reviewerBlocks(result)).toBe(true);
+    });
+    it('in full mode runs two vendors and resolves a human point only when both say so', async () => {
+        const seen = seenNow();
+        const by = (name) => JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: name === 'claude', evidence: 'src/job.ts:2' }], findings: name === 'cursor' ? [{ class: 'dead-code', file: 'a.ts', line: 1, issue: 'a is unused' }] : [] });
+        const result = await runReviewer(repo, 'main', config, fakes(by, seen), () => undefined, { full: true });
+        expect(result.reviewers).toEqual(['claude', 'cursor']);
+        expect(result.items.map(i => [i.kind, i.reviewer])).toEqual([['prior', 'cursor'], ['finding', 'cursor']]);
+        expect(seen.prompts).toHaveLength(2);
+    });
+});
+describe('choosing reviewers', () => {
+    it('runs the newest installed copy of a CLI, not the first on PATH', async () => {
+        const seen = seenNow();
+        const older = installFake(bins[0], 'claude');
+        const newer = installFake(bins[1], 'claude');
+        seen.versions = { [older]: '2.0.34 (Claude Code)', [newer]: '2.1.289 (Claude Code)' };
+        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify(EMPTY), seen), () => undefined);
+        expect(result.outcome).toBe('passed');
+        expect(seen.ran).toEqual([newer]);
+    });
+    it('reads the vendors on the trailers, prefers another one in cross mode, and pairs two vendors in full mode', () => {
+        const authors = vendorsOf('Claude Opus <noreply@example.com>\n');
+        expect([...authors]).toEqual(['anthropic']);
+        const installed = new Set(['claude', 'cursor', 'codex']);
+        expect(selectReviewers(['claude', 'cursor', 'codex'], 'single', authors, installed)).toEqual(['claude']);
+        expect(selectReviewers(['claude', 'cursor', 'codex'], 'cross', authors, installed)).toEqual(['cursor']);
+        expect(selectReviewers(['claude', 'cursor', 'codex'], 'full', authors, installed)).toEqual(['cursor', 'claude']);
+        expect(selectReviewers(['claude', 'cursor'], 'cross', authors, new Set(['claude']))).toEqual(['claude']); // falls back to what is installed
+        expect(selectReviewers(['claude'], 'full', new Set(), new Set())).toEqual([]);
+    });
+});
+describe('verdicts', () => {
+    it('finds the verdict when the reviewer wraps it in a summary or a code fence, and refuses prose', () => {
+        const verdict = JSON.stringify(EMPTY);
+        for (const text of [`## Summary\nAll checked.\n\n\`\`\`json\n${verdict}\n\`\`\`\nDone.`, `Notes first.\n${verdict}\nThat is all {see above}.`]) {
+            expect(parseVerdict(text, true, 'claude', undefined)).toMatchObject({ verdict: { prior_points: [{ point: 'lock before read' }], reviewer: 'claude' } });
         }
+        expect(parseVerdict('Looks good to me!', false, 'claude', undefined)).toMatchObject({ error: expect.stringContaining('no valid verdict') });
+        expect(parseVerdict(JSON.stringify({ ...EMPTY, prior_points: [] }), true, 'claude', undefined)).toEqual({ error: 'claude did not report on the human reviews' });
+    });
+    it('turns reads, scans, redundancy and merge impact into open items with stable ids, and answers non-blocking points in the reply', () => {
+        const verdict = {
+            ...EMPTY,
+            prior_points: [{ point: 'nit: rename', severity: 'non-blocking', resolved: false }],
+            reads: [{ file: 'src/q.ts', line: 10, read: 'select attempts', rules: [{ rule: 'flag off', known_before_read: true, applied_before_read: false }], narrower_source: 'attempt.updated_at', keys: [{ name: 'eventId', inputs: 'answered_at', stable_under_edit: false }], window_bounded: false, keyset: null }],
+            scans: [{ file: 'src/s.ts', line: 3, function: 'later', outer: 'attempts', inner: 'answers', fix: 'index by attempt' }],
+            redundant: [{ file: 'src/r.ts', line: 5, what: 'null guard', made_redundant_by: 'src/r.ts:2', removed: false }, { file: 'src/r.ts', line: 9, what: 'removed guard', removed: true }],
+            merge_impact: [{ symbol: 'parseId', main_file: 'src/id.ts', call_site: 'src/link.ts:4', holds: false, why: 'band dropped' }],
+        };
+        const { open, answerInReply } = account(verdict, undefined, () => true);
+        expect(open.map(i => `${i.class} ${i.file}:${i.line}`)).toEqual([
+            'dead-code src/r.ts:5', 'production-cost src/q.ts:10', 'production-cost src/q.ts:10', 'production-cost src/q.ts:10', 'correctness src/q.ts:10', 'production-cost src/s.ts:3', 'correctness src/link.ts:4',
+        ]);
+        expect(new Set(open.map(i => i.id)).size).toBe(open.length);
+        expect(account(verdict, undefined, () => true).open.map(i => i.id)).toEqual(open.map(i => i.id)); // stable
+        expect(answerInReply).toEqual([expect.objectContaining({ point: 'nit: rename' })]);
     });
-    it('holds a push for an open blocking point, not for a nit the reviewer left open', () => {
-        const verdict = (blocking) => ({ prior_points: [{ point: 'p', resolved: false, blocking }], blocking: [], non_blocking: [] });
-        expect(reviewerBlocks({ verdict: verdict(true), cached: false })).toBe(true);
-        expect(reviewerBlocks({ verdict: verdict(false), cached: false })).toBe(false);
+    it('merges two verdicts: a point is resolved only when every reviewer resolves it', () => {
+        const a = { ...EMPTY, reviewer: 'claude', prior_points: [{ point: 'Lock before read', severity: 'blocking', resolved: true }], resolved_previous: [{ id: 'x', evidence: 'e' }, { id: 'y', evidence: 'e' }] };
+        const b = { ...EMPTY, reviewer: 'cursor', prior_points: [{ point: 'lock before read.', severity: 'blocking', resolved: false }], resolved_previous: [{ id: 'x', evidence: 'e' }] };
+        const merged = mergeVerdicts([a, b]);
+        expect(merged.prior_points).toEqual([expect.objectContaining({ resolved: false, reviewer: 'cursor' })]);
+        expect(merged.resolved_previous.map(r => r.id)).toEqual(['x']);
+        expect(merged.reviewers?.map(r => r.reviewer)).toEqual(['claude', 'cursor']);
     });
-    it('never passes on an answer that is not a verdict', () => {
-        expect(parseVerdict({ exitCode: 1, stdout: '', stderr: 'API error' }, false)).toMatchObject({ error: expect.stringContaining('did not answer') });
-        expect(parseVerdict({ exitCode: 0, stdout: JSON.stringify({ result: 'Looks good to me!' }), stderr: '' }, false)).toMatchObject({ error: expect.stringContaining('not a verdict') });
-        expect(parseVerdict({ exitCode: 0, stdout: JSON.stringify({ result: '{"prior_points":[],"blocking":[]}' }), stderr: '' }, true))
-            .toEqual({ error: 'the reviewer did not report on the previous review' });
-        expect(reviewerBlocks({ error: 'x', cached: false })).toBe(true);
+    it('carries a resolved human point into a delta verdict unless the new commits touch its evidence', () => {
+        const previous = { ...EMPTY, prior_points: [{ point: 'lock before read', resolved: true, evidence: 'src/job.ts:2' }, { point: 'rename it', resolved: true, evidence: 'src/name.ts:9' }] };
+        const fresh = { ...EMPTY, prior_points: [] };
+        expect(carryResolved(fresh, previous, new Set(['src/name.ts'])).prior_points.map(p => p.point)).toEqual(['lock before read']);
+        expect(carryResolved({ ...EMPTY, prior_points: [{ point: 'Lock before read', resolved: false }] }, previous, new Set()).prior_points).toHaveLength(2);
     });
 });

package/dist/review/toolchain.d.ts

@@ -1,11 +1,14 @@
 import type { Config } from '../types/index.js';
 export type ToolStatus = 'pass' | 'fail' | 'skipped';
 export interface ToolResult {
-    tool: 'format' | 'lint' | 'typecheck' | 'test';
+    tool: 'format' | 'lint' | 'overlay' | 'typecheck' | 'test' | 'knip';
     status: ToolStatus;
     /** The command run, or why it was not. */
     command: string;
     /** The tail of the output when it failed. */
     output?: string;
+    /** One line per finding, for tools that report places (the lint overlay, knip). */
+    lines?: string[];
 }
-export declare function runToolchain(cwd: string, changedFiles: string[], config: Config): Promise<ToolResult[]>;
+/** `changedLines`: the lines the change touched, for the tools that report per line (the overlay blocks on those only). */
+export declare function runToolchain(cwd: string, changedFiles: string[], config: Config, changedLines?: Record<string, Set<number>>): Promise<ToolResult[]>;

package/dist/review/toolchain.js

@@ -2,13 +2,16 @@
  * The repository's own tools, run on what a change touched: the formatter, the linter, the type
  * checker and the tests that import changed files. Teams already trust these; Rigour runs them at
  * the moment that matters (before a push) so nobody has to remember. Only tools the project
- * installed are run (node_modules/.bin, never a download); a missing one is reported as skipped.
- * A tool configured under `commands:` is left to that command, which every review already runs.
+ * installed are run (node_modules/.bin, never a download). A tool the project never declared is
+ * skipped and said so; one declared in package.json but not installed FAILS, since a checkout
+ * without its dependencies cannot prove anything about the change. A tool configured under
+ * `commands:` is left to that command, which every review already runs.
  */
 import { execa } from 'execa';
 import fs from 'fs';
 import path from 'path';
 import { installedBin } from '../utils/installed-bin.js';
+import { onChangedLines, overlayUnavailable, writeOverlayConfig } from './lint-overlay.js';
 import { ownOutputs } from './unused-exports.js';
 const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|svelte)$/;
 const FORMATTED = /\.(ts|tsx|js|jsx|mjs|cjs|svelte|json|css|md|ya?ml|html)$/;
@@ -16,7 +19,8 @@ const FORMATTED = /\.(ts|tsx|js|jsx|mjs|cjs|svelte|json|css|md|ya?ml|html)$/;
 const BATCH = 150;
 const TIMEOUT_MS = 10 * 60_000;
 const OUTPUT_LINES = 30;
-export async function runToolchain(cwd, changedFiles, config) {
+/** `changedLines`: the lines the change touched, for the tools that report per line (the overlay blocks on those only). */
+export async function runToolchain(cwd, changedFiles, config, changedLines = {}) {
     const own = ownOutputs(config);
     const files = changedFiles.filter(file => !own.some(o => file === o || file.startsWith(`${o}/`)) && fs.existsSync(path.join(cwd, file)));
     const code = files.filter(file => CODE.test(file));
@@ -27,14 +31,72 @@ export async function runToolchain(cwd, changedFiles, config) {
     };
     await run('format', () => formatCheck(cwd, files.filter(file => FORMATTED.test(file))));
     await run('lint', () => lint(cwd, code));
+    await run('overlay', () => lintOverlay(cwd, code, changedLines));
     await run('typecheck', () => typecheck(cwd));
     await run('test', () => relatedTests(cwd, code));
+    await run('knip', () => knip(cwd, files));
     return results;
 }
+/**
+ * Type-checked rules the repository does not enable (lint-overlay.ts), on changed lines only. The
+ * repository's own eslint and typescript-eslint run it; without them it is skipped and said so.
+ */
+async function lintOverlay(cwd, files, changedLines) {
+    const bin = installedBin(cwd, cwd, 'eslint');
+    if (!bin)
+        return skipped('overlay', 'eslint is not installed');
+    const unavailable = overlayUnavailable(cwd);
+    if (unavailable)
+        return skipped('overlay', unavailable);
+    const lintable = files.filter(file => /\.(ts|mts|cts|js|mjs|svelte)$/.test(file));
+    if (lintable.length === 0)
+        return { tool: 'overlay', status: 'pass', command: 'no lintable changed files' };
+    const configFile = writeOverlayConfig(cwd);
+    try {
+        const command = `eslint --config <typed overlay> --format json (${lintable.length} files)`;
+        const result = await execa(bin, ['--config', configFile, '--no-warn-ignored', '--format', 'json', ...lintable], { cwd, reject: false, timeout: TIMEOUT_MS, env: { ...process.env, CI: '1', FORCE_COLOR: '0' } });
+        const report = onChangedLines(String(result.stdout ?? ''), cwd, changedLines);
+        if ('error' in report)
+            return { tool: 'overlay', status: 'fail', command, output: `${report.error}\n${String(result.stderr ?? '').trim().split('\n').slice(-OUTPUT_LINES).join('\n')}` };
+        const lines = report.blocking.map(m => `${m.file}:${m.line}:${m.column} ${m.rule}: ${m.message}`);
+        const summary = `${command}: ${lines.length} on changed lines, ${report.preexisting} pre-existing (not blocking)`;
+        return lines.length ? { tool: 'overlay', status: 'fail', command: summary, output: lines.join('\n'), lines } : { tool: 'overlay', status: 'pass', command: summary };
+    }
+    finally {
+        fs.rmSync(path.dirname(configFile), { recursive: true, force: true });
+    }
+}
+/**
+ * knip, when the repository installs it, with the repository's own config: unused files and
+ * exports among the files the change touched (a pre-existing dead export elsewhere is backlog).
+ */
+async function knip(cwd, files) {
+    const bin = installedBin(cwd, cwd, 'knip');
+    if (!bin)
+        return notInstalled('knip', cwd, 'knip');
+    if (files.length === 0)
+        return { tool: 'knip', status: 'pass', command: 'no changed files' };
+    const command = 'knip --production --reporter json';
+    const result = await execa(bin, ['--production', '--no-progress', '--reporter', 'json'], { cwd, reject: false, timeout: TIMEOUT_MS, env: { ...process.env, CI: '1', FORCE_COLOR: '0' } });
+    let report;
+    try {
+        report = JSON.parse(String(result.stdout ?? ''));
+    }
+    catch {
+        return { tool: 'knip', status: 'fail', command, output: `knip printed no JSON (exit ${result.exitCode})\n${String(result.stderr ?? '').trim().split('\n').slice(-OUTPUT_LINES).join('\n')}` };
+    }
+    const changed = new Set(files);
+    const normalize = (file) => path.isAbsolute(file) ? path.relative(cwd, file).split(path.sep).join('/') : file;
+    const lines = [
+        ...(report.files ?? []).map(normalize).filter(file => changed.has(file)).map(file => `${file}: nothing imports or runs this file`),
+        ...(report.issues ?? []).filter(issue => changed.has(normalize(issue.file))).flatMap(issue => [...(issue.exports ?? []), ...(issue.types ?? [])].map(e => `${normalize(issue.file)}${e.line ? `:${e.line}` : ''}: unused export ${e.name}`)),
+    ];
+    return lines.length ? { tool: 'knip', status: 'fail', command: `${command}: ${lines.length} in changed files`, output: lines.join('\n'), lines } : { tool: 'knip', status: 'pass', command };
+}
 async function formatCheck(cwd, files) {
     const bin = installedBin(cwd, cwd, 'prettier');
     if (!bin)
-        return skipped('format', 'prettier is not installed');
+        return notInstalled('format', cwd, 'prettier');
     if (files.length === 0)
         return { tool: 'format', status: 'pass', command: 'no files to format' };
     return batched('format', cwd, bin, ['--check', '--ignore-unknown'], files);
@@ -42,7 +104,7 @@ async function formatCheck(cwd, files) {
 async function lint(cwd, files) {
     const bin = installedBin(cwd, cwd, 'eslint');
     if (!bin)
-        return skipped('lint', 'eslint is not installed');
+        return notInstalled('lint', cwd, 'eslint');
     if (files.length === 0)
         return { tool: 'lint', status: 'pass', command: 'no code files' };
     // ESLint 9 warns about an explicitly named ignored file, which --max-warnings=0 would count.
@@ -71,8 +133,21 @@ async function typecheck(cwd) {
     const tsc = fs.existsSync(path.join(cwd, 'tsconfig.json')) && installedBin(cwd, cwd, 'tsc');
     if (tsc)
         return once('typecheck', cwd, tsc, ['--noEmit']);
+    for (const pkg of ['svelte-check', 'typescript'])
+        if (declared(cwd, pkg))
+            return notInstalled('typecheck', cwd, pkg);
     return skipped('typecheck', 'no typecheck/check script, svelte-check or tsc with a tsconfig.json');
 }
+function declared(cwd, pkg) {
+    const manifest = readPackage(cwd);
+    return !!(manifest.dependencies?.[pkg] ?? manifest.devDependencies?.[pkg]);
+}
+/** Declared in package.json but absent from node_modules: a checkout that cannot prove anything fails; a tool never declared is skipped. */
+function notInstalled(tool, cwd, pkg) {
+    return declared(cwd, pkg)
+        ? { tool, status: 'fail', command: `${pkg} is in package.json but not installed`, output: `node_modules has no ${pkg}: install the dependencies (npm install, pnpm install, …) and run again` }
+        : skipped(tool, `${pkg} is not installed`);
+}
 function readPackage(cwd) {
     try {
         return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -85,7 +160,7 @@ function readPackage(cwd) {
 async function relatedTests(cwd, files) {
     const bin = installedBin(cwd, cwd, 'vitest');
     if (!bin)
-        return skipped('test', 'vitest is not installed');
+        return notInstalled('test', cwd, 'vitest');
     if (files.length === 0)
         return { tool: 'test', status: 'pass', command: 'no code files' };
     const first = await once('test', cwd, bin, ['related', '--run', '--passWithNoTests', ...files]);

package/dist/review/toolchain.test.js

@@ -25,7 +25,45 @@ afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
 describe('runToolchain', () => {
     it('reports every tool the project did not install as skipped, never downloading one', async () => {
         const results = await runToolchain(dir, ['src/a.ts'], config());
-        expect(results.map(r => [r.tool, r.status])).toEqual([['format', 'skipped'], ['lint', 'skipped'], ['typecheck', 'skipped'], ['test', 'skipped']]);
+        expect(results.map(r => [r.tool, r.status])).toEqual([['format', 'skipped'], ['lint', 'skipped'], ['overlay', 'skipped'], ['typecheck', 'skipped'], ['test', 'skipped'], ['knip', 'skipped']]);
+    });
+    it('fails, not skips, a tool the project declares but has not installed: a checkout without its dependencies proves nothing', async () => {
+        fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { eslint: '^9', typescript: '^5' } }));
+        const results = await runToolchain(dir, ['src/a.ts'], config());
+        expect(results.map(r => [r.tool, r.status])).toEqual([['format', 'skipped'], ['lint', 'fail'], ['overlay', 'skipped'], ['typecheck', 'fail'], ['test', 'skipped'], ['knip', 'skipped']]);
+        expect(results.find(r => r.tool === 'lint')).toMatchObject({ command: 'eslint is in package.json but not installed', output: expect.stringContaining('install the dependencies') });
+    });
+    it('runs type-checked rules the project does not enable, blocking on changed lines only, with the project\'s own eslint and config', async () => {
+        fs.writeFileSync(path.join(dir, 'eslint.config.js'), 'export default [];\n');
+        fs.mkdirSync(path.join(dir, 'node_modules/typescript-eslint'), { recursive: true });
+        fs.writeFileSync(path.join(dir, 'node_modules/typescript-eslint/package.json'), '{"name":"typescript-eslint","main":"index.js"}');
+        fs.writeFileSync(path.join(dir, 'node_modules/typescript-eslint/index.js'), 'module.exports = {};');
+        const report = JSON.stringify([{ filePath: path.join(dir, 'src/a.ts'), messages: [
+                    { line: 2, column: 5, ruleId: '@typescript-eslint/no-unnecessary-condition', message: 'Unnecessary conditional, value is always truthy.' },
+                    { line: 9, column: 1, ruleId: '@typescript-eslint/no-floating-promises', message: 'Promises must be awaited.' },
+                ] }]);
+        tool('eslint', `if (args[0] === '--version') { console.log('v9.0.0'); process.exit(0); }\nif (args.includes('--format')) { console.log(${JSON.stringify(report)}); process.exit(1); }\nprocess.exit(0);`);
+        const results = await runToolchain(dir, ['src/a.ts'], config(), { 'src/a.ts': new Set([1, 2, 3]) });
+        const overlay = results.find(r => r.tool === 'overlay');
+        expect(overlay).toMatchObject({ status: 'fail', lines: ['src/a.ts:2:5 @typescript-eslint/no-unnecessary-condition: Unnecessary conditional, value is always truthy.'] });
+        expect(overlay.command).toContain('1 on changed lines, 1 pre-existing (not blocking)');
+        const call = calls().split('\n').find(line => line.includes('--format json'));
+        expect(call).toMatch(/eslint --config \S+eslint\.overlay\.config\.mjs --no-warn-ignored --format json src\/a\.ts/);
+        expect(fs.readdirSync(dir)).not.toContain('eslint.overlay.config.mjs'); // never written into the repository
+        // Nothing on a changed line: pass, backlog counted.
+        const clean = await runToolchain(dir, ['src/a.ts'], config(), { 'src/a.ts': new Set([7]) });
+        expect(clean.find(r => r.tool === 'overlay')).toMatchObject({ status: 'pass', command: expect.stringContaining('0 on changed lines, 2 pre-existing') });
+    });
+    it('runs knip when the project installs it, and reports only what is in the changed files', async () => {
+        const report = JSON.stringify({ files: [path.join(dir, 'src/dead.ts'), 'src/elsewhere.ts'], issues: [
+                { file: 'src/a.ts', exports: [{ name: 'spare', line: 3, col: 1 }], types: [{ name: 'Spare', line: 4, col: 1 }] },
+                { file: 'src/other.ts', exports: [{ name: 'old', line: 1, col: 1 }], types: [] },
+            ] });
+        tool('knip', `console.log(${JSON.stringify(report)}); process.exit(1);`);
+        fs.writeFileSync(path.join(dir, 'src/dead.ts'), 'export const dead = 1;\n');
+        const results = await runToolchain(dir, ['src/a.ts', 'src/dead.ts'], config());
+        expect(results.find(r => r.tool === 'knip')).toMatchObject({ status: 'fail', lines: ['src/dead.ts: nothing imports or runs this file', 'src/a.ts:3: unused export spare', 'src/a.ts:4: unused export Spare'] });
+        expect(calls()).toContain('knip --production --no-progress --reporter json');
     });
     it('runs the formatter on changed files only and reports what it said', async () => {
         tool('prettier', "const bad = args.filter(a => a.endsWith('.ts') && fs.readFileSync(a, 'utf8').includes('BAD'));\nif (bad.length) { console.log('[warn] ' + bad.join(' ')); process.exit(1); }");

package/dist/review/typed/program.d.ts

@@ -0,0 +1,27 @@
+import type * as TS from 'typescript';
+export interface TextFile {
+    file: string;
+    text: string;
+}
+export interface TypedProgram {
+    ts: typeof TS;
+    program: TS.Program;
+    checker: TS.TypeChecker;
+    root: string;
+    /** A source file's path relative to the root, posix. */
+    rel(sf: TS.SourceFile): string;
+    /** The sources (outside node_modules, no declaration files) that are not tests: where a host or a reader counts. */
+    appSources: TS.SourceFile[];
+    /** Files the program does not type, as text. */
+    textFiles: TextFile[];
+    inProgram: Set<string>;
+}
+export declare const TEST_FILE: RegExp;
+/** The program, `skip` when this is not a TypeScript project, or `error` when it is one that cannot be loaded. */
+export declare function loadProgram(root: string): {
+    program: TypedProgram;
+} | {
+    skip: string;
+} | {
+    error: string;
+};