@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/estate_map.ts

@@ -0,0 +1,141 @@
+/**
+ * `code-graph map --estate` — one offline page of the registered projects and
+ * the edges the estate index derived between them (ADR-299, step 5.4).
+ *
+ * Projects are nodes; a `package` edge (a declared dependency on a package
+ * another project publishes) is drawn solid, the two guesses (`unique-name`,
+ * `mention`) dashed. The page names client projects, so it is written under
+ * the user-global home and refused anywhere inside a git work tree.
+ *
+ * The page exposes `window.__mapLabelBoxes` and a `#panel .plist` list in the
+ * shape `map_verify` reads, so the same three-width render check applies.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { enclosingWorkTree } from '../_lib/git_common_dir.js';
+import { write_atomic } from '../_lib/fs_atomic.js';
+import { event4u_root } from '../_lib/user_global_paths.js';
+import { openEstate, type XEdge } from './estate_index.js';
+import { verifyMap } from './map_verify.js';
+
+export interface EstateMapData {
+    projects: Array<{ id: string; name: string; indexed_at: string }>;
+    edges: XEdge[];
+}
+
+export function estateMapDir(): string {
+    return path.join(event4u_root(), 'runtime', 'estate', 'map');
+}
+
+/** JSON safe inside a `<script>` element: no `</script>`, no `<!--`. */
+function scriptJson(v: unknown): string {
+    return JSON.stringify(v).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+}
+
+const CSS = `
+:root{--bg:#fbfbf9;--fg:#1d1d1b;--muted:#6b6b66;--line:#3c6e8f;--guess:#b0703a;--node:#ffffff;--ring:#3c6e8f;--hl:#d9e8f2}
+@media (prefers-color-scheme:dark){:root{--bg:#161615;--fg:#ecece8;--muted:#a3a39c;--line:#7fb2d4;--guess:#e0a46b;--node:#22221f;--ring:#7fb2d4;--hl:#25343e}}
+*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.45 system-ui,-apple-system,"Segoe UI",sans-serif}
+header{padding:16px 16px 4px}h1{font-size:18px;margin:0 0 4px}p{margin:0;color:var(--muted);max-width:60ch}
+main{display:flex;flex-wrap:wrap;gap:16px;padding:8px 16px 16px}.stage{flex:1 1 320px;min-width:0}svg{display:block;width:100%;height:auto}
+#panel{flex:0 1 260px;min-width:0}.plist{list-style:none;margin:0;padding:0}.plist button{display:flex;align-items:center;gap:8px;width:100%;
+border:0;background:none;color:inherit;font:inherit;text-align:left;padding:6px 4px;cursor:pointer;border-radius:6px}
+.plist button[aria-pressed=true]{background:var(--hl)}.swatch{flex:0 0 10px;height:10px;border-radius:50%;background:var(--ring)}
+.fname{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0}.legend{display:flex;flex-wrap:wrap;gap:12px;margin-top:8px;color:var(--muted);font-size:12px}
+.k{display:inline-block;width:24px;border-top:2px solid var(--line);vertical-align:middle;margin-right:4px}.k.g{border-top:2px dashed var(--guess)}
+line.package{stroke:var(--line);stroke-width:2}line.guess{stroke:var(--guess);stroke-width:1.5;stroke-dasharray:5 4}
+line.dim{opacity:.15}circle{fill:var(--node);stroke:var(--ring);stroke-width:2}text{fill:var(--fg);font-size:12px}
+`;
+
+const JS = `
+(function(){
+var data=JSON.parse(document.getElementById('estate-data').textContent);
+var svg=document.getElementById('stage');var NS='http://www.w3.org/2000/svg';
+var list=document.getElementById('plist');var selected=null;
+function short(s){return s.length>18?s.slice(0,17)+'\\u2026':s}
+function draw(){
+  while(svg.firstChild)svg.removeChild(svg.firstChild);
+  var w=Math.max(240,svg.parentNode.clientWidth),h=Math.min(w,520);
+  svg.setAttribute('viewBox','0 0 '+w+' '+h);svg.setAttribute('width',w);svg.setAttribute('height',h);
+  var n=data.projects.length,texts=[],maxw=0;
+  var gl=document.createElementNS(NS,'g'),gn=document.createElementNS(NS,'g');svg.appendChild(gl);svg.appendChild(gn);
+  data.projects.forEach(function(p){var t=document.createElementNS(NS,'text');t.textContent=short(p.name);t.setAttribute('text-anchor','middle');gn.appendChild(t);texts.push(t);maxw=Math.max(maxw,t.getComputedTextLength())});
+  var r=n<2?0:Math.max(24,Math.min(w/2-maxw/2-12,h/2-40));var cx=w/2,cy=h/2-8,pos={};
+  data.projects.forEach(function(p,i){var a=-Math.PI/2+2*Math.PI*i/Math.max(1,n);pos[p.id]={x:cx+r*Math.cos(a),y:cy+r*Math.sin(a)}});
+  data.edges.forEach(function(e){var s=pos[e.source],t=pos[e.target];if(!s||!t)return;var l=document.createElementNS(NS,'line');
+    l.setAttribute('x1',s.x);l.setAttribute('y1',s.y);l.setAttribute('x2',t.x);l.setAttribute('y2',t.y);
+    var cls=e.via==='package'?'package':'guess';if(selected&&e.source!==selected&&e.target!==selected)cls+=' dim';l.setAttribute('class',cls);
+    var tt=document.createElementNS(NS,'title');tt.textContent=e.via+': '+e.detail;l.appendChild(tt);gl.appendChild(l)});
+  var boxes=[];
+  data.projects.forEach(function(p,i){var c=document.createElementNS(NS,'circle');var q=pos[p.id];c.setAttribute('cx',q.x);c.setAttribute('cy',q.y);c.setAttribute('r',p.id===selected?9:7);
+    gn.insertBefore(c,texts[0]);var t=texts[i];t.setAttribute('x',q.x);t.setAttribute('y',q.y+22);var b=t.getBBox();boxes.push({x:b.x,y:b.y,w:b.width,h:b.height})});
+  window.__mapLabelBoxes={boxes:boxes,width:w,height:h};
+}
+data.projects.forEach(function(p){var li=document.createElement('li');var b=document.createElement('button');b.type='button';b.setAttribute('aria-pressed','false');
+  var s=document.createElement('span');s.className='swatch';var f=document.createElement('span');f.className='fname';f.textContent=p.name;f.title=p.id;
+  b.appendChild(s);b.appendChild(f);b.addEventListener('click',function(){selected=selected===p.id?null:p.id;
+    Array.prototype.forEach.call(list.querySelectorAll('button'),function(x){x.setAttribute('aria-pressed','false')});if(selected)b.setAttribute('aria-pressed','true');draw()});
+  li.appendChild(b);list.appendChild(li)});
+draw();window.addEventListener('resize',draw);
+})();
+`;
+
+export function renderEstateHtml(data: EstateMapData): string {
+    const packages = data.edges.filter((e) => e.via === 'package').length;
+    const guesses = data.edges.length - packages;
+    return [
+        '<!doctype html>',
+        '<html lang="en">',
+        '<head>',
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<title>Project estate</title>',
+        `<style>${CSS}</style>`,
+        '</head>',
+        '<body>',
+        '<header>',
+        '<h1>Project estate</h1>',
+        `<p>${data.projects.length} registered projects · ${packages} package links · ${guesses} guessed links. Local to this machine; never committed.</p>`,
+        '<div class="legend"><span><span class="k"></span>declared dependency</span><span><span class="k g"></span>guess (unique name or mention)</span></div>',
+        '</header>',
+        '<main>',
+        '<div class="stage"><svg id="stage" role="img" aria-label="Projects and the links between them"></svg></div>',
+        '<aside id="panel"><ul class="plist" id="plist"></ul></aside>',
+        '</main>',
+        `<script type="application/json" id="estate-data">${scriptJson(data)}</script>`,
+        `<script>${JS}</script>`,
+        '</body>',
+        '</html>',
+        '',
+    ].join('\n');
+}
+
+export async function estateMapMain(argv: string[]): Promise<number> {
+    const i = argv.indexOf('--out');
+    const outDir = i >= 0 && i + 1 < argv.length ? path.resolve(argv[i + 1] as string) : estateMapDir();
+    const tree = enclosingWorkTree(outDir);
+    if (tree !== null) {
+        process.stderr.write(`code-graph: refusing to write the estate map inside a git work tree (${tree}): it names client projects\n`);
+        return 1;
+    }
+    const db = openEstate();
+    if (!db) {
+        process.stderr.write('code-graph: no estate index — `code-graph projects index on`, then build or refresh each project\n');
+        return 1;
+    }
+    let data: EstateMapData;
+    try {
+        data = { projects: db.projects().map(({ id, name, indexed_at }) => ({ id, name, indexed_at })), edges: db.xedges() };
+    } finally {
+        db.close();
+    }
+    const page = path.join(outDir, 'index.html');
+    fs.mkdirSync(outDir, { recursive: true });
+    write_atomic(page, renderEstateHtml(data));
+    process.stdout.write(`✅  estate map — ${data.projects.length} projects · ${data.edges.length} links\n    wrote ${page}\n`);
+    if (argv.includes('--no-verify')) return 0;
+    const check = await verifyMap(page);
+    process.stdout.write(`    render check: ${check.verification}${check.reason ? ` — ${check.reason}` : ''}\n`);
+    return check.verification === 'failed' ? 1 : 0;
+}

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, extractRuby } 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,10 @@ 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[];
+    /** C#: the namespace each declared type sits in, by node id, for namespace-scope resolution. */
+    typeNamespaces?: Record<string, string>;
 }
 
 export function loc(n: TsNode): number[] {
@@ -700,6 +704,8 @@ 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 if (lang === 'ruby') extractRuby(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, C# and Ruby extraction — the same shape `extract.ts` emits for
  * PHP / TS / JS, so the build pass resolves them with no language branch
  * beyond module lookup.
  *
@@ -113,11 +113,18 @@ export function extractPython(root: TsNode, file: string, out: FileExtract): voi
             case 'call': {
                 const fn = n.childForFieldName('function');
                 if (fn?.type === 'identifier') {
-                    out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: fn.text, confidenceHint: 'EXTRACTED', callStyle: 'free' });
+                    // `Order(...)` instantiates: a CapWords name is a class by Python convention.
+                    const isNew = /^[A-Z]/.test(fn.text);
+                    out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: fn.text, confidenceHint: 'EXTRACTED', callStyle: isNew ? 'new' : 'free' });
                 } else if (fn?.type === 'attribute') {
                     const obj = fn.childForFieldName('object');
                     const attr = text(fn.childForFieldName('attribute'));
                     const isSelf = obj?.type === 'identifier' && (obj.text === 'self' || obj.text === 'cls');
+                    let base = obj;
+                    while (base?.type === 'attribute') base = base.childForFieldName('object');
+                    // `Post.objects.count()` / `Service.run()` name a class at the root of the chain.
+                    const classRoot = base?.type === 'identifier' && /^[A-Z]/.test(base.text) ? base.text : null;
+                    if (classRoot) out.rawEdges.push({ sourceId: scopeId, relation: 'uses', targetName: classRoot, confidenceHint: 'EXTRACTED' });
                     out.rawEdges.push({
                         sourceId: scopeId,
                         relation: 'calls',
@@ -125,6 +132,7 @@ export function extractPython(root: TsNode, file: string, out: FileExtract): voi
                         confidenceHint: isSelf && classId ? 'INFERRED' : 'AMBIGUOUS',
                         callStyle: isSelf ? 'this' : 'dynamic',
                         ...(classId ? { enclosingClassId: classId } : {}),
+                        ...(classRoot && obj === base ? { scopeName: classRoot } : {}),
                     });
                 }
                 break;
@@ -312,3 +320,234 @@ 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 typeNamespaces: Record<string, string> = {};
+    /** Every project-type name a type expression mentions: `List<Order>` names `List` and `Order`; `int` names none. */
+    const typeNames = (t: TsNode | null, acc: string[] = []): string[] => {
+        if (!t || t.type === 'predefined_type') return acc;
+        if (t.type === 'identifier' || t.type === 'qualified_name') return [...acc, csType(t)];
+        if (t.type === 'generic_name') acc.push(csType(t));
+        for (const c of namedChildren(t)) if (t.type !== 'generic_name' || c.type === 'type_argument_list') acc = typeNames(c, acc);
+        return acc;
+    };
+    const usesTypes = (sourceId: string, t: TsNode | null): void => {
+        for (const nm of new Set(typeNames(t))) out.rawEdges.push({ sourceId, relation: 'uses', targetName: nm, confidenceHint: 'EXTRACTED' });
+    };
+    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) });
+            if (!classId && ns) typeNamespaces[id] = ns;
+            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 'field_declaration':
+            case 'property_declaration': {
+                const decl = n.type === 'field_declaration' ? namedChildren(n).find((c) => c.type === 'variable_declaration') : n;
+                if (classId) usesTypes(classId, decl?.childForFieldName('type') ?? null);
+                break;
+            }
+            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' });
+                usesTypes(id, n.childForFieldName('returns') ?? n.childForFieldName('type'));
+                for (const c of namedChildren(n))
+                    if (c.type === 'parameter_list') for (const p of namedChildren(c)) if (p.type === 'parameter') usesTypes(id, p.childForFieldName('type'));
+                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;
+    out.typeNamespaces = typeNamespaces;
+}
+
+/** The last segment of a Ruby constant path: `Admin::User` → `User`. */
+function rbConst(n: TsNode | null): string {
+    return n ? (n.text.split('::').pop() ?? n.text).trim() : '';
+}
+
+/**
+ * Ruby: classes, modules (as `trait` — a mixin is what PHP calls a trait),
+ * instance and singleton methods, `require` / `require_relative`, the
+ * superclass and every `include` / `extend` / `prepend` as `inherits`, and
+ * calls: implicit-self and `self.` calls on the enclosing class, `Foo.new`,
+ * `Foo.bar` scoped calls (plus a `uses` of `Foo`), and dynamic receivers.
+ */
+export function extractRuby(root: TsNode, file: string, out: FileExtract): void {
+    out.nodes.push({ id: file, label: file, kind: 'file', source_file: file, source_location: [] });
+    const MIXINS = new Set(['include', 'extend', 'prepend']);
+    const walk = (n: TsNode, classId: string | null, scopeId: string): void => {
+        switch (n.type) {
+            case 'class':
+            case 'module': {
+                const nm = rbConst(n.childForFieldName('name')) || '<anon>';
+                const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
+                out.nodes.push({ id, label: nm, kind: n.type === 'class' ? 'class' : 'trait', source_file: file, source_location: loc(n) });
+                out.rawEdges.push({ sourceId: classId ?? file, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                const sup = n.childForFieldName('superclass');
+                const parent = sup ? namedChildren(sup)[0] : undefined;
+                if (parent && (parent.type === 'constant' || parent.type === 'scope_resolution')) out.inherits.push({ classId: id, parentName: rbConst(parent) });
+                const body = n.childForFieldName('body');
+                if (body) for (const c of namedChildren(body)) walk(c, id, id);
+                return;
+            }
+            case 'method':
+            case 'singleton_method': {
+                const nm = nameField(n) ?? '<anon>';
+                const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
+                out.nodes.push({ id, label: nm, kind: classId ? 'method' : 'function', source_file: file, source_location: loc(n) });
+                out.rawEdges.push({ sourceId: classId ?? file, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                const body = n.childForFieldName('body');
+                for (const c of body ? namedChildren(body) : []) {
+                    // A bare identifier statement is an argument-less implicit-self
+                    // call (`audit`); a local read looks the same and resolves to
+                    // nothing, which is what an unresolved call records.
+                    if (c.type === 'identifier' && classId)
+                        out.rawEdges.push({ sourceId: id, relation: 'calls', targetName: c.text, confidenceHint: 'INFERRED', callStyle: 'this', enclosingClassId: classId });
+                    else walk(c, classId, id);
+                }
+                return;
+            }
+            case 'call': {
+                const recv = n.childForFieldName('receiver');
+                const nm = text(n.childForFieldName('method'));
+                const args = n.childForFieldName('arguments');
+                const first = args ? namedChildren(args)[0] : undefined;
+                if (!recv && (nm === 'require' || nm === 'require_relative') && first?.type === 'string') {
+                    const raw = text(namedChildren(first).find((c) => c.type === 'string_content'));
+                    if (raw) {
+                        const spec = nm === 'require_relative' && !raw.startsWith('.') ? `./${raw}` : raw;
+                        out.rawEdges.push({
+                            sourceId: file,
+                            relation: 'imports',
+                            targetName: lastSegment(raw),
+                            confidenceHint: 'EXTRACTED',
+                            moduleSpecifier: spec,
+                            importKind: 'namespace',
+                            // A require binds no name; a local that cannot be written keeps it from shadowing one.
+                            localName: `require:${spec}`,
+                        });
+                    }
+                    return;
+                }
+                if (!recv && classId && MIXINS.has(nm) && args) {
+                    for (const c of namedChildren(args))
+                        if (c.type === 'constant' || c.type === 'scope_resolution') out.inherits.push({ classId, parentName: rbConst(c) });
+                    return;
+                }
+                const ctx = classId ? { enclosingClassId: classId } : {};
+                if (recv && (recv.type === 'constant' || recv.type === 'scope_resolution')) {
+                    const cls = rbConst(recv);
+                    if (nm === 'new') out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: cls, confidenceHint: 'EXTRACTED', callStyle: 'new' });
+                    else {
+                        out.rawEdges.push({ sourceId: scopeId, relation: 'uses', targetName: cls, confidenceHint: 'EXTRACTED' });
+                        out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: nm, confidenceHint: 'AMBIGUOUS', callStyle: 'scoped', scopeName: cls, ...ctx });
+                    }
+                } else if (!recv || recv.type === 'self') {
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'calls',
+                        targetName: nm,
+                        confidenceHint: classId ? 'INFERRED' : 'AMBIGUOUS',
+                        callStyle: classId ? 'this' : 'free',
+                        ...ctx,
+                    });
+                } else if (nm) {
+                    out.rawEdges.push({ sourceId: scopeId, relation: 'calls', targetName: nm, confidenceHint: 'AMBIGUOUS', callStyle: 'dynamic', ...ctx });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        for (const c of namedChildren(n)) walk(c, classId, scopeId);
+    };
+    walk(root, null, file);
+}

package/src/scripts/code_graph/graph_budget.ts

@@ -0,0 +1,158 @@
+/**
+ * The storage budget for user-global graph homes (ADR-299, council O4).
+ *
+ * Only directories under `runtime/graphs/` are ever evicted — a graph under a
+ * repository's own `agents/` is the project's, not this machine's cache.
+ * Eviction is least-recently-QUERIED first: a query touches its home's
+ * `.last-query` marker, a build or refresh records it in the registry, and a
+ * registry scan changes neither. A pinned project's homes, a home whose
+ * refresh lock is held, and a home written to within a stale-lock window or
+ * holding a temp output are never evicted, so a budget can stay exceeded. The
+ * last guard exists because a plain `code-graph build` takes no lock.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { readRegistry, updateRegistry } from '../_lib/project_registry.js';
+import { graphHome, graphsRoot } from './graph_home.js';
+import { isStale, STALE_LOCK_MS } from './refresh_lock.js';
+
+const MB = 1024 * 1024;
+const LAST_QUERY = '.last-query';
+
+/** Record that a query just read `root`'s graph. Only user-global homes keep recency. */
+export function touchHome(root: string): void {
+    try {
+        const home = graphHome(root);
+        if (home.kind !== 'global' || !fs.existsSync(home.dir)) return;
+        const marker = path.join(home.dir, LAST_QUERY);
+        const now = new Date();
+        try {
+            fs.utimesSync(marker, now, now);
+        } catch {
+            fs.writeFileSync(marker, '');
+        }
+    } catch {
+        /* recency is a hint; a query never fails on it */
+    }
+}
+
+interface Walk {
+    bytes: number;
+    /** Newest mtime of anything below the home except the query marker. */
+    newest: number;
+    /** A build's or refresh's temp output is present. */
+    temp: boolean;
+}
+
+const TEMP_RE = /\.refresh-tmp-|\.tmp-/;
+
+function walk(dir: string, top: boolean, acc: Walk = { bytes: 0, newest: 0, temp: false }): Walk {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return acc;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (TEMP_RE.test(e.name)) acc.temp = true;
+        let st: fs.Stats;
+        try {
+            st = fs.lstatSync(p);
+        } catch {
+            continue;
+        }
+        if (!(top && e.name === LAST_QUERY)) acc.newest = Math.max(acc.newest, st.mtimeMs);
+        if (e.isDirectory()) walk(p, false, acc);
+        else acc.bytes += st.size;
+    }
+    return acc;
+}
+
+export interface HomeUsage {
+    dir: string;
+    bytes: number;
+    /** Last query, else last build or refresh, else the directory's own mtime. */
+    used_at: number;
+    pinned: boolean;
+    locked: boolean;
+    /** Written within the last {@link STALE_LOCK_MS}, or holding a temp output: a build may be mid-write. */
+    busy: boolean;
+    project: string | null;
+}
+
+/** Every user-global graph home with its size and why it may or may not go. */
+export function homeUsage(): HomeUsage[] {
+    const base = graphsRoot();
+    let names: string[];
+    try {
+        names = fs.readdirSync(base);
+    } catch {
+        return [];
+    }
+    const reg = readRegistry();
+    const owner = new Map<string, { id: string; pinned: boolean; at: number }>();
+    for (const [id, e] of Object.entries(reg.projects)) {
+        for (const [dir, at] of Object.entries(e.homes)) owner.set(dir, { id, pinned: e.pinned, at: Date.parse(at) || 0 });
+    }
+    const out: HomeUsage[] = [];
+    const now = Date.now();
+    for (const name of names) {
+        const dir = path.join(base, name);
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(dir);
+        } catch {
+            continue;
+        }
+        if (!st.isDirectory()) continue;
+        let queried = 0;
+        try {
+            queried = fs.statSync(path.join(dir, LAST_QUERY)).mtimeMs;
+        } catch {
+            queried = 0;
+        }
+        const o = owner.get(dir);
+        const lock = path.join(dir, 'state', 'code-graph-refresh.lock');
+        const w = walk(dir, true);
+        out.push({
+            dir,
+            bytes: w.bytes,
+            used_at: Math.max(queried, o?.at ?? 0) || st.mtimeMs,
+            pinned: o?.pinned ?? false,
+            locked: fs.existsSync(lock) && !isStale(lock),
+            busy: w.temp || now - w.newest < STALE_LOCK_MS,
+            project: o?.id ?? null,
+        });
+    }
+    return out;
+}
+
+/**
+ * Evict the least recently used homes until the total fits `budget_mb`;
+ * returns what went. `keep` is the home a build just wrote, which is never its
+ * own victim.
+ */
+export function enforceBudget(keep?: string): { evicted: HomeUsage[]; total: number; budget: number } {
+    const budget = readRegistry().budget_mb * MB;
+    const homes = homeUsage();
+    let total = homes.reduce((n, h) => n + h.bytes, 0);
+    const evicted: HomeUsage[] = [];
+    for (const h of [...homes].sort((a, b) => a.used_at - b.used_at)) {
+        if (total <= budget) break;
+        if (h.pinned || h.locked || h.busy || h.dir === keep) continue;
+        fs.rmSync(h.dir, { recursive: true, force: true });
+        total -= h.bytes;
+        evicted.push(h);
+    }
+    if (evicted.length) {
+        const gone = new Set(evicted.map((h) => h.dir));
+        updateRegistry((reg) => {
+            for (const e of Object.values(reg.projects)) {
+                for (const dir of Object.keys(e.homes)) if (gone.has(dir)) delete e.homes[dir];
+            }
+        });
+    }
+    return { evicted, total, budget };
+}