@rigour-labs/core 6.7.2 → 6.7.5

package/dist/review/typed/dead-null-guards.js

@@ -0,0 +1,147 @@
+/** Filters SQL never satisfies with NULL: the column of each, as the query names it. */
+const NON_NULL_FILTERS = new Set(['gt', 'gte', 'lt', 'lte', 'eq', 'in', 'like', 'ilike']);
+export function deadNullGuards(typed, changedSources, h) {
+    const { ts, checker } = typed;
+    const nonNullColumns = (chain) => {
+        const columns = new Set();
+        for (const c of chain) {
+            const col = h.strArg(c.call, 0);
+            if (!col)
+                continue;
+            if (c.name === 'not' && h.strArg(c.call, 1) === 'is' && h.isNullLiteral(c.call.arguments[2]))
+                columns.add(col);
+            else if (NON_NULL_FILTERS.has(c.name) && !h.isNullLiteral(c.call.arguments[1]))
+                columns.add(col);
+        }
+        return columns;
+    };
+    // Every query in the program, by the row type it returns: which columns each guarantees non-null.
+    const byRow = new Map();
+    /**
+     * The named row types a query returns: the type itself, or each named member of an intersection
+     * (`Row & Record<string, unknown>`). A generic's type parameter and a library type are never a row.
+     */
+    const rowSymbols = (t) => {
+        if (!t || t.flags & ts.TypeFlags.TypeParameter)
+            return [];
+        if (t.isIntersection())
+            return t.types.flatMap(rowSymbols);
+        const sym = t.aliasSymbol ?? t.symbol;
+        const decl = sym?.declarations?.[0];
+        return sym && decl && !decl.getSourceFile().isDeclarationFile ? [sym] : [];
+    };
+    for (const sf of typed.appSources) {
+        if (!/\.(from|returns)\b|read[A-Z]\w*</.test(sf.text))
+            continue;
+        h.walk(sf, node => {
+            if (!ts.isCallExpression(node) || !h.outermost(node))
+                return;
+            const chain = h.chainOf(node);
+            if (chain.length === 0 || !startsQuery(chain))
+                return;
+            const columns = nonNullColumns(chain);
+            const touched = chain.some(c => h.touched(c.call.expression.name));
+            for (const sym of rowSymbols(h.rowTypeOf(chain, node))) {
+                const list = byRow.get(sym) ?? [];
+                list.push({ columns, touched, file: sf.fileName, node: chain[0].call });
+                byRow.set(sym, list);
+            }
+        });
+    }
+    // A query starts at `.from(…)`/`.select(…)` (or a bare `from(…)`); `query.or(after)` only continues one already counted.
+    function startsQuery(chain) {
+        if (chain.some(c => /^(from|select|table|selectFrom)$/.test(c.name)))
+            return true;
+        const root = chain[0].call.expression.expression;
+        return ts.isCallExpression(root) && ts.isIdentifier(root.expression) && /^(from|select|table)$/.test(root.expression.text);
+    }
+    for (const [sym, queries] of byRow) {
+        if (!sym.declarations?.length)
+            continue;
+        const type = checker.getDeclaredTypeOfSymbol(sym);
+        for (const prop of checker.getPropertiesOfType(type)) {
+            const decl = prop.declarations?.[0];
+            if (!decl || !ts.isPropertySignature(decl) || !decl.type)
+                continue;
+            const nullable = h.isNullable(checker.getTypeFromTypeNode(decl.type)) || !!decl.questionToken;
+            if (!nullable || !queries.every(q => q.columns.has(prop.name)))
+                continue;
+            if (builtWithout(typed, sym, prop.name, h))
+                continue;
+            const queryFiles = new Set(queries.filter(q => q.touched).map(q => q.file));
+            for (const guard of guardsOn(typed, prop, h)) {
+                if (!h.touched(guard.node) && !queryFiles.has(guard.node.getSourceFile().fileName))
+                    continue;
+                h.report('dead-null-guard', 'Null guard on a column the query makes non-null', guard.node, `\`${guard.text}\` guards \`${prop.name}\`, but ${queries.length === 1 ? 'the only query' : `all ${queries.length} queries`} returning \`${sym.name}\` (${h.at(queries[0].node)}) filter \`${prop.name}\` non-null, so this branch never runs${guard.emptyString ? ' (it still catches an empty string; compare with \'\' if that case is real)' : ''}.`, `Delete the guard, and narrow \`${sym.name}.${prop.name}\` to its non-null type so the next reader sees the guarantee.`);
+            }
+        }
+    }
+}
+/** A null guard on the property: `x.p ?? d`, `x.p?.y`, `x.p == null` / `!== null` / `=== undefined`, `!x.p`, `if (x.p)`, `x.p ? a : b`. */
+function guardsOn(typed, prop, h) {
+    const { ts, checker } = typed;
+    const found = [];
+    const decl = prop.declarations?.[0];
+    const isProp = (access) => {
+        const s = checker.getSymbolAtLocation(access.name);
+        return !!s && (s === prop || s.declarations?.[0] === decl);
+    };
+    const isNullish = (n) => n.kind === ts.SyntaxKind.NullKeyword || (ts.isIdentifier(n) && n.text === 'undefined');
+    for (const sf of typed.appSources) {
+        if (!sf.text.includes(prop.name))
+            continue;
+        h.walk(sf, node => {
+            if (!ts.isPropertyAccessExpression(node) || node.name.text !== prop.name || !isProp(node))
+                return;
+            const p = node.parent;
+            let guard;
+            if (ts.isBinaryExpression(p) && p.left === node && p.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken)
+                guard = p;
+            else if (ts.isPropertyAccessExpression(p) && p.expression === node && p.questionDotToken)
+                guard = p;
+            else if (ts.isBinaryExpression(p) && [ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(p.operatorToken.kind) && (isNullish(p.left === node ? p.right : p.left)))
+                guard = p;
+            else if (ts.isPrefixUnaryExpression(p) && p.operator === ts.SyntaxKind.ExclamationToken)
+                guard = p;
+            else if ((ts.isIfStatement(p) && p.expression === node) || (ts.isConditionalExpression(p) && p.condition === node))
+                guard = node;
+            // A number or boolean column is falsy for 0 or false too: a truthiness test there carries meaning beyond null.
+            // A string one is falsy only for '' besides null; that is reported, with the '' case named.
+            let emptyString = false;
+            if (guard && (ts.isPrefixUnaryExpression(p) || guard === node)) {
+                const t = checker.getNonNullableType(checker.getTypeAtLocation(node));
+                if (t.flags & (ts.TypeFlags.NumberLike | ts.TypeFlags.BooleanLike | ts.TypeFlags.BigIntLike))
+                    guard = undefined;
+                else if (t.flags & ts.TypeFlags.StringLike)
+                    emptyString = true;
+            }
+            if (guard)
+                found.push({ node: guard, text: guard.getText().slice(0, 60), emptyString });
+        });
+    }
+    return found;
+}
+/** An object literal typed as the row that leaves the property out or sets it null: then a null row exists, and the guard is not dead. */
+function builtWithout(typed, sym, name, h) {
+    const { ts, checker } = typed;
+    let built = false;
+    for (const sf of typed.appSources) {
+        if (built || !sf.text.includes(sym.name))
+            continue;
+        h.walk(sf, node => {
+            if (built || !ts.isObjectLiteralExpression(node))
+                return;
+            const ctx = checker.getContextualType(node);
+            // The row type itself, or a type built from it (`Row & Extra`, `Row | Other`).
+            const parts = ctx ? [ctx, ...(ctx.isUnionOrIntersection() ? ctx.types : [])] : [];
+            if (!parts.some(t => (t.aliasSymbol ?? t.symbol) === sym))
+                return;
+            const member = node.properties.find(p => p.name && ts.isIdentifier(p.name) && p.name.text === name);
+            if (node.properties.some(p => ts.isSpreadAssignment(p)))
+                return;
+            if (!member || (ts.isPropertyAssignment(member) && member.initializer.kind === ts.SyntaxKind.NullKeyword))
+                built = true;
+        });
+    }
+    return built;
+}

package/dist/review/typed/redundancy.js

@@ -9,6 +9,8 @@
  *   write-only-property       a property the hosts set and nothing reads. When the value only
  *                             leaves through serialisation to a callee the program does not declare
  *                             (a wire payload), that is a hint for the reviewer, not a block.
+ * Plus dead-null-guard (dead-null-guards.ts): a null guard on a column every query returning the row filters;
+ * constant-member and constant-argument (constant-inputs.ts): an input production never varies.
  * Plus a note, not yet proven on merged pull requests so it never blocks:
  *   nullable-not-null-column  the row type of `.from('t')` says `| null` for a column the
  *                             migrations make NOT NULL (`schema_migrations`, schema-nullability.ts).
@@ -21,6 +23,8 @@ import { emitsDeclarations } from '../package-layout.js';
 import { isTestFile } from '../test-files.js';
 import { loadProgram } from './program.js';
 import { loadSchemaNullability, tableKey } from './schema-nullability.js';
+import { deadNullGuards } from './dead-null-guards.js';
+import { constantInputs } from './constant-inputs.js';
 export const TYPED_CHECKS = 'typed-checks-unavailable';
 /** The typed checks on a change: nothing when it touches no TypeScript or the project has no tsconfig. */
 export function typedChecks(cwd, changedLines, config) {
@@ -147,6 +151,7 @@ function redundancyFailures(typed, changedLines, config) {
             }
         });
     }
+    deadNullGuards(typed, changedSources, { chainOf, outermost, rowTypeOf, strArg, isNullLiteral, isNullable, touched, at, report, walk });
     const declaredTypes = [];
     for (const sf of changedSources) {
         walk(sf, node => {
@@ -214,6 +219,7 @@ function redundancyFailures(typed, changedLines, config) {
         const stem = rel(t.node.getSourceFile()).replace(/\.[cm]?ts$/, '');
         return typed.textFiles.find(s => (word(t.name).test(s.text) || s.text.includes(stem) || s.text.includes(stem.replace(/^src\/lib\//, '$lib/'))) && new RegExp(`\\.${prop}\\b|\\{[^}]*\\b${prop}\\b[^}]*\\}`).test(s.text));
     };
+    constantInputs(typed, changedSources, declaredTypes, { hostsOf, touched, spanTouched, at, rel, report, walk });
     // A value of the type that leaves the program's sight: placed in a string, or passed to a callee the program does not declare.
     const escapeMemo = new Map();
     const escapes = (t) => {

package/dist/review/typed/redundancy.test.js

@@ -119,6 +119,142 @@ export async function scan(since: string): Promise<Row[]> {
         expect(broken.typedError).toMatch(/\.generated\/tsconfig\.json.*install the dependencies/s);
     }, 60_000);
 });
+describe('a null guard on a column the query makes non-null', () => {
+    const SESSION = `import { from } from './db';
+export interface Session { id: string; ended_at: string | null; label: string | null }
+export async function endedSessions(): Promise<Session[]> {
+    return from('sessions').not('ended_at', 'is', null).returns<Session[]>();
+}
+`;
+    const CONSUMER = `import { endedSessions } from './sessions';
+export async function summary(): Promise<string[]> {
+    const rows = await endedSessions();
+    return rows.map(row => {
+        if (row.ended_at == null) return 'open';
+        const ended = row.ended_at ?? 'never';
+        if (!row.label) return ended;
+        return row.label;
+    });
+}
+`;
+    const guards = async () => (await review()).advisory.filter(f => f.id === 'dead-null-guard').map(f => [f.files?.[0], f.line]);
+    it('names each guard the filter made dead, and leaves a guard on a column no query filters alone', async () => {
+        write('src/sessions.ts', SESSION);
+        write('src/summary.ts', CONSUMER);
+        git('add', '-A');
+        git('commit', '-qm', 'sessions');
+        expect(await guards()).toEqual([['src/summary.ts', 5], ['src/summary.ts', 6]]);
+    });
+    it("names a truthiness test on a filtered string column with the empty-string case, and leaves a number's alone", async () => {
+        write('src/sessions.ts', `import { from } from './db';
+export interface Visit { id: string; page: string | null; seconds: number | null }
+export async function visits(): Promise<Visit[]> {
+    return from('visits').not('page', 'is', null).not('seconds', 'is', null).returns<Visit[]>();
+}
+export async function pages(): Promise<string[]> {
+    return (await visits()).filter(v => !!v.page && !v.seconds).map(v => v.page ?? '');
+}
+`);
+        git('add', '-A');
+        git('commit', '-qm', 'visits');
+        const result = (await review()).advisory.filter(f => f.id === 'dead-null-guard');
+        expect(result.map(f => f.line)).toEqual([7, 7]); // \`!v.page\` and \`v.page ?? ''\`, not \`!v.seconds\`
+        expect(result.some(f => /empty string/.test(f.details ?? ''))).toBe(true);
+    });
+    it('follows a query typed through a generic pager and an intersection, and ignores the pager\'s own type parameter', async () => {
+        write('src/pager.ts', `import { from, type Query } from './db';
+export async function readAll<Row>(page: () => Query<unknown>): Promise<Row[]> {
+    await page();
+    return from('audit').returns<Row[]>(); // the helper's own query, typed by its parameter: not a row type
+}
+`);
+        write('src/sessions.ts', `import { from } from './db';
+import { readAll } from './pager';
+export interface Session { id: string; ended_at: string | null }
+export async function endedSessions(): Promise<Session[]> {
+    return readAll<Session & Record<string, unknown>>(() => from('sessions').not('ended_at', 'is', null));
+}
+export async function summary(): Promise<string[]> {
+    return (await endedSessions()).map(row => row.ended_at ?? 'never');
+}
+`);
+        git('add', '-A');
+        git('commit', '-qm', 'pager');
+        expect(await guards()).toEqual([['src/sessions.ts', 8]]);
+    });
+    it('says nothing when another query returns the same rows unfiltered', async () => {
+        write('src/sessions.ts', `${SESSION}export async function allSessions(): Promise<Session[]> {
+    return from('sessions').returns<Session[]>();
+}
+`);
+        write('src/summary.ts', CONSUMER);
+        git('add', '-A');
+        git('commit', '-qm', 'sessions');
+        expect(await guards()).toEqual([]);
+    });
+    it('says nothing when code builds such a row with the column null', async () => {
+        write('src/sessions.ts', `${SESSION}export const draft: Session = { id: 'new', ended_at: null, label: null };
+`);
+        write('src/summary.ts', CONSUMER);
+        git('add', '-A');
+        git('commit', '-qm', 'sessions');
+        expect(await guards()).toEqual([]);
+    });
+});
+describe('an input production never varies', () => {
+    const found = async (id) => (await review()).advisory.filter(f => f.id === id).map(f => [f.files?.[0], f.line]);
+    const commit = () => { git('add', '-A'); git('commit', '-qm', 'change'); };
+    it('names a member every production object sets to the same value while code branches on it; tests do not count', async () => {
+        write('src/jobs.ts', `export interface Job { id: string; retries: number }
+export function next(job: Job): string { return job.retries > 0 ? 'retry' : 'run'; }
+export const nightly: Job = { id: 'nightly', retries: 0 };
+export const hourly: Job = { id: 'hourly', retries: 0 };
+`);
+        write('src/jobs.test.ts', `import { next } from './jobs';
+export const flaky = next({ id: 'flaky', retries: 3 });
+`);
+        commit();
+        expect(await found('constant-member')).toEqual([['src/jobs.ts', 1]]);
+    });
+    it('says nothing when production sets the member differently', async () => {
+        write('src/jobs.ts', `export interface Job { id: string; retries: number }
+export function next(job: Job): string { return job.retries > 0 ? 'retry' : 'run'; }
+export const nightly: Job = { id: 'nightly', retries: 0 };
+export const hourly: Job = { id: 'hourly', retries: 2 };
+`);
+        commit();
+        expect(await found('constant-member')).toEqual([]);
+    });
+    it('names a parameter every production call passes the same literal while the body branches on it', async () => {
+        write('src/format.ts', `export function label(text: string, upper: boolean): string { return upper ? text.toUpperCase() : text; }
+export const a = label('one', false);
+export const b = label('two', false);
+export function wrap(text: string, client: { send(t: string): string }): string { return client.send(text); }
+`);
+        write('src/send.ts', `import { wrap } from './format';
+const client = { send: (t: string) => t };
+export const x = wrap('a', client);
+export const y = wrap('b', client); // the same variable name is not the same literal
+`);
+        write('src/format.test.ts', `import { label } from './format';
+export const loud = label('three', true);
+`);
+        commit();
+        expect(await found('constant-argument')).toEqual([['src/format.ts', 1]]);
+    });
+    it('says nothing when production calls vary, or the function is passed around as a value', async () => {
+        write('src/format.ts', `export function label(text: string, upper: boolean): string { return upper ? text.toUpperCase() : text; }
+export const a = label('one', false);
+export const b = label('two', true);
+export function shout(text: string, loud: boolean): string { return loud ? text + '!' : text; }
+export const c = shout('x', false);
+export const d = shout('y', false);
+export const handlers = [shout];
+`);
+        commit();
+        expect(await found('constant-argument')).toEqual([]);
+    });
+});
 describe('a nullable row type for a NOT NULL column, from migrations in another repository', () => {
     const SUPABASE = `export class Query<T> {
     select(_columns: string): Query<T> { return this; }

package/dist/review/unused-exports.js

@@ -113,7 +113,7 @@ export function unusedExportFailures(cwd, diff, config) {
     const points = pointsAtCache(cwd);
     return candidates
         .filter(exp => ![...(users.get(exp.name) ?? [])].some(user => !isOwnFile(user, exp) && !isTestFile(user) && points(user, exp.file)))
-        .map(unused);
+        .map(exp => unused(exp, !settings.block));
 }
 /**
  * In a project that emits declarations, an exported type named elsewhere in its own file is part
@@ -178,9 +178,10 @@ function filesNaming(cwd, names, excluded) {
     }
     return found;
 }
-function unused(exp) {
+function unused(exp, advisory) {
     return {
         id: 'unused-export',
+        ...(advisory ? { advisory } : {}),
         title: `Unused export \`${exp.name}\``,
         details: `\`${exp.name}\` is exported but no other file uses it (a test is not a consumer). An export nothing imports is dead code that readers and agents treat as part of the module's contract.`,
         severity: 'medium',

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

@@ -9,17 +9,37 @@ export interface ReviewComment {
     commit: string;
     body: string;
     author: string;
+    source?: 'person' | 'bot';
+    prAuthor?: string;
+    /** Whether the lines it points at changed before the merge. */
+    actedOn?: boolean;
+}
+/** A review's body: where a reviewer makes the points that are not about one line. */
+export interface ReviewBody {
+    id: string;
+    prNumber: number;
+    /** The commit the review was written on. */
+    commit: string;
+    body: string;
+    author: string;
+    source?: 'person' | 'bot';
+    prAuthor?: string;
 }
 export interface MergedPr {
     number: number;
     mergeSha: string;
     mergedAt: string;
     comments: ReviewComment[];
+    reviews: ReviewBody[];
 }
 /** 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[];
+/** Every comment whose commit and file can be found, each marked whether its lines changed before the merge. */
+export declare function withActedOn(git: Git, pr: MergedPr): ReviewComment[];
+/** Files the PR changed after a review was written: acted on when there are any. Empty when the commit is unavailable. */
+export declare function changedSince(git: Git, from: string, to: string): string[];
+/** A changed range on the old side, with how many lines it removed and added (a pure insertion removes none). */
+export type Hunk = [start: number, end: number, removed: number, added: number];
 /** 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]>;
+export declare function changedHunks(git: Git, from: string, to: string, file: string): Hunk[];

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

@@ -2,23 +2,34 @@
  * 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.
+ * Acted-on comments are review work the team valued. The learner keeps the
+ * people's by default (a review bot's acted-on comments are mostly one-off fixes,
+ * and on a busy repository they outnumber the people's many times over). 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) {
+/** Every comment whose commit and file can be found, each marked whether its lines changed before the merge. */
+export function withActedOn(git, pr) {
     ensureCommits(git, pr);
-    return pr.comments.filter(comment => {
+    return pr.comments.flatMap(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);
+            return [];
+        const acted = changedHunks(git, comment.commit, pr.mergeSha, comment.path).some(([s, e]) => s <= comment.end && comment.start <= e);
+        return [{ ...comment, actedOn: acted }];
     });
 }
+/** Files the PR changed after a review was written: acted on when there are any. Empty when the commit is unavailable. */
+export function changedSince(git, from, to) {
+    try {
+        return git(['diff', '--name-only', from, to]).split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
 /** Old-side line ranges that changed between two commits in one file. */
 export function changedHunks(git, from, to, file) {
     let diff = '';
@@ -29,17 +40,18 @@ export function changedHunks(git, from, to, file) {
         return [];
     }
     const hunks = [];
-    for (const match of diff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/gm)) {
+    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]);
+        const removed = match[2] === undefined ? 1 : Number(match[2]);
+        const added = match[3] === undefined ? 1 : Number(match[3]);
+        // A pure insertion (removed 0) sits after `start`; it touches that line.
+        hunks.push([start, start + Math.max(removed, 1) - 1, removed, added]);
     }
     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));
+    const missing = [...new Set([...pr.comments.map(c => c.commit), ...pr.reviews.map(r => r.commit)])].filter(sha => !hasCommit(git, sha));
     if (missing.length === 0)
         return;
     try {

package/dist/review-learning/human-edits.d.ts

@@ -0,0 +1,7 @@
+/** Each file as the agent just left it (repository-relative paths). */
+export declare function recordAgentWrites(cwd: string, files: string[]): void;
+/**
+ * The files a person changed since the agent last wrote them, stored as candidate lessons with correction
+ * evidence (the rule writer turns each into the rule behind it, or finds none). Returns how many were taken.
+ */
+export declare function captureHumanEdits(cwd: string, by?: string): number;

package/dist/review-learning/human-edits.js

@@ -0,0 +1,99 @@
+/**
+ * A person editing what an agent wrote is the strongest lesson there is: they corrected the work
+ * toward what the team wants. The after-edit hook records each file as the agent left it
+ * (recordAgentWrites); at the stop and the push, a recorded file that now reads differently was
+ * changed by someone else (captureHumanEdits), and that change becomes a candidate lesson with
+ * correction evidence. A change that came from git (a checkout, a pull) or only moved whitespace
+ * is not a correction. Each edit is taken once. Everything stays in the repository's .rigour/.
+ */
+import crypto from 'crypto';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { compactDiff } from '../review/stories.js';
+import { mergeLessons, readLessons, writeLessons } from './lessons.js';
+const DIR = path.join('.rigour', 'agent-writes');
+const MAX_FILE_BYTES = 200_000;
+/** Lines of the change kept as the lesson's words. */
+const MAX_DIFF_LINES = 12;
+const recordPath = (cwd, file) => path.join(cwd, DIR, `${crypto.createHash('sha256').update(file).digest('hex').slice(0, 16)}.json`);
+const squash = (text) => text.replace(/\s+/g, '');
+function headOf(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function atHead(cwd, file) {
+    try {
+        return execFileSync('git', ['show', `HEAD:${file}`], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 4 * MAX_FILE_BYTES });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Each file as the agent just left it (repository-relative paths). */
+export function recordAgentWrites(cwd, files) {
+    const head = headOf(cwd);
+    for (const file of files) {
+        try {
+            const content = fs.readFileSync(path.join(cwd, file), 'utf8');
+            if (content.length > MAX_FILE_BYTES)
+                continue;
+            fs.mkdirSync(path.join(cwd, DIR), { recursive: true });
+            fs.writeFileSync(recordPath(cwd, file), JSON.stringify({ file, content, ...(head ? { head } : {}), at: new Date().toISOString() }));
+        }
+        catch {
+            // a file the agent deleted or cannot be read: nothing to compare later
+        }
+    }
+}
+/**
+ * The files a person changed since the agent last wrote them, stored as candidate lessons with correction
+ * evidence (the rule writer turns each into the rule behind it, or finds none). Returns how many were taken.
+ */
+export function captureHumanEdits(cwd, by = 'a person') {
+    let entries = [];
+    try {
+        entries = fs.readdirSync(path.join(cwd, DIR));
+    }
+    catch {
+        return 0;
+    }
+    const at = new Date().toISOString();
+    const lessons = [];
+    const head = headOf(cwd);
+    for (const entry of entries) {
+        const record = path.join(cwd, DIR, entry);
+        let write;
+        let now;
+        try {
+            write = JSON.parse(fs.readFileSync(record, 'utf8'));
+            now = fs.readFileSync(path.join(cwd, write.file), 'utf8');
+        }
+        catch {
+            fs.rmSync(record, { force: true });
+            continue;
+        }
+        if (now === write.content)
+            continue;
+        fs.rmSync(record, { force: true }); // taken once, whatever it was
+        if (squash(now) === squash(write.content))
+            continue; // whitespace only
+        if (head && head !== write.head && atHead(cwd, write.file) === now)
+            continue; // came from git: a checkout, a pull, a merge
+        const diff = compactDiff(write.content, now).slice(0, MAX_DIFF_LINES).join('\n');
+        const text = `In ${write.file}, a person changed what the agent wrote:\n${diff}`;
+        lessons.push({
+            id: crypto.createHash('sha256').update(`${write.file}\u0000${diff}`).digest('hex').slice(0, 12),
+            text, file: write.file, symbols: [], state: 'candidate',
+            evidence: [{ kind: 'correction', pr: 0, comment: `edit-${crypto.createHash('sha256').update(`${write.file}${write.at}`).digest('hex').slice(0, 12)}`, author: by, text, detail: `edited after the agent's write of ${write.at}`, at }],
+            createdAt: at, updatedAt: at,
+        });
+    }
+    if (lessons.length)
+        writeLessons(cwd, mergeLessons(readLessons(cwd), lessons).lessons);
+    return lessons.length;
+}

package/dist/review-learning/human-edits.test.d.ts

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

package/dist/review-learning/human-edits.test.js

@@ -0,0 +1,47 @@
+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 { captureHumanEdits, recordAgentWrites } from './human-edits.js';
+import { readLessons } from './lessons.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const write = (body) => fs.writeFileSync(path.join(repo, 'src/job.ts'), body);
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'human-edits-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    fs.mkdirSync(path.join(repo, 'src'));
+    write('export function job(rows) {\n  return rows.map(r => r.id);\n}\n');
+    git('add', '-A');
+    git('commit', '-qm', 'base');
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('a person editing what the agent wrote', () => {
+    it('becomes a lesson with correction evidence, taken once', () => {
+        write('export function job(rows) {\n  return rows.slice(0, 10000).map(r => r.id);\n}\n'); // the agent's write
+        recordAgentWrites(repo, ['src/job.ts']);
+        write('export function job(rows, after) {\n  return rows.filter(r => r.id > after).slice(0, 500).map(r => r.id);\n}\n'); // the person's fix
+        expect(captureHumanEdits(repo, 'lead@acme')).toBe(1);
+        const [lesson] = readLessons(repo);
+        expect(lesson).toMatchObject({ file: 'src/job.ts', state: 'verified', promotedBy: 'correction' });
+        expect(lesson.text).toContain('a person changed what the agent wrote');
+        expect(lesson.text).toContain('+  return rows.filter(r => r.id > after).slice(0, 500).map(r => r.id);');
+        expect(lesson.evidence[0]).toMatchObject({ kind: 'correction', author: 'lead@acme' });
+        expect(captureHumanEdits(repo, 'lead@acme')).toBe(0); // taken once
+    });
+    it('is not a correction when only whitespace moved, or the change came from git', () => {
+        recordAgentWrites(repo, ['src/job.ts']);
+        write('export function job(rows) {\n    return rows.map(r => r.id);\n}\n'); // a formatter
+        expect(captureHumanEdits(repo)).toBe(0);
+        recordAgentWrites(repo, ['src/job.ts']);
+        git('checkout', '-q', '-b', 'other');
+        write('export const job = (rows) => rows.map(r => r.id);\n');
+        git('commit', '-qam', 'someone else\'s branch');
+        expect(captureHumanEdits(repo)).toBe(0); // a checkout brought it, not a person correcting the agent
+        expect(readLessons(repo)).toEqual([]);
+    });
+});