graph-indexer 3.0.1 → 3.1.0

package/src/query/injection.mjs

@@ -0,0 +1,173 @@
+/**
+ * Dependency injection: the edge between a value a class receives and the code that provides it,
+ * which the compiler does not see. In NestJS a constructor parameter marked `@Inject(TOKEN)` gets
+ * whatever a module registered as `{ provide: TOKEN, useClass | useExisting | useFactory | useValue }`;
+ * its declared type is often an interface or a union, so neither the type checker nor grep for the
+ * type name leads to the implementation.
+ *
+ * Recognised from the indexed source (TypeScript):
+ *   - providers: an object with `provide:` and one of `useClass`, `useExisting`, `useFactory`,
+ *     `useValue`, on one line or over the lines that follow;
+ *   - injection points: `@Inject(TOKEN)` on a constructor parameter or property.
+ * Test files are left out: their providers are mocks.
+ * A token is the definition the index binds it to (a constant, a class, a symbol); a string, a
+ * constant declared as that string and `Class.name` are one token. An expression such as
+ * `getRepositoryToken(User)` is matched by its text, only when written the same way, and marked so;
+ * tokens computed at run time (`Object.values(Namespace).map(ns => ({ provide: ns, … }))`) are not
+ * found. Microservice clients registered with `ClientsModule.register([{ name: TOKEN }])` are
+ * providers too.
+ */
+
+import { collectSpring } from './injection-spring.mjs';
+
+const PROVIDE = /\bprovide\s*:\s*([^,}\n]+?)\s*(?:,|}|$)/;
+const USE = /\buse(Class|Existing|Factory|Value)\s*:\s*([^,}\n]*)/;
+const INJECT = /@Inject\(\s*([^)]*?)\s*\)/g;
+const PARAM = /^\s*(?:(?:private|public|protected|readonly|override)\s+)*([A-Za-z_$][\w$]*)\s*[?!]?\s*:\s*([^,=)]+)/;
+
+const strip = (s) => String(s ?? '').trim().replace(/\s+/g, ' ');
+
+/** The definition a name on a line is bound to, through the index. */
+function bound(intel, fileId, line, name) {
+    if (!/^[A-Za-z_$][\w$]*$/.test(name)) return null;
+    const r = intel.store.get('SELECT dst_id FROM refs WHERE file_id = ? AND line = ? AND name = ? AND dst_id IS NOT NULL LIMIT 1', fileId, line, name);
+    return r ? symRow(intel, r.dst_id) : null;
+}
+
+function symRow(intel, id) {
+    return intel.store.get('SELECT s.id, s.name, s.qname, s.kind, s.start_line, s.end_line, s.parent_id, f.path FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.id = ?', id) ?? null;
+}
+
+/** A constant's string value (`const REFLECTOR = 'Reflector'`), if it is declared as one. */
+function stringValue(intel, s) {
+    if (s.kind !== 'constant' && s.kind !== 'variable') return null;
+    const l = intel.fileLines(s.path)?.[s.start_line - 1] ?? '';
+    return new RegExp(`\\b${s.name}\\s*(?::[^=]+)?=\\s*(['"\`])([^'"\`]*)\\1\\s*;?\\s*$`).exec(l)?.[2] ?? null;
+}
+
+/**
+ * A token's identity: the definition it names, or its text (strings and expressions). A string,
+ * a constant holding one and `Class.name` are the same token when the strings are equal; `p.provide`
+ * is the token of the provider declared as `p`.
+ */
+function tokenKey(intel, fileId, line, text) {
+    const t = strip(text);
+    const dotted = /^([\w$]+)\.(name|provide)$/.exec(t);
+    if (dotted) {
+        const head = bound(intel, fileId, line, dotted[1]);
+        if (head && dotted[2] === 'name' && head.kind === 'class') return { key: `str:${head.name}`, token: t, sym: head, exact: true };
+        if (head && dotted[2] === 'provide') return { key: `holder:${head.id}`, token: t, sym: head, exact: true };
+    }
+    const last = /^(?:[\w$]+\.)*([\w$]+)$/.exec(t)?.[1];
+    let s = last ? bound(intel, fileId, line, last) : null;
+    // a member of a type (`FactoryProvider.provide`) is a shape, not a token
+    if (s && (s.kind === 'field' || s.kind === 'property')) s = null;
+    if (s) {
+        const v = stringValue(intel, s);
+        return { key: v != null ? `str:${v}` : `id:${s.id}`, token: s.qname, sym: s, exact: true };
+    }
+    const lit = /^(['"`])(.*)\1$/.exec(t);
+    return { key: lit ? `str:${lit[2]}` : `text:${t}`, token: t, sym: null, exact: !!lit };
+}
+
+/** The variable or constant a line is declared in (`const catsProvider = { provide: … }`). */
+function holderAt(intel, fileId, line) {
+    return intel.store.get(`SELECT id FROM symbols WHERE file_id = ? AND kind IN ('variable', 'constant') AND start_line <= ? AND end_line >= ? ORDER BY start_line DESC LIMIT 1`, fileId, line, line)?.id ?? null;
+}
+
+/** Is the line inside an interface or a type alias? */
+function inTypeDeclaration(intel, fileId, line) {
+    const s = intel.store.get(`SELECT kind FROM symbols WHERE file_id = ? AND start_line <= ? AND end_line >= ? AND kind IN ('class', 'interface', 'type', 'function', 'method', 'variable', 'constant')
+        ORDER BY start_line DESC LIMIT 1`, fileId, line, line);
+    return s?.kind === 'interface' || s?.kind === 'type';
+}
+
+/** The innermost class around a line. */
+function classAt(intel, fileId, line) {
+    return intel.store.get(`SELECT s.id, s.name, s.qname, s.kind, s.start_line, s.end_line, s.parent_id, f.path FROM symbols s JOIN files f ON f.id = s.file_id
+        WHERE s.file_id = ? AND s.kind = 'class' AND s.start_line <= ? AND s.end_line >= ? ORDER BY s.start_line DESC LIMIT 1`, fileId, line, line) ?? null;
+}
+
+/**
+ * Providers and injection points of the repository, keyed by what is asked for (a NestJS token, a
+ * Spring type): { providers: [{ key, token, exact, how, target, targetText, file, line }],
+ *   injections: [{ key, token, exact, owner, param, type, file, line, from, why? }] }, `from`
+ * being the providers the point may receive (Spring: the beans chosen, see injection-spring.mjs).
+ */
+export function collectInjection(intel) {
+    if (intel._injection?.version === intel.ix?.version) return intel._injection.data;
+    const providers = [], injections = [];
+    // test modules register mocks (`{ provide: Service, useValue: { get: jest.fn() } }`): not the app's wiring
+    const files = intel.store.all(`SELECT id, path FROM files WHERE lang IN ('typescript', 'tsx') AND is_test = 0`);
+    for (const f of files) {
+        const lines = intel.fileLines(f.path);
+        if (!lines) continue;
+        const text = lines.join('\n');
+        if (!text.includes('provide') && !text.includes('@Inject(') && !text.includes('ClientsModule')) continue;
+        lines.forEach((l, i) => {
+            const line = i + 1;
+            if (/^\s*(\/\/|\/?\*)/.test(l)) return;
+            const p = PROVIDE.exec(l);
+            // `provide: InjectionToken;` in an interface or type declares the shape, it provides nothing
+            if (p && !inTypeDeclaration(intel, f.id, line)) {
+                // the `use…` of this provider: on its line, or on the lines below before the next one
+                let u = USE.exec(l.slice(p.index)), at = line;
+                for (let j = i + 1; !u && j < Math.min(lines.length, i + 15) && !PROVIDE.test(lines[j]); j++) { u = USE.exec(lines[j]); at = j + 1; }
+                if (u) {
+                    const tk = tokenKey(intel, f.id, line, p[1]);
+                    const targetText = strip(u[2]) || `(${u[1] === 'Value' ? 'a value' : 'code'} on the lines below)`;
+                    const name = /^(?:new\s+)?(?:[\w$]+\.)*([\w$]+)\b/.exec(targetText)?.[1];
+                    let target = name && !/^(async|function)$/.test(name) && !/=>/.test(targetText.split('(')[0]) ? bound(intel, f.id, at, name) : null;
+                    // `useClass: options.useClass` passes along what a caller gave: not a definition here
+                    if (target && (target.kind === 'field' || target.kind === 'property')) target = null;
+                    providers.push({ ...tk, how: `use${u[1]}`, target, targetText, file: f.path, line, holder: holderAt(intel, f.id, line) });
+                }
+            }
+            // a microservice client: `ClientsModule.register([{ name: MATH_SERVICE, transport: … }])`
+            const client = /^\s*name\s*:\s*([^,}\n]+?)\s*(?:,|}|$)/.exec(l) ?? /\{\s*name\s*:\s*([^,}\n]+?)\s*[,}]/.exec(l);
+            if (client && lines.slice(Math.max(0, i - 6), i + 1).some(x => /\bClientsModule\.register(Async)?\s*\(/.test(x))) {
+                providers.push({ ...tokenKey(intel, f.id, line, client[1]), how: 'ClientsModule', target: null, targetText: 'a client proxy for the microservice', file: f.path, line, holder: null });
+            }
+            for (const m of l.matchAll(INJECT)) {
+                if (!m[1]) continue;
+                const tk = tokenKey(intel, f.id, line, m[1]);
+                // the parameter or property it decorates: the rest of the line, or the next line
+                const rest = l.slice(m.index + m[0].length);
+                const pm = PARAM.exec(rest.trim() ? rest : (lines[i + 1] ?? ''));
+                injections.push({ ...tk, owner: classAt(intel, f.id, line), param: pm?.[1] ?? null, type: pm ? strip(pm[2]).replace(/;$/, '') : null, file: f.path, line });
+            }
+        });
+    }
+    // `@Inject(p.provide)`: the token of the provider declared as `p`
+    for (const j of injections) {
+        if (!j.key.startsWith('holder:')) continue;
+        const p = providers.find(x => x.holder === Number(j.key.slice(7)));
+        if (p) Object.assign(j, { key: p.key, token: `${j.token} (${p.token})` });
+    }
+    for (const j of injections) j.from = providers.filter(p => p.key === j.key);
+    const spring = collectSpring(intel);
+    const data = { providers: [...providers, ...spring.providers], injections: [...injections, ...spring.injections] };
+    intel._injection = { version: intel.ix?.version, data };
+    return data;
+}
+
+/** For a definition: the tokens it provides, each with where it is injected. */
+export function providedBy(intel, id) {
+    const { providers, injections } = collectInjection(intel);
+    return providers.filter(p => p.target?.id === id).map(p => ({ ...p, into: injections.filter(j => j.from.includes(p)) }));
+}
+
+/** For a token or a type asked for by injection: what provides it and where it is injected. */
+export function tokenUses(intel, id) {
+    const { providers, injections } = collectInjection(intel);
+    const key = `id:${id}`;
+    const js = injections.filter(j => j.key === key);
+    // a NestJS token's providers name it; a Spring type's are the beans its injection points receive
+    const ps = [...new Set([...providers.filter(p => p.key === key && !p.types), ...js.flatMap(j => j.from)])];
+    return { providers: ps, injections: js };
+}
+
+/** What a class receives by injection (`@Inject(TOKEN)`, Spring's injection points), each with its providers. */
+export function injectedInto(intel, classId) {
+    return collectInjection(intel).injections.filter(j => j.owner?.id === classId);
+}

package/src/query/intel.mjs

@@ -173,9 +173,18 @@ export class CodeIntel {
         }
         const norm = t.replace(/::|#|->/g, '.');
         if (norm.includes('.')) {
-            const name = norm.split('.').pop();
-            const rows = this.store.all(`SELECT id, qname FROM symbols WHERE name = ?`, name).filter(r => r.qname === norm || r.qname.endsWith('.' + norm));
-            if (rows.length) return { matches: this.#rank(rows.map(r => r.id)).slice(0, limit).map(id => this.sym(id)), how: 'qualified' };
+            const qual = norm.split('.'), name = qual.pop();
+            const rows = this.store.all(`SELECT s.id, s.qname, f.path FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.name = ?`, name);
+            const exact = rows.filter(r => r.qname === norm || r.qname.endsWith('.' + norm));
+            if (exact.length) return { matches: this.#rank(exact.map(r => r.id)).slice(0, limit).map(id => this.sym(id)), how: 'qualified' };
+            // `module.func`, `pkg.mod.func`, `ns::Type::method`, `Foo.prototype.bar`: the owner named
+            // last before the name is one of the definition's enclosing names, its file or a directory
+            const owner = qual[qual.length - 1];
+            const inModule = rows.filter(r => r.qname.split('.').slice(0, -1).includes(owner) || r.path.replace(/\.[^./]+$/, '').split('/').includes(owner));
+            if (inModule.length) return { matches: this.#rank(inModule.map(r => r.id)).slice(0, limit).map(id => this.sym(id)), how: 'module' };
+            // the qualifier names nothing that declares `name`: answering with another owner's
+            // `name` would present the wrong definition's uses as the asked one's
+            if (rows.length) return { matches: [], how: 'qualifier-unknown', sameName: this.#rank(rows.map(r => r.id)).slice(0, limit).map(id => this.sym(id)) };
         }
         let rows = this.store.all('SELECT id FROM symbols WHERE name = ?', norm.split('.').pop());
         if (!rows.length) rows = this.store.all('SELECT id FROM symbols WHERE name_lc = ?', norm.split('.').pop().toLowerCase());
@@ -198,6 +207,32 @@ export class CodeIntel {
         return [...ids].sort((a, b) => score(b) - score(a) || a - b);
     }
 
+    /**
+     * Where `word` occurs in code the parser could not read (an ERROR region, give or take a
+     * line): a declaration or a use of it there may be missing from the index or bound wrongly.
+     * The first such line per file.
+     * @returns {{ path: string, line: number }[]}
+     */
+    filesWithParseErrors(word, { lang = null, max = 50 } = {}) {
+        if (!word || !/^[\w$]+$/.test(word)) return [];
+        const re = new RegExp(`(?<![\\w$])${escapeRegExp(word)}(?![\\w$])`);
+        const rows = this.store.all(`SELECT path, parse_error_lines FROM files WHERE parse_errors > 0${lang ? ' AND lang = ?' : ''} ORDER BY is_test, path LIMIT 5000`, ...(lang ? [lang] : []));
+        const out = [];
+        for (const r of rows) {
+            let regions;
+            try { regions = JSON.parse(r.parse_error_lines ?? '[]'); } catch { regions = []; }
+            const lines = regions.length ? this.fileLines(r.path) : null;
+            if (!lines) continue;
+            hit: for (const [a, b] of regions) {
+                for (let ln = Math.max(1, a - 1); ln <= Math.min(lines.length, b + 1); ln++) {
+                    if (re.test(lines[ln - 1])) { out.push({ path: r.path, line: ln }); break hit; }
+                }
+            }
+            if (out.length >= max) break;
+        }
+        return out;
+    }
+
     members(id) {
         return this.store.all('SELECT id, name, qname, kind, start_line, end_line, sig, visibility FROM symbols WHERE parent_id = ? ORDER BY start_line', id);
     }
@@ -235,12 +270,14 @@ export class CodeIntel {
 
     /**
      * The subtypes of a member's type, transitively, split into those that inherit the member — they
-     * run it as their own, so a change to it reaches them — and those that redeclare it (their own
-     * version runs; their subtypes are not followed).
-     * @returns {{ inherit: object[], override: object[] }} index rows of the subtypes
+     * run it as their own, so a change to it reaches them — those that extend it (they redeclare it,
+     * but their version uses this one: `TRANSFORMS = {**Base.TRANSFORMS, …}`, `super().m()`; a change
+     * still reaches them, and their subtypes that inherit their version), and those that override it
+     * (their own version runs without this one).
+     * @returns {{ inherit: object[], extend: object[], override: object[] }} index rows of the subtypes
      */
     inheritance(id, { max = 30 } = {}) {
-        const out = { inherit: [], override: [] };
+        const out = { inherit: [], extend: [], override: [] };
         const sym = this.sym(id);
         if (!sym) return out;
         const type = this.ix.resolver.enclosingType(sym.id);
@@ -263,20 +300,30 @@ export class CodeIntel {
             frontier = next;
         }
         const declares = new Map();
-        const declared = (tid) => { if (!declares.has(tid)) declares.set(tid, this.#membersNamed(tid, sym.name).length > 0); return declares.get(tid); };
+        const declared = (tid) => { if (!declares.has(tid)) declares.set(tid, this.#membersNamed(tid, sym.name)); return declares.get(tid).length > 0; };
+        // a redeclaration that reads the member of a type after it in the resolution order uses that version
+        const usesNext = (tid, rest) => {
+            const later = new Set(rest.flatMap(t => declared(t) ? declares.get(t) : []));
+            return declares.get(tid).some(id => this.store.all('SELECT dst_id FROM refs WHERE src_id = ? AND dst_id IS NOT NULL', id).some(r => later.has(r.dst_id)));
+        };
         for (const sid of subs) {
             const order = this.ix.resolver.mro(sid);
             if (!order.includes(type.id)) continue;
-            const owner = order.find(declared);
+            const declarers = order.filter(declared);
+            const owner = declarers[0];
+            // follow the redeclarations that use the next version down to this one
+            let k = 0;
+            while (declarers[k] !== type.id && k + 1 < declarers.length && usesNext(declarers[k], order.slice(order.indexOf(declarers[k]) + 1))) k++;
             let bucket = null;
             if (owner === type.id) bucket = out.inherit;
+            else if (declarers[k] === type.id) bucket = out.extend;
             // its own version, where it would otherwise run this one
-            else if (owner === sid && order.slice(1).find(declared) === type.id) bucket = out.override;
+            else if (owner === sid && declarers[1] === type.id) bucket = out.override;
             if (!bucket) continue;
             const st = this.sym(sid);
             if (!st) continue;
             bucket.push(st);
-            if (out.inherit.length + out.override.length >= max) return out;
+            if (out.inherit.length + out.extend.length + out.override.length >= max) return out;
         }
         return out;
     }
@@ -308,8 +355,23 @@ export class CodeIntel {
     overloads(sym) {
         // where each overload is a method of its own (Java, C#, Kotlin…), calls are bound to the one they reach
         if (this.ix.resolver.specs[sym.lang]?.distinctOverloads) return [];
-        return this.store.all('SELECT id FROM symbols WHERE file_id = ? AND qname = ? AND kind = ? AND (parent_id IS ? OR parent_id = ?) AND is_static = ?',
-            sym.file_id, sym.qname, sym.kind, sym.parent_id, sym.parent_id, sym.is_static ? 1 : 0).map(r => r.id);
+        // methods of one name from impls of different traits or types (Rust `Debug::fmt` / `Display::fmt`,
+        // `impl AsyncWrite for Cursor<Vec<u8>>` / `… for Cursor<&mut [u8]>`) are not redeclarations
+        return this.store.all('SELECT id FROM symbols WHERE file_id = ? AND qname = ? AND kind = ? AND (parent_id IS ? OR parent_id = ?) AND is_static = ? AND (kind != \'method\' OR (bases IS ? AND (? != \'rust\' OR decorators IS ?)))',
+            sym.file_id, sym.qname, sym.kind, sym.parent_id, sym.parent_id, sym.is_static ? 1 : 0, sym.bases ?? null, sym.lang, sym.decorators ?? null).map(r => r.id);
+    }
+
+    /**
+     * A Rust trait method's implementations (`fn m` in each `impl Trait for X`): calls of them are
+     * calls of the trait's method, as rust-analyzer counts them, so they are its references.
+     */
+    #traitImpls(sym) {
+        if (sym.lang !== 'rust' || sym.kind !== 'method' || sym.parent_id == null) return [];
+        const trait = this.sym(sym.parent_id);
+        if (trait?.kind !== 'trait') return [];
+        const r = this.ix.resolver;
+        return this.store.all("SELECT s.id, s.file_id FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.name = ? AND s.kind = 'method' AND f.lang = 'rust' AND s.bases LIKE ?", sym.name, `%"${trait.name}"%`)
+            .filter(m => m.id !== sym.id && r.resolveTypeName(trait.name, m.file_id)?.id === trait.id).map(m => m.id);
     }
 
     /** Is `memberId` one of the members `sym` overrides (declared in a supertype)? */
@@ -391,7 +453,7 @@ export class CodeIntel {
     references(id, { kinds = null, includeTests = true, minConf = 0, family = true } = {}) {
         const sym = this.sym(id);
         if (!sym) return null;
-        const ids = [...new Set([id, ...this.overloads(sym)])];
+        const ids = [...new Set([id, ...this.overloads(sym), ...this.#traitImpls(sym)])];
         const via = new Map();
         if (family && !sym.is_static && (sym.kind === 'method' || sym.kind === 'property' || sym.kind === 'field')) {
             for (const s of this.#supertypeMembers(sym)) if (!ids.includes(s.id)) { ids.push(s.id); via.set(s.id, s.via); }

package/src/query/issue.mjs

@@ -0,0 +1,156 @@
+/**
+ * Where an issue points in the code. An issue names things in code spans, examples and tracebacks
+ * (`DATE_DIFF`, `rich_club_coefficient(normalized=True)`, `exp.Agg`); the code to change is where
+ * several of those names meet. Each name is matched against identifiers by their words, so
+ * `DATE_DIFF`, `DateDiff` and `_date_diff_sql` are one term, and each definition scores the
+ * rarity (inverse document frequency) of the distinct terms its lines carry, plus the terms its
+ * own name or its file's path is made of. Library code only: tests are left out.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// words of examples that name the language, not the code under it
+const NOISE = new Set(('true false none null undefined self cls this def class return import from print len str int float bool list dict set tuple range '
+    + 'isinstance assert lambda and or not in is if else elif for while with as pass raise try except finally yield async await new let const var '
+    + 'function public private static void string object type repr').split(' '));
+const IDENT = /[A-Za-z_][A-Za-z0-9_]*/g;
+const WORD = /[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+/g;
+const MAX_FILE_BYTES = 1_000_000;
+// examples, benchmarks and docs are not where an issue gets fixed
+const ASIDE_PATH = /(^|\/)(examples?|samples?|demos?|sandbox|playground|docs?(_src|_source|_examples?)?|documentation|benchmarks?|bench|scripts?|fixtures?|testdata|tutorials?|website|\.github)\//i;
+// measured on the dev split of bench/agentic/localize.mjs: mild length normalisation (BM25's b),
+// the title's terms four times an example's, tables and lists of names at 0.6 of a definition
+const B = 0.2;
+const TITLE_W = 4;
+const VALUE_W = 0.6;
+const VALUE_KINDS = new Set(['field', 'property', 'variable', 'constant']);
+
+const partsCache = new Map();
+function parts(id) {
+    let p = partsCache.get(id);
+    if (!p) {
+        p = (id.match(WORD) ?? []).map(w => w.toLowerCase());
+        if (partsCache.size > 200_000) partsCache.clear();
+        partsCache.set(id, p);
+    }
+    return p;
+}
+
+/** Whether an issue reads like one: long enough, or carrying code. */
+export function isIssueText(text) {
+    const t = String(text ?? '');
+    return t.length >= 240 || /```/.test(t) || (t.match(/`[^`\n]+`/g) ?? []).length >= 3;
+}
+
+/** The code-like names an issue uses: from its code spans and blocks, and identifier-shaped words of its prose. */
+export function issueTerms(text) {
+    const t = String(text ?? '');
+    const code = [];
+    // a fence's language tag (```python) is not part of the code
+    const prose = t.replace(/```[^\n]*\n([\s\S]*?)```/g, (_, m) => { code.push(m); return ' '; })
+        .replace(/`([^`\n]+)`/g, (_, m) => { code.push(m); return ' '; });
+    // the title names what the issue is about; examples name everything they touch
+    const title = new Set((t.trim().split('\n')[0].match(IDENT) ?? []).map(x => parts(x).join('_')));
+    const ids = [];
+    for (const c of code) for (const m of c.matchAll(IDENT)) ids.push(m[0]);
+    // prose words that can only be code: snake_case, camelCase, dotted paths
+    for (const m of prose.matchAll(/[A-Za-z_][\w]*(?:\.[A-Za-z_]\w*)+|\b[a-z]+_[a-z_\d]+\b|\b[a-z]+[A-Z]\w*\b|\b[A-Z][a-z]+[A-Z]\w*\b/g)) for (const x of m[0].split('.')) ids.push(x);
+    const terms = new Map();
+    for (const id of ids) {
+        const p = parts(id);
+        if (!p.length || NOISE.has(id.toLowerCase())) continue;
+        if (p.length === 1 && p[0].length < 3) continue;
+        if (p.every(w => /^\d+$/.test(w))) continue;
+        const key = p.join('_');
+        if (!terms.has(key)) terms.set(key, { key, parts: p, forms: new Set(), title: title.has(key) });
+        terms.get(key).forms.add(id);
+    }
+    return [...terms.values()];
+}
+
+/**
+ * Definitions ranked by the issue's terms they carry. Returns [{ id, score, terms }] (best first).
+ * @param {import('./intel.mjs').CodeIntel} intel
+ */
+export function issueSeeds(intel, text, { limit = 12, path: prefix = null } = {}) {
+    const terms = issueTerms(text);
+    if (!terms.length) return [];
+    const byFirst = new Map();
+    for (const t of terms) { if (!byFirst.has(t.parts[0])) byFirst.set(t.parts[0], []); byFirst.get(t.parts[0]).push(t); }
+    const files = intel.store.all('SELECT id, path, size FROM files WHERE is_test = 0');
+    const hits = new Map(); // symbol id -> Set(term key)
+    const owned = new Map(); // symbol id -> lines it owns (its own, not its members')
+    const df = new Map();   // term key -> number of definitions carrying it
+    let total = 0;
+    for (const f of files) {
+        if (prefix && !f.path.startsWith(prefix)) continue;
+        if (f.size > MAX_FILE_BYTES) continue;
+        if (ASIDE_PATH.test(f.path) && !(prefix && ASIDE_PATH.test(prefix))) continue;
+        const syms = intel.store.all('SELECT id, start_line, end_line FROM symbols WHERE file_id = ? ORDER BY start_line', f.id);
+        total += syms.length;
+        if (!syms.length) continue;
+        let text;
+        try { text = fs.readFileSync(path.join(intel.root, f.path), 'utf8'); } catch { continue; }
+        const lines = text.split('\n');
+        // innermost definition of each line
+        const owner = new Int32Array(lines.length + 2).fill(-1);
+        const span = new Int32Array(lines.length + 2).fill(1 << 30);
+        for (const s of syms) {
+            const w = s.end_line - s.start_line;
+            for (let l = s.start_line; l <= Math.min(s.end_line, lines.length); l++) if (w < span[l]) { span[l] = w; owner[l] = s.id; }
+        }
+        for (let i = 0; i < lines.length; i++) {
+            const o = owner[i + 1];
+            if (o < 0) continue;
+            owned.set(o, (owned.get(o) ?? 0) + 1);
+            for (const m of lines[i].matchAll(IDENT)) {
+                const p = parts(m[0]);
+                for (let k = 0; k < p.length; k++) {
+                    const cands = byFirst.get(p[k]);
+                    if (!cands) continue;
+                    for (const t of cands) {
+                        if (k + t.parts.length > p.length) continue;
+                        let ok = true;
+                        for (let j = 1; j < t.parts.length; j++) if (p[k + j] !== t.parts[j]) { ok = false; break; }
+                        if (!ok) continue;
+                        let set = hits.get(o);
+                        if (!set) hits.set(o, (set = new Set()));
+                        if (!set.has(t.key)) { set.add(t.key); df.set(t.key, (df.get(t.key) ?? 0) + 1); }
+                    }
+                }
+            }
+        }
+    }
+    if (!hits.size) return [];
+    const idf = (k) => Math.log(1 + total / (df.get(k) ?? total));
+    const rows = new Map();
+    const ids = [...hits.keys()];
+    for (let i = 0; i < ids.length; i += 500) {
+        const chunk = ids.slice(i, i + 500);
+        for (const r of intel.store.all(`SELECT s.id, s.name, s.kind, s.start_line, s.end_line, f.path FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.id IN (${chunk.map(() => '?').join(',')})`, ...chunk)) rows.set(r.id, r);
+    }
+    // longer definitions carry more terms by chance: BM25's length normalisation, over owned lines
+    let sumLen = 0;
+    for (const v of owned.values()) sumLen += v;
+    const avgLen = sumLen / Math.max(1, owned.size);
+    const byKey = new Map(terms.map(t => [t.key, t]));
+    const scored = [];
+    for (const [id, set] of hits) {
+        const r = rows.get(id);
+        if (!r) continue;
+        let score = 0;
+        for (const k of set) score += idf(k) * (byKey.get(k)?.title ? TITLE_W : 1);
+        // its own name is a term the issue uses: the issue names this definition
+        const own = parts(r.name).join('_');
+        if (set.has(own)) score += idf(own);
+        // its file's path is made of a term (a dialect, a format, a module named in the issue)
+        const pathWords = new Set(r.path.split(/[/._-]+/).flatMap(parts));
+        for (const t of terms) if (t.parts.length === 1 && pathWords.has(t.parts[0]) && !set.has(t.key)) score += 0.5 * idf(t.key);
+        score /= 1 - B + B * ((owned.get(id) ?? 1) / avgLen);
+        // a table or list of names (`__all__`, a function map) enumerates terms rather than combining them
+        if (VALUE_KINDS.has(r.kind)) score *= VALUE_W;
+        scored.push({ id, score, terms: [...set] });
+    }
+    scored.sort((a, b) => b.score - a.score || a.id - b.id);
+    return scored.slice(0, limit);
+}