@rigour-labs/core 6.2.5 → 6.3.1

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;

package/dist/semantic/learn/extract.js

@@ -0,0 +1,122 @@
+/**
+ * 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 { forEachNode, isFunctionLike } from '../ast.js';
+import { guardsOf, literalPropertyNames, namesIn, propertiesNamed } from './conditions.js';
+import { calleeDeclarationOf, calleeNameOf, calleeTextOf, functionKeyOf, functionName, invocationArgs, isInvocation, } from './identity.js';
+export function extractEdits(file, before, after) {
+    const beforeFns = functionTexts(before.sourceFile);
+    const afterFns = functionTexts(after.sourceFile);
+    const changed = [...new Set([...beforeFns.keys(), ...afterFns.keys()])]
+        .filter(fn => beforeFns.get(fn) !== afterFns.get(fn));
+    const beforeCalls = callsByFunction(before.sourceFile);
+    const afterCalls = callsByFunction(after.sourceFile);
+    const edits = [];
+    const withEdit = new Set();
+    for (const [slot, afterCall] of afterCalls) {
+        const beforeCall = beforeCalls.get(slot);
+        if (!beforeCall || beforeCall.getText() === afterCall.getText())
+            continue;
+        const fn = functionKeyOf(afterCall);
+        const found = [...optionEdits(file, fn, before, beforeCall, afterCall), ...guardEdits(file, fn, before, beforeCall, afterCall)];
+        if (found.length > 0)
+            withEdit.add(fn);
+        edits.push(...found);
+    }
+    // A function whose only change is inside a nested function that yielded an edit is covered by it.
+    const covered = (fn) => [...withEdit].some(key => key === fn || key.startsWith(`${fn}>`));
+    return { edits, unsupported: changed.filter(fn => !covered(fn)) };
+}
+/** Text of each named function, keyed by name path. */
+function functionTexts(sf) {
+    const texts = new Map();
+    forEachNode(sf, (node) => {
+        if (isFunctionLike(node) && functionName(node))
+            texts.set(functionKeyOf(node), node.getText(sf));
+    });
+    return texts;
+}
+/** Calls keyed by `<function>|<callee text>|<ordinal>`, so a call pairs with its counterpart. */
+function callsByFunction(sf) {
+    const calls = new Map();
+    const counts = new Map();
+    forEachNode(sf, (node) => {
+        if (!isInvocation(node))
+            return;
+        const base = `${functionKeyOf(node)}|${calleeTextOf(node)}`;
+        const ordinal = counts.get(base) ?? 0;
+        counts.set(base, ordinal + 1);
+        calls.set(`${base}|${ordinal}`, node);
+    });
+    return calls;
+}
+function optionEdits(file, fn, before, beforeCall, afterCall) {
+    const edits = [];
+    const afterArgs = invocationArgs(afterCall);
+    afterArgs.forEach((arg, argIndex) => {
+        const had = new Set(literalPropertyNames(invocationArgs(beforeCall)[argIndex]).map(n => n.toLowerCase()));
+        for (const property of literalPropertyNames(arg)) {
+            if (had.has(property.toLowerCase()))
+                continue;
+            const value = literalValue(arg, property);
+            const candidates = calleeLevels(before, beforeCall).map(({ callee, scoped }) => ({
+                template: 'require-option', callee, argIndex, property, ...(value ? { value } : {}), ...(scoped ? { scope: { file, fn } } : {}),
+            }));
+            edits.push({ file, fn, description: `${calleeTextOf(afterCall)}(...) gained \`${property}\``, candidates });
+        }
+    });
+    return edits;
+}
+function guardEdits(file, fn, before, beforeCall, afterCall) {
+    const edits = [];
+    const seen = new Map();
+    for (const afterProp of invocationArgs(afterCall).flatMap(arg => allProperties(arg))) {
+        const key = afterProp.name.getText().replace(/^['"`]|['"`]$/g, '');
+        const ordinal = seen.get(key.toLowerCase()) ?? 0;
+        seen.set(key.toLowerCase(), ordinal + 1);
+        const beforeProp = invocationArgs(beforeCall).flatMap(arg => propertiesNamed(arg, key))[ordinal];
+        if (!beforeProp)
+            continue;
+        const had = new Set(namesIn(guardsOf(beforeProp, beforeCall)));
+        const guard = namesIn(guardsOf(afterProp, afterCall)).find(n => !had.has(n));
+        if (!guard)
+            continue;
+        const candidates = calleeLevels(before, beforeCall).map(({ callee, scoped }) => ({
+            template: 'require-guard', callee, property: key, guard, appliesWhenArgsMention: !scoped, ...(scoped ? { scope: { file, fn } } : {}),
+        }));
+        edits.push({ file, fn, description: `\`${key}\` in ${calleeTextOf(afterCall)}(...) gained a condition on \`${guard}\``, candidates });
+    }
+    return edits;
+}
+/** Callee matchers from most to least general, ending with this exact call in this function. */
+function calleeLevels(tree, call) {
+    const levels = [];
+    const name = calleeNameOf(call);
+    if (name)
+        levels.push({ callee: { level: 'name', key: name }, scoped: false });
+    const declaration = calleeDeclarationOf(tree.checker, tree.cwd, call);
+    if (declaration)
+        levels.push({ callee: { level: 'declaration', key: declaration }, scoped: false });
+    const text = calleeTextOf(call);
+    levels.push({ callee: { level: 'text', key: text }, scoped: false });
+    levels.push({ callee: { level: 'text', key: text }, scoped: true });
+    return levels;
+}
+function allProperties(root) {
+    const found = [];
+    forEachNode(root, (node) => { if (ts.isPropertyAssignment(node))
+        found.push(node); });
+    return found;
+}
+function literalValue(arg, property) {
+    const prop = propertiesNamed(arg, property)[0];
+    return prop && ts.isStringLiteralLike(prop.initializer) ? prop.initializer.text : undefined;
+}

package/dist/semantic/learn/git-trees.d.ts

@@ -0,0 +1,8 @@
+export interface FixTrees {
+    commit: string;
+    beforeDir: string;
+    afterDir: string;
+    files: string[];
+    dispose(): void;
+}
+export declare function extractFixTrees(repoDir: string, rev: string): FixTrees;

package/dist/semantic/learn/git-trees.js

@@ -0,0 +1,32 @@
+/**
+ * The trees before and after a fix commit, extracted with `git archive` into
+ * a temporary folder. Read-only against the repository: no checkout, no
+ * worktree, no change to its index or refs.
+ */
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+export function extractFixTrees(repoDir, rev) {
+    const git = (...args) => execFileSync('git', ['-C', repoDir, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).trim();
+    const commit = git('rev-parse', '--verify', `${rev}^{commit}`);
+    const parent = git('rev-parse', '--verify', `${commit}^`);
+    const files = git('diff', '--name-only', '--diff-filter=M', parent, commit).split('\n').filter(Boolean);
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rigour-learn-'));
+    const unpack = (sha, name) => {
+        const dir = path.join(root, name);
+        const archive = path.join(root, `${name}.tar`);
+        fs.mkdirSync(dir);
+        git('archive', '--format=tar', '-o', archive, sha);
+        execFileSync('tar', ['-xf', archive, '-C', dir]);
+        fs.rmSync(archive);
+        return dir;
+    };
+    return {
+        commit,
+        beforeDir: unpack(parent, 'before'),
+        afterDir: unpack(commit, 'after'),
+        files,
+        dispose: () => fs.rmSync(root, { recursive: true, force: true }),
+    };
+}

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

@@ -0,0 +1,18 @@
+import ts from 'typescript';
+import type { CalleeMatcher } from './types.js';
+export type Invocation = ts.CallExpression | ts.NewExpression;
+export declare function isInvocation(node: ts.Node): node is Invocation;
+export declare function invocationArgs(call: Invocation): readonly ts.Expression[];
+/** Last name of the callee: `fetch` for `deps.fetch(...)`, `Response` for `new Response(...)`. */
+export declare function calleeNameOf(call: Invocation): string | undefined;
+export declare function calleeTextOf(call: Invocation): string;
+/**
+ * `<file>#<qualified name>` of the declaration the callee resolves to: a
+ * cwd-relative path inside the project, `lib:<file>` for a library.
+ */
+export declare function calleeDeclarationOf(checker: ts.TypeChecker, cwd: string, call: Invocation): string | undefined;
+export declare function calleeKey(checker: ts.TypeChecker, cwd: string, call: Invocation, level: CalleeMatcher['level']): string | undefined;
+/** A function-like node with a name: declared, a method, or assigned to a variable or property. */
+export declare function functionName(fn: ts.Node): string | undefined;
+/** `outer>inner` path of the named functions around `node`, or `<module>` at the top level. */
+export declare function functionKeyOf(node: ts.Node): string;

package/dist/semantic/learn/identity.js

@@ -0,0 +1,97 @@
+/**
+ * Stable identities for calls and functions, shared by learning and scanning.
+ *
+ * The same identity must come out of the code before a fix, the fixed code
+ * and the rest of the repository, so declaration keys are cwd-relative and
+ * function keys are name paths (`Class.method`, `outer>inner`), not positions.
+ */
+import path from 'path';
+import ts from 'typescript';
+import { isFunctionLike, propertyNameText, symbolOf, unwrap } from '../ast.js';
+export function isInvocation(node) {
+    return ts.isCallExpression(node) || ts.isNewExpression(node);
+}
+export function invocationArgs(call) {
+    return call.arguments ?? [];
+}
+/** Last name of the callee: `fetch` for `deps.fetch(...)`, `Response` for `new Response(...)`. */
+export function calleeNameOf(call) {
+    const callee = unwrap(call.expression);
+    if (ts.isIdentifier(callee))
+        return callee.text;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text;
+    return undefined;
+}
+export function calleeTextOf(call) {
+    return call.expression.getText(call.getSourceFile()).replace(/\s+/g, '');
+}
+/**
+ * `<file>#<qualified name>` of the declaration the callee resolves to: a
+ * cwd-relative path inside the project, `lib:<file>` for a library.
+ */
+export function calleeDeclarationOf(checker, cwd, call) {
+    const decl = symbolOf(checker, call.expression)?.declarations?.[0];
+    if (!decl)
+        return undefined;
+    const file = decl.getSourceFile().fileName;
+    const relative = path.relative(cwd, file).replace(/\\/g, '/');
+    const where = relative.startsWith('..') || relative.includes('node_modules/') ? `lib:${path.basename(file)}` : relative;
+    return `${where}#${qualifiedName(decl)}`;
+}
+export function calleeKey(checker, cwd, call, level) {
+    if (level === 'name')
+        return calleeNameOf(call);
+    if (level === 'text')
+        return calleeTextOf(call);
+    return calleeDeclarationOf(checker, cwd, call);
+}
+/** Name path of a named declaration: `HttpDeps.fetch`, `Client.send`, `load`. */
+function qualifiedName(decl) {
+    const names = [];
+    for (let node = decl; node && !ts.isSourceFile(node); node = node.parent) {
+        const name = declarationName(node);
+        if (name)
+            names.unshift(name);
+    }
+    return names.join('.') || '<anonymous>';
+}
+const NAMED_DECLARATIONS = new Set([
+    ts.SyntaxKind.VariableDeclaration, ts.SyntaxKind.FunctionDeclaration, ts.SyntaxKind.ClassDeclaration,
+    ts.SyntaxKind.InterfaceDeclaration, ts.SyntaxKind.TypeAliasDeclaration, ts.SyntaxKind.MethodDeclaration,
+    ts.SyntaxKind.MethodSignature, ts.SyntaxKind.PropertySignature, ts.SyntaxKind.PropertyDeclaration,
+    ts.SyntaxKind.ModuleDeclaration, ts.SyntaxKind.PropertyAssignment,
+]);
+function declarationName(node) {
+    if (!NAMED_DECLARATIONS.has(node.kind))
+        return undefined;
+    const name = node.name;
+    if (!name || ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name))
+        return undefined;
+    return propertyNameText(name);
+}
+/** A function-like node with a name: declared, a method, or assigned to a variable or property. */
+export function functionName(fn) {
+    if (!isFunctionLike(fn))
+        return undefined;
+    if ((ts.isFunctionDeclaration(fn) || ts.isMethodDeclaration(fn)) && fn.name)
+        return propertyNameText(fn.name);
+    const parent = fn.parent;
+    if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name))
+        return parent.name.text;
+    if (ts.isPropertyAssignment(parent))
+        return propertyNameText(parent.name);
+    return undefined;
+}
+/** `outer>inner` path of the named functions around `node`, or `<module>` at the top level. */
+export function functionKeyOf(node) {
+    const names = [];
+    for (let current = node; current && !ts.isSourceFile(current); current = current.parent) {
+        const name = functionName(current);
+        if (!name)
+            continue;
+        const owner = ts.isMethodDeclaration(current) && ts.isClassLike(current.parent) ? current.parent.name?.text : undefined;
+        names.unshift(owner ? `${owner}.${name}` : name);
+    }
+    return names.join('>') || '<module>';
+}

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

@@ -0,0 +1,25 @@
+import { type ProposedEdit } from './extract.js';
+import type { LearnedRule } from './types.js';
+export interface LearnInput {
+    beforeDir: string;
+    afterDir: string;
+    /** Repository the rules will guard; hits here are listed for review. */
+    repoDir: string;
+    /** Changed files, relative to both trees. */
+    files: string[];
+    commit?: string;
+    maxHits?: number;
+}
+export interface Rejection {
+    edit: ProposedEdit;
+    reason: string;
+}
+export interface LearnReport {
+    learned: LearnedRule[];
+    rejected: Rejection[];
+    unsupported: Array<{
+        file: string;
+        fn: string;
+    }>;
+}
+export declare function learnFromFix(input: LearnInput): Promise<LearnReport>;