@rigour-labs/core 6.2.5 → 6.3.0

package/dist/semantic/intent/benchmark.js

@@ -0,0 +1,74 @@
+/**
+ * Intent benchmark: labelled `Promise.all` sites for optional-read-no-fallback.
+ *
+ * Each case is one file (`code.ts`) whose reads are labelled optional or
+ * required, and whether a finding is expected. Scoring separates the raw
+ * answers from the verdicts that survive the flipped-question filter, so
+ * the filter's effect (accuracy gained, answers discarded) is measured.
+ */
+import fs from 'fs';
+import path from 'path';
+import { programBatches, loadProjectConfig } from '../program.js';
+import { classifyReads, findingsFor } from './intent-check.js';
+import { findParallelReads } from './parallel-reads.js';
+export function loadIntentCases(root) {
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, 'case.json')))
+        .map(entry => ({ name: entry.name, ...readCase(path.join(root, entry.name, 'case.json')) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function readCase(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Invalid intent benchmark case ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function runIntentCase(root, bench, model) {
+    const dir = path.join(root, bench.name);
+    const file = path.join(dir, 'code.ts');
+    const [program] = [...programBatches([file], loadProjectConfig(dir).options)];
+    const [site] = findParallelReads(dir, program.getTypeChecker(), program.getSourceFile(file));
+    if (!site)
+        return { case: bench, siteFound: false, verdicts: [], findings: 0 };
+    const verdicts = await classifyReads(model, site);
+    return { case: bench, siteFound: true, verdicts, findings: findingsFor(site, verdicts).length };
+}
+export function scoreIntent(results) {
+    const score = {
+        rawCorrect: 0, rawTotal: 0, consistent: 0, consistentCorrect: 0, reads: 0,
+        truePositives: 0, falseNegatives: 0, falsePositives: 0, finderErrors: [],
+    };
+    for (const result of results) {
+        if (result.siteFound !== (result.case.expectSite ?? true))
+            score.finderErrors.push(result.case.name);
+        for (const verdict of result.verdicts)
+            scoreRead(score, verdict, result.case.labels[verdict.read.label]);
+        scoreSite(score, result);
+    }
+    return score;
+}
+function scoreRead(score, { verdict, answers }, label) {
+    if (!label)
+        return;
+    const optional = label === 'optional';
+    score.reads += 1;
+    score.rawTotal += 2;
+    score.rawCorrect += Number(answers[0] === (optional ? 'yes' : 'no')) + Number(answers[1] === (optional ? 'no' : 'yes'));
+    if (verdict === 'unknown')
+        return;
+    score.consistent += 1;
+    score.consistentCorrect += Number(verdict === label);
+}
+function scoreSite(score, result) {
+    if (result.case.expectFinding) {
+        if (result.findings > 0)
+            score.truePositives += 1;
+        else
+            score.falseNegatives += 1;
+    }
+    else if (result.findings > 0) {
+        score.falsePositives += 1;
+    }
+}

package/dist/semantic/intent/intent-check.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Asks the local model the one thing code cannot say: is a read optional?
+ *
+ * Flipped-question protocol: each read gets two questions of opposite
+ * polarity ("should it still return if X fails?" / "is X required?"). An
+ * answer counts only when both agree (yes/no = optional, no/yes = required);
+ * anything else is unknown, and unknown never becomes a finding. A finding
+ * needs one read judged optional and another judged required at the same
+ * site: then the optional read's failure takes down the required one.
+ */
+import type { InferenceProvider } from '../../inference/types.js';
+import type { SemanticFinding } from '../types.js';
+import type { ParallelRead, ParallelReadSite } from './parallel-reads.js';
+export type Answer = 'yes' | 'no' | null;
+export type Verdict = 'optional' | 'required' | 'unknown';
+export interface YesNoModel {
+    ask(prompt: string): Promise<Answer>;
+}
+export interface ReadVerdict {
+    read: ParallelRead;
+    verdict: Verdict;
+    answers: [Answer, Answer];
+}
+export declare const RULE_ID = "optional-read-no-fallback";
+export declare const YES_NO_SCHEMA: {
+    type: string;
+    properties: {
+        answer: {
+            type: string;
+            enum: string[];
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/** A local provider as a yes/no oracle: schema-constrained, temperature 0. */
+export declare function yesNoModel(provider: InferenceProvider): YesNoModel;
+export declare function verdictOf([ifFails, required]: [Answer, Answer]): Verdict;
+export declare function questionsFor(site: ParallelReadSite, read: ParallelRead): [string, string];
+export declare function promptFor(site: ParallelReadSite, question: string): string;
+export declare function classifyReads(model: YesNoModel, site: ParallelReadSite): Promise<ReadVerdict[]>;
+/** Findings for a site: every read judged optional, when another read is judged required. */
+export declare function findingsFor(site: ParallelReadSite, verdicts: ReadVerdict[]): SemanticFinding[];

package/dist/semantic/intent/intent-check.js

@@ -0,0 +1,72 @@
+import { lineOf } from '../ast.js';
+export const RULE_ID = 'optional-read-no-fallback';
+const MAX_SOURCE_LINES = 80;
+export const YES_NO_SCHEMA = {
+    type: 'object',
+    properties: { answer: { type: 'string', enum: ['yes', 'no'] } },
+    required: ['answer'],
+    additionalProperties: false,
+};
+/** A local provider as a yes/no oracle: schema-constrained, temperature 0. */
+export function yesNoModel(provider) {
+    return {
+        async ask(prompt) {
+            const text = await provider.analyze(prompt, { jsonSchema: YES_NO_SCHEMA, temperature: 0, maxTokens: 16 });
+            try {
+                const answer = JSON.parse(text)?.answer;
+                return answer === 'yes' || answer === 'no' ? answer : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+export function verdictOf([ifFails, required]) {
+    if (ifFails === 'yes' && required === 'no')
+        return 'optional';
+    if (ifFails === 'no' && required === 'yes')
+        return 'required';
+    return 'unknown';
+}
+export function questionsFor(site, read) {
+    return [
+        `If \`${read.label}\` throws, should \`${site.fnName}\` still return a result built from the other calls?`,
+        `Is the result of \`${read.label}\` required for \`${site.fnName}\` to return anything useful?`,
+    ];
+}
+export function promptFor(site, question) {
+    const source = site.fn.getText(site.fn.getSourceFile()).split('\n').slice(0, MAX_SOURCE_LINES).join('\n');
+    return [
+        'You are reviewing a TypeScript function.',
+        '```ts', source, '```',
+        `The calls ${site.reads.map(r => `\`${r.label}\``).join(', ')} run together in \`await Promise.all([...])\`. If any of them throws, the whole Promise.all rejects.`,
+        `Question: ${question}`,
+        'Answer with JSON: {"answer": "yes"} or {"answer": "no"}.',
+    ].join('\n');
+}
+export async function classifyReads(model, site) {
+    const verdicts = [];
+    for (const read of site.reads) {
+        const [ifFails, required] = questionsFor(site, read);
+        const answers = [await model.ask(promptFor(site, ifFails)), await model.ask(promptFor(site, required))];
+        verdicts.push({ read, verdict: verdictOf(answers), answers });
+    }
+    return verdicts;
+}
+/** Findings for a site: every read judged optional, when another read is judged required. */
+export function findingsFor(site, verdicts) {
+    const required = verdicts.filter(v => v.verdict === 'required').map(v => `\`${v.read.label}\``);
+    if (required.length === 0)
+        return [];
+    return verdicts.filter(v => v.verdict === 'optional').map(({ read }) => ({
+        rule: RULE_ID,
+        severity: 'medium',
+        provenance: 'deep-analysis',
+        file: site.file,
+        line: lineOf(read.call),
+        message: `\`${read.label}\` looks optional to \`${site.fnName}\`, but it runs in Promise.all with ${required.join(', ')}, so its failure also discards ${required.length > 1 ? 'them' : 'that result'}.`,
+        hint: 'Give the optional read its own catch that returns a fallback (and tell the caller the result is partial), or confirm it is required.',
+        evidence: [`${site.file}:${site.line} Promise.all`, 'Intent from the local model: two flipped questions answered consistently.'],
+    }));
+}

package/dist/semantic/intent/intent.test.d.ts

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

package/dist/semantic/intent/intent.test.js

@@ -0,0 +1,46 @@
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+import { loadIntentCases, runIntentCase, scoreIntent } from './benchmark.js';
+import { verdictOf } from './intent-check.js';
+const ROOT = path.resolve(__dirname, '../../../../../benchmarks/intent');
+/** Answers from the labels: an oracle, optionally contradicting itself on one read. */
+function labelledModel(labels, contradict) {
+    return {
+        async ask(prompt) {
+            const label = Object.keys(labels).find(name => prompt.includes(`Question: If \`${name}\``) || prompt.includes(`result of \`${name}\``));
+            if (!label)
+                return null;
+            const optional = labels[label] === 'optional';
+            const firstQuestion = prompt.includes('Question: If');
+            if (label === contradict)
+                return 'yes';
+            return firstQuestion === optional ? 'yes' : 'no';
+        },
+    };
+}
+describe('verdictOf', () => {
+    it('counts only consistent flipped answers', () => {
+        expect(verdictOf(['yes', 'no'])).toBe('optional');
+        expect(verdictOf(['no', 'yes'])).toBe('required');
+        expect(verdictOf(['yes', 'yes'])).toBe('unknown');
+        expect(verdictOf(['no', 'no'])).toBe('unknown');
+        expect(verdictOf([null, 'no'])).toBe('unknown');
+    });
+});
+describe('intent benchmark with a labelled oracle', () => {
+    const cases = loadIntentCases(ROOT);
+    it('finds every labelled site, skips the fixed one, and scores the oracle perfectly', async () => {
+        const results = await Promise.all(cases.map(bench => runIntentCase(ROOT, bench, labelledModel(bench.labels))));
+        const score = scoreIntent(results);
+        expect(score.finderErrors).toEqual([]);
+        expect(score.falsePositives).toBe(0);
+        expect(score.falseNegatives).toBe(0);
+        expect(score.rawCorrect).toBe(score.rawTotal);
+    });
+    it('drops a read whose answers contradict each other instead of guessing', async () => {
+        const bench = cases.find(c => c.name === 'dashboard');
+        const result = await runIntentCase(ROOT, bench, labelledModel(bench.labels, 'getRecommendedCourses'));
+        expect(result.verdicts.find(v => v.read.label === 'getRecommendedCourses')?.verdict).toBe('unknown');
+        expect(result.findings).toBe(0);
+    });
+});

package/dist/semantic/intent/parallel-reads.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `await Promise.all([...])` sites where one read failing loses them all.
+ *
+ * This part is deterministic: two or more calls run together with no
+ * handling of their own, and nothing in the function catches the rejection.
+ * Whether that is a bug depends on intent (is one of the reads optional?),
+ * which the code cannot say; see intent-check.ts.
+ */
+import ts from 'typescript';
+import { type FunctionLike } from '../ast.js';
+export interface ParallelRead {
+    call: ts.CallExpression;
+    /** Callee text, e.g. `fetchStepEngagement`. */
+    label: string;
+}
+export interface ParallelReadSite {
+    file: string;
+    line: number;
+    fnName: string;
+    fn: FunctionLike;
+    reads: ParallelRead[];
+}
+export declare function findParallelReads(cwd: string, checker: ts.TypeChecker, sourceFile: ts.SourceFile): ParallelReadSite[];

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

@@ -0,0 +1,59 @@
+/**
+ * `await Promise.all([...])` sites where one read failing loses them all.
+ *
+ * This part is deterministic: two or more calls run together with no
+ * handling of their own, and nothing in the function catches the rejection.
+ * Whether that is a bug depends on intent (is one of the reads optional?),
+ * which the code cannot say; see intent-check.ts.
+ */
+import ts from 'typescript';
+import { calledFunction, enclosingFunction, forEachNode, lineOf, relativeFile, unwrap } from '../ast.js';
+import { promiseAllItems } from '../origins.js';
+import { functionKeyOf } from '../learn/identity.js';
+export function findParallelReads(cwd, checker, sourceFile) {
+    const sites = [];
+    forEachNode(sourceFile, (node) => {
+        if (!ts.isCallExpression(node) || !isPromiseAll(node))
+            return;
+        const fn = enclosingFunction(node);
+        if (!fn || isInsideTry(node, fn))
+            return;
+        const reads = (promiseAllItems(node) ?? [])
+            .map(item => unwrap(item))
+            .filter((item) => ts.isCallExpression(item) && !handlesOwnFailure(checker, item))
+            .map(call => ({ call, label: call.expression.getText(sourceFile).replace(/\s+/g, '') }));
+        if (reads.length < 2)
+            return;
+        sites.push({ file: relativeFile(cwd, sourceFile), line: lineOf(node), fnName: functionKeyOf(node), fn, reads });
+    });
+    return sites;
+}
+function isPromiseAll(call) {
+    const callee = call.expression;
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === 'all'
+        && ts.isIdentifier(callee.expression) && callee.expression.text === 'Promise';
+}
+/** Inside a `try` (with a catch) of the same function: the rejection is handled there. */
+function isInsideTry(node, fn) {
+    for (let child = node, parent = node.parent; parent && parent !== fn; child = parent, parent = parent.parent) {
+        if (ts.isTryStatement(parent) && parent.tryBlock === child && parent.catchClause)
+            return true;
+    }
+    return false;
+}
+/** `x().catch(...)`, `x().then(ok, fail)`, or a callee whose body catches and returns. */
+function handlesOwnFailure(checker, call) {
+    const callee = call.expression;
+    if (ts.isPropertyAccessExpression(callee)) {
+        if (callee.name.text === 'catch' || callee.name.text === 'finally')
+            return true;
+        if (callee.name.text === 'then' && call.arguments.length >= 2)
+            return true;
+    }
+    const target = calledFunction(checker, call);
+    const body = target?.body;
+    return !!body && ts.isBlock(body) && body.statements.some(s => ts.isTryStatement(s) && !!s.catchClause && catchReturns(s.catchClause));
+}
+function catchReturns(clause) {
+    return clause.block.statements.some(s => ts.isReturnStatement(s));
+}

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

@@ -0,0 +1,20 @@
+import { type LearnReport } from './learn.js';
+export interface LearnCase {
+    name: string;
+    note: string;
+    expect: {
+        template: string;
+        property: string;
+        guard?: string;
+        scoped: boolean;
+    } | null;
+    variants?: string[];
+    unsupported?: string[];
+}
+export interface LearnCaseResult {
+    case: LearnCase;
+    report: LearnReport;
+    problems: string[];
+}
+export declare function loadLearnCases(root: string): LearnCase[];
+export declare function runLearnCase(root: string, bench: LearnCase): Promise<LearnCaseResult>;

package/dist/semantic/learn/benchmark.js

@@ -0,0 +1,71 @@
+/**
+ * Learn benchmark: fixes whose rule `rigour learn` must reproduce.
+ *
+ * Each case has `before/` and `after/` trees and a `case.json` naming the rule
+ * expected (or `null` when no rule may be learned). The learned rule is then
+ * run over `variants/`: it must report exactly the listed locations, which
+ * measures whether it generalises beyond the code it came from.
+ */
+import fs from 'fs';
+import path from 'path';
+import { analyzeFiles } from '../engine.js';
+import { compileLearnedRule } from './compile.js';
+import { learnFromFix } from './learn.js';
+export function loadLearnCases(root) {
+    return fs.readdirSync(root, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, 'case.json')))
+        .map(entry => ({ name: entry.name, ...readCase(path.join(root, entry.name, 'case.json')) }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function readCase(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Invalid learn benchmark case ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function runLearnCase(root, bench) {
+    const dir = path.join(root, bench.name);
+    const beforeDir = path.join(dir, 'before');
+    const afterDir = path.join(dir, 'after');
+    const report = await learnFromFix({ beforeDir, afterDir, repoDir: afterDir, files: changedFiles(beforeDir, afterDir) });
+    const problems = [...expectationProblems(bench, report)];
+    const [rule] = report.learned;
+    if (rule && bench.variants)
+        problems.push(...variantProblems(path.join(dir, 'variants'), rule, bench.variants));
+    return { case: bench, report, problems };
+}
+function changedFiles(beforeDir, afterDir) {
+    return fs.readdirSync(beforeDir).filter(name => {
+        const after = path.join(afterDir, name);
+        return fs.existsSync(after) && fs.readFileSync(path.join(beforeDir, name), 'utf8') !== fs.readFileSync(after, 'utf8');
+    });
+}
+function expectationProblems(bench, report) {
+    const problems = [];
+    for (const fn of bench.unsupported ?? []) {
+        if (!report.unsupported.some(u => u.fn === fn))
+            problems.push(`expected ${fn} to be reported unsupported`);
+    }
+    if (bench.expect === null) {
+        if (report.learned.length > 0)
+            problems.push(`learned ${report.learned.map(r => r.id).join(', ')} but no rule was expected`);
+        return problems;
+    }
+    const want = bench.expect;
+    const matches = report.learned.filter(rule => rule.pattern.template === want.template
+        && rule.pattern.property === want.property
+        && (rule.pattern.template !== 'require-guard' || rule.pattern.guard === want.guard)
+        && Boolean(rule.pattern.scope) === want.scoped);
+    if (matches.length !== 1 || report.learned.length !== 1) {
+        problems.push(`expected one ${want.template} rule for ${want.property}; learned ${JSON.stringify(report.learned.map(r => r.pattern))}, rejected ${report.rejected.map(r => r.reason).join('; ')}`);
+    }
+    return problems;
+}
+function variantProblems(variantsDir, rule, expected) {
+    const files = fs.readdirSync(variantsDir).filter(f => /\.[cm]?[jt]sx?$/.test(f));
+    const found = analyzeFiles(variantsDir, files, { rules: [compileLearnedRule(rule)] }).map(f => `${f.file}:${f.line}`).sort();
+    const want = [...expected].sort();
+    return JSON.stringify(found) === JSON.stringify(want) ? [] : [`variants: expected ${want.join(', ') || 'none'}, got ${found.join(', ') || 'none'}`];
+}

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

@@ -0,0 +1,4 @@
+import type { SemanticRule } from '../types.js';
+import type { LearnedRule } from './types.js';
+export declare const LEARNED_PREFIX = "learned/";
+export declare function compileLearnedRule(rule: LearnedRule): SemanticRule;

package/dist/semantic/learn/compile.js

@@ -0,0 +1,56 @@
+import { forEachNode, lineOf, relativeFile, snippet } from '../ast.js';
+import { guardsOf, mentionsName, namesIn, propertiesNamed, setsProperty } from './conditions.js';
+import { calleeKey, functionKeyOf, invocationArgs, isInvocation } from './identity.js';
+export const LEARNED_PREFIX = 'learned/';
+export function compileLearnedRule(rule) {
+    const id = `${LEARNED_PREFIX}${rule.id}`;
+    return {
+        id,
+        check(ctx) {
+            const findings = [];
+            const file = relativeFile(ctx.cwd, ctx.sourceFile);
+            if (rule.pattern.scope && rule.pattern.scope.file !== file)
+                return findings;
+            forEachNode(ctx.sourceFile, (node) => {
+                if (!isInvocation(node) || !matchesCall(ctx, rule.pattern, node))
+                    return;
+                const at = violation(ctx, rule.pattern, node);
+                if (!at)
+                    return;
+                findings.push({
+                    rule: id,
+                    severity: rule.severity,
+                    provenance: 'traditional',
+                    file,
+                    line: lineOf(at),
+                    message: rule.message,
+                    hint: `Learned from ${describeSource(rule)}. Apply the same fix here, or delete .rigour/rules/${rule.id}.json if the rule no longer holds.`,
+                    evidence: [`${file}:${lineOf(node)} ${snippet(node)}`],
+                });
+            });
+            return findings;
+        },
+    };
+}
+function matchesCall(ctx, pattern, call) {
+    if (pattern.scope && functionKeyOf(call) !== pattern.scope.fn)
+        return false;
+    return calleeKey(ctx.checker, ctx.cwd, call, pattern.callee.level) === pattern.callee.key;
+}
+/** The node that breaks the rule in `call`, or undefined when the call complies. */
+function violation(ctx, pattern, call) {
+    const args = invocationArgs(call);
+    if (pattern.template === 'require-option') {
+        return setsProperty(ctx.checker, args[pattern.argIndex], pattern.property) ? undefined : call;
+    }
+    for (const prop of args.flatMap(arg => propertiesNamed(arg, pattern.property))) {
+        const applies = !pattern.appliesWhenArgsMention || args.some(arg => mentionsName(arg, pattern.guard, prop));
+        if (applies && !namesIn(guardsOf(prop, call)).includes(pattern.guard))
+            return prop;
+    }
+    return undefined;
+}
+function describeSource(rule) {
+    const where = `${rule.source.file} (${rule.source.function})`;
+    return rule.source.commit ? `fix ${rule.source.commit.slice(0, 8)} in ${where}` : `a fix in ${where}`;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * What guards a value, and whether an options object sets a property.
+ *
+ * A guard is a condition the value's selection depends on inside the call:
+ * `c ? v : w`, `c && v`, or a spread chosen by `...(c ? { k: v } : {})`.
+ */
+import ts from 'typescript';
+/** Conditions between `node` and `stop` (exclusive) that decide whether `node` is used, plus its own `?:` test. */
+export declare function guardsOf(node: ts.Node, stop: ts.Node): ts.Expression[];
+/** Identifier and property names read by `exprs`; property names (`x.stepsAvailable`) listed first. */
+export declare function namesIn(exprs: ts.Node[]): string[];
+/** Property assignments named `key` (case-insensitive) anywhere inside `root`. */
+export declare function propertiesNamed(root: ts.Node, key: string): ts.PropertyAssignment[];
+/** Whether `root` reads `name`, outside the subtree `except`. */
+export declare function mentionsName(root: ts.Node, name: string, except?: ts.Node): boolean;
+/**
+ * Whether `arg` provably sets `property`: an object literal with the property
+ * (directly or through a resolved spread), or a variable whose every origin is one.
+ */
+export declare function setsProperty(checker: ts.TypeChecker, arg: ts.Expression | undefined, property: string): boolean;
+/** Property names an object literal argument sets directly. */
+export declare function literalPropertyNames(arg: ts.Expression | undefined): string[];

package/dist/semantic/learn/conditions.js

@@ -0,0 +1,93 @@
+/**
+ * What guards a value, and whether an options object sets a property.
+ *
+ * A guard is a condition the value's selection depends on inside the call:
+ * `c ? v : w`, `c && v`, or a spread chosen by `...(c ? { k: v } : {})`.
+ */
+import ts from 'typescript';
+import { originsOf, propertyValues } from '../origins.js';
+import { propertyNameText, unwrap } from '../ast.js';
+const SHORT_CIRCUIT = new Set([ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.QuestionQuestionToken, ts.SyntaxKind.BarBarToken]);
+/** Conditions between `node` and `stop` (exclusive) that decide whether `node` is used, plus its own `?:` test. */
+export function guardsOf(node, stop) {
+    const guards = [];
+    const value = ts.isPropertyAssignment(node) ? unwrap(node.initializer) : undefined;
+    if (value && ts.isConditionalExpression(value))
+        guards.push(value.condition);
+    for (let child = node, parent = node.parent; parent && parent !== stop; child = parent, parent = parent.parent) {
+        const guard = selectingCondition(parent, child);
+        if (guard)
+            guards.push(guard);
+    }
+    return guards;
+}
+/** The condition in `parent` that decides whether `child` is evaluated, if any. */
+function selectingCondition(parent, child) {
+    if (ts.isConditionalExpression(parent) && child !== parent.condition)
+        return parent.condition;
+    if (ts.isBinaryExpression(parent) && parent.right === child && SHORT_CIRCUIT.has(parent.operatorToken.kind))
+        return parent.left;
+    return undefined;
+}
+/** Identifier and property names read by `exprs`; property names (`x.stepsAvailable`) listed first. */
+export function namesIn(exprs) {
+    const properties = [];
+    const identifiers = [];
+    const walk = (node) => {
+        if (ts.isPropertyAccessExpression(node))
+            properties.push(node.name.text);
+        else if (ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node))
+            identifiers.push(node.text);
+        ts.forEachChild(node, walk);
+    };
+    exprs.forEach(walk);
+    return [...new Set([...properties, ...identifiers])];
+}
+/** Property assignments named `key` (case-insensitive) anywhere inside `root`. */
+export function propertiesNamed(root, key) {
+    const found = [];
+    const wanted = key.toLowerCase();
+    const walk = (node) => {
+        if (ts.isPropertyAssignment(node) && propertyNameText(node.name)?.toLowerCase() === wanted)
+            found.push(node);
+        ts.forEachChild(node, walk);
+    };
+    walk(root);
+    return found;
+}
+/** Whether `root` reads `name`, outside the subtree `except`. */
+export function mentionsName(root, name, except) {
+    let found = false;
+    const walk = (node) => {
+        if (found || node === except)
+            return;
+        if (ts.isIdentifier(node) && node.text === name)
+            found = true;
+        else
+            ts.forEachChild(node, walk);
+    };
+    walk(root);
+    return found;
+}
+/**
+ * Whether `arg` provably sets `property`: an object literal with the property
+ * (directly or through a resolved spread), or a variable whose every origin is one.
+ */
+export function setsProperty(checker, arg, property) {
+    if (!arg)
+        return false;
+    const expr = unwrap(arg);
+    if (ts.isObjectLiteralExpression(expr))
+        return propertyValues(checker, expr, property).values.length > 0;
+    const origins = originsOf(checker, expr);
+    return origins.length > 0 && origins.every(o => o.kind === 'object' && propertyValues(checker, o.node, property).values.length > 0);
+}
+/** Property names an object literal argument sets directly. */
+export function literalPropertyNames(arg) {
+    const expr = arg && unwrap(arg);
+    if (!expr || !ts.isObjectLiteralExpression(expr))
+        return [];
+    return expr.properties
+        .map(p => (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p)) ? propertyNameText(p.name) : undefined)
+        .filter((n) => n !== undefined);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Finds the edit a fix made and proposes rules that would have caught it.
+ *
+ * Functions are aligned by name path, calls inside them by callee text and
+ * order. Two edit shapes are generalised (Getafix-style templates):
+ *  - require-option: an argument gains a property (`init` -> `{ ...init, redirect: 'manual' }`);
+ *  - require-guard: a property's value gains a condition (`max-age` only when `stepsAvailable`).
+ * Each edit yields candidates from most general (callee name) to most
+ * specific (this call in this function); validation picks the first that holds.
+ */
+import ts from 'typescript';
+import type { LearnedPattern } from './types.js';
+export interface TreeFile {
+    cwd: string;
+    checker: ts.TypeChecker;
+    sourceFile: ts.SourceFile;
+}
+export interface ProposedEdit {
+    file: string;
+    fn: string;
+    /** e.g. "deps.fetch(...) gained `redirect`". */
+    description: string;
+    candidates: LearnedPattern[];
+}
+export interface Extraction {
+    edits: ProposedEdit[];
+    /** Changed functions whose edit matches no template. */
+    unsupported: string[];
+}
+export declare function extractEdits(file: string, before: TreeFile, after: TreeFile): Extraction;