@event4u/agent-config 9.7.0 → 9.8.0

package/src/scripts/code_graph/extract.ts

@@ -0,0 +1,386 @@
+/**
+ * Per-file extraction — WASM tree-sitter, LLM-free, deterministic.
+ *
+ * Emits definition nodes and *raw* edges; the second pass in `build.ts`
+ * resolves raw-edge targets against the whole-repo symbol table and finalises
+ * the honest confidence taxonomy:
+ *
+ *   EXTRACTED — definitions, `use`/`import`, extends/implements, trait use,
+ *               `new X()`, direct free-function calls.
+ *   INFERRED  — `$this->`/`self::`/`static::`/`parent::` and TS `this.`
+ *               receivers resolved against the parsed class hierarchy.
+ *   AMBIGUOUS — dynamic method calls, facades, scoped calls to an unresolved
+ *               name: kept with candidates, never dropped. This is the
+ *               expected majority for dynamic-dispatch code (Laravel etc.).
+ */
+import {
+    type CodeNode,
+    type EdgeConfidence,
+    type Lang,
+    MAX_FILE_BYTES,
+    type Relation,
+} from './types.js';
+import { getParser, nodeHasError, type TsNode } from './loader.js';
+
+export type CallStyle = 'new' | 'free' | 'this' | 'self' | 'static' | 'parent' | 'scoped' | 'dynamic';
+
+export interface RawEdge {
+    /** caller / container scope node id (method, function, class, or file). */
+    sourceId: string;
+    relation: Relation;
+    /** bare symbol or method name to resolve in the second pass. */
+    targetName: string;
+    confidenceHint: EdgeConfidence;
+    callStyle?: CallStyle;
+    /** enclosing class id, for this/self/static/parent resolution. */
+    enclosingClassId?: string;
+    /** scope token for `Scope::m()` scoped calls (a class name / self / static). */
+    scopeName?: string;
+}
+
+export interface FileExtract {
+    file: string;
+    lang: Lang;
+    nodes: CodeNode[];
+    rawEdges: RawEdge[];
+    /** local class id → its declared parent/interface names (2nd-pass inherits). */
+    inherits: Array<{ classId: string; parentName: string }>;
+    parseError: boolean;
+}
+
+function loc(n: TsNode): number[] {
+    return [
+        n.startPosition.row + 1,
+        n.startPosition.column + 1,
+        n.endPosition.row + 1,
+        n.endPosition.column + 1,
+    ];
+}
+
+function namedChildren(n: TsNode): TsNode[] {
+    const out: TsNode[] = [];
+    for (let i = 0; i < n.namedChildCount; i += 1) {
+        const c = n.namedChild(i);
+        if (c) out.push(c);
+    }
+    return out;
+}
+
+/** First descendant (DFS, named) whose type is in `types`. */
+function firstNamed(n: TsNode, types: ReadonlySet<string>): TsNode | null {
+    for (const c of namedChildren(n)) {
+        if (types.has(c.type)) return c;
+        const deep = firstNamed(c, types);
+        if (deep) return deep;
+    }
+    return null;
+}
+
+function nameField(n: TsNode): string | null {
+    const nm = n.childForFieldName('name');
+    if (nm) return nm.text;
+    return null;
+}
+
+const NAME_TYPES = new Set(['name', 'identifier', 'qualified_name', 'type_identifier']);
+/** last `\`- or `.`-separated segment of a qualified name. */
+function baseName(raw: string): string {
+    const s = raw.trim().replace(/^\\+/, '');
+    const parts = s.split(/[\\.]/);
+    return parts[parts.length - 1] ?? s;
+}
+
+// ── PHP ──────────────────────────────────────────────────────────────────────
+
+function extractPhp(root: TsNode, file: string, out: FileExtract): void {
+    const fileId = file;
+
+    const walk = (n: TsNode, classId: string | null, scopeId: string): void => {
+        switch (n.type) {
+            case 'namespace_use_declaration': {
+                for (const clause of namedChildren(n)) {
+                    const nameNode = firstNamed(clause, new Set(['qualified_name', 'name']));
+                    if (nameNode) {
+                        out.rawEdges.push({
+                            sourceId: fileId,
+                            relation: 'imports',
+                            targetName: baseName(nameNode.text),
+                            confidenceHint: 'EXTRACTED',
+                        });
+                    }
+                }
+                return;
+            }
+            case 'class_declaration':
+            case 'interface_declaration':
+            case 'trait_declaration': {
+                const nm = nameField(n) ?? '<anon>';
+                const kind =
+                    n.type === 'class_declaration'
+                        ? 'class'
+                        : n.type === 'interface_declaration'
+                          ? 'interface'
+                          : 'trait';
+                const id = `${file}#${nm}`;
+                out.nodes.push({ id, label: nm, kind, source_file: file, source_location: loc(n) });
+                out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                // extends / implements
+                for (const c of namedChildren(n)) {
+                    if (c.type === 'base_clause' || c.type === 'class_interface_clause') {
+                        for (const nameNode of namedChildren(c)) {
+                            if (NAME_TYPES.has(nameNode.type)) {
+                                out.inherits.push({ classId: id, parentName: baseName(nameNode.text) });
+                            }
+                        }
+                    }
+                }
+                for (const c of namedChildren(n)) walk(c, id, id);
+                return;
+            }
+            case 'use_declaration': {
+                // trait use inside a class body
+                if (classId) {
+                    for (const nameNode of namedChildren(n)) {
+                        if (NAME_TYPES.has(nameNode.type)) {
+                            out.rawEdges.push({
+                                sourceId: classId,
+                                relation: 'uses',
+                                targetName: baseName(nameNode.text),
+                                confidenceHint: 'EXTRACTED',
+                            });
+                        }
+                    }
+                }
+                return;
+            }
+            case 'method_declaration':
+            case 'function_definition': {
+                const nm = nameField(n) ?? '<anon>';
+                const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                out.nodes.push({
+                    id,
+                    label: nm,
+                    kind: n.type === 'method_declaration' ? 'method' : 'function',
+                    source_file: file,
+                    source_location: loc(n),
+                });
+                out.rawEdges.push({
+                    sourceId: classId ?? fileId,
+                    relation: 'member',
+                    targetName: nm,
+                    confidenceHint: 'EXTRACTED',
+                });
+                const body = n.childForFieldName('body');
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                return;
+            }
+            case 'object_creation_expression': {
+                const nameNode = firstNamed(n, new Set(['qualified_name', 'name']));
+                if (nameNode)
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'calls',
+                        targetName: baseName(nameNode.text),
+                        confidenceHint: 'EXTRACTED',
+                        callStyle: 'new',
+                    });
+                break;
+            }
+            case 'function_call_expression': {
+                const fn = n.childForFieldName('function');
+                if (fn && NAME_TYPES.has(fn.type))
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'calls',
+                        targetName: baseName(fn.text),
+                        confidenceHint: 'EXTRACTED',
+                        callStyle: 'free',
+                    });
+                break;
+            }
+            case 'member_call_expression': {
+                const obj = n.childForFieldName('object');
+                const nm = n.childForFieldName('name');
+                if (nm) {
+                    const objText = obj?.text ?? '';
+                    const isThis = objText === '$this';
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'calls',
+                        targetName: nm.text,
+                        confidenceHint: isThis && classId ? 'INFERRED' : 'AMBIGUOUS',
+                        callStyle: isThis ? 'this' : 'dynamic',
+                        ...(classId ? { enclosingClassId: classId } : {}),
+                    });
+                }
+                break;
+            }
+            case 'scoped_call_expression': {
+                const scope = n.childForFieldName('scope');
+                const nm = n.childForFieldName('name');
+                if (nm) {
+                    const scopeText = scope?.text ?? '';
+                    const isSelf = /^(self|static|parent)$/.test(scopeText);
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'calls',
+                        targetName: nm.text,
+                        confidenceHint: isSelf && classId ? 'INFERRED' : 'AMBIGUOUS',
+                        callStyle: isSelf ? (scopeText as CallStyle) : 'scoped',
+                        ...(classId ? { enclosingClassId: classId } : {}),
+                        ...(isSelf ? {} : { scopeName: baseName(scopeText) }),
+                    });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        for (const c of namedChildren(n)) walk(c, classId, scopeId);
+    };
+
+    out.nodes.push({ id: fileId, label: file, kind: 'file', source_file: file, source_location: [] });
+    walk(root, null, fileId);
+}
+
+// ── TypeScript / JavaScript ───────────────────────────────────────────────────
+
+function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
+    const fileId = file;
+
+    const walk = (n: TsNode, classId: string | null, scopeId: string): void => {
+        switch (n.type) {
+            case 'import_statement': {
+                const clause = firstNamed(n, new Set(['import_clause']));
+                if (clause) {
+                    for (const spec of namedChildren(clause)) {
+                        for (const idn of [spec, ...namedChildren(spec)])
+                            if (idn.type === 'identifier' || idn.type === 'import_specifier') {
+                                const nm = idn.type === 'import_specifier' ? nameField(idn) ?? idn.text : idn.text;
+                                out.rawEdges.push({
+                                    sourceId: fileId,
+                                    relation: 'imports',
+                                    targetName: baseName(nm),
+                                    confidenceHint: 'EXTRACTED',
+                                });
+                            }
+                    }
+                }
+                return;
+            }
+            case 'class_declaration': {
+                const nm = nameField(n) ?? '<anon>';
+                const id = `${file}#${nm}`;
+                out.nodes.push({ id, label: nm, kind: 'class', source_file: file, source_location: loc(n) });
+                out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                const heritage = firstNamed(n, new Set(['class_heritage']));
+                if (heritage)
+                    for (const cl of namedChildren(heritage))
+                        for (const idn of namedChildren(cl))
+                            if (idn.type === 'identifier' || idn.type === 'type_identifier')
+                                out.inherits.push({ classId: id, parentName: baseName(idn.text) });
+                const body = n.childForFieldName('body');
+                if (body) for (const c of namedChildren(body)) walk(c, id, id);
+                return;
+            }
+            case 'method_definition': {
+                const nm = nameField(n) ?? '<anon>';
+                const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                out.nodes.push({ id, label: nm, kind: 'method', source_file: file, source_location: loc(n) });
+                out.rawEdges.push({
+                    sourceId: classId ?? fileId,
+                    relation: 'member',
+                    targetName: nm,
+                    confidenceHint: 'EXTRACTED',
+                });
+                const body = n.childForFieldName('body');
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                return;
+            }
+            case 'function_declaration': {
+                const nm = nameField(n) ?? '<anon>';
+                const id = `${file}#${nm}`;
+                out.nodes.push({ id, label: nm, kind: 'function', source_file: file, source_location: loc(n) });
+                out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                const body = n.childForFieldName('body');
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                return;
+            }
+            case 'new_expression': {
+                const ctor = n.childForFieldName('constructor');
+                if (ctor && (ctor.type === 'identifier' || ctor.type === 'type_identifier' || ctor.type === 'member_expression'))
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'calls',
+                        targetName: baseName(ctor.text.split('.').pop() ?? ctor.text),
+                        confidenceHint: 'EXTRACTED',
+                        callStyle: 'new',
+                    });
+                break;
+            }
+            case 'call_expression': {
+                const fn = n.childForFieldName('function');
+                if (fn) {
+                    if (fn.type === 'identifier') {
+                        out.rawEdges.push({
+                            sourceId: scopeId,
+                            relation: 'calls',
+                            targetName: fn.text,
+                            confidenceHint: 'EXTRACTED',
+                            callStyle: 'free',
+                        });
+                    } else if (fn.type === 'member_expression') {
+                        const obj = fn.childForFieldName('object');
+                        const prop = fn.childForFieldName('property');
+                        if (prop) {
+                            const isThis = obj?.type === 'this';
+                            out.rawEdges.push({
+                                sourceId: scopeId,
+                                relation: 'calls',
+                                targetName: prop.text,
+                                confidenceHint: isThis && classId ? 'INFERRED' : 'AMBIGUOUS',
+                                callStyle: isThis ? 'this' : 'dynamic',
+                                ...(classId ? { enclosingClassId: classId } : {}),
+                            });
+                        }
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        for (const c of namedChildren(n)) walk(c, classId, scopeId);
+    };
+
+    out.nodes.push({ id: fileId, label: file, kind: 'file', source_file: file, source_location: [] });
+    walk(root, null, fileId);
+}
+
+/**
+ * Extract one file. `source` is the file's UTF-8 content; `relPath` is the
+ * repo-relative POSIX path used to build collision-free node ids.
+ */
+export async function extractFile(relPath: string, source: string, lang: Lang): Promise<FileExtract> {
+    const out: FileExtract = { file: relPath, lang, nodes: [], rawEdges: [], inherits: [], parseError: false };
+    if (Buffer.byteLength(source, 'utf-8') > MAX_FILE_BYTES) {
+        out.nodes.push({
+            id: relPath,
+            label: relPath,
+            kind: 'skipped',
+            source_file: relPath,
+            source_location: [],
+        });
+        return out;
+    }
+    const parser = await getParser(lang);
+    const tree = parser.parse(source);
+    try {
+        out.parseError = nodeHasError(tree.rootNode);
+        if (lang === 'php') extractPhp(tree.rootNode, relPath, out);
+        else extractTsJs(tree.rootNode, relPath, out);
+    } finally {
+        tree.delete(); // delete the tree, never the cached parser (loader.ts)
+    }
+    return out;
+}

package/src/scripts/code_graph/loader.ts

@@ -0,0 +1,123 @@
+/**
+ * WASM tree-sitter loader for the code-graph engine.
+ *
+ * Pinned pair (ABI-verified 2026-07-23): `web-tree-sitter@0.24.7` +
+ * `tree-sitter-wasms@0.1.13` → grammar ABI 14. The ABI smoke test
+ * (`tests/scripts/code_graph_abi.test.ts`) asserts this pairing loads and
+ * parses before merge; a bump to either dependency re-runs it. No network,
+ * no node-gyp — grammars load from `node_modules` via the resolved path.
+ *
+ * web-tree-sitter 0.24.x is CJS with a single default export (the Parser
+ * class) and the classic `Parser.Language.load()` API; we reach it through
+ * `createRequire` so this ESM module stays portable under the repo's tsx
+ * runner.
+ */
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+
+import { EXPECTED_GRAMMAR_ABI, GRAMMAR_WASM, type Lang } from './types.js';
+
+const require = createRequire(import.meta.url);
+
+// Minimal structural types for the 0.24.x surface we use (the package ships
+// its own .d.ts, but the CJS-default shape is simplest to pin locally).
+export interface TsNode {
+    type: string;
+    text: string;
+    startPosition: { row: number; column: number };
+    endPosition: { row: number; column: number };
+    namedChildCount: number;
+    childCount: number;
+    namedChild(i: number): TsNode | null;
+    child(i: number): TsNode | null;
+    childForFieldName(field: string): TsNode | null;
+    hasError: boolean | (() => boolean);
+}
+export interface TsTree {
+    rootNode: TsNode;
+    delete(): void;
+}
+export interface TsLanguage {
+    version: number;
+}
+export interface TsParser {
+    setLanguage(l: TsLanguage): void;
+    parse(src: string): TsTree;
+    delete(): void;
+}
+interface ParserStatic {
+    init(): Promise<void>;
+    new (): TsParser;
+    Language: { load(wasmPath: string): Promise<TsLanguage> };
+}
+
+let _wasmDir: string | null = null;
+function wasmDir(): string {
+    if (_wasmDir === null) {
+        _wasmDir = path.join(path.dirname(require.resolve('tree-sitter-wasms/package.json')), 'out');
+    }
+    return _wasmDir;
+}
+
+let _initialized = false;
+const _langCache = new Map<Lang, TsLanguage>();
+const _parserCache = new Map<Lang, TsParser>();
+
+export function grammarWasmPath(lang: Lang): string {
+    return path.join(wasmDir(), GRAMMAR_WASM[lang]);
+}
+
+let _mod: ParserStatic | null = null;
+function _Parser(): ParserStatic {
+    // Require exactly once and cache the class reference — repeated
+    // createRequire calls under tsx can hand back a module view whose static
+    // `Language` is not yet populated, which breaks the second grammar load.
+    if (_mod === null) _mod = require('web-tree-sitter') as ParserStatic;
+    return _mod;
+}
+
+async function _init(): Promise<void> {
+    if (!_initialized) {
+        await _Parser().init();
+        _initialized = true;
+    }
+}
+
+/** Load (and cache) a grammar; asserts the ABI matches the pinned expectation. */
+export async function loadLanguage(lang: Lang): Promise<TsLanguage> {
+    const cached = _langCache.get(lang);
+    if (cached) return cached;
+    await _init();
+    const language = await _Parser().Language.load(grammarWasmPath(lang));
+    if (language.version !== EXPECTED_GRAMMAR_ABI) {
+        throw new Error(
+            `code-graph: grammar ABI drift for ${lang} — got ${language.version}, ` +
+                `pinned ${EXPECTED_GRAMMAR_ABI}. Re-pin web-tree-sitter/tree-sitter-wasms ` +
+                `and re-run the ABI smoke test.`,
+        );
+    }
+    _langCache.set(lang, language);
+    return language;
+}
+
+/**
+ * A parser bound to `lang`, cached per language for the process lifetime.
+ * Callers MUST NOT `.delete()` it — emscripten's runtime is torn down on
+ * parser deletion, breaking every subsequent `new Parser()`. Delete only the
+ * per-parse `tree` (extract.ts does), so the emscripten heap does not balloon.
+ */
+export async function getParser(lang: Lang): Promise<TsParser> {
+    const cached = _parserCache.get(lang);
+    if (cached) return cached;
+    await _init();
+    const language = await loadLanguage(lang);
+    const parser = new (_Parser())();
+    parser.setLanguage(language);
+    _parserCache.set(lang, parser);
+    return parser;
+}
+
+/** Normalise the 0.24.x `hasError` (property) vs newer (method). */
+export function nodeHasError(n: TsNode): boolean {
+    return typeof n.hasError === 'function' ? n.hasError() : n.hasError;
+}

package/src/scripts/code_graph/query.ts

@@ -0,0 +1,176 @@
+/**
+ * Query tier — one engine, two sources (ADR-124 § 2). Runs identically over
+ * the native cache and a consumer-shipped `graph.json`; every answer names
+ * which source answered. BFS/DFS with a token budget; hybrid seed-matching
+ * (exact id / label → BM25 fallback via `_lib/lexical_index.ts`). All string
+ * fields pass the retrieved-content sanitizer before returning.
+ */
+import * as fs from 'node:fs';
+
+import { LexicalIndex, tokenize } from '../_lib/lexical_index.js';
+import { sanitizeLabel } from './sanitize.js';
+import type { CodeEdge, CodeGraph } from './types.js';
+import { validateGraph } from './validate.js';
+
+const APPROX_CHARS_PER_TOKEN = 4;
+
+export interface LoadedGraph {
+    graph: CodeGraph;
+    source: string; // attribution path
+    byId: Map<string, CodeGraph['nodes'][number]>;
+    out: Map<string, CodeEdge[]>;
+    in: Map<string, CodeEdge[]>;
+    lex: LexicalIndex;
+}
+
+export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
+    const parsed = JSON.parse(fs.readFileSync(graphPath, 'utf-8')) as unknown;
+    const v = validateGraph(parsed);
+    if (!v.ok) throw new Error(`invalid graph at ${graphPath}: ${v.errors.slice(0, 3).join('; ')}`);
+    const graph = parsed as CodeGraph;
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const outM = new Map<string, CodeEdge[]>();
+    const inM = new Map<string, CodeEdge[]>();
+    const add = (m: Map<string, CodeEdge[]>, k: string, e: CodeEdge): void => {
+        const arr = m.get(k);
+        if (arr) arr.push(e);
+        else m.set(k, [e]);
+    };
+    for (const e of graph.edges) {
+        add(outM, e.source, e);
+        add(inM, e.target, e);
+    }
+    const lex = new LexicalIndex(graph.nodes.map((n) => ({ id: n.id, text: `${n.label} ${n.id}` })));
+    return { graph, source, byId, out: outM, in: inM, lex };
+}
+
+/** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
+export function resolveSeeds(g: LoadedGraph, seed: string, limit = 5): string[] {
+    if (g.byId.has(seed)) return [seed];
+    const exactLabel = g.graph.nodes.filter((n) => n.label === seed).map((n) => n.id);
+    if (exactLabel.length) return exactLabel.slice(0, limit);
+    const ranked = g.lex.rank(tokenize(seed)).filter((r) => r.score > 0);
+    return ranked.slice(0, limit).map((r) => r.id);
+}
+
+function label(g: LoadedGraph, id: string): string {
+    return sanitizeLabel(g.byId.get(id)?.label ?? id);
+}
+function edgeLine(g: LoadedGraph, e: CodeEdge): string {
+    const cand = e.candidates?.length ? ` [${e.candidates.map((c) => sanitizeLabel(c)).join(', ')}]` : '';
+    return `${e.confidence} ${sanitizeLabel(e.source)} --${e.relation}--> ${sanitizeLabel(e.target)}${cand}`;
+}
+
+export interface QueryResult {
+    source: string;
+    seeds: string[];
+    lines: string[];
+    truncated: boolean;
+}
+
+function budgetedLines(source: string, seeds: string[], lines: string[], budget: number): QueryResult {
+    const cap = budget * APPROX_CHARS_PER_TOKEN;
+    const kept: string[] = [];
+    let used = 0;
+    let truncated = false;
+    for (const l of lines) {
+        if (used + l.length > cap) {
+            truncated = true;
+            break;
+        }
+        kept.push(l);
+        used += l.length + 1;
+    }
+    return { source, seeds, lines: kept, truncated };
+}
+
+/** `query <seed>` — the seed's direct (1-hop) outgoing relations. */
+export function query(g: LoadedGraph, seed: string, budget = 1500): QueryResult {
+    const seeds = resolveSeeds(g, seed);
+    const lines: string[] = [];
+    for (const s of seeds) for (const e of g.out.get(s) ?? []) lines.push(edgeLine(g, e));
+    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+}
+
+/** `explain <seed>` — 2-hop neighbourhood (out-edges of seeds + their targets). */
+export function explain(g: LoadedGraph, seed: string, budget = 1500): QueryResult {
+    const seeds = resolveSeeds(g, seed);
+    const seen = new Set<string>();
+    const lines: string[] = [];
+    const frontier = [...seeds];
+    for (let hop = 0; hop < 2 && frontier.length; hop += 1) {
+        const next: string[] = [];
+        for (const s of frontier.splice(0)) {
+            if (seen.has(s)) continue;
+            seen.add(s);
+            for (const e of g.out.get(s) ?? []) {
+                lines.push(edgeLine(g, e));
+                next.push(e.target);
+            }
+        }
+        frontier.push(...next);
+    }
+    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+}
+
+/** `affected <target>` — reverse BFS: who calls / references the target. */
+export function affected(g: LoadedGraph, target: string, depth = 2, budget = 1500): QueryResult {
+    const seeds = resolveSeeds(g, target);
+    const seen = new Set<string>(seeds);
+    const lines: string[] = [];
+    let frontier = [...seeds];
+    for (let d = 0; d < depth && frontier.length; d += 1) {
+        const next: string[] = [];
+        for (const t of frontier) {
+            for (const e of g.in.get(t) ?? []) {
+                lines.push(edgeLine(g, e));
+                if (!seen.has(e.source)) {
+                    seen.add(e.source);
+                    next.push(e.source);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return budgetedLines(g.source, seeds.map((s) => label(g, s)), lines, budget);
+}
+
+/** `path <a> <b>` — shortest undirected path (direction preserved per edge). */
+export function path(g: LoadedGraph, a: string, b: string, budget = 1500): QueryResult {
+    const starts = resolveSeeds(g, a, 1);
+    const goals = new Set(resolveSeeds(g, b, 1));
+    if (!starts.length || !goals.size) return { source: g.source, seeds: [], lines: [], truncated: false };
+    const start = starts[0] as string;
+    const prev = new Map<string, CodeEdge>();
+    const seen = new Set<string>([start]);
+    let frontier = [start];
+    let hit: string | null = goals.has(start) ? start : null;
+    while (frontier.length && !hit) {
+        const next: string[] = [];
+        for (const cur of frontier) {
+            const adj = [...(g.out.get(cur) ?? []), ...(g.in.get(cur) ?? [])];
+            for (const e of adj) {
+                const nb = e.source === cur ? e.target : e.source;
+                if (seen.has(nb)) continue;
+                seen.add(nb);
+                prev.set(nb, e);
+                if (goals.has(nb)) {
+                    hit = nb;
+                    break;
+                }
+                next.push(nb);
+            }
+            if (hit) break;
+        }
+        frontier = next;
+    }
+    if (!hit) return { source: g.source, seeds: [label(g, start)], lines: ['(no path found)'], truncated: false };
+    const chain: CodeEdge[] = [];
+    let cur = hit;
+    while (prev.has(cur)) {
+        const e = prev.get(cur) as CodeEdge;
+        chain.unshift(e);
+        cur = e.source === cur ? e.target : e.source;
+    }
+    return budgetedLines(g.source, [label(g, start), label(g, hit)], chain.map((e) => edgeLine(g, e)), budget);
+}