@rigour-labs/core 6.6.5 → 6.7.0

package/dist/review/typed/redundancy.js

@@ -0,0 +1,378 @@
+/**
+ * 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 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).
+ * 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 { isTestFile } from '../test-files.js';
+import { loadProgram } from './program.js';
+import { loadSchemaNullability, tableKey } from './schema-nullability.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) && !isTestFile(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') && !isTestFile(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));
+    // nullable-not-null-column: read once, and only when a changed file queries a table.
+    let schema;
+    const reportedDecls = new Set();
+    const notNullColumns = (chain, outer, filtered) => {
+        const from = chain.find(c => c.name === 'from' && strArg(c.call, 0));
+        if (!from)
+            return;
+        const schemaCall = chain.find(c => c.name === 'schema' && strArg(c.call, 0));
+        const table = `${schemaCall ? `${strArg(schemaCall.call, 0)}.` : ''}${strArg(from.call, 0)}`;
+        schema ??= loadSchemaNullability(typed.root, settings.schema_migrations);
+        const columns = schema.get(tableKey(table));
+        const row = columns && rowTypeOf(chain, outer);
+        if (!columns || !row)
+            return;
+        const select = chain.find(c => c.name === 'select');
+        const selected = select ? strArg(select.call, 0) ?? '' : '';
+        // The query's own line the change touched: a call's start is the start of the whole chain, so its method name.
+        const queryLine = chain.map(c => c.call.expression.name).find(touched);
+        for (const prop of checker.getPropertiesOfType(row)) {
+            const decl = prop.declarations?.[0];
+            const name = prop.name;
+            if (!decl || !ts.isPropertySignature(decl) || !decl.type || reportedDecls.has(decl) || filtered.has(name))
+                continue;
+            // An alias (`name:other_column`) maps another column onto this property.
+            if (columns.get(name) !== true || new RegExp(`(^|[\\s,(])${name.replace(/[$]/g, '\\$')}\\s*:`).test(selected) || !isNullable(checker.getTypeFromTypeNode(decl.type)))
+                continue;
+            const anchor = touched(decl) ? decl : queryLine;
+            if (!anchor)
+                continue;
+            reportedDecls.add(decl);
+            report('nullable-not-null-column', 'Nullable type for a NOT NULL column', anchor, `\`${name}\` is declared nullable at ${at(decl)} but \`${table}.${name}\` is NOT NULL in the migrations, so every guard on it is dead.`, 'Narrow the row type and delete the guards on it. If the migrations Rigour read are not the ones this code runs against, point gates.redundancy.schema_migrations at them.');
+        }
+    };
+    // duplicate-null-filter, nullable-filtered-column and nullable-not-null-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));
+            notNullColumns(chain, node, new Set(nots.map(n => strArg(n.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,179 @@
+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);
+});
+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; }
+    returns<R>(): Promise<R> { return Promise.resolve([] as unknown as R); }
+}
+export const db = {
+    schema(_name: string) { return db; },
+    from(_table: string): Query<unknown> { return new Query(); },
+};
+`;
+    let migrations;
+    beforeEach(() => {
+        migrations = fs.mkdtempSync(path.join(os.tmpdir(), 'other-repo-migrations-'));
+        fs.writeFileSync(path.join(migrations, '20240101_sets.sql'), 'create table study_set (id uuid primary key, owner_id uuid not null, title text, archived_at timestamptz not null);');
+        write('src/sb.ts', SUPABASE);
+        git('add', '-A');
+        git('commit', '-qm', 'client');
+    });
+    afterEach(() => { fs.rmSync(migrations, { recursive: true, force: true }); });
+    it('notes the nullable member the change declared, never blocking, and skips nullable columns and aliases', async () => {
+        write('src/sets.ts', `import { db } from './sb';
+export interface SetRow { id: string; owner_id: string | null; title: string | null; done: string | null }
+export async function sets(): Promise<SetRow[]> {
+    return db.from('study_set').select('id, owner_id, title, done:archived_at').returns<SetRow[]>();
+}
+`);
+        git('add', '-A');
+        git('commit', '-qm', 'sets');
+        const result = await review(config({ schema_migrations: [migrations] }));
+        expect(result.findings.filter(f => f.id === 'nullable-not-null-column')).toEqual([]);
+        const notes = result.advisory.filter(f => f.id === 'nullable-not-null-column');
+        expect(notes.map(f => [f.files?.[0], f.line])).toEqual([['src/sets.ts', 2]]);
+        expect(notes[0].details).toContain('`owner_id` is declared nullable at src/sets.ts:2 but `study_set.owner_id` is NOT NULL');
+    });
+    it('anchors on the new query when the row type is older, and reads the schema the query names', async () => {
+        fs.writeFileSync(path.join(migrations, '20240202_app.sql'), 'create table app.study_set (id uuid, owner_id uuid);');
+        git('checkout', '-q', 'main'); // the row type is older than the branch
+        write('src/rows.ts', 'export interface SetRow { id: string; owner_id: string | null }\n');
+        git('add', '-A');
+        git('commit', '-qm', 'rows');
+        git('checkout', '-q', 'feature');
+        git('merge', '-q', '--no-edit', 'main');
+        write('src/sets.ts', `import { db } from './sb';
+import type { SetRow } from './rows';
+export async function publicSets(): Promise<SetRow[]> {
+    return db
+        .from('study_set').select('*').returns<SetRow[]>();
+}
+export async function appSets(): Promise<SetRow[]> {
+    return db.schema('app').from('study_set').select('*').returns<SetRow[]>();
+}
+`);
+        git('add', '-A');
+        git('commit', '-qm', 'sets');
+        const result = await review(config({ schema_migrations: [migrations] }));
+        expect(result.advisory.filter(f => f.id === 'nullable-not-null-column').map(f => [f.files?.[0], f.line])).toEqual([['src/sets.ts', 5]]);
+    });
+});

package/dist/review/typed/schema-nullability.d.ts

@@ -0,0 +1,6 @@
+/** `schema.table` → column → NOT NULL. A table mapped to `null` is one whose columns cannot be known. */
+export type SchemaNullability = Map<string, Map<string, boolean> | null>;
+/** The migrations in `dirs` (relative to the repository, absolute, or `~/`), replayed in file-name order. Missing folders are skipped. */
+export declare function loadSchemaNullability(root: string, dirs: string[]): SchemaNullability;
+/** `schema.table` with Postgres's folding: unquoted names lower-cased, the schema `public` by default. */
+export declare function tableKey(name: string): string;