@rigour-labs/core 6.6.4 → 6.6.6

package/dist/review/typed/program.js

@@ -0,0 +1,90 @@
+/**
+ * The project's TypeScript program, built once per review from its own tsconfig.json and its own
+ * `typescript` (the compiler version and options then match what the project type-checks with;
+ * Rigour's bundled compiler is the fallback). What the type checker knows (which literal is typed
+ * as T, which property is read where) is what the typed checks reason from. Files outside the
+ * program (.svelte, a package under its own tsconfig) are kept as text and scanned by name only,
+ * which can suppress a finding and never adds one.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+import ownTs from 'typescript';
+import { installedBin } from '../../utils/installed-bin.js';
+export const TEST_FILE = /\.(test|spec|e2e)\.[cm]?[jt]sx?$|(^|\/)(tests?|e2e|__tests__|__mocks__)\//;
+const GIT_TIMEOUT_MS = 10_000;
+/** The program, `skip` when this is not a TypeScript project, or `error` when it is one that cannot be loaded. */
+export function loadProgram(root) {
+    const tsconfig = path.join(root, 'tsconfig.json');
+    if (!fs.existsSync(tsconfig))
+        return { skip: 'no tsconfig.json' };
+    const ts = projectTypescript(root);
+    let parsed = parseConfig(ts, tsconfig);
+    if ('error' in parsed && /\.svelte-kit\//.test(parsed.error) && syncSvelteKit(root))
+        parsed = parseConfig(ts, tsconfig);
+    if ('error' in parsed)
+        return { error: `tsconfig.json cannot be loaded: ${parsed.error}` };
+    const program = ts.createProgram({ rootNames: parsed.config.fileNames, options: { ...parsed.config.options, noEmit: true } });
+    const rel = (sf) => path.relative(root, sf.fileName).split(path.sep).join('/');
+    const sources = program.getSourceFiles().filter(sf => !sf.isDeclarationFile && !sf.fileName.includes('/node_modules/'));
+    const inProgram = new Set(sources.map(rel));
+    return {
+        program: {
+            ts, program, checker: program.getTypeChecker(), root, rel,
+            appSources: sources.filter(sf => !TEST_FILE.test(rel(sf))),
+            textFiles: textFiles(root, inProgram),
+            inProgram,
+        },
+    };
+}
+function projectTypescript(root) {
+    try {
+        return createRequire(path.join(root, 'package.json'))('typescript');
+    }
+    catch {
+        return ownTs;
+    }
+}
+function parseConfig(ts, tsconfig) {
+    try {
+        const config = ts.getParsedCommandLineOfConfigFile(tsconfig, {}, {
+            ...ts.sys,
+            onUnRecoverableConfigFileDiagnostic: diagnostic => {
+                throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+            },
+        });
+        if (!config)
+            return { error: 'unreadable' };
+        // A missing `extends` target or an unknown option is a diagnostic, not an exception; tsc would fail on it too.
+        const errors = config.errors.filter(d => d.category === ts.DiagnosticCategory.Error).map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+        return errors.length ? { error: errors.join('; ') } : { config };
+    }
+    catch (error) {
+        return { error: String(error.message ?? error) };
+    }
+}
+/** A SvelteKit tsconfig extends a generated one; `svelte-kit sync` writes it (never downloaded: the project's own binary or nothing). */
+function syncSvelteKit(root) {
+    const bin = installedBin(root, root, 'svelte-kit');
+    if (!bin)
+        return false;
+    return spawnSync(bin, ['sync'], { cwd: root, stdio: 'ignore', timeout: 120_000 }).status === 0;
+}
+function textFiles(root, inProgram) {
+    const listed = spawnSync('git', ['ls-files', '--', '*.svelte', '*.ts', '*.js'], { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+    if (listed.status !== 0)
+        return [];
+    const files = [];
+    for (const file of listed.stdout.split('\n')) {
+        if (!file || inProgram.has(file) || file.endsWith('.d.ts') || TEST_FILE.test(file))
+            continue;
+        try {
+            files.push({ file, text: fs.readFileSync(path.join(root, file), 'utf8') });
+        }
+        catch {
+            // deleted in the working tree
+        }
+    }
+    return files;
+}

package/dist/review/typed/redundancy.d.ts

@@ -0,0 +1,10 @@
+import type { Config, Failure } from '../../types/index.js';
+export interface Redundancy {
+    failures: Failure[];
+    hints: string[];
+    /** A TypeScript project whose program cannot be built: the checks could not run, which is never a pass (review.ts turns it into a gate error). */
+    error?: string;
+}
+export declare 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 declare function typedChecks(cwd: string, changedLines: Record<string, Set<number>>, config: Config): Redundancy;

package/dist/review/typed/redundancy.js

@@ -0,0 +1,339 @@
+/**
+ * What a change made redundant, found with the TypeScript checker instead of a model's attention.
+ * Four blocking classes, the dead code a person kept finding after every other gate was green:
+ *   duplicate-null-filter     `.not(col, 'is', null)` in a query chain that already ranges or
+ *                             equals on `col` (SQL excludes NULL there);
+ *   nullable-filtered-column  the query filters `col` non-null, the row type still says `| null`,
+ *                             so every guard on it is dead;
+ *   optional-always-supplied  an optional property every host object supplies;
+ *   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 a hint: a function that scans a collection, called once per item of another (nested-scan).
+ * Scoped to lines the change touched and members it declared, or whose every host it wrote; a
+ * pre-existing member with one touched writer is the team's backlog, not this change's.
+ */
+import micromatch from 'micromatch';
+import { emitsDeclarations } from '../package-layout.js';
+import { loadProgram, TEST_FILE } from './program.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) {
+    if (!config.gates.redundancy?.enabled || !Object.keys(changedLines).some(file => /\.[cm]?ts$/.test(file) && !TEST_FILE.test(file)))
+        return { failures: [], hints: [] };
+    const loaded = loadProgram(cwd);
+    if ('skip' in loaded)
+        return { failures: [], hints: [] };
+    if ('error' in loaded)
+        return { failures: [], hints: [], error: `${loaded.error} (install the dependencies, and run the framework's sync if it has one)` };
+    return redundancyFailures(loaded.program, changedLines, config);
+}
+const RANGE = new Set(['gt', 'gte', 'lt', 'lte', 'eq', 'in', 'like', 'ilike']);
+const MENTION_DEPTH = 3;
+function redundancyFailures(typed, changedLines, config) {
+    const settings = config.gates.redundancy;
+    if (!settings?.enabled)
+        return { failures: [], hints: [] };
+    const { ts, checker, rel } = typed;
+    const changed = Object.keys(changedLines).filter(file => /\.[cm]?ts$/.test(file) && !file.endsWith('.d.ts') && !TEST_FILE.test(file));
+    const failures = [];
+    const hints = [];
+    const line = (node) => node.getSourceFile().getLineAndCharacterOfPosition(node.getStart()).line + 1;
+    const at = (node) => `${rel(node.getSourceFile())}:${line(node)}`;
+    const touched = (node) => !!changedLines[rel(node.getSourceFile())]?.has(line(node));
+    const spanTouched = (node) => {
+        const set = changedLines[rel(node.getSourceFile())];
+        if (!set)
+            return false;
+        const sf = node.getSourceFile();
+        for (let l = sf.getLineAndCharacterOfPosition(node.getStart()).line + 1; l <= sf.getLineAndCharacterOfPosition(node.getEnd()).line + 1; l++)
+            if (set.has(l))
+                return true;
+        return false;
+    };
+    const report = (id, title, node, details, hint) => failures.push({ id, title, details, hint, severity: 'medium', provenance: 'traditional', files: [rel(node.getSourceFile())], line: line(node) });
+    const walk = (node, fn) => {
+        fn(node);
+        ts.forEachChild(node, child => walk(child, fn));
+    };
+    const strArg = (call, i) => call.arguments[i] && ts.isStringLiteralLike(call.arguments[i]) ? call.arguments[i].text : undefined;
+    const isNullLiteral = (n) => !!n && n.kind === ts.SyntaxKind.NullKeyword;
+    const changedSources = changed.map(file => typed.program.getSourceFile(`${typed.root}/${file}`)).filter((sf) => !!sf);
+    // A method chain `a.b(...).c(...)` as its calls, outermost last.
+    const chainOf = (call) => {
+        const calls = [];
+        let n = call;
+        while (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+            calls.unshift({ call: n, name: n.expression.name.text });
+            n = n.expression.expression;
+        }
+        return calls;
+    };
+    const outermost = (call) => !(ts.isPropertyAccessExpression(call.parent) && ts.isCallExpression(call.parent.parent) && call.parent.parent.expression === call.parent);
+    const elementType = (t) => checker.isArrayType(t) ? checker.getTypeArguments(t)[0] : (t.getNumberIndexType() ?? t);
+    /** The row type a chain returns: `.returns<Row[]>()`, else the type argument of an enclosing `read…<Row>()` call. */
+    const rowTypeOf = (chain, outer) => {
+        const ret = chain.find(c => c.name === 'returns' && c.call.typeArguments?.length);
+        if (ret)
+            return elementType(checker.getTypeFromTypeNode(ret.call.typeArguments[0]));
+        for (let n = outer.parent; n; n = n.parent) {
+            if (ts.isCallExpression(n) && n.typeArguments?.length && ts.isIdentifier(n.expression) && /^read[A-Z]\w*$/.test(n.expression.text))
+                return checker.getTypeFromTypeNode(n.typeArguments[0]);
+        }
+        return undefined;
+    };
+    const isNullable = (t) => t.isUnion() && t.types.some(m => !!(m.flags & ts.TypeFlags.Null));
+    // duplicate-null-filter and nullable-filtered-column
+    for (const sf of changedSources) {
+        walk(sf, node => {
+            if (!ts.isCallExpression(node) || !outermost(node))
+                return;
+            const chain = chainOf(node);
+            const nots = chain.filter(c => c.name === 'not' && strArg(c.call, 1) === 'is' && isNullLiteral(c.call.arguments[2]) && strArg(c.call, 0));
+            if (nots.length === 0 || !spanTouched(node))
+                return;
+            for (const n of nots) {
+                const col = strArg(n.call, 0);
+                const range = chain.find(c => RANGE.has(c.name) && strArg(c.call, 0) === col);
+                if (range) {
+                    report('duplicate-null-filter', 'Redundant null filter', n.call, `\`.not('${col}', 'is', null)\` is redundant next to \`.${range.name}('${col}', …)\` at ${at(range.call)}: SQL already excludes NULL there.`, 'Delete the null filter.');
+                }
+                const row = rowTypeOf(chain, node);
+                const prop = row && checker.getPropertyOfType(row, col);
+                const decl = prop?.declarations?.[0];
+                if (decl && ts.isPropertySignature(decl) && decl.type && isNullable(checker.getTypeFromTypeNode(decl.type))) {
+                    // Anchored on the query the change wrote; the declaration may be in a file it did not touch.
+                    report('nullable-filtered-column', 'Nullable type for a column the query filters non-null', n.call, `\`${col}\` is declared nullable at ${at(decl)} but this query filters it non-null, so every guard on it is dead.`, 'Narrow the row type and delete the guards on it.');
+                }
+            }
+        });
+    }
+    const declaredTypes = [];
+    for (const sf of changedSources) {
+        walk(sf, node => {
+            if (!(ts.isInterfaceDeclaration(node) || (ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type))))
+                return;
+            const sym = checker.getSymbolAtLocation(node.name);
+            if (!sym)
+                return;
+            const members = (ts.isInterfaceDeclaration(node) ? node.members : node.type.members).filter((m) => ts.isPropertySignature(m) && ts.isIdentifier(m.name));
+            declaredTypes.push({ node, name: node.name.text, sym, type: checker.getDeclaredTypeOfSymbol(sym), members });
+        });
+    }
+    // Does a type carry T: itself, an array of it, a union or intersection member, or a property a few levels down.
+    const mentionMemo = new Map();
+    const mentionsType = (t, ty, depth = 0) => {
+        if (!ty || depth > MENTION_DEPTH)
+            return false;
+        if (ty.symbol === t.sym || ty.aliasSymbol === t.sym)
+            return true;
+        if (ty.aliasTypeArguments?.some(a => mentionsType(t, a, depth + 1)))
+            return true;
+        const key = `${t.sym.escapedName}|${ty.id}`;
+        if (mentionMemo.has(key))
+            return mentionMemo.get(key);
+        mentionMemo.set(key, false);
+        let hit = false;
+        if (checker.isArrayType(ty))
+            hit = mentionsType(t, checker.getTypeArguments(ty)[0], depth + 1);
+        else if (ty.isUnionOrIntersection())
+            hit = ty.types.some(m => mentionsType(t, m, depth + 1));
+        else if (ty.flags & ts.TypeFlags.Object && !(ty.symbol && ty.symbol.flags & ts.SymbolFlags.Function))
+            hit = checker.getPropertiesOfType(ty).some(p => mentionsType(t, checker.getTypeOfSymbol(p), depth + 1));
+        mentionMemo.set(key, hit);
+        return hit;
+    };
+    // Object literals the checker types as T, in non-test files that mention T by name.
+    const hostsOf = (t) => {
+        const hosts = [];
+        const mentions = (ty) => ty.symbol === t.sym || ty.aliasSymbol === t.sym || (ty.isUnionOrIntersection() && ty.types.some(mentions));
+        for (const sf of typed.appSources) {
+            if (!sf.text.includes(t.name))
+                continue;
+            walk(sf, node => {
+                if (!ts.isObjectLiteralExpression(node))
+                    return;
+                const ctx = checker.getContextualType(node);
+                if (ctx && mentions(ctx))
+                    hosts.push(node);
+            });
+        }
+        return hosts;
+    };
+    const literalHas = (lit, name) => lit.properties.some(p => (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p) || ts.isMethodDeclaration(p)) && !!p.name && ts.isIdentifier(p.name) && p.name.text === name);
+    const literalSpreads = (lit) => lit.properties.some(p => ts.isSpreadAssignment(p));
+    const word = (s) => new RegExp(`\\b${s.replace(/[$]/g, '\\$')}\\b`);
+    // An untyped file is a host when it names the type and visibly supplies a required member (a consumer only reads them).
+    const supplyRe = (key) => new RegExp(`(?<![.\\w])${key}\\s*:|(?<![.\\w])${key}\\s*\\([^()]*\\)\\s*\\{|[{,]\\s*${key}\\s*[,}]`);
+    const textHosts = (t) => {
+        const required = t.members.filter(m => !m.questionToken).map(m => m.name.getText());
+        const keys = required.length ? required : t.members.map(m => m.name.getText());
+        return typed.textFiles.filter(s => word(t.name).test(s.text) && keys.some(k => supplyRe(k).test(s.text)));
+    };
+    // A read in an untyped file counts only where that file names the type or imports its module.
+    const textReads = (t, prop) => {
+        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));
+    };
+    // 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) => {
+        if (escapeMemo.has(t.sym))
+            return escapeMemo.get(t.sym);
+        let found;
+        for (const sf of typed.appSources) {
+            if (found)
+                break;
+            walk(sf, node => {
+                if (found || !ts.isExpression(node) || !node.parent)
+                    return;
+                const p = node.parent;
+                const isArg = ts.isCallExpression(p) && p.arguments.includes(node);
+                const stringified = ts.isTemplateSpan(p) || (ts.isBinaryExpression(p) && p.operatorToken.kind === ts.SyntaxKind.PlusToken);
+                if (!isArg && !stringified)
+                    return;
+                const ty = (ts.isObjectLiteralExpression(node) && checker.getContextualType(node)) || checker.getTypeAtLocation(node);
+                if (!mentionsType(t, ty))
+                    return;
+                if (stringified) {
+                    found = `string building at ${at(node)}`;
+                    return;
+                }
+                const call = p;
+                const sig = checker.getResolvedSignature(call);
+                const decl = sig?.declaration;
+                // Storing into a collection (events.push(e), map.set(k, v)) keeps the value typed and visible.
+                if (decl?.getSourceFile().isDeclarationFile && ts.isPropertyAccessExpression(call.expression)) {
+                    const holder = checker.getTypeAtLocation(call.expression.expression);
+                    const holderName = String(holder.symbol?.escapedName ?? holder.aliasSymbol?.escapedName ?? '');
+                    if (checker.isArrayType(holder) || /^(Map|Set|WeakMap|WeakSet|Promise|ReadonlyMap|ReadonlySet)$/.test(holderName))
+                        return;
+                }
+                const param = sig?.parameters[call.arguments.indexOf(node)];
+                const paramType = param && checker.getTypeOfSymbolAtLocation(param, call);
+                if (!decl || !typed.inProgram.has(rel(decl.getSourceFile())) || !mentionsType(t, paramType))
+                    found = `${call.expression.getText().slice(0, 40)}() at ${at(node)}`;
+            });
+        }
+        escapeMemo.set(t.sym, found);
+        return found;
+    };
+    // A property is read when any non-test file accesses or destructures it; a spread only passes it on.
+    const isWriteTarget = (access) => ts.isBinaryExpression(access.parent) && access.parent.left === access && access.parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+    const isRead = (t, name) => {
+        const sym = checker.getPropertyOfType(t.type, name);
+        if (!sym)
+            return 'no such property';
+        const declaration = sym.declarations?.[0];
+        const isOurs = (s) => !!s && (s === sym || !!s.declarations?.some(d => d === declaration));
+        const ofType = (expr) => mentionsType(t, checker.getTypeAtLocation(expr));
+        for (const sf of typed.appSources) {
+            if (!sf.text.includes(name) && !sf.text.includes('...'))
+                continue;
+            let read;
+            walk(sf, node => {
+                if (read)
+                    return;
+                if (ts.isPropertyAccessExpression(node) && node.name.text === name && !isWriteTarget(node) && isOurs(checker.getSymbolAtLocation(node.name)))
+                    read = node;
+                else if (ts.isBindingElement(node) && ts.isObjectBindingPattern(node.parent) && ((node.propertyName && ts.isIdentifier(node.propertyName) && node.propertyName.text === name) || (!node.propertyName && ts.isIdentifier(node.name) && node.name.text === name)) && ofType(node.parent))
+                    read = node;
+                else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression) && node.argumentExpression.text === name && ofType(node.expression))
+                    read = node;
+            });
+            if (read)
+                return at(read);
+        }
+        const text = textReads(t, name);
+        return text ? `${text.file} (by name)` : undefined;
+    };
+    for (const t of declaredTypes) {
+        const hosts = hostsOf(t);
+        if (hosts.length === 0 && !t.members.some(m => m.questionToken))
+            continue;
+        // A declared wire contract (a payload another service reads) is read by that service: its members are never write-only here.
+        const wire = micromatch.isMatch(rel(t.node.getSourceFile()), settings.wire_contracts);
+        // In a library (declarations emitted), an exported type is read by consumers outside this program: what looks
+        // write-only or always-supplied here is a hint for the reviewer, not a block.
+        const published = !!t.node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) && emitsDeclarations(typed.root, rel(t.node.getSourceFile()));
+        const publish = (id, node, text) => hints.push(`${id} ${at(node)}: ${text} (an exported type of a library: consumers outside this program may read it)`);
+        for (const m of t.members) {
+            const name = m.name.getText();
+            const supplied = hosts.filter(h => literalHas(h, name));
+            const spreads = hosts.some(literalSpreads);
+            // The change owns the finding when it declared the member or wrote every host; it is anchored on
+            // a line the change touched (the member, else a host it wrote) and names the other place.
+            const anchor = touched(m) ? m : hosts.length && hosts.every(spanTouched) ? hosts.find(spanTouched) : undefined;
+            if (!anchor)
+                continue;
+            const member = `\`${t.name}.${name}\`${anchor === m ? '' : ` (${at(m)})`}`;
+            if (m.questionToken && !spreads) {
+                const outside = textHosts(t);
+                const all = hosts.length + outside.length;
+                if (all > 0 && supplied.length === hosts.length && outside.every(s => supplyRe(name).test(s.text))) {
+                    const text = `${member} is optional but every host supplies it (${all} host(s), e.g. ${hosts[0] ? at(hosts[0]) : outside[0].file}).`;
+                    if (published)
+                        publish('optional-always-supplied', m, text);
+                    else
+                        report('optional-always-supplied', 'Optional member every host supplies', anchor, text, 'Make it required and drop the `?.` and the fallbacks on it.');
+                }
+            }
+            if (supplied.length && !wire && !isRead(t, name)) {
+                const exit = escapes(t);
+                if (exit)
+                    hints.push(`write-only-property ${at(m)}: ${t.name}.${name} is set by ${supplied.length} host(s) and read by no code; the value leaves only through ${exit}. Confirm an external reader needs it, else delete it`);
+                else if (published)
+                    publish('write-only-property', m, `${member} is set by ${supplied.length} host(s) and read nowhere in this program`);
+                else {
+                    report('write-only-property', 'Property written and never read', anchor, `${member} is set by ${supplied.length} host(s) (e.g. ${at(supplied[0])}) and read nowhere outside tests.`, 'Delete it, or name the reader. If another service reads this type, list its file under gates.redundancy.wire_contracts.');
+                }
+            }
+        }
+    }
+    // Hint: a function with a collection parameter that scans it, called inside a loop or an array callback over another collection.
+    for (const sf of changedSources) {
+        const scanners = new Map();
+        walk(sf, node => {
+            if (!(ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) || !node.body)
+                return;
+            const name = ts.isFunctionDeclaration(node) ? node.name?.text : ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name) ? node.parent.name.text : undefined;
+            if (!name)
+                return;
+            const collections = node.parameters.filter(p => ts.isIdentifier(p.name) && p.type && (ts.isArrayTypeNode(p.type) || (ts.isTypeOperatorNode(p.type) && ts.isArrayTypeNode(p.type.type)) || (ts.isTypeReferenceNode(p.type) && /^(Array|ReadonlyArray|Map|Set|Iterable)$/.test(p.type.typeName.getText())))).map(p => p.name.text);
+            if (collections.length === 0)
+                return;
+            let scans;
+            walk(node.body, n => {
+                if (scans)
+                    return;
+                if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && /^(find|filter|some|every|findIndex|includes|indexOf)$/.test(n.expression.name.text) && ts.isIdentifier(n.expression.expression) && collections.includes(n.expression.expression.text))
+                    scans = n.expression.expression.text;
+                if (ts.isForOfStatement(n) && ts.isIdentifier(n.expression) && collections.includes(n.expression.text))
+                    scans = n.expression.text;
+            });
+            if (scans)
+                scanners.set(name, scans);
+        });
+        if (scanners.size === 0)
+            continue;
+        const inLoop = (n) => {
+            for (let p = n.parent; p; p = p.parent) {
+                if (ts.isForOfStatement(p) || ts.isForStatement(p) || ts.isForInStatement(p) || ts.isWhileStatement(p))
+                    return 'a loop';
+                if ((ts.isArrowFunction(p) || ts.isFunctionExpression(p)) && ts.isCallExpression(p.parent) && ts.isPropertyAccessExpression(p.parent.expression) && /^(map|flatMap|filter|forEach|some|every|find|reduce)$/.test(p.parent.expression.name.text))
+                    return `.${p.parent.expression.name.text}() over ${p.parent.expression.expression.getText().slice(0, 40)}`;
+                if (ts.isFunctionDeclaration(p))
+                    return undefined;
+            }
+            return undefined;
+        };
+        walk(sf, node => {
+            if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || !scanners.has(node.expression.text))
+                return;
+            const loop = inLoop(node);
+            if (loop)
+                hints.push(`nested-scan ${at(node)}: ${node.expression.text}() scans its \`${scanners.get(node.expression.text)}\` argument and is called inside ${loop}; confirm the sizes or index the inner collection once`);
+        });
+    }
+    return { failures, hints };
+}

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

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

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

@@ -0,0 +1,121 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import { createRequire } from 'module';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigSchema } from '../../types/index.js';
+import { reviewChange } from '../review.js';
+let repo;
+const git = (...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim();
+const write = (rel, body) => {
+    fs.mkdirSync(path.dirname(path.join(repo, rel)), { recursive: true });
+    fs.writeFileSync(path.join(repo, rel), body);
+};
+const config = (redundancy = {}) => ConfigSchema.parse({ version: 1, gates: { redundancy, unused_exports: { enabled: false }, orphan_files: { enabled: false } } });
+const typescriptDir = path.dirname(createRequire(import.meta.url).resolve('typescript/package.json'));
+const DB = `export interface Row { id: string; set_id: string | null; updated_at: string }
+export class Query<T> {
+    not(_column: string, _operator: string, _value: unknown): Query<T> { return this; }
+    gte(_column: string, _value: unknown): Query<T> { return this; }
+    returns<R>(): Promise<R> { return Promise.resolve([] as unknown as R); }
+}
+export function from(_table: string): Query<unknown> { return new Query(); }
+`;
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'typed-'));
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.email', 't@example.com');
+    git('config', 'user.name', 't');
+    git('config', 'commit.gpgsign', 'false');
+    write('package.json', '{"name":"fixture","devDependencies":{"typescript":"*"}}\n');
+    write('tsconfig.json', '{"compilerOptions":{"strict":true,"module":"esnext","target":"es2022","moduleResolution":"bundler","skipLibCheck":true},"include":["src"]}\n');
+    write('.gitignore', 'node_modules\n');
+    fs.mkdirSync(path.join(repo, 'node_modules'));
+    fs.symlinkSync(typescriptDir, path.join(repo, 'node_modules/typescript'), 'junction'); // the project's own compiler, never downloaded
+    write('src/db.ts', DB);
+    write('src/main.ts', "export const main = 1;\n");
+    git('add', '-A');
+    git('commit', '-qm', 'base');
+    git('checkout', '-qb', 'feature');
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+const review = (cfg = config()) => reviewChange({ cwd: repo, config: cfg, source: { mode: 'base', base: 'main' }, typed: true });
+describe('what a change made redundant', () => {
+    it('reports a null filter beside a range on the same column, and the nullable row type the query filters non-null', async () => {
+        write('src/scan.ts', `import { from, type Row } from './db';
+export async function scan(since: string): Promise<Row[]> {
+    return from('t').not('set_id', 'is', null).gte('set_id', since).returns<Row[]>();
+}
+`);
+        git('add', '-A');
+        git('commit', '-qm', 'scan');
+        const result = await review();
+        const found = result.findings.map(f => [f.id, f.files?.[0], f.line]);
+        expect(found).toContainEqual(['duplicate-null-filter', 'src/scan.ts', 3]);
+        expect(found).toContainEqual(['nullable-filtered-column', 'src/scan.ts', 3]); // anchored on the query the change wrote
+        expect(result.findings.find(f => f.id === 'nullable-filtered-column')?.details).toContain('declared nullable at src/db.ts:1');
+        expect(result.findings.find(f => f.id === 'duplicate-null-filter')?.details).toContain("`.gte('set_id', …)` at src/scan.ts:3");
+    }, 60_000);
+    it('reports an optional member every host supplies and a property written but never read; a spread host or a read elsewhere clears them', async () => {
+        write('src/types.ts', 'export interface Candidate { userId?: string; title: string; extra: string }\n');
+        write('src/a.ts', "import type { Candidate } from './types';\nexport const a: Candidate = { userId: 'u1', title: 'one', extra: 'x' };\n");
+        write('src/b.ts', "import type { Candidate } from './types';\nexport const b: Candidate = { userId: 'u2', title: 'two', extra: 'y' };\n");
+        write('src/use.ts', "import { a } from './a';\nimport { b } from './b';\nexport const titles = [a.title, b.title];\n");
+        git('add', '-A');
+        git('commit', '-qm', 'candidates');
+        const result = await review();
+        const found = result.findings.map(f => [f.id, f.files?.[0]]);
+        expect(found).toContainEqual(['optional-always-supplied', 'src/types.ts']);
+        expect(found).toContainEqual(['write-only-property', 'src/types.ts']);
+        const writeOnly = result.findings.filter(f => f.id === 'write-only-property').map(f => f.details.match(/`([^`]+)`/)[1]);
+        expect(writeOnly).toEqual(['Candidate.userId', 'Candidate.extra']); // userId is supplied everywhere and read nowhere: both findings hold
+        expect(found.map(([id]) => id)).not.toContain('typed-checks-unavailable');
+        // Declared as a wire contract: another service reads it, so nothing on it is write-only.
+        const wired = await review(config({ wire_contracts: ['src/types.ts'] }));
+        expect(wired.findings.map(f => f.id)).not.toContain('write-only-property');
+        // A value that leaves only through serialisation is a hint for the reviewer, not a block.
+        write('src/send.ts', "import { a } from './a';\nexport const body = JSON.stringify(a);\n");
+        git('add', '-A');
+        git('commit', '-qm', 'send');
+        const sent = await review();
+        expect(sent.findings.map(f => f.id)).not.toContain('write-only-property');
+        expect(sent.hints).toEqual([expect.stringContaining('Candidate.userId is set by 2 host(s)'), expect.stringContaining('write-only-property src/types.ts:1: Candidate.extra')]);
+        expect(sent.hints[1]).toContain('leaves only through JSON.stringify() at src/send.ts:2');
+    }, 60_000);
+    it('in a library, an exported type has consumers the program cannot see: its members are hints, a local type still blocks', async () => {
+        write('tsconfig.json', '{"compilerOptions":{"strict":true,"declaration":true,"module":"esnext","target":"es2022","moduleResolution":"bundler","skipLibCheck":true},"include":["src"]}\n');
+        write('src/types.ts', 'export interface Result { items?: string[]; cached: boolean }\ninterface Local { note: string }\nexport const local: Local = { note: "n" };\n');
+        write('src/a.ts', "import type { Result } from './types';\nexport const a: Result = { items: [], cached: true };\n");
+        write('src/b.ts', "import type { Result } from './types';\nexport const b: Result = { items: [], cached: false };\n");
+        git('add', '-A');
+        git('commit', '-qm', 'library');
+        const result = await review();
+        expect(result.findings.map(f => [f.id, f.details.match(/`([^`]+)`/)[1]])).toEqual([['write-only-property', 'Local.note']]);
+        expect(result.hints).toEqual([
+            expect.stringMatching(/^optional-always-supplied src\/types\.ts:1: `Result\.items` is optional .* consumers outside this program may read it\)$/),
+            expect.stringMatching(/^write-only-property src\/types\.ts:1: `Result\.items` is set by 2 host\(s\)/),
+            expect.stringMatching(/^write-only-property src\/types\.ts:1: `Result\.cached` is set by 2 host\(s\)/),
+        ]);
+    }, 60_000);
+    it('hints at a function that scans a collection, called once per item of another', async () => {
+        write('src/later.ts', 'export function hasLater(starts: string[], at: string): boolean {\n    return starts.some(s => s > at);\n}\nexport function plan(rows: string[], starts: string[]): boolean[] {\n    return rows.map(r => hasLater(starts, r));\n}\n');
+        git('add', '-A');
+        git('commit', '-qm', 'later');
+        const result = await review();
+        expect(result.hints).toEqual([expect.stringMatching(/^nested-scan src\/later\.ts:5: hasLater\(\) scans its `starts` argument and is called inside \.map\(\) over rows/)]);
+        expect(result.findings).toEqual([]);
+    }, 60_000);
+    it('says nothing for a project with no tsconfig, and blocks a TypeScript project whose program cannot be built', async () => {
+        write('src/x.ts', 'export const x = 1;\n');
+        git('add', '-A');
+        git('commit', '-qm', 'x');
+        fs.unlinkSync(path.join(repo, 'tsconfig.json'));
+        expect((await review()).findings).toEqual([]);
+        write('tsconfig.json', '{"extends":"./.generated/tsconfig.json"}\n');
+        const broken = await review();
+        expect(broken.status).toBe('ERROR'); // a check that could not run is a crashed gate, never a pass
+        expect(broken.gateErrors).toEqual(['typed-checks-unavailable']);
+        expect(broken.typedError).toMatch(/\.generated\/tsconfig\.json.*install the dependencies/s);
+    }, 60_000);
+});

package/dist/review/unused-exports.js

@@ -5,8 +5,10 @@
  * dead exports pile up in agent-written code. Only exports on added lines are checked. Another
  * file uses an export when it names the symbol as a whole word AND points at the module: an import,
  * re-export, dynamic import or mock whose specifier ends in the module's name (its folder's, for an
- * index file). A same-named word elsewhere, such as an unrelated route parameter, is not a use. What a framework calls by convention
- * (SvelteKit and Next.js route modules, hooks, serverless functions) is never reported.
+ * index file). A same-named word elsewhere, such as an unrelated route parameter, is not a use, and
+ * neither is a test: an export only its tests import is dead in production, and exporting a thing
+ * for its test is the habit that keeps it so. What a framework calls by convention (SvelteKit and
+ * Next.js route modules, hooks, serverless functions) is never reported.
  */
 import { spawnSync } from 'child_process';
 import fs from 'fs';
@@ -15,6 +17,8 @@ import { emitsDeclarations, isPackageEntry } from './package-layout.js';
 const GIT_TIMEOUT_MS = 10_000;
 const CODE = /\.(ts|tsx|js|jsx|mjs|svelte)$/;
 const SKIPPED = /\.(test|spec)\.|\.d\.ts$|(^|\/)(dist|build|out|coverage|\.next|[\w-]+-dist)\//;
+/** A test is not a consumer: production code must use the export. */
+const TEST = /\.(test|spec|e2e)\.[cm]?[jt]sx?$|(^|\/)(tests?|e2e|__tests__|__mocks__)\//;
 /** What a route or hook module exports for its framework, not for an importer. */
 const FRAMEWORK_EXPORTS = new Set([
     'load', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD', 'fallback', 'actions',
@@ -109,7 +113,7 @@ export function unusedExportFailures(cwd, diff, config) {
         return []; // git could not answer: say nothing rather than guess
     const points = pointsAtCache(cwd);
     return candidates
-        .filter(exp => ![...(users.get(exp.name) ?? [])].some(user => !isOwnFile(user, exp) && points(user, exp.file)))
+        .filter(exp => ![...(users.get(exp.name) ?? [])].some(user => !isOwnFile(user, exp) && !TEST.test(user) && points(user, exp.file)))
         .map(unused);
 }
 /**
@@ -179,7 +183,7 @@ function unused(exp) {
     return {
         id: 'unused-export',
         title: 'Unused export',
-        details: `\`${exp.name}\` is exported but no other file uses it. An export nothing imports is dead code that readers and agents treat as part of the module's contract.`,
+        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',
         provenance: 'traditional',
         files: [exp.file],

package/dist/templates/universal-config.js

@@ -255,6 +255,13 @@ export const UNIVERSAL_CONFIG = {
         optional_params: {
             enabled: true,
         },
+        change_sweep: {
+            enabled: true,
+        },
+        redundancy: {
+            enabled: true,
+            wire_contracts: [],
+        },
         duplicate_functions: {
             enabled: true,
         },
@@ -314,7 +321,10 @@ export const UNIVERSAL_CONFIG = {
         show_preexisting: false,
         reviewer: {
             enabled: false,
-            command: 'claude',
+            on_push: 'background',
+            reviewers: ['claude'],
+            mode: 'single',
+            models: {},
             timeout_ms: 900000,
         },
     },