@rigour-labs/core 6.6.1 → 6.6.3

package/dist/review/baseline.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { splitIntroduced } from './baseline.js';
+const finding = (file, title, details = 'd') => ({ id: 'AST_COMPLEXITY', title, details, files: [file] });
+describe('splitIntroduced', () => {
+    it("drops what the base already had, even when the change moved its numbers", () => {
+        const base = { failures: [finding('a.ts', "Function 'f' has complexity of 105 (max: 10)", 'L12: x')], added: new Set() };
+        const head = [finding('a.ts', "Function 'f' has complexity of 109 (max: 10)", 'L19: x'), finding('a.ts', "Function 'g' has complexity of 11 (max: 10)")];
+        const split = splitIntroduced(head, base);
+        expect(split.preexisting.map(f => f.title)).toEqual(["Function 'f' has complexity of 109 (max: 10)"]);
+        expect(split.introduced.map(f => f.title)).toEqual(["Function 'g' has complexity of 11 (max: 10)"]);
+    });
+    it('matches each base finding once, so a second copy of an old problem is new', () => {
+        const old = finding('a.ts', 'Unhandled promise', 'L3: then');
+        const split = splitIntroduced([old, finding('a.ts', 'Unhandled promise', 'L9: then')], { failures: [old], added: new Set() });
+        expect(split.preexisting).toHaveLength(1);
+        expect(split.introduced).toHaveLength(1);
+    });
+    it('never treats a finding in a file the change adds as old', () => {
+        const f = finding('new.ts', 'Naming drift');
+        expect(splitIntroduced([f], { failures: [f], added: new Set(['new.ts']) }).introduced).toEqual([f]);
+    });
+});

package/dist/review/branch-checks.d.ts

@@ -0,0 +1,6 @@
+import type { Config, Failure } from '../types/index.js';
+export declare function branchFailures(cwd: string, base: string, mainRef: string, config: Config): Failure[];
+/** Files that conflict when the branch merges into `mainRef`; empty when it merges cleanly or git cannot say. */
+export declare function mergeConflicts(cwd: string, mainRef: string): Failure[];
+/** Places that still name a file the branch deleted (since `base`). */
+export declare function staleReferences(cwd: string, base: string, config: Config): Failure[];

package/dist/review/branch-checks.js

@@ -0,0 +1,83 @@
+/**
+ * Checks on a branch as a whole, not on the lines it changed, run before an agent stops or pushes:
+ *
+ * - merge-conflict: the branch no longer merges cleanly into main. A reviewer cannot approve it,
+ *   and CI on the merge result never runs. `git merge-tree --write-tree` (git 2.38+) answers without
+ *   touching the working tree; its exit status, not `--quiet`, says whether it conflicts.
+ * - stale-reference: a file the branch deleted is still named in another file (a comment, a doc,
+ *   a script), so the next reader follows a path that no longer exists.
+ *
+ * Both are certain, so both block; neither reads beyond git and the files it names.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { ownOutputs } from './unused-exports.js';
+const GIT_TIMEOUT_MS = 30_000;
+/** Files a deleted path can still be named in: code, docs, config and scripts. */
+const MENTIONER = /\.(ts|tsx|js|jsx|mjs|cjs|svelte|md|mdx|json|ya?ml|toml|sh)$/;
+export function branchFailures(cwd, base, mainRef, config) {
+    return [...mergeConflicts(cwd, mainRef), ...staleReferences(cwd, base, config)];
+}
+/** Files that conflict when the branch merges into `mainRef`; empty when it merges cleanly or git cannot say. */
+export function mergeConflicts(cwd, mainRef) {
+    const result = spawnSync('git', ['merge-tree', '--write-tree', '--name-only', '--no-messages', 'HEAD', mainRef], { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+    if (result.status !== 1)
+        return []; // 0: clean; anything else: git too old or the refs unknown
+    const files = result.stdout.split('\n').slice(1).map(line => line.trim()).filter(Boolean);
+    const main = mainRef.replace(/^refs\/(remotes\/|heads\/)/, '');
+    return [...new Set(files)].map(file => ({
+        id: 'merge-conflict',
+        title: 'Merge conflict',
+        details: `\`${file}\` conflicts with \`${main}\`: the branch no longer merges cleanly.`,
+        severity: 'high',
+        provenance: 'traditional',
+        files: [file],
+        line: 1,
+        hint: `Merge or rebase onto \`${main}\` and resolve \`${file}\`.`,
+    }));
+}
+/** Places that still name a file the branch deleted (since `base`). */
+export function staleReferences(cwd, base, config) {
+    const deleted = git(cwd, ['diff', '--name-only', '--diff-filter=D', base])?.split('\n').filter(Boolean) ?? [];
+    if (deleted.length === 0)
+        return [];
+    const own = ownOutputs(config);
+    const files = git(cwd, ['ls-files', '--cached', '--others', '--exclude-standard'])?.split('\n')
+        .filter(file => file && MENTIONER.test(file) && !own.some(o => file === o || file.startsWith(`${o}/`))) ?? [];
+    // The whole path, not a prefix of a longer one: a deleted `src/a.ts` is not `src/a.tsx`.
+    const mentions = deleted.map(gone => [gone, new RegExp(`(?<![\\w./-])${gone.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w./-])`)]);
+    const failures = [];
+    for (const file of files) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(cwd, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split('\n');
+        for (const [gone, pattern] of mentions) {
+            const index = lines.findIndex(line => pattern.test(line));
+            if (index >= 0)
+                failures.push(stale(file, index + 1, gone));
+        }
+    }
+    return failures;
+}
+function stale(file, line, gone) {
+    return {
+        id: 'stale-reference',
+        title: 'Reference to a deleted file',
+        details: `\`${file}\` still names \`${gone}\`, which this branch deleted.`,
+        severity: 'medium',
+        provenance: 'traditional',
+        files: [file],
+        line,
+        hint: `Update or remove the mention of \`${gone}\`.`,
+    };
+}
+function git(cwd, args) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+    return result.status === 0 ? result.stdout : undefined;
+}

package/dist/review/branch-checks.test.d.ts

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

package/dist/review/branch-checks.test.js

@@ -0,0 +1,48 @@
+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 { mergeConflicts, staleReferences } from './branch-checks.js';
+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);
+};
+const config = ConfigSchema.parse({ version: 1 });
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'branch-checks-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write('src/limits.ts', 'export const LIMIT = 1;\n');
+    write('scripts/seed.ts', 'console.log(1);\n');
+    write('scripts/seed.tsx', 'console.log(2);\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('branch checks', () => {
+    it('reports the files that conflict with main, and nothing when it merges cleanly', () => {
+        git('checkout', '-q', '-b', 'feature');
+        write('src/limits.ts', 'export const LIMIT = 2;\n');
+        git('commit', '-qam', 'feature');
+        expect(mergeConflicts(repo, 'main')).toEqual([]);
+        git('checkout', '-q', 'main');
+        write('src/limits.ts', 'export const LIMIT = 3;\n');
+        git('commit', '-qam', 'main moved');
+        git('checkout', '-q', 'feature');
+        expect(mergeConflicts(repo, 'main').map(f => [f.id, f.files?.[0]])).toEqual([['merge-conflict', 'src/limits.ts']]);
+    });
+    it('reports a mention of a file the branch deleted, but not of a longer path that starts with it', () => {
+        const base = git('rev-parse', 'HEAD').trim();
+        git('rm', '-q', 'scripts/seed.ts');
+        write('README.md', 'Run `scripts/seed.ts` first.\nThen scripts/seed.tsx.\n');
+        write('src/notes.ts', '// see scripts/seed.tsx\nexport const n = 1;\n');
+        const found = staleReferences(repo, base, config).map(f => [f.files?.[0], f.line]);
+        expect(found).toEqual([['README.md', 1]]);
+    });
+});

package/dist/review/code-patterns.test.d.ts

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

package/dist/review/code-patterns.test.js

@@ -0,0 +1,84 @@
+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 { diffFromGit } from './git-diff.js';
+import { duplicateFunctionFailures } from './duplicate-functions.js';
+import { optionalParamFailures } from './optional-params.js';
+import { queryPatternFailures } from './query-patterns.js';
+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);
+};
+const config = ConfigSchema.parse({ version: 1 });
+const changed = () => parseDiff(diffFromGit(repo));
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'code-patterns-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write('README.md', 'x\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('query patterns', () => {
+    it('reports offset paging in a loop and in a pager callback, not a single page a request asks for', () => {
+        write('src/sweep.ts', [
+            'export async function sweep(db: any) {',
+            '  for (let from = 0; ; from += 500) {',
+            "    const { data } = await db.from('rows').select('id').order('id').range(from, from + 499);",
+            '    if (!data?.length) return;',
+            '  }',
+            '}',
+            "export const all = (db: any) => readAllPages((from: number, to: number) => db.from('rows').select('id').order('id').range(from, to));",
+            "export function page(db: any, from: number, to: number) { return db.from('rows').select('id').range(from, to); }",
+            'declare function readAllPages(f: (from: number, to: number) => unknown): unknown;',
+        ].join('\n'));
+        expect(queryPatternFailures(repo, changed(), config).map(f => [f.id, f.line])).toEqual([['offset-paging', 3], ['offset-paging', 7]]);
+    });
+    it('reports a window read only from its start, not a bounded window or everything since an event', () => {
+        write('src/window.ts', [
+            "export const open = (db: any, window: { from: string; to: string }) => db.from('events').select('id').gte('created_at', window.from);",
+            "export const closed = (db: any, window: { from: string; to: string }) => db.from('events').select('id').gte('created_at', window.from).lte('created_at', window.to);",
+            "export const since = (db: any, since: string) => db.from('events').select('id').gt('started_at', since);",
+        ].join('\n'));
+        expect(queryPatternFailures(repo, changed(), config).map(f => [f.id, f.line])).toEqual([['unbounded-window', 1]]);
+    });
+});
+describe('optional for tests', () => {
+    it('reports an optional parameter or option that every production call passes and only a test omits', () => {
+        write('src/build.ts', 'export function build(items: string[], opts: { resumes?: string[] }, limit?: number) { return [items, opts, limit]; }\n');
+        write('src/run.ts', "import { build } from './build';\nbuild(['a'], { resumes: [] }, 5);\n");
+        write('src/build.test.ts', "import { build } from './build';\nbuild(['a'], {});\n");
+        const found = optionalParamFailures(repo, changed(), config).map(f => f.details.match(/`([^`]+)`/)[1]).sort();
+        expect(found).toEqual(['limit', 'resumes']);
+    });
+    it('stays quiet when production itself omits it, or when tests pass it too', () => {
+        write('src/build.ts', 'export function build(items: string[], limit?: number) { return [items, limit]; }\n');
+        write('src/run.ts', "import { build } from './build';\nbuild(['a']);\nbuild(['b'], 2);\n");
+        write('src/build.test.ts', "import { build } from './build';\nbuild(['a']);\n");
+        expect(optionalParamFailures(repo, changed(), config)).toEqual([]);
+    });
+});
+describe('duplicate functions', () => {
+    const body = (name) => `export function ${name}(x: number) {\n  const a = x + 1;\n  const b = a * 2;\n  if (b > 10) return b;\n  console.log(a, b);\n  return a;\n}\n`;
+    it('reports a changed function whose body copies another, in TypeScript and Svelte alike', () => {
+        write('src/a.ts', body('first'));
+        write('src/b.svelte', `<script lang="ts">\n${body('second').replace('export ', '')}</script>\n<p>hi</p>\n`);
+        const found = duplicateFunctionFailures(repo, changed(), config);
+        expect(found.map(f => [f.files?.[0], f.line])).toEqual([['src/b.svelte', 2]]);
+        expect(found[0].details).toContain('`first` in `src/a.ts:1`');
+    });
+    it('ignores small look-alike functions', () => {
+        write('src/a.ts', 'export const one = (x: number) => { return x + 1; };\n');
+        write('src/b.ts', 'export const two = (x: number) => { return x + 1; };\n');
+        expect(duplicateFunctionFailures(repo, changed(), config)).toEqual([]);
+    });
+});

package/dist/review/dead-code.test.d.ts

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

package/dist/review/dead-code.test.js

@@ -0,0 +1,126 @@
+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 { diffFromGit } from './git-diff.js';
+import { orphanFileFailures } from './orphan-files.js';
+import { unusedExportFailures } from './unused-exports.js';
+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);
+};
+const config = (gates = {}) => ConfigSchema.parse({ version: 1, gates });
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'dead-code-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write('src/index.ts', "import { start } from './app';\nstart();\n");
+    write('src/app.ts', 'export function start() {}\n');
+    write('package.json', '{"scripts":{"seed":"node scripts/seed.mjs"}}\n');
+    git('add', '-A');
+    git('commit', '-qm', 'init');
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('unused exports', () => {
+    it('reports an added export no other file names, on its own line', () => {
+        write('src/app.ts', 'export function start() {}\n\nexport const LIMIT = 5;\nexport function lonely() { return LIMIT; }\n');
+        write('src/use.ts', "import { LIMIT } from './app';\nconsole.log(LIMIT);\n");
+        const failures = unusedExportFailures(repo, diffFromGit(repo), config());
+        expect(failures.map(f => [f.files?.[0], f.line, f.id])).toEqual([['src/app.ts', 4, 'unused-export']]);
+        expect(failures[0].details).toContain('`lonely`');
+    });
+    it('reports a re-export nothing imports, without counting the module it comes from as a use', () => {
+        write('src/types.ts', 'export type Row = { id: string };\nexport type Used = { n: number };\n');
+        write('src/index.ts', "import { start } from './app';\nstart();\nexport type { Row, Used } from './types';\n");
+        write('src/consumer.ts', "import type { Used } from './index';\nexport const u: Used = { n: 1 };\nconsole.log(u);\n");
+        const names = unusedExportFailures(repo, diffFromGit(repo), config()).map(f => [f.files?.[0], f.details.match(/`([^`]+)`/)[1]]);
+        expect(names).toContainEqual(['src/index.ts', 'Row']);
+        expect(names).not.toContainEqual(['src/index.ts', 'Used']);
+    });
+    it('skips what a framework calls by name, and names the team allows', () => {
+        write('src/routes/+page.server.ts', 'export const load = () => ({});\nexport const helper = 1;\n');
+        write('src/plugin.ts', 'export const register = () => {};\n');
+        const names = unusedExportFailures(repo, diffFromGit(repo), config({ unused_exports: { allow: ['register'] } }))
+            .map(f => f.details.match(/`([^`]+)`/)[1]);
+        expect(names).toEqual(['helper']);
+    });
+    it('does not count the same word in a file that never imports the module', () => {
+        write('src/payload.ts', 'export function eventId(kind: string) { return kind; }\nexport const used = eventId("x");\n');
+        write('src/main2.ts', "import { used } from './payload';\nconsole.log(used);\n");
+        write('src/routes/[eventId]/handler.ts', "const eventId = 'route-param';\nconsole.log(eventId);\n");
+        write('src/schedule.ts', 'const eventId = 7;\nconsole.log(eventId);\n');
+        const names = unusedExportFailures(repo, diffFromGit(repo), config()).map(f => f.details.match(/`([^`]+)`/)[1]);
+        expect(names).toContain('eventId');
+        expect(names).not.toContain('used');
+    });
+    it('reports a type imported then exported again that nothing imports from here', () => {
+        write('src/entry.ts', "export type Entry = 'a' | 'b';\n");
+        write('src/resume.ts', "import type { Entry } from './entry';\nexport type { Entry };\nexport const pick = (e: Entry) => e;\n");
+        write('src/main.ts', "import { pick } from './resume';\nconsole.log(pick('a'));\n");
+        const found = unusedExportFailures(repo, diffFromGit(repo), config()).map(f => [f.files?.[0], f.details.match(/`([^`]+)`/)[1]]);
+        expect(found).toContainEqual(['src/resume.ts', 'Entry']);
+        expect(found).not.toContainEqual(['src/entry.ts', 'Entry']);
+    });
+    it("never counts Rigour's own report as a use", () => {
+        write('src/app.ts', 'export function start() {}\nexport const orphanName = 1;\n');
+        write('rigour-report.json', '{"failures":[{"details":"orphanName"}]}\n');
+        expect(unusedExportFailures(repo, diffFromGit(repo), config())).toHaveLength(1);
+    });
+    it('is off when disabled', () => {
+        write('src/app.ts', 'export function start() {}\nexport const x = 1;\n');
+        expect(unusedExportFailures(repo, diffFromGit(repo), config({ unused_exports: { enabled: false } }))).toEqual([]);
+    });
+});
+describe('package layout', () => {
+    it("never reports a package entry point's exports, which are its public API", () => {
+        write('packages/lib/package.json', '{"name":"lib","main":"dist/index.js","types":"dist/index.d.ts"}\n');
+        write('packages/lib/src/index.ts', "export { helper, type Shape } from './helper';\n");
+        write('packages/lib/src/helper.ts', 'export type Shape = { a: 1 };\nexport const helper = 1;\n');
+        write('packages/lib/src/tools/index.ts', "export { toolA } from './a';\n");
+        write('packages/lib/src/tools/a.ts', 'export const toolA = 1;\n');
+        write('packages/lib/src/index.ts', "export { helper, type Shape } from './helper';\nexport * from './tools/index.js';\n");
+        const reported = unusedExportFailures(repo, diffFromGit(repo), config()).map(f => f.files?.[0]);
+        expect(reported).not.toContain('packages/lib/src/index.ts');
+        expect(reported).not.toContain('packages/lib/src/tools/index.ts'); // re-exported whole by the entry
+    });
+    it('keeps an exported type in a signature when the project emits declarations, and only then', () => {
+        write('src/run.ts', 'export interface RunResult { ok: boolean }\nexport function run(): RunResult { return { ok: true }; }\n');
+        write('src/main.ts', "import { run } from './run';\nrun();\n");
+        const names = () => unusedExportFailures(repo, diffFromGit(repo), config()).map(f => f.details.match(/`([^`]+)`/)[1]);
+        expect(names()).toContain('RunResult'); // an application: drop the export
+        write('tsconfig.base.json', '{ "compilerOptions": { "declaration": true } }\n');
+        write('tsconfig.json', '{ "extends": "./tsconfig.base.json" }\n');
+        expect(names()).not.toContain('RunResult'); // a library: TypeScript needs it exported
+    });
+    it("counts a package.json bin or main path as running its source file", () => {
+        write('packages/tool/package.json', '{"name":"tool","bin":{"tool":"dist/bin.js"}}\n');
+        write('packages/tool/src/bin.ts', 'console.log("hi");\n');
+        expect(orphanFileFailures(repo, diffFromGit(repo), config())).toEqual([]);
+    });
+});
+describe('orphaned files', () => {
+    it('reports new files nothing outside the new files reaches, including a pair that only import each other', () => {
+        write('src/wired.ts', 'export const w = 1;\n');
+        write('src/index.ts', "import { start } from './app';\nimport { w } from './wired';\nstart(w);\n");
+        write('src/lonely.ts', 'export const l = 1;\n');
+        write('src/pair/a.ts', "import { b } from './b';\nexport const a = b;\n");
+        write('src/pair/b.ts', "import { a } from './a';\nexport const b = a;\n");
+        write('scripts/seed.mjs', 'console.log(1);\n');
+        write('src/tested.ts', 'export const t = 1;\n');
+        write('src/tested.test.ts', "import { t } from './tested';\n"); // a test runs it: reached
+        const files = orphanFileFailures(repo, diffFromGit(repo), config()).map(f => f.files?.[0]).sort();
+        expect(files).toEqual(['src/lonely.ts', 'src/pair/a.ts', 'src/pair/b.ts']);
+    });
+    it('lets a file through when a docs page is its only mention, and honours allow globs', () => {
+        write('src/tool.ts', 'export const t = 1;\n');
+        write('docs/tool.md', 'Run `src/tool.ts` by hand.\n');
+        expect(orphanFileFailures(repo, diffFromGit(repo), config()).map(f => f.files?.[0])).toEqual(['src/tool.ts']);
+        expect(orphanFileFailures(repo, diffFromGit(repo), config({ orphan_files: { allow: ['src/tool.ts'] } }))).toEqual([]);
+    });
+});

package/dist/review/duplicate-functions.d.ts

@@ -0,0 +1,2 @@
+import type { Config, Failure } from '../types/index.js';
+export declare function duplicateFunctionFailures(cwd: string, changedLines: Record<string, Set<number>>, config: Config): Failure[];

package/dist/review/duplicate-functions.js

@@ -0,0 +1,98 @@
+/**
+ * Duplicate function: a function the change adds or edits whose body is, line for line, the same as
+ * another function's in the files the change touched. Two copies drift: the next fix lands in one.
+ * Bodies are compared as code (comments and layout ignored), and only bodies of real size count,
+ * so small adapters that happen to match are not reported.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { isTestFile } from './test-files.js';
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|svelte)$/;
+const MIN_STATEMENTS = 4;
+const MIN_LINES = 6;
+export function duplicateFunctionFailures(cwd, changedLines, config) {
+    if (!config.gates.duplicate_functions?.enabled)
+        return [];
+    const bodies = [];
+    for (const [file, lines] of Object.entries(changedLines)) {
+        if (!CODE.test(file) || isTestFile(file))
+            continue;
+        bodies.push(...bodiesIn(cwd, file, lines));
+    }
+    const byKey = new Map();
+    for (const body of bodies)
+        byKey.set(body.key, [...(byKey.get(body.key) ?? []), body]);
+    const failures = [];
+    for (const same of byKey.values()) {
+        if (same.length < 2)
+            continue;
+        for (const copy of same.filter(b => b.changed)) {
+            const original = same.find(b => b !== copy && (!b.changed || b.file < copy.file || (b.file === copy.file && b.line < copy.line)));
+            if (original)
+                failures.push(duplicate(copy, original));
+        }
+    }
+    return failures;
+}
+function bodiesIn(cwd, file, changed) {
+    let source;
+    let offset = 0; // a Svelte component's script starts below its first line
+    try {
+        let text = fs.readFileSync(path.join(cwd, file), 'utf8');
+        if (file.endsWith('.svelte')) {
+            const script = text.match(/<script[^>]*>([\s\S]*?)<\/script>/);
+            if (!script || script.index === undefined)
+                return [];
+            offset = text.slice(0, script.index + script[0].indexOf(script[1])).split('\n').length - 1;
+            text = script[1];
+        }
+        source = ts.createSourceFile(file.endsWith('.svelte') ? `${file}.ts` : file, text, ts.ScriptTarget.Latest, true);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    const visit = (node) => {
+        if ((ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.body && ts.isBlock(node.body)) {
+            const start = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1 + offset;
+            const end = source.getLineAndCharacterOfPosition(node.getEnd()).line + 1 + offset;
+            if (node.body.statements.length >= MIN_STATEMENTS && end - start + 1 >= MIN_LINES) {
+                const isChanged = [...changed].some(l => l >= start && l <= end);
+                found.push({ file, name: nameOf(node) ?? `function at line ${start}`, line: start, changed: isChanged, key: normalized(node.body, source) });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** The body as tokens: comments and whitespace dropped. */
+function normalized(body, source) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, body.getText(source));
+    const tokens = [];
+    for (let kind = scanner.scan(); kind !== ts.SyntaxKind.EndOfFileToken; kind = scanner.scan())
+        tokens.push(scanner.getTokenText());
+    return tokens.join(' ');
+}
+function nameOf(node) {
+    if ((ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name && ts.isIdentifier(node.name))
+        return node.name.text;
+    if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name))
+        return node.parent.name.text;
+    if (ts.isPropertyAssignment(node.parent) && ts.isIdentifier(node.parent.name))
+        return node.parent.name.text;
+    return undefined;
+}
+function duplicate(copy, original) {
+    return {
+        id: 'duplicate-function',
+        title: 'Duplicate function',
+        details: `\`${copy.name}\` has the same body as \`${original.name}\` in \`${original.file}:${original.line}\`: two copies drift, and the next fix lands in one.`,
+        severity: 'medium',
+        provenance: 'traditional',
+        files: [copy.file],
+        line: copy.line,
+        hint: `Keep one: call \`${original.name}\` (moving it somewhere both can import), or extract the shared body.`,
+    };
+}

package/dist/review/effectiveness.d.ts

@@ -11,6 +11,9 @@ export interface AgentEvent {
     blocked?: boolean;
     /** Findings that blocked a stop. */
     blocking?: number;
+    /** stop_review: what the review was measured against, and whether there was nothing to look at. */
+    against?: string;
+    nothing_to_review?: boolean;
     /** lessons_served: where the agent got them, and their subjects (learning-events.ts). */
     via?: string;
     lessons?: string[];

package/dist/review/optional-params.d.ts

@@ -0,0 +1,2 @@
+import type { Config, Failure } from '../types/index.js';
+export declare function optionalParamFailures(cwd: string, changedLines: Record<string, Set<number>>, config: Config): Failure[];

package/dist/review/optional-params.js

@@ -0,0 +1,123 @@
+/**
+ * Optional only for tests: a parameter the change adds as optional (`p?: T`) that every call
+ * outside tests passes. Production never takes the "omitted" path, so it is untested where it
+ * matters and the type lies about what callers must provide. Calls are found by name in the files
+ * that import the function's module (and its own file), read from the syntax tree.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { isTestFile } from './test-files.js';
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const GIT_TIMEOUT_MS = 10_000;
+export function optionalParamFailures(cwd, changedLines, config) {
+    if (!config.gates.optional_params?.enabled)
+        return [];
+    const failures = [];
+    for (const param of addedOptionalParams(cwd, changedLines)) {
+        const calls = callsOf(cwd, param);
+        const production = calls.filter(c => !isTestFile(c.file));
+        const tests = calls.filter(c => isTestFile(c.file));
+        if (production.length > 0 && production.every(c => passes(c, param)) && tests.some(c => !passes(c, param))) {
+            failures.push(onlyTestsOmit(param, production.length));
+        }
+    }
+    return failures;
+}
+/** Optional parameters (`p?: T`) on named functions, declared on lines the change added. */
+function addedOptionalParams(cwd, changedLines) {
+    const found = [];
+    for (const [file, lines] of Object.entries(changedLines)) {
+        if (!CODE.test(file) || isTestFile(file) || lines.size === 0)
+            continue;
+        const source = parse(cwd, file);
+        if (!source)
+            continue;
+        const visit = (node) => {
+            const name = functionName(node);
+            if (name && ts.isFunctionLike(node)) {
+                node.parameters.forEach((p, index) => {
+                    const line = source.getLineAndCharacterOfPosition(p.getStart(source)).line + 1;
+                    if (p.questionToken && ts.isIdentifier(p.name) && lines.has(line) && !p.dotDotDotToken)
+                        found.push({ file, fn: name, name: p.name.text, index, line });
+                    if (!p.questionToken && p.type && ts.isTypeLiteralNode(p.type)) {
+                        for (const member of p.type.members) {
+                            const at = source.getLineAndCharacterOfPosition(member.getStart(source)).line + 1;
+                            if (ts.isPropertySignature(member) && member.questionToken && ts.isIdentifier(member.name) && lines.has(at)) {
+                                found.push({ file, fn: name, name: member.name.text, index, line: at, property: member.name.text });
+                            }
+                        }
+                    }
+                });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return found;
+}
+function functionName(node) {
+    if (ts.isFunctionDeclaration(node))
+        return node.name?.text;
+    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name))
+        return node.parent.name.text;
+    return undefined;
+}
+/** Whether a call provides the parameter, or the property inside the object parameter. Unreadable calls count as providing it. */
+function passes(call, param) {
+    if (call.args <= param.index)
+        return false;
+    if (!param.property)
+        return true;
+    return call.keys === null || call.keys === undefined || call.keys.has(param.property);
+}
+/** Calls of `param.fn` (`fn(…)` or `x.fn(…)`) in its own file and the files that name it. */
+function callsOf(cwd, param) {
+    const grep = spawnSync('git', ['grep', '--untracked', '-l', '-w', '-F', '-e', param.fn], { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+    const files = grep.status === 0 ? grep.stdout.split('\n').filter(f => f && CODE.test(f)) : [];
+    const calls = [];
+    for (const file of new Set([param.file, ...files])) {
+        const source = parse(cwd, file);
+        if (!source)
+            continue;
+        const visit = (node) => {
+            if (ts.isCallExpression(node)) {
+                const callee = node.expression;
+                const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : undefined;
+                if (name === param.fn)
+                    calls.push({ file, args: node.arguments.some(a => ts.isSpreadElement(a)) ? Infinity : node.arguments.length, keys: objectKeys(node.arguments[param.index]) });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return calls;
+}
+function objectKeys(arg) {
+    if (!arg)
+        return undefined;
+    if (!ts.isObjectLiteralExpression(arg) || arg.properties.some(p => ts.isSpreadAssignment(p)))
+        return null;
+    return new Set(arg.properties.map(p => (p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) ? p.name.text : '')).filter(Boolean));
+}
+function parse(cwd, file) {
+    try {
+        return ts.createSourceFile(file, fs.readFileSync(path.join(cwd, file), 'utf8'), ts.ScriptTarget.Latest, true);
+    }
+    catch {
+        return undefined;
+    }
+}
+function onlyTestsOmit(param, productionCalls) {
+    return {
+        id: 'optional-for-tests',
+        title: 'Optional only for tests',
+        details: `\`${param.name}\`${param.property ? ' (an option)' : ''} of \`${param.fn}\` is optional, but all ${productionCalls} call(s) outside tests pass it; only tests omit it.`,
+        severity: 'medium',
+        provenance: 'traditional',
+        files: [param.file],
+        line: param.line,
+        hint: `Make \`${param.name}\` required and pass it in the tests too, so the type says what callers must provide.`,
+    };
+}

package/dist/review/orphan-files.d.ts

@@ -0,0 +1,2 @@
+import type { Config, Failure } from '../types/index.js';
+export declare function orphanFileFailures(cwd: string, diff: string, config: Config): Failure[];