@rigour-labs/core 6.7.2 → 6.7.4

package/dist/review/reviewer.test.js

@@ -8,7 +8,7 @@ import { reviewerBlocks, runReviewer } from './reviewer.js';
 import { dismissReviewerFinding } from './reviewer/context.js';
 import { reviewStatus } from './reviewer/background.js';
 import { selectReviewers, vendorsOf } from './reviewer/adapters.js';
-import { account, carryResolved, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
+import { account, carryResolved, checkoutVerifier, mergeVerdicts, parseVerdict } from './reviewer/verdict.js';
 let repo;
 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();
@@ -49,6 +49,7 @@ function fakes(answer, seen, pr = PR) {
             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);
         (seen.args ??= []).push(args);
+        (seen.unset ??= []).push(options.unset);
         const name = binary === 'claude' ? 'claude' : binary === 'cursor-agent' ? 'cursor' : 'codex';
         const prompt = binary === 'claude' ? args[args.indexOf('-p') + 1] : args[args.length - 1];
         seen.prompts.push(prompt);
@@ -99,7 +100,7 @@ afterEach(() => {
 describe('the reviewer', () => {
     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 answer = JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: false, evidence: 'src/job.ts:2', file: 'src/job.ts', line: 2, quote: 'export function job() {' }] });
         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.');
@@ -115,7 +116,7 @@ describe('the reviewer', () => {
     });
     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', consequence: 'a second run reads stale rows', why: 'x' }] });
+        const open = JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'export function job() {', consequence: 'a second run reads stale rows', why: 'x' }] });
         const first = await runReviewer(repo, 'main', config, fakes(() => open, seen), () => undefined, { checks: ['src/job.ts:1 Unused export `job`'] });
         expect(first.items).toHaveLength(1);
         const again = await runReviewer(repo, 'main', config, fakes(() => open, seen), () => undefined, { checks: ['src/job.ts:1 Unused export `job`'] });
@@ -138,7 +139,7 @@ describe('the reviewer', () => {
     });
     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', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: 'src/ghost.ts', line: 1, issue: 'unused', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: '', issue: 'somewhere, no file named', consequence: 'a second run reads stale rows' }] }), seen), () => undefined);
+        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', quote: 'export function job() {', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: 'src/ghost.ts', line: 1, issue: 'unused', consequence: 'a second run reads stale rows' }, { class: 'dead-code', file: '', issue: 'somewhere, no file named', consequence: 'a second run reads stale rows' }] }), 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;
@@ -170,6 +171,32 @@ describe('the reviewer', () => {
         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('for a backtest, gives the description as it read at the review, never a later edit', async () => {
+        const versions = { lastEditedAt: '2026-10-06T00:00:00Z', body: 'today: refunds are issued by the nightly job', userContentEdits: { totalCount: 3, nodes: [
+                    { editedAt: '2026-10-06T00:00:00Z', diff: 'today: refunds are issued by the nightly job' },
+                    { editedAt: '2026-10-02T00:00:00Z', diff: 'then: refunds are issued on request' },
+                    { editedAt: '2026-09-30T00:00:00Z', diff: 'first draft' },
+                ] } };
+        const withEdits = (answer, seen, graphql) => {
+            const base = fakes(answer, seen);
+            return async (command, args, options) => command === 'gh' && args[0] === 'api' && args[1] === 'graphql'
+                ? { exitCode: graphql ? 0 : 1, stdout: JSON.stringify({ data: { repository: { pullRequest: graphql } } }), stderr: '' }
+                : base(command, args, options);
+        };
+        const reply = () => JSON.stringify({ ...EMPTY, prior_points: [] });
+        const seen = seenNow();
+        await runReviewer(repo, 'main', config, withEdits(reply, seen, versions), () => undefined, { pr: 42, reviewsBefore: '2026-10-03T00:00:00Z', force: true });
+        expect(seen.files['pr-description.md']).toBe('then: refunds are issued on request');
+        await runReviewer(repo, 'main', config, withEdits(reply, seen, null), () => undefined, { pr: 42, reviewsBefore: '2026-10-03T00:00:00Z', force: true });
+        expect(seen.files['pr-description.md']).toContain('could not be recovered');
+    });
+    it('blind, reviews the commit alone and never asks GitHub', async () => {
+        const seen = seenNow();
+        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, prior_points: [] }), seen), () => undefined, { blind: true, trigger: 'backtest', force: true });
+        expect(result.outcome).toBe('passed');
+        expect(seen.ghArgs).toEqual([]);
+        expect(seen.files['previous-reviews.md']).toBe('none\n');
+    });
     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)') });
@@ -182,9 +209,51 @@ describe('the reviewer', () => {
         for (const result of [crashed, prose])
             expect(reviewerBlocks(result)).toBe(true);
     });
+    it('keeps where each judge run spent its tokens and what it read, labelled, in the local verdict', async () => {
+        const seen = seenNow();
+        const base = fakes(() => JSON.stringify(EMPTY), seen);
+        const streaming = async (command, args, options) => {
+            if (path.basename(command).replace(/\.(cmd|exe)$/, '') !== 'claude' || args[0] === '--version')
+                return base(command, args, options); // claude.cmd on Windows
+            const prompt = args[args.indexOf('-p') + 1];
+            const diff = /(\S+full\.diff)/.exec(prompt)[1];
+            const call = (id, name, input) => ({ type: 'assistant', message: { id: `m-${id}`, usage: { input_tokens: 1, cache_read_input_tokens: 100, cache_creation_input_tokens: 10, output_tokens: 5 }, content: [{ type: 'tool_use', id, name, input }] } });
+            const events = [
+                call('1', 'Read', { file_path: diff }), call('2', 'Read', { file_path: path.join(repo, 'src/job.ts') }), call('3', 'Read', { file_path: path.join(repo, 'a.ts') }),
+                call('4', 'Bash', { command: 'git log -3' }), call('5', 'Grep', { pattern: 'job' }),
+                { type: 'result', result: JSON.stringify(EMPTY), total_cost_usd: 0.2, usage: { input_tokens: 5, output_tokens: 25 } },
+            ];
+            return { exitCode: 0, stdout: events.map(e => JSON.stringify(e)).join('\n'), stderr: '' };
+        };
+        await runReviewer(repo, 'main', config, streaming, () => undefined, { force: true });
+        const store = path.join(repo, '.git', 'rigour-reviewer');
+        const verdict = fs.readdirSync(store).filter(f => /^[0-9a-f]{40}\.[0-9a-f]{8}\.json$/.test(f)).map(f => JSON.parse(fs.readFileSync(path.join(store, f), 'utf8')))[0];
+        expect(verdict.reviewers[0].trace).toMatchObject({ turns: 5, usage: { input: 5, cacheRead: 500, cacheWrite: 50, output: 25 } });
+        expect(verdict.reviewers[0].trace.calls.map((c) => c.category)).toEqual(['rigour-input', 'changed-file', 'other-file', 'git', 'search']);
+    });
+    it('asks a judge once more after an answer that is not a verdict, and is unavailable only when the second is not one either', async () => {
+        const seen = seenNow();
+        let calls = 0;
+        const slipOnce = await runReviewer(repo, 'main', config, fakes(() => (++calls === 1 ? '{"prior_points":[], "findings":[{"class"' : JSON.stringify(EMPTY)), seen), () => undefined, { force: true });
+        expect(slipOnce.outcome).toBe('passed');
+        expect(seen.prompts).toHaveLength(2);
+        const twice = seenNow();
+        const slipTwice = await runReviewer(repo, 'main', config, fakes(() => 'not json', twice), () => undefined, { force: true });
+        expect(slipTwice).toMatchObject({ outcome: 'unavailable', reason: expect.stringContaining('no valid verdict') });
+        expect(twice.prompts).toHaveLength(2); // once more, never a loop
+    });
+    it('says what was asked and that nothing ran when a review ends early, with why a judge is missing', async () => {
+        const seen = { ...seenNow(), installed: ['claude'] }; // cursor is listed but not installed
+        const unreadable = async (command, args, options) => command === 'gh' && args[0] === 'pr' ? { exitCode: 1, stdout: '', stderr: 'gh auth login required' } : fakes(() => '', seen)(command, args, options);
+        const result = await runReviewer(repo, 'main', config, unreadable, () => undefined, { choice: { mode: 'full', panel: true } });
+        expect(result).toMatchObject({ outcome: 'unavailable', reviewers: ['claude'] });
+        expect(result.mode).toMatchObject({ asked: 'panel', ran: 'none', source: 'flag', degraded: expect.stringContaining('not installed: cursor-agent') });
+        const early = await runReviewer(repo, 'main', config, fakes(() => '', { ...seenNow(), installed: [] }), () => undefined, { choice: { mode: 'full', panel: true } });
+        expect(early).toMatchObject({ outcome: 'unavailable', mode: { asked: 'panel', ran: 'none', source: 'flag' } }); // before any judge was found
+    });
     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', consequence: 'a second run reads stale rows' }] : [] });
+        const by = (name) => JSON.stringify({ ...EMPTY, prior_points: [{ point: 'lock before read', severity: 'blocking', resolved: name === 'claude', evidence: 'src/job.ts:2', file: 'src/job.ts', line: 2, quote: 'export function job() {' }], findings: name === 'cursor' ? [{ class: 'dead-code', file: 'a.ts', line: 1, issue: 'a is unused', consequence: 'a second run reads stale rows', quote: 'export const a = 1;' }] : [] });
         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']]);
@@ -221,7 +290,72 @@ describe('verdicts', () => {
         expect(parseVerdict('Looks good to me!', false, 'claude', {})).toMatchObject({ error: expect.stringContaining('no valid verdict') });
         expect(parseVerdict(JSON.stringify({ ...EMPTY, prior_points: [] }), true, 'claude', {})).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', () => {
+    it('keeps the journey, sibling parity and claims as working notes, never blocks, and reads a verdict cached before they existed', () => {
+        const verdict = {
+            ...EMPTY,
+            journey: [
+                { file: 'src/w.ts', line: 4, what: 'stamps sent_at', cleared_by: null, retry_safe: false, overlap_safe: true, can_move_back: true, keys: [{ name: 'dedupeKey', inputs: 'updated_at', stable_under_edit: false }] },
+                { file: 'src/w.ts', line: 9, what: 'caches the token', cleared_by: 'ttl', retry_safe: true, overlap_safe: true, can_move_back: null },
+            ],
+            siblings: [
+                { changed: 'src/a/run.ts:3', sibling: 'src/b/run.ts:7', needs_same_change: true, has_it: false, why: 'same lock' },
+                { changed: 'src/a/run.ts:3', sibling: 'src/c/run.ts:2', needs_same_change: true, has_it: true },
+                { changed: 'src/a/run.ts:3', sibling: 'src/d/run.ts:2', needs_same_change: false, has_it: false },
+            ],
+            claims: [
+                { source: 'description', claim: 'at worst one email', file: 'src/w.ts', line: 12, holds: false, evidence: 'loop sends per row' },
+                { source: 'comment', claim: 'runs daily', file: 'src/cron.ts', line: 1, holds: true },
+            ],
+        };
+        const { open, notes } = account(verdict, undefined, () => true);
+        expect(open).toEqual([]);
+        expect(notes.map(i => `${i.kind} ${i.class} ${i.file}:${i.line}`)).toEqual([
+            'journey correctness src/w.ts:4', 'journey correctness src/w.ts:4', 'journey correctness src/w.ts:4',
+            'sibling correctness src/b/run.ts:7', 'claim stale-claim src/w.ts:12',
+        ]);
+        expect(notes[3].issue).toContain('needs the same change as src/a/run.ts:3: same lock');
+        const cached = { ...EMPTY };
+        delete cached.journey;
+        delete cached.siblings;
+        delete cached.claims;
+        expect(account(cached, undefined, () => true).open).toEqual([]);
+        expect(mergeVerdicts([cached, { ...verdict, reviewer: 'codex' }]).claims).toHaveLength(2);
+    });
+    it('blocks on a finding only when the code it quotes is at the line it names, and never carries an old working note as a block', () => {
+        const verify = checkoutVerifier(repo);
+        const at = (quote, line = 2) => account({ ...EMPTY, prior_points: [], findings: [{ class: 'correctness', file: 'src/job.ts', line, issue: 'returns before the lock', input: 'two runs at once', consequence: 'two emails', ...(quote === undefined ? {} : { quote }) }] }, undefined, verify);
+        expect(at('    return 1;').open).toHaveLength(1);
+        expect(at('return   1;').open).toHaveLength(1); // whitespace aside
+        expect(at('return 1;', 9)).toMatchObject({ open: [], unverified: [expect.objectContaining({ issue: 'returns before the lock' })] }); // past the end
+        expect(at('return 99;')).toMatchObject({ open: [], unverified: [expect.anything()] }); // not in the file
+        expect(at()).toMatchObject({ open: [], unverified: [expect.anything()] }); // no quote at all
+        const old = { id: 'r1', kind: 'read', class: 'production-cost', file: 'src/q.ts', line: 3, issue: 'window not bounded' };
+        const carried = account({ ...EMPTY, prior_points: [] }, [old], verify);
+        expect(carried).toMatchObject({ open: [], notes: [expect.objectContaining({ id: 'r1' })] });
+    });
+    it('shows a team lesson the change repeats as a note, never a block on its own', () => {
+        const verdict = { ...EMPTY, lessons: [
+                { lesson: 'Regenerate the API client after changing the schema.', applies: true, file: 'src/schema.ts', line: 3, evidence: 'schema.ts changed, client not' },
+                { lesson: 'Paginate with keyset.', applies: false, file: 'src/scan.ts', line: 9 },
+            ] };
+        const { open, notes } = account(verdict, undefined, () => true);
+        expect(open).toEqual([]);
+        expect(notes.map(n => [n.kind, n.class, n.issue])).toEqual([['lesson', 'team-lesson', 'repeats a team lesson: Regenerate the API client after changing the schema.']]);
+    });
+    it('blocks only on what it can show: a quoted open human point, a blocking finding, never a missing thing that is there or a point a human accepted', () => {
+        const verify = checkoutVerifier(repo);
+        const decide = (v) => account({ ...EMPTY, prior_points: [], ...v }, undefined, verify);
+        const open = { point: 'take the lock before the first read', severity: 'blocking', resolved: false };
+        expect(decide({ prior_points: [{ ...open, file: 'src/job.ts', line: 2, quote: 'return 1;' }] }).open).toHaveLength(1);
+        expect(decide({ prior_points: [open] })).toMatchObject({ open: [], unverified: [expect.objectContaining({ kind: 'prior' })] }); // a later commit may have done it: no quote, no block
+        const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'job never closes the connection', input: 'every run', consequence: 'one connection leaks per run', quote: 'return 1;' };
+        expect(decide({ findings: [{ ...finding, absent: 'return 1' }] })).toMatchObject({ open: [], unverified: [expect.anything()] }); // "missing", but the file has it
+        expect(decide({ findings: [{ ...finding, absent: 'conn.close(' }] }).open).toHaveLength(1);
+        expect(decide({ findings: [{ ...finding, severity: 'should' }] })).toMatchObject({ open: [], notes: [expect.anything()] });
+        const accepted = { point: 'job never closes the connection after the read', severity: 'non-blocking', resolved: false };
+        expect(decide({ prior_points: [accepted], findings: [finding] })).toMatchObject({ open: [], notes: [expect.anything()] }); // a human raised it and accepted it
+    });
+    it('keeps reads, scans, redundancy and merge impact as notes with stable ids, and answers non-blocking points in the reply', () => {
         const verdict = {
             ...EMPTY,
             prior_points: [{ point: 'nit: rename', severity: 'non-blocking', resolved: false }],
@@ -230,12 +364,13 @@ describe('verdicts', () => {
             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([
+        const { open, notes, answerInReply } = account(verdict, undefined, () => true);
+        expect(open).toEqual([]);
+        expect(notes.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(new Set(notes.map(i => i.id)).size).toBe(notes.length);
+        expect(account(verdict, undefined, () => true).notes.map(i => i.id)).toEqual(notes.map(i => i.id)); // stable
         expect(answerInReply).toEqual([expect.objectContaining({ point: 'nit: rename' })]);
     });
     it('merges two verdicts: a point is resolved only when every reviewer resolves it', () => {
@@ -255,9 +390,27 @@ describe('verdicts', () => {
 });
 describe('a panel of judges', () => {
     const panelConfig = (reviewer) => ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor', 'codex'], mode: 'full', panel: 'on', ...reviewer } } });
-    const LOCK = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', consequence: 'two runs send the same email' };
-    const LONE = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', consequence: 'a reader treats it as the contract' };
-    const OPINION = { class: 'duplication', file: 'src/job.ts', line: 2, issue: 'could be one line shorter', consequence: '' };
+    const LOCK = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', quote: 'export function job() {', consequence: 'two runs send the same email' };
+    const LONE = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', quote: 'export function job() {', consequence: 'a reader treats it as the contract' };
+    const OPINION = { class: 'duplication', file: 'src/job.ts', line: 2, issue: 'could be one line shorter', quote: 'export function job() {', consequence: '' };
+    it("keeps Rigour's own key from every judge, and a key the team names from that judge, in reviews and cross-examinations alike", async () => {
+        installFake(bins[0], 'codex');
+        const seen = { ...seenNow(), installed: ['claude', 'cursor-agent', 'codex'] };
+        const reply = (name) => {
+            const prompt = seen.prompts.at(-1) ?? '';
+            if (prompt.includes('The other\nreviewer raised')) {
+                const ids = [...prompt.matchAll(/"id": "([0-9a-f]+)"/g)].map(m => m[1]);
+                return JSON.stringify({ answers: ids.map(id => ({ id, call: 'refute', evidence: `src/job.ts:1 ${name}: job is imported by the runner` })) });
+            }
+            return JSON.stringify({ ...EMPTY, findings: name === 'codex' ? [LONE] : [] });
+        };
+        await runReviewer(repo, 'main', panelConfig({ judges: 3, judge_env: { codex: { unset: ['OPENAI_API_KEY'] } } }), fakes(reply, seen), () => undefined);
+        const runs = seen.ran.map((command, i) => ({ judge: path.basename(command).replace(/\.(cmd|exe)$/, ''), unset: seen.unset?.[i] ?? [] }));
+        expect(runs.length).toBe(5); // three reviews and two cross-examinations
+        for (const run of runs)
+            expect(run.unset).toContain('RIGOUR_API_KEY');
+        expect(runs.filter(r => r.unset.includes('OPENAI_API_KEY')).map(r => r.judge)).toEqual(['codex']);
+    });
     it('confirms what a majority raised, drops what the others refute with evidence, and never blocks on an opinion', async () => {
         installFake(bins[0], 'codex');
         const seen = { ...seenNow(), installed: ['claude', 'cursor-agent', 'codex'] };
@@ -303,7 +456,7 @@ describe('a panel of judges', () => {
     });
     it('counts every run, stops new reviews at the cost cap, and leaves a cross-examination past the run cap disputed', async () => {
         const seen = seenNow();
-        const lone = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', consequence: 'a reader treats it as the contract' };
+        const lone = { class: 'dead-code', file: 'src/job.ts', line: 1, issue: 'job is exported and never called', quote: 'export function job() {', consequence: 'a reader treats it as the contract' };
         const reply = (name) => JSON.stringify({ ...EMPTY, findings: name === 'claude' ? [LOCK] : [{ ...LOCK, line: 3, issue: 'the lock is taken only after it returns' }, lone] });
         // Two judges fit in a cap of 2; the cross-examination of cursor's lone finding would be a third run.
         const result = await runReviewer(repo, 'main', panelConfig({ max_runs_per_day: 2 }), fakes(reply, seen), () => undefined);
@@ -326,7 +479,7 @@ describe('a panel of judges', () => {
 describe('what the team already knows', () => {
     const allowing = ConfigSchema.parse({ version: 1, review: { github_account: 'reviewer-account', reviewer: { enabled: true, reviewers: ['claude', 'cursor'], dismissals: true } } });
     it('refuses a dismissal unless the team allows them: fix the code, or the reviewer', async () => {
-        const first = await runReviewer(repo, 'main', allowing, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', consequence: 'two runs send the same email' }] }), seenNow()), () => undefined);
+        const first = await runReviewer(repo, 'main', allowing, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', quote: 'export function job() {', consequence: 'two runs send the same email' }] }), seenNow()), () => undefined);
         expect((await dismissReviewerFinding(repo, first.items[0].id, 'the runner holds a lock', false)).error).toContain('this team does not dismiss reviewer findings');
         expect(fs.existsSync(path.join(repo, '.rigour/dismissed-review-items.json'))).toBe(false);
     });
@@ -335,7 +488,7 @@ describe('what the team already knows', () => {
         fs.writeFileSync(path.join(repo, 'docs/jobs.md'), 'The job runner (src/job.ts) takes the lock first.\n');
         git('add', '-A');
         git('commit', '-qm', 'docs');
-        const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', consequence: 'two runs send the same email' };
+        const finding = { class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock is taken', quote: 'export function job() {', consequence: 'two runs send the same email' };
         const first = await runReviewer(repo, 'main', allowing, fakes(() => JSON.stringify({ ...EMPTY, findings: [finding] }), seenNow()), () => undefined);
         expect(first.outcome).toBe('findings');
         expect(await dismissReviewerFinding(repo, 'abcdef0123', 'not one of ours', true)).toEqual({ error: 'no open reviewer finding abcdef0123 on feature: run `rigour review --reviewer` and copy the id it shows' });
@@ -358,7 +511,7 @@ describe('what the team already knows', () => {
         expect(told.files['team-knowledge.md']).toContain("## Already found by Rigour's checks: they block on their own, so do not report them again\n- src/job.ts:1 Unused export `job`");
     });
     it('fails closed: a finding whose judge left out the consequence still blocks', async () => {
-        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock' }] }), seenNow()), () => undefined);
+        const result = await runReviewer(repo, 'main', config, fakes(() => JSON.stringify({ ...EMPTY, findings: [{ class: 'correctness', file: 'src/job.ts', line: 2, issue: 'returns before the lock', quote: 'export function job() {' }] }), seenNow()), () => undefined);
         expect(result.items.map(i => i.issue)).toEqual(['returns before the lock']);
         expect(result.notes).toEqual([]);
     });

package/dist/review/typed/constant-inputs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Inputs that never vary in production, so the code that handles other values is dead:
+ *
+ *   constant-member    a property every production object of the type sets to the same literal
+ *                      (`count: 0` in each), while code branches on it: the other branches never run.
+ *   constant-argument  a parameter every production call passes the same literal, while the body
+ *                      branches on it: the other branch never runs outside tests.
+ *
+ * Tests are not production: a test that passes other values is exactly the sign the generality
+ * exists only for them. Scoped like the other typed checks: the change declared the member or the
+ * function, or wrote every production host or call.
+ */
+import type * as TS from 'typescript';
+import type { TypedProgram } from './program.js';
+export interface DeclaredType {
+    node: TS.InterfaceDeclaration | TS.TypeAliasDeclaration;
+    name: string;
+    members: TS.PropertySignature[];
+}
+export interface ConstantHelpers {
+    hostsOf: (t: DeclaredType & {
+        sym: TS.Symbol;
+        type: TS.Type;
+    }) => TS.ObjectLiteralExpression[];
+    touched: (node: TS.Node) => boolean;
+    spanTouched: (node: TS.Node) => boolean;
+    at: (node: TS.Node) => string;
+    rel: (sf: TS.SourceFile) => string;
+    report: (id: string, title: string, node: TS.Node, details: string, hint: string) => void;
+    walk: (node: TS.Node, fn: (n: TS.Node) => void) => void;
+}
+export declare function constantInputs(typed: TypedProgram, changedSources: TS.SourceFile[], declared: Array<DeclaredType & {
+    sym: TS.Symbol;
+    type: TS.Type;
+}>, h: ConstantHelpers): void;

package/dist/review/typed/constant-inputs.js

@@ -0,0 +1,168 @@
+import { isTestFile } from '../test-files.js';
+export function constantInputs(typed, changedSources, declared, h) {
+    constantMembers(typed, declared, h);
+    constantArguments(typed, changedSources, h);
+}
+/** A literal's value as text (`0`, `'a'`, `true`, `null`), or undefined for anything computed. */
+function literal(ts, node) {
+    if (!node)
+        return undefined;
+    if (ts.isNumericLiteral(node) || ts.isStringLiteralLike(node))
+        return `${ts.isNumericLiteral(node) ? '' : "'"}${node.text}${ts.isNumericLiteral(node) ? '' : "'"}`;
+    if (node.kind === ts.SyntaxKind.TrueKeyword)
+        return 'true';
+    if (node.kind === ts.SyntaxKind.FalseKeyword)
+        return 'false';
+    if (node.kind === ts.SyntaxKind.NullKeyword)
+        return 'null';
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand))
+        return `-${node.operand.text}`;
+    return undefined;
+}
+/** The access is tested: an `if`/ternary/`while` condition, a comparison, `!`, `&&`/`||`, or a `switch`. */
+function inCondition(ts, node) {
+    for (let n = node, p = node.parent; p; n = p, p = p.parent) {
+        if ((ts.isIfStatement(p) || ts.isWhileStatement(p) || ts.isConditionalExpression(p)) && p.expression === n)
+            return true;
+        if (ts.isConditionalExpression(p) && p.condition === n)
+            return true;
+        if (ts.isSwitchStatement(p) && p.expression === n)
+            return true;
+        if (ts.isBinaryExpression(p) && [ts.SyntaxKind.GreaterThanToken, ts.SyntaxKind.LessThanToken, ts.SyntaxKind.GreaterThanEqualsToken, ts.SyntaxKind.LessThanEqualsToken, ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken].includes(p.operatorToken.kind)) {
+            if (ts.isIfStatement(p.parent) || ts.isConditionalExpression(p.parent) || ts.isBinaryExpression(p.parent) || ts.isPrefixUnaryExpression(p.parent) || ts.isReturnStatement(p.parent))
+                return true;
+            continue;
+        }
+        if (ts.isPrefixUnaryExpression(p) && p.operator === ts.SyntaxKind.ExclamationToken)
+            continue;
+        if (ts.isParenthesizedExpression(p))
+            continue;
+        return false;
+    }
+    return false;
+}
+function constantMembers(typed, declared, h) {
+    const { ts, checker } = typed;
+    for (const t of declared) {
+        const hosts = h.hostsOf(t).filter(host => !isTestFile(h.rel(host.getSourceFile())));
+        if (hosts.length < 2 || hosts.some(host => host.properties.some(p => ts.isSpreadAssignment(p))))
+            continue;
+        for (const m of t.members) {
+            const name = m.name.getText();
+            const values = hosts.map(host => {
+                const p = host.properties.find(q => q.name && ts.isIdentifier(q.name) && q.name.text === name);
+                return p && ts.isPropertyAssignment(p) ? literal(ts, p.initializer) : undefined;
+            });
+            if (values.some(v => v === undefined) || new Set(values).size !== 1)
+                continue;
+            const anchor = h.touched(m) ? m : hosts.every(h.spanTouched) ? hosts.find(h.spanTouched) : undefined;
+            if (!anchor)
+                continue;
+            const sym = checker.getPropertyOfType(t.type, name);
+            const tested = sym && findReads(typed, sym, h).find(read => inCondition(ts, read));
+            if (!tested)
+                continue;
+            h.report('constant-member', 'A member every production object sets to the same value', anchor, `\`${t.name}.${name}\` is ${values[0]} in all ${hosts.length} production objects of the type (e.g. ${h.at(hosts[0])}), yet ${h.at(tested)} branches on it: the other branches never run outside tests.`, `Delete the branches and the member, or pass the real value where the objects are built.`);
+        }
+    }
+}
+/** Every non-test read of the property symbol. */
+function findReads(typed, sym, h) {
+    const { ts, checker } = typed;
+    const decl = sym.declarations?.[0];
+    const reads = [];
+    for (const sf of typed.appSources) {
+        if (isTestFile(h.rel(sf)) || !sf.text.includes(sym.name))
+            continue;
+        h.walk(sf, node => {
+            if (!ts.isPropertyAccessExpression(node) || node.name.text !== sym.name)
+                return;
+            const s = checker.getSymbolAtLocation(node.name);
+            if (s && (s === sym || s.declarations?.[0] === decl))
+                reads.push(node);
+        });
+    }
+    return reads;
+}
+function constantArguments(typed, changedSources, h) {
+    const { ts, checker } = typed;
+    // Functions the change declared, by declaration node.
+    const functions = [];
+    for (const sf of changedSources) {
+        h.walk(sf, node => {
+            if (ts.isFunctionDeclaration(node) && node.name && node.body && node.parameters.length)
+                functions.push(node);
+            else if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name) && node.parameters.length)
+                functions.push(node);
+        });
+    }
+    if (functions.length === 0)
+        return;
+    const wanted = new Set(functions);
+    const calls = new Map();
+    // Tests included: a test passing another value is the evidence a production-only constant is a test seam.
+    for (const sf of typed.program.getSourceFiles().filter(f => !f.isDeclarationFile && !f.fileName.includes('/node_modules/'))) {
+        const test = isTestFile(h.rel(sf));
+        h.walk(sf, node => {
+            if (!ts.isCallExpression(node))
+                return;
+            const decl = checker.getResolvedSignature(node)?.declaration;
+            if (!decl || !wanted.has(decl))
+                return;
+            const entry = calls.get(decl) ?? { prod: [], test: [] };
+            (test ? entry.test : entry.prod).push(node);
+            calls.set(decl, entry);
+        });
+    }
+    // A function handed around as a value (a callback, an export others call dynamically) has callers the checker cannot list.
+    const passedAsValue = (fn) => {
+        const name = ts.isFunctionDeclaration(fn) ? fn.name : ts.isVariableDeclaration(fn.parent) ? fn.parent.name : undefined;
+        if (!name || !ts.isIdentifier(name))
+            return true;
+        const sym = checker.getSymbolAtLocation(name);
+        let escaped = false;
+        for (const sf of typed.appSources) {
+            if (escaped || !sf.text.includes(name.text))
+                continue;
+            h.walk(sf, node => {
+                if (escaped || !ts.isIdentifier(node) || node.text !== name.text || node === name)
+                    return;
+                if (checker.getSymbolAtLocation(node) !== sym)
+                    return;
+                const p = node.parent;
+                const called = ts.isCallExpression(p) && p.expression === node;
+                const imported = ts.isImportSpecifier(p) || ts.isExportSpecifier(p) || ts.isImportClause(p);
+                if (!called && !imported)
+                    escaped = true;
+            });
+        }
+        return escaped;
+    };
+    for (const fn of functions) {
+        const entry = calls.get(fn);
+        if (!entry || entry.prod.length < 2 || passedAsValue(fn) || !fn.body)
+            continue;
+        fn.parameters.forEach((param, i) => {
+            if (param.dotDotDotToken || !ts.isIdentifier(param.name))
+                return;
+            // Literals only: two calls passing a variable of the same name do not pass the same value.
+            const texts = entry.prod.map(c => (c.arguments[i] ? literal(ts, c.arguments[i]) : 'undefined'));
+            if (texts.some(t => t === undefined) || new Set(texts).size !== 1)
+                return;
+            // Proof of dead code: the body branches on the parameter, and production only ever takes one side.
+            const paramSym = checker.getSymbolAtLocation(param.name);
+            let tested;
+            h.walk(fn.body, node => {
+                if (!tested && ts.isIdentifier(node) && node.text === param.name.text && checker.getSymbolAtLocation(node) === paramSym && inCondition(ts, node))
+                    tested = node;
+            });
+            if (!tested)
+                return;
+            const anchor = h.touched(param) ? param : entry.prod.every(c => h.spanTouched(c)) ? entry.prod[0] : undefined;
+            if (!anchor)
+                return;
+            const fnName = ts.isFunctionDeclaration(fn) ? fn.name.text : fn.parent.name.text;
+            h.report('constant-argument', 'A parameter every production call passes the same value', anchor, `\`${fnName}\`'s \`${param.name.text}\` is ${texts[0]} in all ${entry.prod.length} production calls (e.g. ${h.at(entry.prod[0])}), yet ${h.at(tested)} branches on it: the other branch never runs outside tests.`, `Inline the value and delete the branch, or pass the real value where it is called.`);
+        });
+    }
+}

package/dist/review/typed/dead-null-guards.d.ts

@@ -0,0 +1,34 @@
+/**
+ * dead-null-guard: code that guards a column against null after the query already made it non-null.
+ *
+ * A query that filters `col` (`.not(col, 'is', null)`, or a range or equality on it, which SQL never
+ * matches on NULL) returns rows whose `col` is never null. A guard on `row.col` in code that reads
+ * those rows (`?? fallback`, `?.`, `== null`, `!row.col`) can then never fire: dead code that
+ * reviewers keep finding round after round, and a row type that keeps telling the next reader
+ * otherwise. nullable-filtered-column names the type; this names each guard.
+ *
+ * Reported only when it is certain: the row type is the one the filtered query returns (`.returns<Row[]>()`
+ * or `read…<Row>()`), EVERY query in the program that returns that row type filters the same column,
+ * and no object literal builds a row of that type with the column missing or null. A guard is
+ * reported on a line the change touched, or anywhere in a file whose filtered query the change touched.
+ */
+import type * as TS from 'typescript';
+import type { TypedProgram } from './program.js';
+type Chain = Array<{
+    call: TS.CallExpression;
+    name: string;
+}>;
+export interface GuardHelpers {
+    chainOf: (call: TS.CallExpression) => Chain;
+    outermost: (call: TS.CallExpression) => boolean;
+    rowTypeOf: (chain: Chain, outer: TS.Node) => TS.Type | undefined;
+    strArg: (call: TS.CallExpression, i: number) => string | undefined;
+    isNullLiteral: (n: TS.Node | undefined) => boolean;
+    isNullable: (t: TS.Type) => boolean;
+    touched: (node: TS.Node) => boolean;
+    at: (node: TS.Node) => string;
+    report: (id: string, title: string, node: TS.Node, details: string, hint: string) => void;
+    walk: (node: TS.Node, fn: (n: TS.Node) => void) => void;
+}
+export declare function deadNullGuards(typed: TypedProgram, changedSources: TS.SourceFile[], h: GuardHelpers): void;
+export {};