@rigour-labs/core 6.3.1 → 6.4.1

package/dist/review/effectiveness.js

@@ -0,0 +1,114 @@
+/**
+ * Is the review loop working? Computed from the local event log
+ * (`.rigour/events.jsonl`, written by the MCP server and the stop hook), so
+ * nothing leaves the machine.
+ *
+ * - a finding is resolved when a later review no longer reports it (same rule, same file);
+ * - a blocked stop is followed through when the same session later stops cleanly;
+ * - a self-review is a rigour_review call made before an attempt to stop.
+ */
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+const EVENTS = path.join('.rigour', 'events.jsonl');
+export function readAgentEvents(cwd) {
+    let text = '';
+    try {
+        text = fs.readFileSync(path.join(cwd, EVENTS), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return text.split('\n').filter(Boolean).flatMap(line => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** Append an event in the same format the MCP server writes; never throws. */
+export function appendAgentEvent(cwd, event) {
+    try {
+        fs.mkdirSync(path.join(cwd, '.rigour'), { recursive: true });
+        fs.appendFileSync(path.join(cwd, EVENTS), JSON.stringify({ id: randomUUID(), timestamp: new Date().toISOString(), ...event }) + '\n');
+    }
+    catch {
+        // The event log is best-effort; it must never break a hook or a tool call.
+    }
+}
+/** `rule:file` keys, so a finding that moved lines is still the same finding. */
+export function findingKeys(findings) {
+    return findings.map(f => `${f.id ?? '?'}:${f.file ?? '?'}`);
+}
+export function computeEffectiveness(events) {
+    const stats = {
+        toolCalls: {}, reviews: 0, failedReviews: 0, findingsReported: 0, findingsResolved: 0,
+        stopChecks: 0, stopBlocks: 0, blockedStopsFollowedThrough: 0, stopsWithSelfReview: 0,
+    };
+    const open = new Set();
+    const blockedSessions = new Set();
+    let reviewedSinceStop = false;
+    for (const event of events) {
+        if (event.type === 'tool_call' && event.tool) {
+            stats.toolCalls[event.tool] = (stats.toolCalls[event.tool] ?? 0) + 1;
+            if (event.tool === 'rigour_review')
+                reviewedSinceStop = true;
+        }
+        else if (event.type === 'tool_response' && event.tool === 'rigour_review') {
+            countReview(stats, open, reviewKeys(event));
+        }
+        else if (event.type === 'stop_review') {
+            countStop(stats, blockedSessions, event, reviewedSinceStop);
+            reviewedSinceStop = false;
+        }
+    }
+    return stats;
+}
+function countReview(stats, open, keys) {
+    if (keys === null)
+        return;
+    stats.reviews++;
+    if (keys.length)
+        stats.failedReviews++;
+    const now = new Set(keys);
+    for (const key of [...open]) {
+        if (!now.has(key)) {
+            open.delete(key);
+            stats.findingsResolved++;
+        }
+    }
+    for (const key of now) {
+        if (!open.has(key)) {
+            open.add(key);
+            stats.findingsReported++;
+        }
+    }
+}
+function countStop(stats, blockedSessions, event, selfReviewed) {
+    const session = event.session ?? 'default';
+    stats.stopChecks++;
+    if (selfReviewed)
+        stats.stopsWithSelfReview++;
+    if (event.blocked) {
+        stats.stopBlocks++;
+        blockedSessions.add(session);
+    }
+    else if (blockedSessions.delete(session)) {
+        stats.blockedStopsFollowedThrough++;
+    }
+}
+/** Finding keys from a rigour_review response, or null when it is not a review result. */
+function reviewKeys(event) {
+    const text = event.content?.find(c => c.type === 'text')?.text;
+    if (!text)
+        return null;
+    try {
+        const body = JSON.parse(text);
+        return Array.isArray(body.failures) ? findingKeys(body.failures) : null;
+    }
+    catch {
+        return null;
+    }
+}

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

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

package/dist/review/effectiveness.test.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+import { appendAgentEvent, computeEffectiveness, readAgentEvents } from './effectiveness.js';
+const review = (failures) => [
+    { type: 'tool_call', tool: 'rigour_review' },
+    { type: 'tool_response', tool: 'rigour_review', content: [{ type: 'text', text: JSON.stringify({ status: failures.length ? 'FAIL' : 'PASS', failures }) }] },
+];
+describe('computeEffectiveness', () => {
+    it('counts reviews, findings resolved by later reviews, and tool calls', () => {
+        const events = [
+            { type: 'tool_call', tool: 'rigour_recall' },
+            ...review([{ id: 'semantic-bugs', file: 'a.ts' }, { id: 'promise-safety', file: 'b.ts' }]),
+            ...review([{ id: 'promise-safety', file: 'b.ts' }]),
+            ...review([]),
+        ];
+        expect(computeEffectiveness(events)).toMatchObject({
+            reviews: 3, failedReviews: 2, findingsReported: 2, findingsResolved: 2,
+            toolCalls: { rigour_recall: 1, rigour_review: 3 },
+        });
+    });
+    it('follows a blocked stop through to a clean stop in the same session, and counts self-reviews', () => {
+        const events = [
+            { type: 'stop_review', session: 's1', blocked: true },
+            ...review([]),
+            { type: 'stop_review', session: 's1', blocked: false },
+            { type: 'stop_review', session: 's2', blocked: false },
+        ];
+        expect(computeEffectiveness(events)).toMatchObject({
+            stopChecks: 3, stopBlocks: 1, blockedStopsFollowedThrough: 1, stopsWithSelfReview: 1,
+        });
+    });
+    it('reads the log it writes and skips malformed lines', () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'effectiveness-'));
+        appendAgentEvent(dir, { type: 'stop_review', blocked: true });
+        fs.appendFileSync(path.join(dir, '.rigour', 'events.jsonl'), 'not json\n');
+        expect(readAgentEvents(dir).map(e => e.type)).toEqual(['stop_review']);
+        expect(readAgentEvents(path.join(dir, 'missing'))).toEqual([]);
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+});

package/dist/review/git-diff.d.ts

@@ -0,0 +1,9 @@
+export type DiffSource = {
+    mode: 'working';
+} | {
+    mode: 'base';
+    base: string;
+};
+export declare class GitDiffError extends Error {
+}
+export declare function diffFromGit(cwd: string, source?: DiffSource): string;

package/dist/review/git-diff.js

@@ -0,0 +1,42 @@
+/**
+ * The diff to review, taken from git so callers do not have to build one.
+ *
+ * - working: uncommitted changes against HEAD, staged or not, plus new files
+ *   git does not track yet (what an agent has just written).
+ * - base: everything on this branch since it left `base` (the merge-base),
+ *   including uncommitted changes (what a pull request contains).
+ */
+import { spawnSync } from 'child_process';
+export class GitDiffError extends Error {
+}
+export function diffFromGit(cwd, source = { mode: 'working' }) {
+    if (source.mode === 'base') {
+        const mergeBase = git(cwd, ['merge-base', source.base, 'HEAD']).trim();
+        return git(cwd, ['diff', '--no-color', '--no-ext-diff', mergeBase]);
+    }
+    const tracked = hasHead(cwd) ? git(cwd, ['diff', '--no-color', '--no-ext-diff', 'HEAD']) : '';
+    return tracked + untrackedFiles(cwd).map(file => newFileDiff(cwd, file)).join('');
+}
+function untrackedFiles(cwd) {
+    return git(cwd, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean);
+}
+/** `git diff --no-index` exits 1 when the files differ, which for a new file is always. */
+function newFileDiff(cwd, file) {
+    const result = spawnSync('git', ['diff', '--no-color', '--no-ext-diff', '--no-index', '--', '/dev/null', file], {
+        cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.status !== 0 && result.status !== 1)
+        throw new GitDiffError(`git diff for new file ${file} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}
+function hasHead(cwd) {
+    return spawnSync('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd }).status === 0;
+}
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (result.error)
+        throw new GitDiffError(`git is not available: ${result.error.message}`);
+    if (result.status !== 0)
+        throw new GitDiffError(`git ${args.join(' ')} failed: ${result.stderr.trim()}`);
+    return result.stdout;
+}

package/dist/review/review.d.ts

@@ -0,0 +1,38 @@
+import type { Config, DeepOptions, Failure, Report } from '../types/index.js';
+import { type DiffSource } from './git-diff.js';
+export interface ReviewInput {
+    cwd: string;
+    config: Config;
+    /** A unified diff; when omitted, it is taken from git (`source`). */
+    diff?: string;
+    source?: DiffSource;
+    /** Review exactly these files instead of the ones the diff touches. */
+    files?: string[];
+    /** 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'>;
+}
+export interface ReviewResult {
+    status: 'PASS' | 'FAIL' | 'ERROR';
+    findings: Failure[];
+    fileFindings: Failure[];
+    unlocated: number;
+    excludedOutsideChangedLines: number;
+    changedLines: Record<string, Set<number>>;
+    report: Report | null;
+    deepError?: string;
+}
+export interface ReviewFinding {
+    id: string;
+    gate: string;
+    severity: string;
+    provenance: string;
+    message: string;
+    file: string;
+    line: number | null;
+    suggestion?: string;
+}
+export declare function reviewChange(input: ReviewInput): Promise<ReviewResult>;
+/** The JSON shape of a finding, shared by the CLI's --json and the MCP tool. */
+export declare function toReviewFinding(failure: Failure): ReviewFinding;

package/dist/review/review.js

@@ -0,0 +1,52 @@
+/**
+ * reviewChange: the one review engine behind `rigour review`, the MCP
+ * `rigour_review` tool and the GitHub integration.
+ *
+ * Runs the configured gates on the files a change touches and keeps what
+ * belongs to the change (see changed-lines.ts). A deep run that was asked for
+ * but could not analyze anything makes the result ERROR, never a clean PASS.
+ */
+import { GateRunner } from '../gates/runner.js';
+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 { 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 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 };
+    }
+    const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(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 deepError = deepAnalysisError(report);
+    return {
+        status: deepError ? 'ERROR' : split.findings.length > 0 ? 'FAIL' : 'PASS',
+        findings: split.findings,
+        fileFindings: split.fileFindings,
+        unlocated: split.unlocated,
+        excludedOutsideChangedLines: split.outside,
+        changedLines,
+        report,
+        ...(deepError ? { deepError } : {}),
+    };
+}
+/** The JSON shape of a finding, shared by the CLI's --json and the MCP tool. */
+export function toReviewFinding(failure) {
+    return {
+        id: failure.id,
+        gate: failure.title,
+        severity: failure.severity || 'medium',
+        provenance: failure.provenance || 'traditional',
+        message: failure.details,
+        file: failure.files?.[0] || '',
+        line: failure.line ?? null,
+        ...(failure.hint ? { suggestion: failure.hint } : {}),
+    };
+}

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

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

package/dist/review/review.test.js

@@ -0,0 +1,87 @@
+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 { ConfigSchema } from '../types/index.js';
+import { parseDiff } from '../utils/diff.js';
+import { splitByChangedLines } from './changed-lines.js';
+import { diffFromGit } from './git-diff.js';
+import { reviewChange, toReviewFinding } from './review.js';
+const LEAKY = [
+    'export async function notify(endpoint: string, signature: string) {',
+    "  return fetch(endpoint, { method: 'POST', headers: { 'x-hook-signature': signature } });",
+    '}',
+    '',
+].join('\n');
+function failure(file, line) {
+    return { id: 'x', title: 'X', details: 'd', files: file ? [file] : [], ...(line !== undefined ? { line } : {}) };
+}
+describe('splitByChangedLines', () => {
+    it('separates changed-line, file-level, unlocated and outside findings', () => {
+        const changed = { 'a.ts': new Set([3]) };
+        const split = splitByChangedLines([failure('a.ts', 3), failure('a.ts', 9), failure('a.ts'), failure('b.ts'), failure(undefined)], changed);
+        expect(split.findings.map(f => f.line)).toEqual([3]);
+        expect(split.fileFindings).toHaveLength(1);
+        expect(split.unlocated).toBe(1);
+        expect(split.outside).toBe(2);
+    });
+});
+describe('git-backed review', () => {
+    let repo;
+    const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
+    const write = (rel, body) => {
+        fs.mkdirSync(path.dirname(path.join(repo, rel)), { recursive: true });
+        fs.writeFileSync(path.join(repo, rel), body);
+    };
+    beforeEach(() => {
+        repo = fs.mkdtempSync(path.join(os.tmpdir(), 'review-core-'));
+        git('init', '-q', '-b', 'main');
+        git('config', 'user.email', 't@example.com');
+        git('config', 'user.name', 't');
+        git('config', 'commit.gpgsign', 'false');
+    });
+    afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+    it('works in a repository with no commits yet', () => {
+        write('src/new.ts', 'export const a = 1;\n');
+        expect(parseDiff(diffFromGit(repo))).toEqual({ 'src/new.ts': new Set([1]) });
+    });
+    it('takes uncommitted edits and untracked files from the working tree', () => {
+        write('src/a.ts', 'export const a = 1;\nexport const b = 2;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        write('src/a.ts', 'export const a = 1;\nexport const b = 3;\n');
+        write('src/new.ts', 'export const c = 1;\nexport const d = 2;\n');
+        expect(parseDiff(diffFromGit(repo))).toEqual({ 'src/a.ts': new Set([2]), 'src/new.ts': new Set([1, 2]) });
+    });
+    it('takes a branch against its merge-base, committed and uncommitted', () => {
+        write('src/a.ts', 'export const a = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        git('checkout', '-q', '-b', 'feature');
+        write('src/b.ts', 'export const b = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'feature');
+        write('src/a.ts', 'export const a = 1;\nexport const z = 2;\n');
+        expect(parseDiff(diffFromGit(repo, { mode: 'base', base: 'main' }))).toEqual({ 'src/a.ts': new Set([2]), 'src/b.ts': new Set([1]) });
+    });
+    it('fails a change that introduces a bug and ignores the same bug in untouched code', async () => {
+        write('src/old.ts', LEAKY);
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        write('src/notify.ts', LEAKY);
+        const config = ConfigSchema.parse({ version: 1, gates: { semantic_bugs: { enabled: true } } });
+        const result = await reviewChange({ cwd: repo, config });
+        const semantic = result.findings.filter(f => f.id === 'semantic-bugs');
+        expect(result.status).toBe('FAIL');
+        expect(semantic.map(f => [f.files?.[0], f.line])).toEqual([['src/notify.ts', 2]]);
+        expect(toReviewFinding(semantic[0])).toMatchObject({ id: 'semantic-bugs', file: 'src/notify.ts', line: 2, severity: 'high' });
+    });
+    it('passes when nothing changed', async () => {
+        write('src/a.ts', 'export const a = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        const result = await reviewChange({ cwd: repo, config: ConfigSchema.parse({ version: 1 }) });
+        expect(result).toMatchObject({ status: 'PASS', findings: [], report: null });
+    });
+});

package/dist/semantic/benchmark.js

@@ -6,7 +6,7 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { analyzeFiles } from './engine.js';
+import { ALL_RULES, analyzeFiles } from './engine.js';
 export function loadCases(root) {
     return fs.readdirSync(root, { withFileTypes: true })
         .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, 'case.json')))
@@ -27,5 +27,5 @@ function findingsIn(dir) {
     if (!fs.existsSync(dir))
         return [];
     const files = fs.readdirSync(dir).filter(f => /\.[cm]?[jt]sx?$/.test(f));
-    return analyzeFiles(dir, files).map(f => `${f.rule} ${f.file}:${f.line}`);
+    return analyzeFiles(dir, files, { rules: ALL_RULES }).map(f => `${f.rule} ${f.file}:${f.line}`);
 }

package/dist/semantic/benchmark.test.js

@@ -1,12 +1,16 @@
 import path from 'path';
 import { describe, expect, it } from 'vitest';
+import { CANDIDATE_RULES, ECOSYSTEM_RULES } from './rules/ecosystem/index.js';
 import { loadCases, runCase } from './benchmark.js';
 const ROOT = path.resolve(__dirname, '../../../../benchmarks/semantic');
 describe('semantic benchmark', () => {
     const cases = loadCases(ROOT);
     it('has cases for every built-in rule, including negatives', () => {
         const rules = new Set(cases.map(c => c.rule));
-        expect(rules).toEqual(new Set(['in-memory-aggregation', 'credential-redirect', 'degraded-response-cached', null]));
+        expect(rules).toEqual(new Set([
+            'in-memory-aggregation', 'credential-redirect', 'degraded-response-cached',
+            ...[...ECOSYSTEM_RULES, ...CANDIDATE_RULES].map(rule => rule.id), null,
+        ]));
     });
     for (const bench of cases) {
         it(`${bench.name}: ${bench.note}`, () => {

package/dist/semantic/engine.d.ts

@@ -1,5 +1,8 @@
 import type { SemanticFinding, SemanticRule } from './types.js';
+/** Rules that run by default. */
 export declare const BUILT_IN_RULES: SemanticRule[];
+/** Every rule Rigour ships, candidates included: what can be named to run. */
+export declare const ALL_RULES: SemanticRule[];
 export interface EngineOptions {
     rules?: SemanticRule[];
     batchSize?: number;

package/dist/semantic/engine.js

@@ -3,11 +3,16 @@
  */
 import path from 'path';
 import { loadProjectConfig, programBatches } from './program.js';
+import { ProjectFacts } from './project-facts.js';
 import { Summaries } from './summaries.js';
 import { inMemoryAggregation } from './rules/in-memory-aggregation.js';
 import { credentialRedirect } from './rules/credential-redirect.js';
 import { degradedResponseCached } from './rules/degraded-response-cached.js';
-export const BUILT_IN_RULES = [inMemoryAggregation, credentialRedirect, degradedResponseCached];
+import { CANDIDATE_RULES, ECOSYSTEM_RULES } from './rules/ecosystem/index.js';
+/** Rules that run by default. */
+export const BUILT_IN_RULES = [inMemoryAggregation, credentialRedirect, degradedResponseCached, ...ECOSYSTEM_RULES];
+/** Every rule Rigour ships, candidates included: what can be named to run. */
+export const ALL_RULES = [...BUILT_IN_RULES, ...CANDIDATE_RULES];
 /** Analyze `files` (cwd-relative or absolute). Declaration files are skipped. */
 export function analyzeFiles(cwd, files, opts = {}) {
     const rules = opts.rules ?? BUILT_IN_RULES;
@@ -19,6 +24,7 @@ export function analyzeFiles(cwd, files, opts = {}) {
     const { options } = loadProjectConfig(cwd);
     const rootSet = new Set(roots.map(r => path.normalize(r)));
     const findings = [];
+    const project = new ProjectFacts(cwd);
     for (const program of programBatches(roots, options, opts.batchSize)) {
         const checker = program.getTypeChecker();
         const summaries = new Summaries(checker);
@@ -26,7 +32,7 @@ export function analyzeFiles(cwd, files, opts = {}) {
             if (!rootSet.has(path.normalize(sourceFile.fileName)))
                 continue;
             for (const rule of rules) {
-                findings.push(...rule.check({ cwd, checker, sourceFile, summaries }));
+                findings.push(...rule.check({ cwd, program, checker, sourceFile, summaries, project }));
             }
             rootSet.delete(path.normalize(sourceFile.fileName));
         }

package/dist/semantic/failure-handling.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Does a call handle its own failure? Shared by the intent checks and the
+ * training-site export, so both see a call the same way.
+ */
+import ts from 'typescript';
+import { type FunctionLike } from './ast.js';
+export declare function isPromiseAll(call: ts.CallExpression): boolean;
+export declare function isPromiseAllSettled(call: ts.CallExpression): boolean;
+/** Inside a `try` (with a catch) of the same function: the rejection is handled there. */
+export declare function isInsideTry(node: ts.Node, fn: FunctionLike): boolean;
+/** `x().catch(...)`, `x().then(ok, fail)`, or a callee whose body catches and returns. */
+export declare function handlesOwnFailure(checker: ts.TypeChecker, call: ts.CallExpression): boolean;

package/dist/semantic/failure-handling.js

@@ -0,0 +1,41 @@
+/**
+ * Does a call handle its own failure? Shared by the intent checks and the
+ * training-site export, so both see a call the same way.
+ */
+import ts from 'typescript';
+import { calledFunction } from './ast.js';
+export function isPromiseAll(call) {
+    return isPromiseMethod(call, 'all');
+}
+export function isPromiseAllSettled(call) {
+    return isPromiseMethod(call, 'allSettled');
+}
+function isPromiseMethod(call, name) {
+    const callee = call.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === name
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'Promise';
+}
+/** Inside a `try` (with a catch) of the same function: the rejection is handled there. */
+export function isInsideTry(node, fn) {
+    for (let child = node, parent = node.parent; parent && parent !== fn; child = parent, parent = parent.parent) {
+        if (ts.isTryStatement(parent) && parent.tryBlock === child && parent.catchClause)
+            return true;
+    }
+    return false;
+}
+/** `x().catch(...)`, `x().then(ok, fail)`, or a callee whose body catches and returns. */
+export function handlesOwnFailure(checker, call) {
+    const callee = call.expression;
+    if (ts.isPropertyAccessExpression(callee)) {
+        if (callee.name.text === 'catch' || callee.name.text === 'finally')
+            return true;
+        if (callee.name.text === 'then' && call.arguments.length >= 2)
+            return true;
+    }
+    const target = calledFunction(checker, call);
+    const body = target?.body;
+    return !!body && ts.isBlock(body) && body.statements.some(s => ts.isTryStatement(s) && !!s.catchClause && catchReturns(s.catchClause));
+}
+function catchReturns(clause) {
+    return clause.block.statements.some(s => ts.isReturnStatement(s));
+}

package/dist/semantic/intent/parallel-reads.js

@@ -7,7 +7,8 @@
  * which the code cannot say; see intent-check.ts.
  */
 import ts from 'typescript';
-import { calledFunction, enclosingFunction, forEachNode, lineOf, relativeFile, unwrap } from '../ast.js';
+import { enclosingFunction, forEachNode, lineOf, relativeFile, unwrap } from '../ast.js';
+import { handlesOwnFailure, isInsideTry, isPromiseAll } from '../failure-handling.js';
 import { promiseAllItems } from '../origins.js';
 import { functionKeyOf } from '../learn/identity.js';
 export function findParallelReads(cwd, checker, sourceFile) {
@@ -28,32 +29,3 @@ export function findParallelReads(cwd, checker, sourceFile) {
     });
     return sites;
 }
-function isPromiseAll(call) {
-    const callee = call.expression;
-    return ts.isPropertyAccessExpression(callee) && callee.name.text === 'all'
-        && ts.isIdentifier(callee.expression) && callee.expression.text === 'Promise';
-}
-/** Inside a `try` (with a catch) of the same function: the rejection is handled there. */
-function isInsideTry(node, fn) {
-    for (let child = node, parent = node.parent; parent && parent !== fn; child = parent, parent = parent.parent) {
-        if (ts.isTryStatement(parent) && parent.tryBlock === child && parent.catchClause)
-            return true;
-    }
-    return false;
-}
-/** `x().catch(...)`, `x().then(ok, fail)`, or a callee whose body catches and returns. */
-function handlesOwnFailure(checker, call) {
-    const callee = call.expression;
-    if (ts.isPropertyAccessExpression(callee)) {
-        if (callee.name.text === 'catch' || callee.name.text === 'finally')
-            return true;
-        if (callee.name.text === 'then' && call.arguments.length >= 2)
-            return true;
-    }
-    const target = calledFunction(checker, call);
-    const body = target?.body;
-    return !!body && ts.isBlock(body) && body.statements.some(s => ts.isTryStatement(s) && !!s.catchClause && catchReturns(s.catchClause));
-}
-function catchReturns(clause) {
-    return clause.block.statements.some(s => ts.isReturnStatement(s));
-}

package/dist/semantic/learn/learn.d.ts

@@ -23,3 +23,5 @@ export interface LearnReport {
     }>;
 }
 export declare function learnFromFix(input: LearnInput): Promise<LearnReport>;
+/** Learn from one file's before and after (e.g. an agent's fix), validated against the repository at `repoDir`. */
+export declare function learnFromFileChange(repoDir: string, file: string, before: string, after: string, maxHits?: number): Promise<LearnReport>;

package/dist/semantic/learn/learn.js

@@ -8,6 +8,8 @@
  * reported with the reason the most specific one failed.
  */
 import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { globby } from 'globby';
 import { analyzeFiles } from '../engine.js';
@@ -47,6 +49,22 @@ export async function learnFromFix(input) {
     }
     return report;
 }
+/** Learn from one file's before and after (e.g. an agent's fix), validated against the repository at `repoDir`. */
+export async function learnFromFileChange(repoDir, file, before, after, maxHits) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-learn-'));
+    try {
+        const place = (tree, content) => {
+            const target = path.join(root, tree, file);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, content);
+            return path.join(root, tree);
+        };
+        return await learnFromFix({ beforeDir: place('before', before), afterDir: place('after', after), repoDir, files: [file], maxHits });
+    }
+    finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+}
 function openTree(cwd, file) {
     const root = path.join(cwd, file);
     const [program] = [...programBatches([root], loadProjectConfig(cwd).options)];

package/dist/semantic/project-facts.d.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+export declare class ProjectFacts {
+    private readonly cwd;
+    private readonly packages;
+    private readonly options;
+    constructor(cwd: string);
+    /** Declared dependency names and version ranges of the package that owns `file`. */
+    dependencies(file: string): Map<string, string>;
+    /** Directory of the package.json that owns `file`. */
+    packageDir(file: string): string | undefined;
+    /** The `name` of the package that owns `file`. */
+    packageName(file: string): string | undefined;
+    declares(file: string, ...names: string[]): boolean;
+    /**
+     * Highest major version a declared dependency may run on, across every field
+     * and `||` alternative (`>=18.0.0 || >=19.0.0` -> 19). A package that supports
+     * a major must work on it. Undefined when no range names a version (`catalog:`, `workspace:*`).
+     */
+    majorVersion(file: string, name: string): number | undefined;
+    /** Compiler options of the nearest tsconfig.json above `file`, extends resolved. */
+    compilerOptions(file: string): ts.CompilerOptions;
+    private dirsUp;
+    private nearestPackage;
+    private readPackage;
+}