@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/projects_cli.ts

@@ -0,0 +1,254 @@
+/**
+ * `code-graph projects …` — the registry of projects this machine works in
+ * (ADR-299). A project is added by use (a build or refresh calls
+ * {@link registerUse}) or by hand with `add`; nothing here walks a directory
+ * tree looking for repositories.
+ *
+ *   projects list                       every entry; a root missing for 30 days is flagged
+ *   projects add <path>                 register a project by hand
+ *   projects remove <id|name|path>      drop one entry and its user-global graph homes
+ *   projects prune                      drop the flagged entries
+ *   projects index on|off|status        the estate index switch (council O1, default off)
+ *   projects budget [MB]                show or set the graph-home budget (default 2048)
+ *   projects pin|unpin <id|name|path>   keep a project's graph homes out of eviction
+ *   projects evict                      evict least recently queried homes down to the budget
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { findProjects, mainRoot, type ProjectEntry, readRegistry, recordProject, repoIdOf, updateRegistry } from '../_lib/project_registry.js';
+import { dropProjectRows, indexAfterRefresh, indexPath } from './estate_index.js';
+import { enforceBudget, homeUsage } from './graph_budget.js';
+import { graphHome, graphsRoot } from './graph_home.js';
+import type { CodeGraph } from './types.js';
+
+/** A root missing this long is flagged by `list` and removed by `prune` (6.2). */
+export const STALE_ROOT_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export type RootState = 'present' | 'missing' | 'stale';
+
+export function rootState(e: ProjectEntry, now: Date = new Date()): RootState {
+    if (fs.existsSync(e.root)) return 'present';
+    return now.getTime() - Date.parse(e.last_seen) >= STALE_ROOT_DAYS * DAY_MS ? 'stale' : 'missing';
+}
+
+/**
+ * Record that `root`'s graph was just built or refreshed. Best-effort: the
+ * registry is bookkeeping, and a failure to write it never fails a build.
+ *
+ * A linked worktree shares its main checkout's repo id, so it records only its
+ * own home (for eviction and removal) and never the entry's graph home, commit,
+ * languages or estate row — a feature-branch build must not replace what the
+ * main checkout recorded.
+ */
+export function registerUse(root: string, graph: CodeGraph | null, commit: string | null): string | null {
+    try {
+        const home = graphHome(root);
+        const real = fs.realpathSync(root);
+        const worktree = mainRoot(real) !== real;
+        const usedHome = home.kind === 'global' ? { usedHome: home.dir } : {};
+        const id = recordProject(
+            root,
+            worktree
+                ? usedHome
+                : {
+                      graph_home: home.dir,
+                      ...(commit ? { graph_commit: commit } : {}),
+                      ...(graph ? { languages: [...graph.languages], providers: (graph.providers ?? []).map((p) => p.id) } : {}),
+                      ...usedHome,
+                  },
+        );
+        if (!worktree) {
+            // A row the pre-checkout registry wrote under the bare repo id goes once that entry was re-keyed.
+            if (readRegistry().projects[repoIdOf(id)] === undefined) dropProjectRows(repoIdOf(id));
+            indexAfterRefresh(id, real, home.cachePath, graph);
+        }
+        if (home.kind === 'global') enforceBudget(home.dir);
+        return id;
+    } catch {
+        return null;
+    }
+}
+
+/** User-global homes are removable caches; a home under a repository's own `agents/` never is. */
+function removeGlobalHomes(e: ProjectEntry): string[] {
+    const base = graphsRoot();
+    const removed: string[] = [];
+    for (const dir of new Set([...Object.keys(e.homes), ...(e.graph_home ? [e.graph_home] : [])])) {
+        const rel = path.relative(base, dir);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        fs.rmSync(dir, { recursive: true, force: true });
+        removed.push(dir);
+    }
+    return removed;
+}
+
+function cmdList(): number {
+    const reg = readRegistry();
+    const rows = Object.entries(reg.projects);
+    if (!rows.length) {
+        process.stdout.write('no registered projects — a `code-graph build` or `code-graph projects add <path>` registers one\n');
+        return 0;
+    }
+    for (const [id, e] of rows) {
+        const state = rootState(e);
+        const flag = state === 'stale' ? ` · STALE (missing ${STALE_ROOT_DAYS}+ days — \`projects prune\` removes it)` : state === 'missing' ? ' · missing' : '';
+        process.stdout.write(
+            `${id}  ${e.root}${e.pinned ? ' · pinned' : ''}${flag}\n` +
+                `    last seen ${e.last_seen}${e.graph_commit ? ` · commit ${e.graph_commit.slice(0, 12)}` : ''}` +
+                `${e.languages.length ? ` · ${e.languages.join(', ')}` : ''}${e.providers.length ? ` · providers ${e.providers.join(', ')}` : ''}\n`,
+        );
+    }
+    process.stdout.write(`estate index: ${reg.index ? 'on' : 'off'} · budget ${reg.budget_mb} MB\n`);
+    return 0;
+}
+
+function cmdAdd(target: string | undefined): number {
+    if (!target) {
+        process.stderr.write('usage: code-graph projects add <path>\n');
+        return 2;
+    }
+    const abs = path.resolve(target);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+        process.stderr.write(`code-graph: not a directory: ${abs}\n`);
+        return 1;
+    }
+    const id = recordProject(abs);
+    process.stdout.write(`registered ${id}  ${fs.realpathSync(abs)}\n`);
+    return 0;
+}
+
+function cmdRemove(ref: string | undefined): number {
+    if (!ref) {
+        process.stderr.write('usage: code-graph projects remove <id|name|path>\n');
+        return 2;
+    }
+    const hits = findProjects(readRegistry(), ref);
+    if (hits.length === 0) {
+        process.stderr.write(`code-graph: no registered project matches '${ref}'\n`);
+        return 1;
+    }
+    if (hits.length > 1) {
+        process.stderr.write(`code-graph: '${ref}' names ${hits.length} projects — use an id:\n`);
+        for (const [id, e] of hits) process.stderr.write(`  ${id}  ${e.root}\n`);
+        return 1;
+    }
+    const [id, entry] = hits[0] as [string, ProjectEntry];
+    updateRegistry((reg) => {
+        delete reg.projects[id];
+    });
+    const removed = removeGlobalHomes(entry);
+    dropProjectRows(id);
+    process.stdout.write(`removed ${id}  ${entry.root}${removed.length ? ` · ${removed.length} graph home(s) deleted` : ''}\n`);
+    return 0;
+}
+
+function cmdPrune(): number {
+    const now = new Date();
+    const dropped = updateRegistry((reg) => {
+        const out: Array<[string, ProjectEntry]> = [];
+        for (const [id, e] of Object.entries(reg.projects)) {
+            if (rootState(e, now) !== 'stale') continue;
+            out.push([id, e]);
+            delete reg.projects[id];
+        }
+        return out;
+    });
+    for (const [id, e] of dropped) {
+        removeGlobalHomes(e);
+        dropProjectRows(id);
+        process.stdout.write(`pruned ${id}  ${e.root}\n`);
+    }
+    process.stdout.write(`${dropped.length} pruned\n`);
+    return 0;
+}
+
+function cmdIndex(action: string | undefined): number {
+    if (action === 'on' || action === 'off') {
+        updateRegistry((reg) => {
+            reg.index = action === 'on';
+        });
+        if (action === 'off') fs.rmSync(indexPath(), { force: true });
+        process.stdout.write(
+            action === 'on'
+                ? 'estate index on — each registered project is indexed on its next build or refresh. It names client projects by path and never leaves this machine.\n'
+                : 'estate index off — the index file is deleted and nothing is indexed.\n',
+        );
+        return 0;
+    }
+    if (action !== undefined && action !== 'status') {
+        process.stderr.write('usage: code-graph projects index on|off|status\n');
+        return 2;
+    }
+    const reg = readRegistry();
+    process.stdout.write(`estate index: ${reg.index ? 'on' : 'off'} · ${fs.existsSync(indexPath()) ? indexPath() : 'no index file'}\n`);
+    return 0;
+}
+
+function one(ref: string | undefined, verb: string): [string, ProjectEntry] | null {
+    if (!ref) {
+        process.stderr.write(`usage: code-graph projects ${verb} <id|name|path>\n`);
+        return null;
+    }
+    const hits = findProjects(readRegistry(), ref);
+    if (hits.length !== 1) {
+        process.stderr.write(`code-graph: '${ref}' matches ${hits.length} registered projects — use an id from \`projects list\`\n`);
+        return null;
+    }
+    return hits[0] as [string, ProjectEntry];
+}
+
+function cmdPin(ref: string | undefined, pinned: boolean): number {
+    const hit = one(ref, pinned ? 'pin' : 'unpin');
+    if (!hit) return 1;
+    updateRegistry((reg) => {
+        const e = reg.projects[hit[0]];
+        if (e) e.pinned = pinned;
+    });
+    process.stdout.write(`${pinned ? 'pinned' : 'unpinned'} ${hit[0]}  ${hit[1].root}\n`);
+    return 0;
+}
+
+function cmdBudget(value: string | undefined): number {
+    if (value !== undefined) {
+        const mb = Number(value);
+        if (!Number.isFinite(mb) || mb <= 0) {
+            process.stderr.write('usage: code-graph projects budget [MB] — a positive number\n');
+            return 2;
+        }
+        updateRegistry((reg) => {
+            reg.budget_mb = mb;
+        });
+    }
+    const used = homeUsage().reduce((n, h) => n + h.bytes, 0);
+    process.stdout.write(`graph-home budget: ${readRegistry().budget_mb} MB · in use ${(used / (1024 * 1024)).toFixed(1)} MB under ${graphsRoot()}\n`);
+    return 0;
+}
+
+function cmdEvict(): number {
+    const r = enforceBudget();
+    for (const h of r.evicted) process.stdout.write(`evicted ${h.dir} (${(h.bytes / (1024 * 1024)).toFixed(1)} MB)\n`);
+    const over = r.total > r.budget;
+    process.stdout.write(
+        `${r.evicted.length} evicted · ${(r.total / (1024 * 1024)).toFixed(1)} of ${(r.budget / (1024 * 1024)).toFixed(1)} MB` +
+            (over ? ' — still over: the rest is pinned, lock-held or being written' : '') +
+            '\n',
+    );
+    return 0;
+}
+
+export function projectsMain(argv: string[]): number {
+    const [verb, ...rest] = argv;
+    const positional = rest.filter((a) => !a.startsWith('--'));
+    if (verb === undefined || verb === 'list') return cmdList();
+    if (verb === 'add') return cmdAdd(positional[0]);
+    if (verb === 'remove') return cmdRemove(positional[0]);
+    if (verb === 'prune') return cmdPrune();
+    if (verb === 'index') return cmdIndex(positional[0]);
+    if (verb === 'budget') return cmdBudget(positional[0]);
+    if (verb === 'pin' || verb === 'unpin') return cmdPin(positional[0], verb === 'pin');
+    if (verb === 'evict') return cmdEvict();
+    process.stderr.write('usage: code-graph projects list|add|remove|prune|index|budget|pin|unpin|evict\n');
+    return 2;
+}

package/src/scripts/code_graph/providers/angular.ts

@@ -0,0 +1,55 @@
+/**
+ * Angular:
+ *
+ *   { path: 'x', component: XComponent }            PAGE /x --routes-to--> XComponent
+ *   { path: 'x', loadComponent: () => import('./x').then((m) => m.X) }   → X, else the module
+ *   @Component({ templateUrl: './x.html' }) class    --renders-->  the template file
+ *   constructor(private s: S) · s = inject(S)        --injects-->  S (in a decorated class)
+ *
+ * Child route paths are not joined to their parent's; `loadChildren` modules,
+ * inline `template:` strings and `styleUrls` are not followed.
+ */
+import * as path from 'node:path';
+
+import { npmRoots } from './shared/detect.js';
+import { constructorInjection, routeObjects } from './shared/js.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const EXTS = ['.ts'];
+
+function templateUrls(kit: Kit): number {
+    const inventory = new Set(kit.paths);
+    let count = 0;
+    for (const f of kit.filesWithExt(...EXTS)) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/@Component\(\s*\{(?<body>[^]*?)\}\s*\)/g)) {
+            const url = /\btemplateUrl\s*:\s*(['"`])([^'"`]+)\1/.exec(m.groups?.['body'] ?? '');
+            if (!url) continue;
+            const cls = kit.nextSymbol(f.path, at(m.index as number), ['class']);
+            const target = path.posix.join(path.posix.dirname(f.path), url[2] as string);
+            if (!cls || cls.kind !== 'class' || !inventory.has(target)) continue;
+            kit.fileNode(target);
+            kit.emit(cls.id, target, 'renders', 'directive-scan');
+            count += 1;
+        }
+    }
+    return count;
+}
+
+export const angularProvider: ConventionProvider = {
+    id: 'angular',
+    detect: (probe) => npmRoots(probe, ['@angular/core']),
+    build: (input) => {
+        const kit = makeKit(input);
+        routeObjects(kit, { exts: EXTS, componentKeys: ['component', 'loadComponent'] });
+        templateUrls(kit);
+        constructorInjection(kit, {
+            exts: EXTS,
+            classDecorator: /@(?:Component|Injectable|Directive|Pipe)\(/,
+            reach: 12,
+            injectCall: /=\s*inject\(\s*([A-Za-z_$][\w$]*)\s*\)/g,
+        });
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/providers/aspnetcore.ts

@@ -0,0 +1,182 @@
+/**
+ * ASP.NET Core, read by its conventions:
+ *
+ *   routing     `[HttpGet("x")]` / `[HttpPost]` / `[Route("x")]` on an action,
+ *               under a class `[Route("api/[controller]")]` → route --routes-to--> the action;
+ *               `app.MapGet("/x", Handler)` → the handler when it is a method group
+ *   EF Core     `DbSet<User> Users` in a `DbContext` → User --persists--> table:Users
+ *               (`[Table("x")]` on the entity wins)
+ *   views       `View()` / `View("Name")` in a controller action
+ *               → `Views/<Controller>/<Name or action>.cshtml`, else `Views/Shared/`
+ *   DI          a constructor parameter typed as an in-repo class or interface → injects
+ *
+ * Not followed: conventional routing tables (`MapControllerRoute`), a view named
+ * by a variable or `View(model)`, primary constructors, and a type name two
+ * in-repo declarations share — each gets no edge rather than a guess.
+ */
+import * as path from 'node:path';
+
+import type { CodeNode } from '../types.js';
+import { dotnetRoots } from './shared/detect.js';
+import { callRoutes, joinRoute, lastArgName } from './shared/extractors.js';
+import { escapeRe, type Kit, lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const ATTR =
+    /[[,]\s*(?<attr>Http(?:Get|Post|Put|Patch|Delete|Head|Options)|Route)(?:Attribute)?\b(?:\s*\(\s*(?:template\s*:\s*)?"(?<path>[^"]*)"[^)]*\))?/g;
+
+/** In-repo types by simple name, kept only when the name is declared once. */
+function uniqueTypes(kit: Kit): Map<string, CodeNode> {
+    const seen = new Map<string, CodeNode | null>();
+    for (const n of kit.nodeById.values()) {
+        if (!n.source_file.endsWith('.cs') || (n.kind !== 'class' && n.kind !== 'interface')) continue;
+        seen.set(n.label, seen.has(n.label) ? null : n);
+    }
+    const out = new Map<string, CodeNode>();
+    for (const [k, v] of seen) if (v) out.set(k, v);
+    return out;
+}
+
+const controllerName = (cls: CodeNode): string => cls.label.replace(/Controller$/, '');
+
+function attributeRoutes(kit: Kit): void {
+    for (const f of kit.filesWithExt('.cs')) {
+        const at = lineIndex(f.source);
+        const prefixes = new Map<string, string>();
+        const actions = new Map<string, { node: CodeNode; line: number; verbs: Array<{ verb: string; path?: string }>; routes: string[] }>();
+        for (const m of f.source.matchAll(ATTR)) {
+            const line = at(m.index as number);
+            const attr = m.groups?.['attr'] as string;
+            const tpl = m.groups?.['path'];
+            const owner = kit.enclosing(f.path, line);
+            const method = owner === f.path ? null : kit.nodeById.get(owner);
+            if (!method) {
+                const cls = kit.classAt(f.path, line);
+                if (cls && attr === 'Route' && tpl !== undefined) prefixes.set(cls.id, tpl);
+                continue;
+            }
+            const a = actions.get(method.id) ?? { node: method, line, verbs: [], routes: [] };
+            if (attr === 'Route') {
+                if (tpl !== undefined) a.routes.push(tpl);
+            } else a.verbs.push({ verb: attr.slice(4).toUpperCase(), ...(tpl !== undefined ? { path: tpl } : {}) });
+            actions.set(method.id, a);
+        }
+        for (const a of actions.values()) {
+            const cls = kit.classAt(f.path, a.node.source_location[0] as number);
+            const prefix = cls ? prefixes.get(cls.id) : undefined;
+            const pairs: Array<[string, string | undefined]> = [];
+            for (const v of a.verbs) {
+                if (v.path !== undefined) pairs.push([v.verb, v.path]);
+                else if (a.routes.length > 0) for (const r of a.routes) pairs.push([v.verb, r]);
+                else pairs.push([v.verb, undefined]);
+            }
+            if (a.verbs.length === 0) for (const r of a.routes) pairs.push(['ANY', r]);
+            for (const [verb, tpl] of pairs) {
+                const absolute = tpl !== undefined && /^~?\//.test(tpl);
+                const raw = absolute ? joinRoute(tpl.replace(/^~/, '')) : joinRoute(prefix, tpl);
+                const routePath = raw
+                    .replace(/\[controller\]/gi, cls ? controllerName(cls) : '[controller]')
+                    .replace(/\[action\]/gi, a.node.label);
+                kit.emit(kit.route(f.path, verb, routePath, a.line), a.node.id, 'routes-to', 'route-table');
+            }
+        }
+    }
+}
+
+function minimalApi(kit: Kit, types: Map<string, CodeNode>): void {
+    callRoutes(kit, {
+        exts: ['.cs'],
+        call: /\b\w+\s*\.\s*Map(?<verb>Get|Post|Put|Patch|Delete)\(\s*"(?<path>[^"]*)"\s*,(?=(?<rest>[\s\S]{0,300}))/g,
+        handler: (_k, file, rest) => {
+            const name = lastArgName(rest);
+            if (!name) return null;
+            const [head, member] = name.split('.') as [string, string | undefined];
+            if (member) {
+                const cls = types.get(head);
+                return cls ? kit.methodOf(cls.id, member) : null;
+            }
+            const local = kit.nodesInFile(file).filter((n) => n.label === head && (n.kind === 'method' || n.kind === 'function'));
+            return local.length === 1 ? (local[0] as CodeNode).id : null;
+        },
+    });
+}
+
+function entities(kit: Kit, types: Map<string, CodeNode>): void {
+    const sourceOf = new Map(kit.files.map((f) => [f.path, f.source] as const));
+    for (const f of kit.filesWithExt('.cs')) {
+        if (!/\bclass\s+\w+[^{;]*:\s*[^{;]*\bDbContext\b/.test(f.source)) continue;
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/\bDbSet<\s*(?:[\w.]+\.)?(?<entity>\w+)\s*>\s+(?<prop>\w+)/g)) {
+            const entity = types.get(m.groups?.['entity'] as string);
+            if (!entity || entity.kind !== 'class') continue;
+            const lines = (sourceOf.get(entity.source_file) ?? '').split('\n');
+            const start = entity.source_location[0] as number;
+            const head = lines.slice(start - 1, start + 5).join('\n').split(/\bclass\b/)[0] ?? '';
+            const explicit = /\[\s*Table\s*\(\s*"(?<name>[^"]+)"/.exec(head)?.groups?.['name'];
+            const table = kit.table(explicit ?? (m.groups?.['prop'] as string), f.path, at(m.index as number));
+            kit.emit(entity.id, table, 'persists', 'schema-call');
+        }
+    }
+}
+
+function views(kit: Kit): void {
+    const inventory = new Set(kit.paths);
+    for (const f of kit.filesWithExt('.cs')) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/\b(?:Partial)?View\(\s*(?:"(?<name>[^"]+)"\s*)?[,)]/g)) {
+            const line = at(m.index as number);
+            const owner = kit.enclosing(f.path, line);
+            const action = owner === f.path ? null : kit.nodeById.get(owner);
+            const cls = action ? kit.classAt(f.path, line) : null;
+            if (!action || !cls || !cls.label.endsWith('Controller')) continue;
+            const name = m.groups?.['name'] ?? action.label;
+            const candidates: string[] = [];
+            for (const root of kit.roots) {
+                if (/^~?\//.test(name)) candidates.push(path.posix.join(root, name.replace(/^~?\//, '')));
+                else {
+                    const file = name.endsWith('.cshtml') ? name : `${name}.cshtml`;
+                    candidates.push(path.posix.join(root, 'Views', controllerName(cls), file), path.posix.join(root, 'Views', 'Shared', file));
+                }
+            }
+            const target = candidates.find((c) => inventory.has(c));
+            if (!target) continue;
+            kit.fileNode(target);
+            kit.emit(action.id, target, 'renders', 'directive-scan');
+        }
+    }
+}
+
+function injection(kit: Kit, types: Map<string, CodeNode>): void {
+    const sourceOf = new Map(kit.files.map((f) => [f.path, f.source] as const));
+    for (const n of kit.nodeById.values()) {
+        if (n.kind !== 'method' || !n.source_file.endsWith('.cs')) continue;
+        const clsId = n.id.split('::').slice(0, -1).join('::');
+        const cls = kit.nodeById.get(clsId);
+        if (!cls || cls.kind !== 'class' || cls.label !== n.label) continue;
+        const lines = (sourceOf.get(n.source_file) ?? '').split('\n');
+        const start = n.source_location[0] as number;
+        const decl = lines.slice(start - 1, (n.source_location[2] as number) ?? start).join('\n');
+        const params = new RegExp(`\\b${escapeRe(n.label)}\\s*\\(([^)]*)\\)`).exec(decl)?.[1] ?? '';
+        for (const p of params.split(',')) {
+            const t = /(?:^|\s)(?:[\w.]+\.)?(?<type>[A-Za-z_]\w*)\s*(?:<[^>]*>)?\??\s+\w+\s*(?:=.*)?$/.exec(p.trim())?.groups?.['type'];
+            const target = t ? types.get(t) : undefined;
+            if (target && target.id !== cls.id) kit.emit(cls.id, target.id, 'injects', 'di-binding');
+        }
+    }
+}
+
+export const aspnetcoreProvider: ConventionProvider = {
+    id: 'aspnetcore',
+    detect: (probe) => dotnetRoots(probe, /Sdk\s*=\s*"Microsoft\.NET\.Sdk\.Web"|Include\s*=\s*"Microsoft\.AspNetCore\./),
+    build: (input) => {
+        const kit = makeKit(input);
+        const types = uniqueTypes(kit);
+        attributeRoutes(kit);
+        minimalApi(kit, types);
+        entities(kit, types);
+        views(kit);
+        injection(kit, types);
+        return kit.result();
+    },
+    roleOf: (p) => (p.endsWith('.cshtml') ? 'view' : path.posix.basename(p) === 'Program.cs' ? 'entry' : undefined),
+};