@event4u/agent-config 9.7.0 → 9.9.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/intent.ts

@@ -0,0 +1,45 @@
+/**
+ * Intent-conditioned verb selection (Phase 9 D3, road-to-reachable-code-memory)
+ * — a PURE regex table, no model call. `suggestVerb` maps a natural-language
+ * structure question to the `code_graph` subcommand most likely to answer it:
+ *
+ *   affected — "who calls / uses / references this", "what would break",
+ *              "blast radius" — a reverse (who-depends-on-it) lookup.
+ *   path     — "how does X reach/connect to Y", "is A reachable from B",
+ *              "trace the route between A and B" — connectivity between
+ *              two named seeds.
+ *   explain  — "overview", "what's around X", "the neighbourhood of X",
+ *              "walk me through X" — a broader 2-hop neighbourhood, not a
+ *              single direct-relations answer.
+ *   query    — the default: a seed's own direct (1-hop) relations.
+ *
+ * Order matters — first pattern class to match wins: affected → path →
+ * explain → query. Ship gate (pre-registered in
+ * `tests/fixtures/code-graph-intent/queries.json`, written BEFORE this file):
+ * `suggestVerb` must beat the always-`query` baseline's correct-verb rate
+ * over that 30-query set, or this module stays unwired (evidence only, per
+ * the D3 evidence note in `agents/evidence/reports/`).
+ */
+
+export type Verb = 'query' | 'affected' | 'path' | 'explain';
+
+const AFFECTED_RE =
+    /\b(who\s+(calls?|uses?|else|references?)|where\s+(is|are|'s)?\s*.*\bused\b|impact(s|ed|ing)?|blast\s+radius|break(s|ing)?|would\s+break|caller(s)?|referenc(e|es|ed|ing)|touch(es|ed)?)\b/i;
+
+const PATH_RE =
+    /\b(reach(able|es|ing)?|connect(s|ed|ion|ing)?|\btrace\b|\broute\b|\bpath\b|shortest)\b/i;
+
+const EXPLAIN_RE =
+    /\b(overview|explain(s|ed|ing)?|\baround\b|surround(ing|s)?|\bcontext\b|big\s+picture|neighbo[u]?rhood|walk\s+me\s+through|summar(y|ize|ise))\b/i;
+
+/**
+ * Suggest the `code_graph` verb a free-text structure question most likely
+ * needs. Deterministic, side-effect-free, no network, no model call.
+ */
+export function suggestVerb(question: string): Verb {
+    const q = question.trim();
+    if (AFFECTED_RE.test(q)) return 'affected';
+    if (PATH_RE.test(q)) return 'path';
+    if (EXPLAIN_RE.test(q)) return 'explain';
+    return 'query';
+}

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;
+}