@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/conventions_default.ts

@@ -0,0 +1,247 @@
+/**
+ * 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';
+
+/** A line that is a log, print or throw call up to this point: its literals are messages, not files. */
+const MESSAGE_CALL =
+    /(?:\bconsole\.\w+|\blog(?:ger|ging)?\.\w+|\bLog::\w+|\b(?:print|println|printf|echo|error_log)\b|\bthrow\s+new\s+\w+)\s*\(?/;
+
+/** `src` with comments and Python docstrings blanked to spaces, every offset and newline kept. */
+function maskComments(src: string, lang: string | undefined): string {
+    const blank = (m: string): string => m.replace(/[^\n]/g, ' ');
+    let out = src
+        .replace(/\/\*[\s\S]*?\*\//g, blank)
+        .replace(/(^|[^:'"\\])(\/\/[^\n]*)/g, (_m, pre: string, c: string) => pre + blank(c));
+    if (lang === 'python' || lang === 'php') out = out.replace(/(^|[ \t])(#[^\n]*)/gm, (_m, pre: string, c: string) => pre + blank(c));
+    if (lang === 'python') out = out.replace(/("""|''')[\s\S]*?\1/g, blank);
+    return out;
+}
+
+/** 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.
+            // Comments and docstrings are blanked first, so a path they mention is never read.
+            const code = maskComments(f.source, lang);
+            for (const m of code.matchAll(/(['"])([^'"`\s\\${}()<>|,;]{3,200})\1/g)) {
+                const lit = m[2] as string;
+                const lineStart = code.lastIndexOf('\n', m.index as number) + 1;
+                if (MESSAGE_CALL.test(code.slice(lineStart, m.index as number))) continue;
+                // 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/detect.ts

@@ -19,6 +19,7 @@ import * as path from 'node:path';
 
 import { load_agent_settings } from '../_lib/agent_settings.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { projectHome } from './graph_home.js';
 import { EXT_LANG } from './types.js';
 import { validateGraph } from './validate.js';
 
@@ -226,9 +227,6 @@ export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
     };
 }
 
-/** Cache path a repository root's native graph lives at, repo-relative. */
-export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
-
 /**
  * The four-state staleness token every consumer of the graph reports.
  *
@@ -328,10 +326,12 @@ function hasUncommittedIndexedEdit(root: string): boolean {
  * report `absent` while answering from that very file — the state of a cache
  * nobody asked about. Passing the graph the verb is actually reading makes the
  * printed staleness a statement about the answer rather than about a
- * convention.
+ * convention. The default is the project home only: the hooks that call this
+ * ship in the dispatch bundle, which cannot carry the user-global resolver, so
+ * a caller serving a user-global home passes `graphHome(root).cachePath`.
  */
 export function graphState(root: string, nativeCache?: string): GraphState {
-    const picked = pickSource(detectSources(root, nativeCache ?? path.join(root, NATIVE_CACHE_REL)));
+    const picked = pickSource(detectSources(root, nativeCache ?? projectHome(root).cachePath));
     if (!picked) return 'absent';
     if (picked.stale === true) {
         const behind = picked.commits_behind;

package/src/scripts/code_graph/estate_cli.ts

@@ -0,0 +1,135 @@
+/**
+ * `code-graph estate …` — questions about every registered project at once,
+ * answered from the estate index alone (ADR-299, step 5.3). No project graph
+ * is opened: an estate answer is as current as each project's last refresh,
+ * and says when it was indexed.
+ *
+ *   estate where-used <package|symbol>      who declares, imports, publishes or references it
+ *   estate projects-using <package>         projects that declare or import a package
+ *   estate advisory-impact [--package P]    advisory packages × the projects that use them
+ *
+ * `--json` prints the answer as JSON.
+ */
+import { readState } from '../_lib/advisory_notice.js';
+import { type EstateReader, openEstate } from './estate_index.js';
+
+const NO_INDEX =
+    'no estate index — switch it on with `code-graph projects index on`, then build or refresh each project once';
+
+export interface WhereUsed {
+    name: string;
+    package_users: ReturnType<EstateReader['projectsUsing']>;
+    publishers: ReturnType<EstateReader['publishers']>;
+    declared_by: ReturnType<EstateReader['exporters']>;
+    referenced_by: ReturnType<EstateReader['referrers']>;
+}
+
+export interface AdvisoryImpact {
+    package: string;
+    advisories: string[];
+    projects: ReturnType<EstateReader['projectsUsing']>;
+}
+
+export function whereUsed(db: EstateReader, name: string): WhereUsed {
+    return {
+        name,
+        package_users: db.projectsUsing(name),
+        publishers: db.publishers(name),
+        declared_by: db.exporters(name),
+        referenced_by: db.referrers(name),
+    };
+}
+
+/**
+ * Advisory packages from each indexed project's own advisory cache (or the one
+ * `--package` names), joined with the index. A project that imports the
+ * package in code is the one an advisory reaches first; `imports` says so.
+ */
+export function advisoryImpact(db: EstateReader, only: string | null): AdvisoryImpact[] {
+    const ids = new Map<string, Set<string>>();
+    if (only !== null) ids.set(only, new Set());
+    else {
+        for (const p of db.projects()) {
+            for (const f of readState(p.root)?.findings ?? []) {
+                if (!ids.has(f.package)) ids.set(f.package, new Set());
+                ids.get(f.package)?.add(f.id);
+            }
+        }
+    }
+    return [...ids.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([pkg, adv]) => ({ package: pkg, advisories: [...adv].sort(), projects: db.projectsUsing(pkg) }))
+        .filter((r) => only !== null || r.projects.length > 0);
+}
+
+function flagValue(argv: string[], name: string): string | null {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
+}
+
+function line(p: { id: string; root: string }, extra = ''): string {
+    return `  ${p.id}  ${p.root}${extra}\n`;
+}
+
+export function estateMain(argv: string[]): number {
+    const [verb, ...rest] = argv;
+    const json = rest.includes('--json');
+    const positional = rest.filter((a, i) => !a.startsWith('--') && rest[i - 1] !== '--package');
+    if (verb !== 'where-used' && verb !== 'projects-using' && verb !== 'advisory-impact') {
+        process.stderr.write('usage: code-graph estate where-used <name>|projects-using <package>|advisory-impact [--package P] [--json]\n');
+        return 2;
+    }
+    if (verb !== 'advisory-impact' && !positional[0]) {
+        process.stderr.write(`usage: code-graph estate ${verb} <name> [--json]\n`);
+        return 2;
+    }
+    const db = openEstate();
+    if (!db) {
+        process.stdout.write(`${NO_INDEX}\n`);
+        return 1;
+    }
+    try {
+        const name = positional[0] as string;
+        if (verb === 'projects-using') {
+            const rows = db.projectsUsing(name);
+            if (json) process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+            else {
+                process.stdout.write(`projects using ${name} (${rows.length}):\n`);
+                for (const r of rows) process.stdout.write(line(r, `${r.declared_in.length ? ` · declared in ${r.declared_in.join(', ')}` : ''}${r.imports ? ` · imported ${r.imports}×` : ''}`));
+            }
+            return 0;
+        }
+        if (verb === 'where-used') {
+            const w = whereUsed(db, name);
+            if (json) {
+                process.stdout.write(`${JSON.stringify(w, null, 2)}\n`);
+                return 0;
+            }
+            const section = (title: string, rows: Array<{ id: string; root: string }>): void => {
+                if (!rows.length) return;
+                process.stdout.write(`${title} (${rows.length}):\n`);
+                for (const r of rows) process.stdout.write(line(r));
+            };
+            section(`declare or import package ${name}`, w.package_users);
+            section(`publish package ${name}`, w.publishers);
+            section(`declare a top-level symbol ${name}`, w.declared_by);
+            section(`reference ${name} without resolving it (a guess)`, w.referenced_by);
+            if (!w.package_users.length && !w.publishers.length && !w.declared_by.length && !w.referenced_by.length) {
+                process.stdout.write(`no registered project uses ${name}\n`);
+            }
+            return 0;
+        }
+        const impact = advisoryImpact(db, flagValue(rest, '--package'));
+        if (json) process.stdout.write(`${JSON.stringify(impact, null, 2)}\n`);
+        else {
+            if (!impact.length) process.stdout.write('no advisory package is used by a registered project\n');
+            for (const r of impact) {
+                process.stdout.write(`${r.package}${r.advisories.length ? ` — ${r.advisories.join(', ')}` : ''}:\n`);
+                for (const p of r.projects) process.stdout.write(line(p, p.imports ? ` · imported ${p.imports}×` : ' · declared only'));
+            }
+        }
+        return 0;
+    } finally {
+        db.close();
+    }
+}