@event4u/agent-config 17.2.1 → 17.3.0

package/src/scripts/code_graph/conventions_default.ts

@@ -0,0 +1,228 @@
+/**
+ * The default convention pass (ADR-298): runs for every project, names no
+ * framework, and links only what a string can state about a file.
+ *
+ *   literal-path    './x' · 'views/a.html'      code --reads-->     the one code or template file it names
+ *   literal-dotted  render('a.b')               code --renders-->   the one template at a/b.<template ext>
+ *   fs-route        pages/a/[id].tsx            route --routes-to-> the page module
+ *
+ * Every edge is INFERRED, drawn only on a single match, and never where an
+ * edge between the same two files already exists — an import, a provider's
+ * edge or an earlier literal outranks it. The two axes are independent
+ * (`types.ts`): the confidence is INFERRED because a convention connects the
+ * pair, while the mechanism is a statement — the literal names that exact file
+ * — so these edges count as stated for the map and the gate verbs.
+ */
+import * as path from 'node:path';
+
+import type { SourceFile } from './build.js';
+import type { CodeEdge, CodeNode, ResolvedVia } from './types.js';
+import { EXT_LANG, MAX_FILE_BYTES } from './types.js';
+
+/** The text right before a JS/TS module specifier: `from`, `import`, `import(`, `require(`. */
+const IMPORT_POSITION = /(?:\bfrom|\bimport|\bimport\s*\(|\brequire\s*\()\s*$/;
+
+export type DefaultMechanism = 'literal-path' | 'literal-dotted' | 'fs-route';
+
+/**
+ * Which mechanisms run. A mechanism under the 90 % precision bar is switched off
+ * here, never the pass (readings: `graph-providers-baseline-2026-10-23.md`).
+ * `literal-dotted` measured 3 of 6 on Fixture L — a translation key such as
+ * `trans('common.sort')` matches a view of the same name — so dotted names are
+ * left to providers, which know which call takes a template.
+ */
+export const DEFAULT_MECHANISMS: Readonly<Record<DefaultMechanism, boolean>> = {
+    'literal-path': true,
+    'literal-dotted': false,
+    'fs-route': true,
+};
+
+/** Template extensions a dotted name may resolve to; longest first so `.blade.php` wins over `.php`. */
+const TEMPLATE_EXTS = [
+    '.blade.php',
+    '.handlebars',
+    '.mustache',
+    '.jinja2',
+    '.cshtml',
+    '.liquid',
+    '.jinja',
+    '.razor',
+    '.twig',
+    '.html',
+    '.htm',
+    '.hbs',
+    '.ejs',
+    '.pug',
+    '.njk',
+    '.erb',
+    '.tpl',
+    '.j2',
+];
+
+const PAGE_EXTS = new Set(['.tsx', '.jsx', '.ts', '.js', '.vue', '.svelte', '.astro', '.mdx']);
+
+export interface DefaultInput {
+    files: readonly SourceFile[];
+    /** Every path in the project, code or not; the code and doc paths when the build knows no more. */
+    paths: readonly string[];
+    nodes: readonly CodeNode[];
+    edges: readonly CodeEdge[];
+    mechanisms?: Readonly<Record<DefaultMechanism, boolean>>;
+}
+
+export interface DefaultStats {
+    'literal-path': number;
+    'literal-dotted': number;
+    'fs-route': number;
+}
+
+export function templateBase(p: string): string | null {
+    for (const ext of TEMPLATE_EXTS) if (p.endsWith(ext) && p.length > ext.length) return p.slice(0, -ext.length);
+    return null;
+}
+
+/** `pages/a/[id].tsx` → `/a/[id]`; null when the file is no page module. */
+export function fsRoutePath(p: string, pageDirs: ReadonlySet<string>): { verb: string; route: string } | null {
+    const ext = path.posix.extname(p);
+    if (!PAGE_EXTS.has(ext)) return null;
+    const segs = p.split('/');
+    const base = segs[segs.length - 1] as string;
+    const stem = base.slice(0, -ext.length);
+    const clean = (parts: string[]): string =>
+        `/${parts.filter((s) => !/^\(.*\)$/.test(s) && !s.startsWith('@') && s !== 'index').join('/')}`.replace(/\/$/, '') || '/';
+    const at = (dir: string): number => segs.lastIndexOf(dir, segs.length - 2);
+    const app = at('app');
+    if (app >= 0 && (stem === 'page' || stem === 'route') && pageDirs.has(segs.slice(0, app + 1).join('/'))) {
+        return { verb: stem === 'route' ? 'ROUTE' : 'PAGE', route: clean(segs.slice(app + 1, -1)) };
+    }
+    const routes = at('routes');
+    if (routes >= 1 && segs[routes - 1] === 'src' && /^\+(page|server)$/.test(stem)) {
+        return { verb: stem === '+server' ? 'ROUTE' : 'PAGE', route: clean(segs.slice(routes + 1, -1)) };
+    }
+    const pages = at('pages');
+    if (pages >= 0 && !stem.startsWith('_') && pageDirs.has(segs.slice(0, pages + 1).join('/'))) {
+        const rest = [...segs.slice(pages + 1, -1), stem];
+        return { verb: rest[0] === 'api' ? 'ROUTE' : 'PAGE', route: clean(rest) };
+    }
+    return null;
+}
+
+/** Directories that hold page-shaped modules: an `app/` with a `page.*`, a `pages/` with an `index.*`. */
+function pageDirectories(paths: readonly string[]): Set<string> {
+    const dirs = new Set<string>();
+    for (const p of paths) {
+        const segs = p.split('/');
+        const base = segs[segs.length - 1] as string;
+        const ext = path.posix.extname(base);
+        if (!PAGE_EXTS.has(ext)) continue;
+        const stem = base.slice(0, -ext.length);
+        for (let i = segs.length - 2; i >= 0; i--) {
+            if (segs[i] === 'app' && stem === 'page') dirs.add(segs.slice(0, i + 1).join('/'));
+            if (segs[i] === 'pages' && stem === 'index') dirs.add(segs.slice(0, i + 1).join('/'));
+        }
+    }
+    return dirs;
+}
+
+export function conventionsDefault(input: DefaultInput): { nodes: CodeNode[]; edges: CodeEdge[]; stats: DefaultStats } {
+    const on = input.mechanisms ?? DEFAULT_MECHANISMS;
+    const stats: DefaultStats = { 'literal-path': 0, 'literal-dotted': 0, 'fs-route': 0 };
+    const nodes: CodeNode[] = [];
+    const edges: CodeEdge[] = [];
+    const fileNodes = new Set(input.nodes.filter((n) => n.kind === 'file').map((n) => n.id));
+    // A literal may name code, a document or a template — never a data file or
+    // a dotfile, which would fill the map with what the code merely configures.
+    const inventory = new Set([...input.paths.filter((p) => templateBase(p) !== null), ...fileNodes]);
+    const nodeIds = new Set(input.nodes.map((n) => n.id));
+    const fileOf = new Map(input.nodes.map((n) => [n.id, n.source_file] as const));
+    const linked = new Set<string>();
+    for (const e of input.edges) {
+        const a = fileOf.get(e.source);
+        const b = fileOf.get(e.target) ?? (inventory.has(e.target) ? e.target : undefined);
+        if (a && b) linked.add(`${a}\0${b}`);
+    }
+    const ensureFile = (p: string): void => {
+        if (nodeIds.has(p)) return;
+        nodeIds.add(p);
+        nodes.push({ id: p, label: p, kind: 'file', source_file: p, source_location: [] });
+    };
+    const link = (source: string, target: string, relation: CodeEdge['relation'], via: ResolvedVia & DefaultMechanism): void => {
+        const key = `${source}\0${target}`;
+        if (source === target || linked.has(key)) return;
+        linked.add(key);
+        ensureFile(target);
+        edges.push({ source, target, relation, confidence: 'INFERRED', resolved_via: via, provider: 'native' });
+        stats[via] += 1;
+    };
+
+    // Dotted names: `a/b/c` → the template files whose path ends there.
+    const byDotted = new Map<string, string[]>();
+    if (on['literal-dotted']) {
+        for (const p of input.paths) {
+            const base = templateBase(p);
+            if (!base) continue;
+            const segs = base.split('/');
+            for (let i = 0; i <= segs.length - 2; i++) {
+                const key = segs.slice(i).join('/');
+                byDotted.set(key, [...(byDotted.get(key) ?? []), p]);
+            }
+        }
+    }
+
+    for (const f of [...input.files].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+        if (Buffer.byteLength(f.source, 'utf-8') > MAX_FILE_BYTES) continue;
+        const dir = path.posix.dirname(f.path);
+        const lang = EXT_LANG[path.posix.extname(f.path).toLowerCase()];
+        const infer = lang === 'php' ? ['.php'] : lang === 'python' ? ['.py'] : ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.vue'];
+        const jsLike = lang === 'typescript' || lang === 'javascript';
+        if (on['literal-path']) {
+            // Single and double quotes only: a backtick span is usually a mention in a comment.
+            for (const m of f.source.matchAll(/(['"])([^'"`\s\\${}()<>|,;]{3,200})\1/g)) {
+                const lit = m[2] as string;
+                // A module specifier belongs to the import tier: resolved, it is an
+                // `imports` edge already; unresolved, it is an external module — a
+                // read in neither case.
+                if (jsLike && IMPORT_POSITION.test(f.source.slice(Math.max(0, (m.index as number) - 40), m.index as number))) continue;
+                if (lit.includes('://') || lit.startsWith('/') || lit.includes('*') || lit.endsWith('/')) continue;
+                const hasExt = /\.[A-Za-z0-9]{1,10}$/.test(path.posix.basename(lit));
+                if (!lit.includes('/') && !hasExt) continue;
+                const relative = lit.startsWith('./') || lit.startsWith('../');
+                const bases = relative ? [path.posix.join(dir, lit)] : [path.posix.normalize(lit), path.posix.join(dir, lit)];
+                const hits = new Set<string>();
+                for (const b of bases) {
+                    if (b.startsWith('..')) continue;
+                    if (inventory.has(b)) hits.add(b);
+                    if (!hasExt) for (const ext of infer) for (const c of [`${b}${ext}`, `${b}/index${ext}`]) if (inventory.has(c)) hits.add(c);
+                }
+                if (hits.size === 1) link(f.path, [...hits][0] as string, 'reads', 'literal-path');
+            }
+        }
+        if (on['literal-dotted']) {
+            for (const m of f.source.matchAll(/\(\s*(['"])([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)+)\1/g)) {
+                const hits = byDotted.get((m[2] as string).replace(/\./g, '/')) ?? [];
+                if (hits.length === 1) link(f.path, hits[0] as string, 'renders', 'literal-dotted');
+            }
+        }
+    }
+
+    if (on['fs-route']) {
+        const pageDirs = pageDirectories(input.paths);
+        const seen = new Set<string>();
+        // A provider that knows the framework already declared this module's routes.
+        const routedFiles = new Set(input.nodes.filter((n) => n.kind === 'route').map((n) => n.source_file));
+        for (const p of input.paths) {
+            const r = fsRoutePath(p, pageDirs);
+            if (!r || routedFiles.has(p)) continue;
+            const id = `${p}#route:${r.verb} ${r.route}`;
+            // A provider that knows this framework may already have drawn the page.
+            if (seen.has(id) || nodeIds.has(id)) continue;
+            seen.add(id);
+            ensureFile(p);
+            nodes.push({ id, label: `${r.verb} ${r.route}`, kind: 'route', source_file: p, source_location: [] });
+            edges.push({ source: p, target: id, relation: 'member', confidence: 'EXTRACTED', resolved_via: 'same-file', provider: 'native' });
+            edges.push({ source: id, target: p, relation: 'routes-to', confidence: 'INFERRED', resolved_via: 'fs-route', provider: 'native' });
+            stats['fs-route'] += 1;
+        }
+    }
+    return { nodes, edges, stats };
+}

package/src/scripts/code_graph/extract.ts

@@ -11,7 +11,7 @@
  *               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.).
+ *               expected majority for dynamic-dispatch code (PHP frameworks etc.).
  */
 import {
     type CodeNode,
@@ -20,7 +20,7 @@ import {
     MAX_FILE_BYTES,
     type Relation,
 } from './types.js';
-import { extractGo, extractJava, extractPython } from './extract_more.js';
+import { extractCSharp, extractGo, extractJava, extractPython } from './extract_more.js';
 import { getParser, nodeHasError, type TsNode } from './loader.js';
 
 export type CallStyle = 'new' | 'free' | 'this' | 'self' | 'static' | 'parent' | 'scoped' | 'dynamic';
@@ -88,6 +88,8 @@ export interface FileExtract {
     /** local class id → its declared parent/interface names (2nd-pass inherits). */
     inherits: Array<{ classId: string; parentName: string }>;
     parseError: boolean;
+    /** C#: the namespaces the file declares, for `using` resolution in the build pass. */
+    namespaces?: string[];
 }
 
 export function loc(n: TsNode): number[] {
@@ -700,6 +702,7 @@ export async function extractFile(relPath: string, source: string, lang: Lang):
         else if (lang === 'python') extractPython(tree.rootNode, relPath, out);
         else if (lang === 'java') extractJava(tree.rootNode, relPath, out);
         else if (lang === 'go') extractGo(tree.rootNode, relPath, out);
+        else if (lang === 'csharp') extractCSharp(tree.rootNode, relPath, out);
         else extractTsJs(tree.rootNode, relPath, out);
     } finally {
         tree.delete(); // delete the tree, never the cached parser (loader.ts)

package/src/scripts/code_graph/extract_more.ts

@@ -1,5 +1,5 @@
 /**
- * Python, Go and Java extraction — the same shape `extract.ts` emits for
+ * Python, Go, Java and C# extraction — the same shape `extract.ts` emits for
  * PHP / TS / JS, so the build pass resolves them with no language branch
  * beyond module lookup.
  *
@@ -312,3 +312,107 @@ export function extractGo(root: TsNode, file: string, out: FileExtract): void {
     };
     walk(root, file);
 }
+
+/** The name a C# type expression names: `List<User>` → `List`, `A.B` → `B`. */
+function csType(n: TsNode): string {
+    if (n.type === 'generic_name') return text(namedChildren(n).find((c) => c.type === 'identifier'));
+    if (n.type === 'qualified_name') return lastSegment(n.text.replace(/<.*$/, ''));
+    return n.text.replace(/<.*$/, '');
+}
+
+export function extractCSharp(root: TsNode, file: string, out: FileExtract): void {
+    out.nodes.push({ id: file, label: file, kind: 'file', source_file: file, source_location: [] });
+    const TYPES: Record<string, 'class' | 'interface' | 'enum'> = {
+        class_declaration: 'class',
+        record_declaration: 'class',
+        struct_declaration: 'class',
+        interface_declaration: 'interface',
+        enum_declaration: 'enum',
+    };
+    const namespaces: string[] = [];
+    const walk = (n: TsNode, classId: string | null, scopeId: string, ns = ''): void => {
+        const kind = TYPES[n.type];
+        if (kind) {
+            const nm = nameField(n) ?? '<anon>';
+            const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
+            out.nodes.push({ id, label: nm, kind, source_file: file, source_location: loc(n) });
+            out.rawEdges.push({ sourceId: classId ?? file, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+            for (const c of namedChildren(n)) {
+                if (c.type !== 'base_list') continue;
+                for (const t of namedChildren(c)) {
+                    if (t.type === 'identifier' || t.type === 'generic_name' || t.type === 'qualified_name') {
+                        out.inherits.push({ classId: id, parentName: csType(t) });
+                    }
+                }
+            }
+            for (const c of namedChildren(n)) if (c.type === 'declaration_list') for (const d of namedChildren(c)) walk(d, id, id, ns);
+            return;
+        }
+        switch (n.type) {
+            case 'namespace_declaration':
+            case 'file_scoped_namespace_declaration': {
+                const name = n.childForFieldName('name');
+                const inner = ns ? `${ns}.${text(name)}` : text(name);
+                if (name && !namespaces.includes(inner)) namespaces.push(inner);
+                const body = n.childForFieldName('body') ?? n;
+                for (const c of namedChildren(body)) if (!same(c, name)) walk(c, classId, scopeId, inner);
+                return;
+            }
+            case 'using_directive': {
+                const parts = namedChildren(n);
+                const spec = parts.find((c) => c.type === 'qualified_name' || c.type === 'identifier');
+                const target = parts.filter((c) => c.type === 'qualified_name' || c.type === 'identifier').pop();
+                if (spec && target) {
+                    const aliased = parts.some((c) => c.type === 'name_equals') || n.text.includes('=');
+                    out.rawEdges.push({
+                        sourceId: file,
+                        relation: 'imports',
+                        targetName: lastSegment(target.text),
+                        confidenceHint: 'EXTRACTED',
+                        moduleSpecifier: target.text,
+                        importKind: 'namespace',
+                        ...(aliased && spec !== target ? { localName: spec.text } : {}),
+                    });
+                }
+                return;
+            }
+            case 'method_declaration':
+            case 'constructor_declaration': {
+                const nm = nameField(n) ?? '<anon>';
+                const id = uniq(out, 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 ?? file, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                for (const c of namedChildren(n)) if (c.type === 'block' || c.type === 'arrow_expression_clause') walk(c, classId, id, ns);
+                return;
+            }
+            case 'invocation_expression': {
+                const fn = n.childForFieldName('function');
+                const ctx = classId ? { enclosingClassId: classId } : {};
+                if (fn && (fn.type === 'identifier' || fn.type === 'generic_name')) {
+                    out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: csType(fn), confidenceHint: classId ? 'INFERRED' : 'AMBIGUOUS', callStyle: 'this', ...ctx });
+                } else if (fn && fn.type === 'member_access_expression') {
+                    const obj = fn.childForFieldName('expression');
+                    const nm = csType(fn.childForFieldName('name') ?? fn);
+                    if (obj && (obj.type === 'this_expression' || obj.type === 'base_expression')) {
+                        out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: nm, confidenceHint: classId ? 'INFERRED' : 'AMBIGUOUS', callStyle: obj.type === 'base_expression' ? 'parent' : 'this', ...ctx });
+                    } else if (obj && obj.type === 'identifier' && /^[A-Z]/.test(obj.text)) {
+                        out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: nm, confidenceHint: 'AMBIGUOUS', callStyle: 'scoped', scopeName: obj.text, ...ctx });
+                    } else {
+                        out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: nm, confidenceHint: 'AMBIGUOUS', callStyle: 'dynamic', ...ctx });
+                    }
+                }
+                break;
+            }
+            case 'object_creation_expression': {
+                const t = n.childForFieldName('type');
+                if (t) out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: csType(t), confidenceHint: 'EXTRACTED', callStyle: 'new' });
+                break;
+            }
+            default:
+                break;
+        }
+        for (const c of namedChildren(n)) walk(c, classId, scopeId, ns);
+    };
+    walk(root, null, file);
+    out.namespaces = namespaces;
+}

package/src/scripts/code_graph/loader.ts

@@ -146,16 +146,24 @@ async function _init(): Promise<void> {
     }
 }
 
+/**
+ * Grammars the pinned `tree-sitter-wasms` compiles at another ABI than the rest.
+ * The C# grammar ships at ABI 13, which the pinned runtime still loads; the pin
+ * stays exact per language, so a drift is still caught.
+ */
+export const GRAMMAR_ABI_PIN: Readonly<Partial<Record<Lang, number>>> = { csharp: 13 };
+
 /** 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) {
+    const pinned = GRAMMAR_ABI_PIN[lang] ?? EXPECTED_GRAMMAR_ABI;
+    if (language.version !== pinned) {
         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 ` +
+                `pinned ${pinned}. Re-pin web-tree-sitter/tree-sitter-wasms ` +
                 `and re-run the ABI smoke test.`,
         );
     }