@rigour-labs/core 6.4.4 → 6.5.1

package/dist/review/quiet.js

@@ -0,0 +1,71 @@
+/**
+ * Quiet by default: a review speaks only when it can prove the defect.
+ *
+ * Proven findings come from rules that trace the defect itself: a value
+ * followed from where it enters to where it does harm (semantic bugs and the
+ * rules learned from fixes), an import that resolves to nothing, a secret in
+ * the source, a model finding grounded in code it read (only when a model was
+ * asked for), a function that behaves differently before and after.
+ * Heuristics (size, complexity, patterns that guess at intent) are advisory:
+ * returned for whoever asks, never deciding a verdict, never posted, never
+ * blocking. A team that wants them back sets review.include_heuristics.
+ *
+ * A finding a person judged "not a bug" is dismissed by its key and never
+ * reported again (.rigour/dismissed.json, meant to be committed).
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests']);
+export const DISMISSED_FILE = path.join('.rigour', 'dismissed.json');
+export function isProven(failure) {
+    return PROVEN_GATES.has(failure.id);
+}
+/** The same finding across runs and pushes: gate, file and message, never the line (lines move). */
+export function findingKey(failure) {
+    return crypto.createHash('sha256').update(`${failure.id}\u0000${failure.files?.[0] ?? ''}\u0000${failure.details}`).digest('hex').slice(0, 16);
+}
+export function quietSplit(cwd, findings, includeHeuristics = false) {
+    const dismissed = dismissedKeys(cwd);
+    const split = { speaking: [], advisory: [], dismissed: 0, dismissedByGate: {} };
+    for (const finding of findings) {
+        if (dismissed.has(findingKey(finding))) {
+            split.dismissed++;
+            split.dismissedByGate[finding.id] = (split.dismissedByGate[finding.id] ?? 0) + 1;
+        }
+        else if (includeHeuristics || isProven(finding))
+            split.speaking.push(finding);
+        else
+            split.advisory.push(finding);
+    }
+    return split;
+}
+export function dismissedKeys(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, DISMISSED_FILE), 'utf8'));
+        return new Set(Array.isArray(parsed?.entries) ? parsed.entries.map((e) => e?.key).filter((k) => typeof k === 'string') : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Record "not a bug" for a finding key; idempotent. */
+export function dismissFinding(cwd, key, reason, at = new Date().toISOString()) {
+    if (!/^[0-9a-f]{16}$/.test(key))
+        return false;
+    const file = path.join(cwd, DISMISSED_FILE);
+    let entries = [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (Array.isArray(parsed?.entries))
+            entries = parsed.entries;
+    }
+    catch {
+        // First dismissal in this repository.
+    }
+    if (!entries.some(e => e.key === key))
+        entries.push({ key, reason: reason.trim(), at });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ version: 1, entries }, null, 2) + '\n');
+    return true;
+}

package/dist/review/quiet.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/review/quiet.test.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { dismissFinding, findingKey, quietSplit } from './quiet.js';
+let dir;
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'quiet-')); });
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+const finding = (id, details = 'd', line = 3) => ({ id, title: id, details, files: ['src/a.ts'], line });
+describe('quiet by default', () => {
+    it('lets only findings that prove a defect speak; heuristics are advisory unless the team asks for them', () => {
+        const all = [finding('semantic-bugs'), finding('security-patterns'), finding('promise-safety'), finding('file-size'), finding('deep-analysis')];
+        const quiet = quietSplit(dir, all);
+        expect(quiet.speaking.map(f => f.id)).toEqual(['semantic-bugs', 'security-patterns', 'deep-analysis']);
+        expect(quiet.advisory.map(f => f.id)).toEqual(['promise-safety', 'file-size']);
+        expect(quietSplit(dir, all, true).speaking).toHaveLength(5);
+    });
+    it('never reports a dismissed finding again, even after its line moves', () => {
+        const leak = finding('security-patterns', 'Hardcoded token in `client`');
+        expect(dismissFinding(dir, findingKey(leak), 'test fixture token, never deployed')).toBe(true);
+        expect(dismissFinding(dir, findingKey(leak), 'again')).toBe(true); // idempotent
+        const moved = { ...leak, line: 40 };
+        expect(quietSplit(dir, [moved, finding('semantic-bugs')])).toMatchObject({ dismissed: 1, dismissedByGate: { 'security-patterns': 1 }, speaking: [expect.objectContaining({ id: 'semantic-bugs' })] });
+        expect(JSON.parse(fs.readFileSync(path.join(dir, '.rigour/dismissed.json'), 'utf8')).entries).toHaveLength(1);
+        expect(dismissFinding(dir, 'not-a-key', 'x')).toBe(false);
+    });
+});

package/dist/review/review-ack.d.ts

@@ -0,0 +1,16 @@
+import { type LedgerEntry } from './ledger.js';
+export interface ReviewAck {
+    file: string;
+    function: string;
+    verdict: string;
+    note: string;
+    reviewer?: string;
+}
+export type AckResult = {
+    ok: true;
+    entry: LedgerEntry;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function acknowledgeReview(cwd: string, ack: ReviewAck): AckResult;

package/dist/review/review-ack.js

@@ -0,0 +1,25 @@
+/**
+ * Acknowledge a review-task item: "I checked this function, here is what I
+ * found". The hash is taken from the file as it is now, so an acknowledgement
+ * covers exactly the code that was reviewed; editing the function afterwards
+ * puts it back in the task.
+ */
+import { findFunction } from '../deep/risk.js';
+import { recordReview } from './ledger.js';
+const MIN_NOTE_CHARS = 10;
+const VERDICTS = ['fixed', 'no_issue'];
+export function acknowledgeReview(cwd, ack) {
+    if (!VERDICTS.includes(ack.verdict))
+        return { ok: false, error: `verdict must be one of: ${VERDICTS.join(', ')}` };
+    const note = (ack.note ?? '').trim();
+    if (note.length < MIN_NOTE_CHARS)
+        return { ok: false, error: 'note must say what was checked (at least 10 characters)' };
+    const file = ack.file.replace(/\\/g, '/').replace(/^\.\//, '');
+    const current = findFunction(cwd, file, ack.function);
+    if (!current)
+        return { ok: false, error: `no function \`${ack.function}\` in ${file}` };
+    const entry = recordReview(cwd, {
+        file, function: ack.function, hash: current.hash, reviewer: ack.reviewer || 'agent', verdict: ack.verdict, note,
+    });
+    return { ok: true, entry };
+}

package/dist/review/review-task.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A review task for the developer's own coding agent (or the developer).
+ *
+ * Inside Claude Code, Cursor and the like, a frontier model is already
+ * running and already paid for. Rigour does not need to call a model of its
+ * own: it picks the changed functions worth a careful look (risk.ts), says
+ * what to check in each, and records the agent's verdict in the ledger.
+ * On real PRs, a model that read the repository with these questions in mind
+ * pre-empted four times as many acted-on review comments as chunked prompts.
+ */
+import { type RouterPolicy } from '../deep/router.js';
+import { type LessonMode } from '../review-learning/team-lessons.js';
+export interface ReviewTaskItem {
+    file: string;
+    function: string;
+    start: number;
+    end: number;
+    score: number;
+    hash: string;
+    /** What to check, from the function's risk signals. */
+    questions: string[];
+}
+export interface ReviewTask {
+    items: ReviewTaskItem[];
+    /** Risky functions already reviewed at their current content. */
+    alreadyReviewed: number;
+    /** The team's past review lessons that apply to this change. */
+    lessons: Array<{
+        file: string;
+        text: string;
+        prs: number[];
+    }>;
+    /** The repository's own rules (AGENTS.md, …) that name what this change touches. */
+    rules: Array<{
+        source: string;
+        text: string;
+    }>;
+    instructions: string;
+}
+export declare function buildReviewTask(cwd: string, diff: string, policy?: RouterPolicy, lessonMode?: LessonMode, repoRules?: boolean): ReviewTask;

package/dist/review/review-task.js

@@ -0,0 +1,50 @@
+/**
+ * A review task for the developer's own coding agent (or the developer).
+ *
+ * Inside Claude Code, Cursor and the like, a frontier model is already
+ * running and already paid for. Rigour does not need to call a model of its
+ * own: it picks the changed functions worth a careful look (risk.ts), says
+ * what to check in each, and records the agent's verdict in the ledger.
+ * On real PRs, a model that read the repository with these questions in mind
+ * pre-empted four times as many acted-on review comments as chunked prompts.
+ */
+import { DEFAULT_MAX_FUNCTIONS, DEFAULT_MIN_SCORE } from '../deep/router.js';
+import { rankChangedFunctions } from '../deep/risk.js';
+import { changedLinesByFile, parseDiff, removedByFile } from '../utils/diff.js';
+import { isReviewed, reviewedKeys } from './ledger.js';
+import { lessonsForDiff } from '../review-learning/team-lessons.js';
+import { rulesForDiff } from '../review-learning/repo-rules.js';
+const QUESTIONS = {
+    'data-write': 'Is the write safe under concurrent calls (no check-then-act), idempotent on retry, and does an upsert/conflict clause do what the caller expects?',
+    paging: 'Can the cursor, offset or limit skip, repeat or stall rows at page boundaries, caps or retries?',
+    auth: 'Is every path authorized, and are tokens or secrets kept out of logs, errors and responses?',
+    'money-or-time': 'Are units, rounding, time zones and clock comparisons consistent with the callers?',
+    concurrency: 'What happens if two calls overlap, or one step fails half-way through?',
+    network: 'Are timeouts, aborts and non-2xx responses handled, and does a retry repeat a side effect?',
+};
+export function buildReviewTask(cwd, diff, policy = {}, lessonMode = 'off', repoRules = false) {
+    const changed = parseDiff(diff);
+    const ranked = rankChangedFunctions(cwd, changedLinesByFile(changed), removedByFile(diff));
+    const risky = ranked.filter(f => f.score >= (policy.min_score ?? DEFAULT_MIN_SCORE)).slice(0, policy.max_functions ?? DEFAULT_MAX_FUNCTIONS);
+    const reviewed = reviewedKeys(cwd);
+    const pending = risky.filter(f => !isReviewed(reviewed, { file: f.file, function: f.name, hash: f.hash }));
+    const lessons = lessonsForDiff(cwd, diff, lessonMode).map(l => ({ file: l.file, text: l.text, prs: [...new Set(l.evidence.map(e => e.pr))] }));
+    return {
+        items: pending.map(toItem),
+        alreadyReviewed: risky.length - pending.length,
+        lessons,
+        rules: rulesForDiff(cwd, diff, repoRules).map(r => ({ source: r.source, text: r.text })),
+        instructions: pending.length === 0
+            ? 'No risky changed function is waiting for review.'
+            : 'For each item: read the function, its callers and what it calls; answer its questions against the code. '
+                + 'Fix any real defect. Then call rigour_review_ack with verdict "fixed" or "no_issue" and a one-line note saying what you checked.',
+    };
+}
+function toItem(f) {
+    const questions = [
+        ...(f.signals.removedGuard ? ['The change removed a condition, return or throw here: which inputs did it guard against, and are they still handled?'] : []),
+        ...f.signals.sensitive.map(kind => QUESTIONS[kind]).filter(Boolean),
+        `Do the callers of \`${f.name}\` still get what they assume (types, empty and error cases)?`,
+    ];
+    return { file: f.file, function: f.name, start: f.start, end: f.end, score: f.score, hash: f.hash, questions };
+}

package/dist/review/review-task.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/review/review-task.test.js

@@ -0,0 +1,80 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { diffFromGit } from './git-diff.js';
+import { acknowledgeReview } from './review-ack.js';
+import { buildReviewTask } from './review-task.js';
+import { exportReviewed, readLedger, REVIEWED_FILE } from './ledger.js';
+import { reviewAckMessage } from '../hooks/stop-review.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
+const write = (body) => fs.writeFileSync(path.join(repo, 'sync.ts'), body);
+const BEFORE = [
+    'export async function syncOrders(db, cursor) {',
+    '  const rows = await page(cursor);',
+    '  return rows;',
+    '}',
+    'function label(name) {',
+    '  return name;',
+    '}',
+    '',
+].join('\n');
+const AFTER = [
+    'export async function syncOrders(db, cursor) {',
+    '  const rows = await page(cursor);',
+    "  await db.from('orders').upsert(rows);",
+    '  return rows;',
+    '}',
+    'function label(name) {',
+    '  return name.trim();',
+    '}',
+    '',
+].join('\n');
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'review-task-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write(BEFORE);
+    git('add', '-A');
+    git('commit', '-q', '-m', 'base');
+    write(AFTER);
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('review task and acknowledgements', () => {
+    it('asks about the risky changed function only, with questions from its signals', () => {
+        const task = buildReviewTask(repo, diffFromGit(repo));
+        expect(task.items.map(i => i.function)).toEqual(['syncOrders']);
+        expect(task.items[0].questions[0]).toMatch(/concurrent calls/);
+        expect(task.items[0].questions.at(-1)).toContain('`syncOrders`');
+    });
+    it('drops an acknowledged function from the task until its code changes again', () => {
+        const ack = acknowledgeReview(repo, { file: 'sync.ts', function: 'syncOrders', verdict: 'no_issue', note: 'upsert key is the unique order id; callers retry safely' });
+        expect(ack.ok).toBe(true);
+        expect(buildReviewTask(repo, diffFromGit(repo))).toMatchObject({ items: [], alreadyReviewed: 1 });
+        write(AFTER.replace('return rows;', 'return rows.slice(1);'));
+        expect(buildReviewTask(repo, diffFromGit(repo)).items.map(i => i.function)).toEqual(['syncOrders']);
+    });
+    it('refuses an acknowledgement without a real note, a known verdict, or a real function', () => {
+        expect(acknowledgeReview(repo, { file: 'sync.ts', function: 'syncOrders', verdict: 'no_issue', note: 'ok' })).toMatchObject({ ok: false });
+        expect(acknowledgeReview(repo, { file: 'sync.ts', function: 'syncOrders', verdict: 'lgtm', note: 'looked at it carefully' })).toMatchObject({ ok: false });
+        expect(acknowledgeReview(repo, { file: 'sync.ts', function: 'nope', verdict: 'fixed', note: 'looked at it carefully' })).toMatchObject({ ok: false });
+        expect(readLedger(repo)).toEqual([]);
+    });
+    it('exports hashes and verdicts only, and a committed export clears the task too', () => {
+        acknowledgeReview(repo, { file: 'sync.ts', function: 'syncOrders', verdict: 'fixed', note: 'made the upsert key explicit' });
+        exportReviewed(repo);
+        const exported = JSON.parse(fs.readFileSync(path.join(repo, REVIEWED_FILE), 'utf8'));
+        expect(Object.keys(exported.entries[0]).sort()).toEqual(['file', 'function', 'hash', 'reviewer', 'verdict']);
+        fs.rmSync(path.join(repo, '.rigour', 'review-ledger.jsonl'));
+        expect(buildReviewTask(repo, diffFromGit(repo)).items).toEqual([]);
+    });
+    it('tells a stopping agent which functions still need review, and how', () => {
+        const message = reviewAckMessage(buildReviewTask(repo, diffFromGit(repo)).items, 1);
+        expect(message).toContain('sync.ts:1 `syncOrders`');
+        expect(message).toContain('rigour_review_ack');
+    });
+});

package/dist/review/review.d.ts

@@ -11,12 +11,19 @@ export interface ReviewInput {
     /** Run changed functions before and after the change (needs deep, on the max or a cloud tier). */
     diffTests?: boolean;
     /** Deep analysis; `focusLines` and `removedLines` are filled from the diff. */
-    deep?: Omit<DeepOptions, 'focusLines' | 'removedLines'>;
+    deep?: Omit<DeepOptions, 'focusLines' | 'removedLines' | 'diff'>;
 }
 export interface ReviewResult {
     status: 'PASS' | 'FAIL' | 'ERROR';
     findings: Failure[];
     fileFindings: Failure[];
+    /** Deep findings elsewhere in a changed file: shown, never blocking. */
+    contextFindings: Failure[];
+    /** Heuristic findings on changed lines: returned on request, never deciding the verdict (quiet.ts). */
+    advisory: Failure[];
+    /** Findings a person dismissed as not a bug, and the gates they came from. */
+    dismissed: number;
+    dismissedByGate: Record<string, number>;
     unlocated: number;
     excludedOutsideChangedLines: number;
     changedLines: Record<string, Set<number>>;
@@ -31,6 +38,10 @@ export interface ReviewFinding {
     message: string;
     file: string;
     line: number | null;
+    /** For a finding inside a changed function but off the changed lines: the changed line to post it on. */
+    anchor_line?: number;
+    /** Stable across runs: `rigour dismiss <key>` silences this finding for good. */
+    key: string;
     suggestion?: string;
 }
 export declare function reviewChange(input: ReviewInput): Promise<ReviewResult>;

package/dist/review/review.js

@@ -11,25 +11,33 @@ import { changedLinesByFile, parseDiff, removedByFile } from '../utils/diff.js';
 import { normalizeScopePatterns } from '../utils/scope.js';
 import { deepAnalysisError } from '../utils/deep-status.js';
 import { splitByChangedLines } from './changed-lines.js';
+import { changedFunctionSpans } from './changed-function-spans.js';
+import { withoutGenerated } from './generated-files.js';
+import { findingKey, quietSplit } from './quiet.js';
 import { diffFromGit } from './git-diff.js';
 import { diffTestFailures } from './diff-test-findings.js';
 export async function reviewChange(input) {
     const diff = input.diff ?? diffFromGit(input.cwd, input.source);
-    const changedLines = parseDiff(diff);
+    const changedLines = withoutGenerated(input.cwd, parseDiff(diff));
     const targets = input.files?.length ? input.files : Object.keys(changedLines);
     if (targets.length === 0) {
-        return { status: 'PASS', findings: [], fileFindings: [], unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null };
     }
-    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff) } : undefined;
+    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
     const report = await new GateRunner(input.config).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
     if (input.diffTests && deep)
         report.failures.push(...await diffTestFailures(input.cwd, input.source, deep));
-    const split = splitByChangedLines(report.failures, changedLines);
+    const split = splitByChangedLines(report.failures, changedLines, deep ? changedFunctionSpans(input.cwd, changedLines) : {});
     const deepError = deepAnalysisError(report);
+    const quiet = quietSplit(input.cwd, split.findings, input.config.review?.include_heuristics);
     return {
-        status: deepError ? 'ERROR' : split.findings.length > 0 ? 'FAIL' : 'PASS',
-        findings: split.findings,
+        status: deepError ? 'ERROR' : quiet.speaking.length > 0 ? 'FAIL' : 'PASS',
+        findings: quiet.speaking,
+        advisory: quiet.advisory,
+        dismissed: quiet.dismissed,
+        dismissedByGate: quiet.dismissedByGate,
         fileFindings: split.fileFindings,
+        contextFindings: split.contextFindings,
         unlocated: split.unlocated,
         excludedOutsideChangedLines: split.outside,
         changedLines,
@@ -45,8 +53,10 @@ export function toReviewFinding(failure) {
         severity: failure.severity || 'medium',
         provenance: failure.provenance || 'traditional',
         message: failure.details,
+        key: findingKey(failure),
         file: failure.files?.[0] || '',
         line: failure.line ?? null,
+        ...(failure.anchorLine !== undefined ? { anchor_line: failure.anchorLine } : {}),
         ...(failure.hint ? { suggestion: failure.hint } : {}),
     };
 }

package/dist/review/review.test.js

@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { ConfigSchema } from '../types/index.js';
 import { parseDiff } from '../utils/diff.js';
 import { splitByChangedLines } from './changed-lines.js';
+import { anchorInChangedFunction, changedFunctionSpans } from './changed-function-spans.js';
 import { diffFromGit } from './git-diff.js';
 import { reviewChange, toReviewFinding } from './review.js';
 const LEAKY = [
@@ -26,6 +27,30 @@ describe('splitByChangedLines', () => {
         expect(split.unlocated).toBe(1);
         expect(split.outside).toBe(2);
     });
+    it('keeps a deep finding inside a changed function, anchored on the nearest changed line', () => {
+        const deep = (line) => ({ ...failure('a.ts', line), provenance: 'deep-analysis' });
+        const changed = { 'a.ts': new Set([12, 14]) };
+        const spans = { 'a.ts': [[10, 20]] };
+        const split = splitByChangedLines([deep(11), deep(30), failure('a.ts', 11)], changed, spans);
+        expect(split.findings).toEqual([expect.objectContaining({ line: 11, anchorLine: 12 })]);
+        expect(split.contextFindings.map(f => f.line)).toEqual([30]); // elsewhere in a changed file: shown, not blocking
+        expect(split.outside).toBe(1); // a rule finding on an unchanged line is pre-existing, as before
+    });
+});
+describe('changedFunctionSpans', () => {
+    it('spans the outermost function around changed lines, and anchors to the nearest changed line in it', () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'spans-'));
+        try {
+            fs.writeFileSync(path.join(dir, 'a.ts'), 'const x = 1;\nexport function f(a: number) {\n  if (a > 0) {\n    return a;\n  }\n  return 0;\n}\n');
+            const spans = changedFunctionSpans(dir, { 'a.ts': new Set([4]), 'missing.ts': new Set([1]), 'notes.md': new Set([1]) });
+            expect(spans).toEqual({ 'a.ts': [[2, 7]] });
+            expect(anchorInChangedFunction(6, new Set([4]), spans['a.ts'])).toBe(4);
+            expect(anchorInChangedFunction(1, new Set([4]), spans['a.ts'])).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
 });
 describe('git-backed review', () => {
     let repo;

package/dist/review-learning/acted-on.d.ts

@@ -0,0 +1,25 @@
+export interface ReviewComment {
+    id: string;
+    prNumber: number;
+    path: string;
+    /** Lines the comment covers on its commit (start ≤ end). */
+    start: number;
+    end: number;
+    /** The commit the comment was written on. */
+    commit: string;
+    body: string;
+    author: string;
+}
+export interface MergedPr {
+    number: number;
+    mergeSha: string;
+    mergedAt: string;
+    comments: ReviewComment[];
+}
+/** git in one repository; tests substitute their own. */
+export type Git = (args: string[]) => string;
+export declare function gitIn(cwd: string): Git;
+/** Acted-on comments of a merged PR; comments whose commit or file cannot be found are skipped. */
+export declare function actedOn(git: Git, pr: MergedPr): ReviewComment[];
+/** Old-side line ranges that changed between two commits in one file. */
+export declare function changedHunks(git: Git, from: string, to: string, file: string): Array<[number, number]>;

package/dist/review-learning/acted-on.js

@@ -0,0 +1,69 @@
+/**
+ * Which review comments a developer acted on: the lines a comment points at
+ * changed between the commit it was written on and the merged result.
+ *
+ * Acted-on comments are review work the team valued, whoever wrote them (a
+ * person, a review bot, Rigour). A comment nobody acted on is not evidence of
+ * anything and never becomes a lesson.
+ */
+import { execFileSync } from 'child_process';
+export function gitIn(cwd) {
+    return (args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+/** Acted-on comments of a merged PR; comments whose commit or file cannot be found are skipped. */
+export function actedOn(git, pr) {
+    ensureCommits(git, pr);
+    return pr.comments.filter(comment => {
+        if (!hasFile(git, comment.commit, comment.path) || !hasFile(git, pr.mergeSha, comment.path))
+            return false;
+        return changedHunks(git, comment.commit, pr.mergeSha, comment.path).some(([s, e]) => s <= comment.end && comment.start <= e);
+    });
+}
+/** Old-side line ranges that changed between two commits in one file. */
+export function changedHunks(git, from, to, file) {
+    let diff = '';
+    try {
+        diff = git(['diff', '--no-color', '-U0', from, to, '--', file]);
+    }
+    catch {
+        return [];
+    }
+    const hunks = [];
+    for (const match of diff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/gm)) {
+        const start = Number(match[1]);
+        const count = match[2] === undefined ? 1 : Number(match[2]);
+        // A pure insertion (count 0) sits after `start`; it touches that line.
+        hunks.push([start, start + Math.max(count, 1) - 1]);
+    }
+    return hunks;
+}
+/** Commits a comment was written on may have been force-pushed away; GitHub still serves the PR ref. */
+function ensureCommits(git, pr) {
+    const missing = [...new Set(pr.comments.map(c => c.commit))].filter(sha => !hasCommit(git, sha));
+    if (missing.length === 0)
+        return;
+    try {
+        git(['fetch', '-q', 'origin', `pull/${pr.number}/head`]);
+    }
+    catch {
+        // Offline or no remote: the comments on missing commits are skipped.
+    }
+}
+function hasCommit(git, sha) {
+    try {
+        git(['cat-file', '-e', `${sha}^{commit}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasFile(git, sha, file) {
+    try {
+        git(['cat-file', '-e', `${sha}:${file}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/review-learning/learn-from-reviews.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `rigour learn --from-reviews`: turn a repository's acted-on review comments
+ * into review lessons. Reads GitHub (merged PRs and their review comments) and
+ * the local clone; writes only .rigour/review-lessons.json.
+ */
+import { type Git } from './acted-on.js';
+type Fetch = (url: string, init?: any) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<any>;
+}>;
+export interface LearnFromReviewsOptions {
+    token: string;
+    /** owner/name */
+    repo: string;
+    /** Only PRs merged on or after this ISO date. */
+    since?: string;
+    /** Only PRs merged before this ISO date (a time split for measuring). */
+    until?: string;
+    limit?: number;
+    apiUrl?: string;
+    fetch?: Fetch;
+    git?: Git;
+}
+export interface LearnFromReviewsResult {
+    prs: number;
+    comments: number;
+    actedOn: number;
+    added: number;
+    verified: number;
+    total: number;
+}
+export declare function learnFromReviews(cwd: string, options: LearnFromReviewsOptions): Promise<LearnFromReviewsResult>;
+export {};

package/dist/review-learning/learn-from-reviews.js

@@ -0,0 +1,65 @@
+/**
+ * `rigour learn --from-reviews`: turn a repository's acted-on review comments
+ * into review lessons. Reads GitHub (merged PRs and their review comments) and
+ * the local clone; writes only .rigour/review-lessons.json.
+ */
+import { actedOn, gitIn } from './acted-on.js';
+import { lessonFromComment, mergeLessons, readLessons, writeLessons } from './lessons.js';
+export async function learnFromReviews(cwd, options) {
+    const git = options.git ?? gitIn(cwd);
+    const prs = await mergedPrs(options);
+    const lessons = [];
+    let comments = 0;
+    let acted = 0;
+    for (const pr of prs) {
+        comments += pr.comments.length;
+        for (const comment of actedOn(git, pr)) {
+            acted++;
+            const lesson = lessonFromComment(git, comment);
+            if (lesson)
+                lessons.push(lesson);
+        }
+    }
+    const merged = mergeLessons(readLessons(cwd), lessons);
+    writeLessons(cwd, merged.lessons);
+    return { prs: prs.length, comments, actedOn: acted, added: merged.added, verified: merged.verified, total: merged.lessons.length };
+}
+async function mergedPrs(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const base = `${(options.apiUrl || 'https://api.github.com').replace(/\/$/, '')}/repos/${options.repo}`;
+    const get = async (url) => {
+        const response = await fetchImpl(url, { headers: { Authorization: `Bearer ${options.token}`, Accept: 'application/vnd.github+json' } });
+        if (!response.ok)
+            throw new Error(`GitHub ${url.replace(base, '')}: HTTP ${response.status}`);
+        return response.json();
+    };
+    const limit = options.limit ?? 100;
+    const prs = [];
+    for (let page = 1; prs.length < limit && page <= 20; page++) {
+        const batch = await get(`${base}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`);
+        if (batch.length === 0)
+            break;
+        for (const pr of batch) {
+            if (!pr.merged_at || !pr.merge_commit_sha)
+                continue;
+            if (options.since && pr.merged_at < options.since)
+                continue;
+            if (options.until && pr.merged_at >= options.until)
+                continue;
+            const raw = await get(`${base}/pulls/${pr.number}/comments?per_page=100`);
+            prs.push({ number: pr.number, mergeSha: pr.merge_commit_sha, mergedAt: pr.merged_at, comments: raw.flatMap(c => toComment(pr.number, c)) });
+            if (prs.length >= limit)
+                break;
+        }
+    }
+    return prs;
+}
+/** A review comment where it was written: its original commit and lines. */
+function toComment(prNumber, c) {
+    const end = c.original_line ?? c.line;
+    const commit = c.original_commit_id ?? c.commit_id;
+    if (!c.path || !end || !commit || c.in_reply_to_id)
+        return [];
+    const start = c.original_start_line ?? c.start_line ?? end;
+    return [{ id: String(c.id), prNumber, path: c.path, start: Math.min(start, end), end, commit, body: String(c.body ?? ''), author: String(c.user?.login ?? '') }];
+}