@event4u/agent-config 17.2.1 → 17.3.0

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

@@ -0,0 +1,62 @@
+/**
+ * SQLAlchemy (and Flask-SQLAlchemy, SQLModel): a declarative class with
+ * `__tablename__ = "x"` --persists--> `table:x`; a SQLModel class declared with
+ * `table=True` and no `__tablename__` gets SQLModel's default, its lowercased
+ * class name. `relationship("Other")` / `relationship(Other)` inside a mapped
+ * class --relates--> the mapped class named: a string resolves to the one mapped
+ * class of that name in the project, a bare name the way the file imports it.
+ *
+ * Not drawn: imperative `Table("x", metadata, ...)` mappings, Flask-SQLAlchemy's
+ * implicit table names (a `db.Model` without `__tablename__`), a
+ * `relationship(lambda: X)` or a target named only in a `Mapped[...]` annotation,
+ * and SQLModel's `Relationship(...)`.
+ */
+import type { CodeNode } from '../types.js';
+import { pythonRoots } from './shared/detect.js';
+import { lineIndex, makeKit } from './shared/kit.js';
+import { balanced, spanText, splitArgs, stringLiteral } from './shared/python.js';
+import type { ConventionProvider } from './types.js';
+
+export const sqlalchemyProvider: ConventionProvider = {
+    id: 'sqlalchemy',
+    detect: (probe) => pythonRoots(probe, ['sqlalchemy', 'flask-sqlalchemy', 'sqlmodel']),
+    build: (input) => {
+        const kit = makeKit(input);
+        const mapped = new Map<string, { node: CodeNode; source: string }>();
+        for (const f of kit.filesWithExt('.py')) {
+            const at = lineIndex(f.source);
+            for (const m of f.source.matchAll(/^[ \t]+__tablename__\s*(?::[^=\n]+)?=\s*(['"])(\w+)\1/gm)) {
+                const cls = kit.classAt(f.path, at(m.index as number));
+                if (!cls || mapped.has(cls.id)) continue;
+                mapped.set(cls.id, { node: cls, source: f.source });
+                kit.emit(cls.id, kit.table(m[2] as string, f.path, cls.source_location[0] as number), 'persists', 'schema-call');
+            }
+            for (const n of kit.nodesInFile(f.path)) {
+                if (n.kind !== 'class' || mapped.has(n.id)) continue;
+                const head = /^\s*class\s+\w+\s*\(([^)]*)\)/.exec(spanText(f.source, n))?.[1] ?? '';
+                if (!/\btable\s*=\s*True\b/.test(head)) continue;
+                mapped.set(n.id, { node: n, source: f.source });
+                kit.emit(n.id, kit.table(n.label.toLowerCase(), f.path, n.source_location[0] as number), 'persists', 'schema-call');
+            }
+        }
+        const byLabel = (label: string): string | null => {
+            const hits = [...mapped.values()].filter((x) => x.node.label === label);
+            return hits.length === 1 ? (hits[0]?.node.id ?? null) : null;
+        };
+        for (const { node, source } of mapped.values()) {
+            const region = spanText(source, node);
+            for (const r of region.matchAll(/\brelationship\s*\(/g)) {
+                const first = splitArgs(balanced(region, (r.index as number) + r[0].length - 1))[0] ?? '';
+                const lit = stringLiteral(first);
+                let target: string | null = null;
+                if (lit !== null) target = byLabel(lit.slice(lit.lastIndexOf('.') + 1));
+                else if (/^\w+$/.test(first)) {
+                    const resolved = kit.resolveName(node.source_file, first);
+                    target = resolved && mapped.has(resolved) ? resolved : null;
+                }
+                if (target && target !== node.id) kit.emit(node.id, target, 'relates', 'orm-relation');
+            }
+        }
+        return kit.result();
+    },
+};

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

@@ -0,0 +1,59 @@
+/**
+ * SvelteKit file routing under `src/routes/` of a package root:
+ *
+ *   +page.svelte · +page.ts     PAGE /a/[slug]           --routes-to--> that module
+ *   +server.ts                  GET /api/x · POST …      --routes-to--> the exported verb function
+ *   +layout.svelte              --includes-->             every +page.svelte below its directory
+ *
+ * Route groups drop out of the path; route ids match the default pass's, so a
+ * page drawn here replaces the generic one. `+page.server.ts` load functions,
+ * `+layout@group` resets and a custom `kit.files.routes` directory are not
+ * followed; the default pass still adds its generic `ROUTE` node for a
+ * `+server.ts`.
+ */
+import * as path from 'node:path';
+
+import { npmRoots } from './shared/detect.js';
+import { cleanRoute, exportedVerbRoutes, underRoot } from './shared/js.js';
+import { makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const PAGE = /^\+page\.(svelte|ts|js)$/;
+const SERVER = /^\+server\.(ts|js)$/;
+const LAYOUT = /^\+layout\.svelte$/;
+
+export const sveltekitProvider: ConventionProvider = {
+    id: 'sveltekit',
+    detect: (probe) => npmRoots(probe, ['@sveltejs/kit']),
+    build: (input) => {
+        const kit = makeKit(input);
+        const pages: string[] = [];
+        const layouts: string[] = [];
+        for (const p of kit.paths) {
+            const at = underRoot(kit.roots, p);
+            if (!at) continue;
+            const segs = at.rel.split('/');
+            if (segs[0] !== 'src' || segs[1] !== 'routes') continue;
+            const base = segs[segs.length - 1] as string;
+            const route = cleanRoute(segs.slice(2, -1));
+            if (PAGE.test(base)) {
+                kit.fileNode(p);
+                kit.emit(kit.route(p, 'PAGE', route, 1), p, 'routes-to', 'route-table');
+                if (base.endsWith('.svelte')) pages.push(p);
+            } else if (SERVER.test(base)) {
+                if (kit.fileIds.has(p)) exportedVerbRoutes(kit, p, route);
+            } else if (LAYOUT.test(base)) {
+                layouts.push(p);
+            }
+        }
+        for (const layout of layouts) {
+            const dir = `${path.posix.dirname(layout)}/`;
+            for (const page of pages) {
+                if (!page.startsWith(dir)) continue;
+                kit.fileNode(layout);
+                kit.emit(layout, page, 'includes', 'directive-scan');
+            }
+        }
+        return kit.result();
+    },
+};

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

@@ -0,0 +1,142 @@
+/**
+ * Symfony: the links a Symfony application makes by attribute or convention.
+ *
+ *   #[Route('/x', methods: ['GET'])] · @Route("/x")   route --routes-to--> the method below it,
+ *                                                       under the class-level `#[Route('/prefix')]`
+ *   $this->render('a/b.html.twig')                     method --renders--> templates/a/b.html.twig
+ *   #[ORM\Entity] (+ #[ORM\Table(name: 't')])          entity --persists--> table:t (default: snake_case short name)
+ *   #[ORM\ManyToOne(targetEntity: X::class)] …          entity --relates--> X (else the property's type)
+ *   migrations/*.php  $this->addSql('CREATE TABLE t')   migration --migrates--> table:t
+ *   __construct(private Mailer $m)                     class --injects--> Mailer (an in-repo class only)
+ *
+ * Class references resolve through the file's `use` aliases and the PSR-4
+ * map, so a same-named class in another namespace is never the target. A route
+ * with several `methods` is declared once, under the first. Twig's own
+ * `{% include %}` / `{% extends %}` are not followed: a provider reads only
+ * code files, and `.twig` is not one.
+ */
+import * as path from 'node:path';
+
+import type { FileRole } from '../map_model.js';
+import { composerRoots } from './shared/detect.js';
+import { annotationRoutes, tableMapping, templateRoots } from './shared/extractors.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import { classNode, matchingClose, phpScope, qualify } from './shared/php.js';
+import type { ConventionProvider } from './types.js';
+import type { ResolutionConfig } from '../resolution_tiers.js';
+
+/** Arguments of an attribute or annotation, one level of nested brackets deep. */
+const ARGS = String.raw`(?<args>(?:[^()\[\]{}]|\[[^\]]*\]|\{[^}]*\})*)`;
+/** The next declaration after the match is a method, not a class (`Post::class` is no declaration). */
+const BEFORE = (decl: string): string =>
+    String.raw`(?=(?:(?!(?<!::)\bclass\s+[A-Za-z_]|\bfunction\b)[\s\S]){0,800}${decl})`;
+const ROUTE_HEAD = String.raw`(?:#\[|@)Route\(\s*(?:path\s*[:=]\s*)?(['"])(?<path>[^'"]*)\1${ARGS}\)`;
+const METHOD_ROUTE = new RegExp(ROUTE_HEAD + BEFORE(String.raw`\bfunction\b`), 'g');
+const CLASS_ROUTE = new RegExp(ROUTE_HEAD + BEFORE(String.raw`(?<!::)\bclass\s+[A-Za-z_]`), 'g');
+
+const RELATION = /(?:#\[|@)ORM\\(?:ManyToOne|OneToMany|ManyToMany|OneToOne)\b(?<args>\((?:[^()]|\([^()]*\))*\))?/g;
+const TARGET_ENTITY = /targetEntity\s*[:=]\s*(?:(?<cls>[\\\w]+)::class|(['"])(?<str>[\\\w]+)\2)/;
+const PROPERTY = /(?:public|protected|private|var)\s+(?:readonly\s+)?(?:(?<type>\??[\\\w]+)\s+)?\$\w+/;
+
+const snake = (name: string): string => name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+function verbOf(m: RegExpMatchArray): string {
+    const args = m.groups?.['args'] ?? '';
+    return /methods\s*[:=]\s*[[{]\s*['"](\w+)['"]/.exec(args)?.[1] ?? 'ANY';
+}
+
+function relations(kit: Kit, resolution: ResolutionConfig): void {
+    for (const f of kit.filesWithExt('.php')) {
+        const at = lineIndex(f.source);
+        const scope = phpScope(f.source);
+        for (const m of f.source.matchAll(RELATION)) {
+            const line = at(m.index as number);
+            const cls = kit.classAt(f.path, line);
+            if (!cls) continue;
+            const t = TARGET_ENTITY.exec(m.groups?.['args'] ?? '');
+            let fq: string | null = null;
+            if (t?.groups?.['cls']) fq = qualify(t.groups['cls'], scope);
+            else if (t?.groups?.['str']) {
+                const s = t.groups['str'];
+                fq = s.includes('\\') ? s.replace(/^\\/, '') : qualify(s, { namespace: scope.namespace, uses: new Map() });
+            } else {
+                const type = PROPERTY.exec(f.source.slice((m.index as number) + m[0].length))?.groups?.['type'];
+                if (type) fq = qualify(type.replace(/^\?/, ''), scope);
+            }
+            const target = fq ? classNode(kit, fq, resolution) : null;
+            if (target && target !== cls.id) kit.emit(cls.id, target, 'relates', 'orm-relation');
+        }
+    }
+}
+
+/** Top-level comma split of a parameter list. */
+function params(list: string): string[] {
+    const out: string[] = [];
+    let depth = 0;
+    let cur = '';
+    for (const ch of list) {
+        if (ch === '(' || ch === '[' || ch === '{') depth += 1;
+        else if (ch === ')' || ch === ']' || ch === '}') depth -= 1;
+        if (ch === ',' && depth === 0) {
+            out.push(cur);
+            cur = '';
+        } else cur += ch;
+    }
+    out.push(cur);
+    return out;
+}
+
+function injections(kit: Kit, resolution: ResolutionConfig): void {
+    for (const f of kit.filesWithExt('.php')) {
+        const at = lineIndex(f.source);
+        const scope = phpScope(f.source);
+        for (const m of f.source.matchAll(/\bfunction\s+__construct\s*\(/g)) {
+            const open = (m.index as number) + m[0].length - 1;
+            const cls = kit.classAt(f.path, at(m.index as number));
+            if (!cls) continue;
+            for (const p of params(f.source.slice(open + 1, matchingClose(f.source, open)))) {
+                const type = /^\s*(?:#\[[^\]]*\]\s*)*(?:(?:public|protected|private|readonly)\s+)*(?<type>\??[\\\w|]+)\s+&?(?:\.\.\.)?\$\w+/.exec(p)?.groups?.['type'];
+                for (const ref of (type ?? '').replace(/^\?/, '').split('|').filter(Boolean)) {
+                    const target = classNode(kit, qualify(ref, scope), resolution);
+                    if (target && target !== cls.id) kit.emit(cls.id, target, 'injects', 'di-binding');
+                }
+            }
+        }
+    }
+}
+
+function symfonyRole(p: string): FileRole | undefined {
+    if (p.startsWith('templates/')) return 'view';
+    if (p === 'public/index.php' || p === 'bin/console') return 'entry';
+    if (p.startsWith('migrations/')) return 'migration';
+    return undefined;
+}
+
+export const symfonyProvider: ConventionProvider = {
+    id: 'symfony',
+    detect: (probe) => composerRoots(probe, ['symfony/framework-bundle', 'symfony/symfony']),
+    build: (input) => {
+        const kit = makeKit(input);
+        annotationRoutes(kit, { exts: ['.php'], route: METHOD_ROUTE, verb: verbOf, prefix: CLASS_ROUTE, prefixReach: 12 });
+        templateRoots(kit, {
+            exts: ['.php'],
+            call: /\$this->render(?:View|Block)?\(\s*(['"])(?<name>[\w./@-]+)\1/g,
+            roots: ['templates'],
+            extensions: ['.html.twig', '.twig'],
+        });
+        tableMapping(kit, {
+            exts: ['.php'],
+            entity: /(?:#\[|@)ORM\\Entity\b/g,
+            tableName: /(?:#\[|@)ORM\\Table\(\s*(?:name\s*[:=]\s*)?(['"])(?<name>\w+)\1/,
+            convention: snake,
+            migration: {
+                files: (p) => /(?:^|\/)migrations\/[^/]+\.php$/.test(p),
+                create: /addSql\(\s*(['"])\s*(?:CREATE|ALTER)\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"]?(?<name>\w+)/gi,
+            },
+        });
+        relations(kit, input.resolution);
+        injections(kit, input.resolution);
+        return kit.result();
+    },
+    roleOf: (p) => symfonyRole(path.posix.normalize(p)),
+};

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

@@ -0,0 +1,58 @@
+/**
+ * TypeORM, in files that import from `typeorm` (MikroORM shares `@Entity`):
+ *
+ *   @Entity('t') · @Entity({ name: 't' }) · @Entity()   class --persists--> table:t
+ *                                                       (bare: snake_case of the class, TypeORM's default naming)
+ *   @ManyToOne(() => X) · @OneToMany(() => X, …)        class --relates-->  X
+ *   queryRunner.createTable(new Table({ name: 't' }))   migration --migrates--> table:t
+ *
+ * A custom naming strategy, `@ViewEntity`, string-named relation targets and
+ * `EntitySchema` definitions are not followed.
+ */
+import { npmRoots } from './shared/detect.js';
+import { scopeKit } from './shared/js.js';
+import { lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const EXTS = ['.ts', '.js'];
+
+/** TypeORM's DefaultNamingStrategy table name: `UserProfile` → `user_profile`, `HTTPLog` → `http_log`. */
+export function typeormTableName(className: string): string {
+    return className
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .toLowerCase();
+}
+
+export const typeormProvider: ConventionProvider = {
+    id: 'typeorm',
+    detect: (probe) => npmRoots(probe, ['typeorm']),
+    build: (input) => {
+        const kit = scopeKit(makeKit(input), (src) => /\bfrom\s+['"]typeorm['"]|require\(\s*['"]typeorm['"]\s*\)/.test(src));
+        for (const f of kit.filesWithExt(...EXTS)) {
+            const at = lineIndex(f.source);
+            for (const m of f.source.matchAll(/@Entity\(\s*(?:(['"`])(?<name>[^'"`]+)\1|\{(?<opts>[^}]*)\})?/g)) {
+                const cls = kit.nextSymbol(f.path, at(m.index as number), ['class']);
+                if (!cls || cls.kind !== 'class') continue;
+                const fromOpts = /\bname\s*:\s*(['"`])([^'"`]+)\1/.exec(m.groups?.['opts'] ?? '')?.[2];
+                const name = m.groups?.['name'] ?? fromOpts ?? typeormTableName(cls.label);
+                kit.emit(cls.id, kit.table(name, f.path, cls.source_location[0] as number), 'persists', 'schema-call');
+            }
+            const relation = /@(?:ManyToOne|OneToMany|OneToOne|ManyToMany)\(\s*(?:\(\s*\w*\s*\)|\w+)\s*=>\s*([A-Za-z_$][\w$]*)/g;
+            for (const m of f.source.matchAll(relation)) {
+                const owner = kit.classAt(f.path, at(m.index as number));
+                const target = kit.resolveName(f.path, m[1] as string);
+                if (!owner || !target || target === owner.id || kit.nodeById.get(target)?.kind !== 'class') continue;
+                kit.emit(owner.id, target, 'relates', 'orm-relation');
+            }
+            const create = /new\s+Table\(\s*\{\s*name\s*:\s*(['"`])(?<name>[^'"`]+)\1|CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(?<raw>\w+)/gi;
+            if (/\bMigrationInterface\b/.test(f.source)) {
+                for (const m of f.source.matchAll(create)) {
+                    const name = m.groups?.['name'] ?? m.groups?.['raw'];
+                    if (name) kit.emit(f.path, kit.table(name, f.path, at(m.index as number)), 'migrates', 'schema-call');
+                }
+            }
+        }
+        return kit.result();
+    },
+};

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

@@ -0,0 +1,56 @@
+/**
+ * The provider seam (ADR-298): everything a framework links by convention
+ * reaches the graph through a registered provider, never through a call the
+ * build hard-wires. The core imports providers only through `./index.ts`.
+ */
+import type { SourceFile } from '../build.js';
+import type { FileRole } from '../map_model.js';
+import type { ResolutionConfig } from '../resolution_tiers.js';
+import type { CodeEdge, CodeNode } from '../types.js';
+
+/**
+ * What a provider may read to decide whether it applies: manifests and marker
+ * files, never file suffixes — `.php` does not mean any one framework.
+ */
+export interface ProjectProbe {
+    /** Manifest files by repo-relative POSIX path → text. */
+    manifests: ReadonlyMap<string, string>;
+    /** Repo-relative paths of marker files that carry no text worth reading (an entry script). */
+    markers: ReadonlySet<string>;
+    /** Every project path, sorted, code or not (templates, assets); empty when unknown. */
+    paths: readonly string[];
+}
+
+export const EMPTY_PROBE: ProjectProbe = { manifests: new Map(), markers: new Set(), paths: [] };
+
+export interface ProviderInput {
+    files: readonly SourceFile[];
+    baseNodes: readonly CodeNode[];
+    /** The graph's edges so far, read-only (import bindings, for resolving a handler name). */
+    baseEdges: readonly CodeEdge[];
+    /** Every project path under the provider's roots, code or not (templates). */
+    paths: readonly string[];
+    /** The manifests under the provider's roots, by repo-relative path → text. */
+    manifests: ReadonlyMap<string, string>;
+    resolution: ResolutionConfig;
+    /** Package roots the provider was detected in; `''` is the repository root. */
+    roots: readonly string[];
+}
+
+export interface ProviderResult {
+    nodes: CodeNode[];
+    edges: CodeEdge[];
+    /** Base edges the provider proves false; applied only when it drew something. */
+    contest?: (e: CodeEdge) => boolean;
+}
+
+export interface ConventionProvider {
+    id: string;
+    /** Basenames of marker files whose presence the probe should record (an entry script). */
+    markers?: readonly string[];
+    /** Package roots this provider applies to; empty when it does not. */
+    detect(probe: ProjectProbe): string[];
+    build(input: ProviderInput): ProviderResult;
+    /** A role the map gives a file by this provider's conventions. */
+    roleOf?(path: string): FileRole | undefined;
+}

package/src/scripts/code_graph/providers/vue-router.ts

@@ -0,0 +1,21 @@
+/**
+ * Vue Router: route objects `{ path: '/x', component: X }` or
+ * `component: () => import('./views/X.vue')` → PAGE /x --routes-to--> the
+ * component the file names or the single-file component it imports. Child
+ * paths are not joined to their parent's; `components: { default: … }` named
+ * views and alias specifiers (`@/views/X.vue`) are not followed.
+ */
+import { npmRoots } from './shared/detect.js';
+import { routeObjects } from './shared/js.js';
+import { makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+export const vueRouterProvider: ConventionProvider = {
+    id: 'vue-router',
+    detect: (probe) => npmRoots(probe, ['vue-router']),
+    build: (input) => {
+        const kit = makeKit(input);
+        routeObjects(kit, { exts: ['.ts', '.js', '.mjs'], componentKeys: ['component'] });
+        return kit.result();
+    },
+};

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

@@ -0,0 +1,128 @@
+/**
+ * WordPress: hooks and theme parts, which no import or call states.
+ *
+ *   add_action('init', 'cb') · add_filter(…)       route `HOOK init` --routes-to--> the callback
+ *   add_shortcode('card', 'cb')                    route `SHORTCODE card` --routes-to--> the callback
+ *   get_template_part('parts/card'[, 'wide'])       caller --renders--> parts/card(-wide).php
+ *
+ * A hook name is no URL, so its route path is the name as written, without the
+ * leading slash an HTTP route carries. A callback resolves as a function of the
+ * same file, else the one function of that name in the tree; `[$this, 'm']`
+ * resolves to the enclosing class's method, `[X::class, 'm']` to X's method
+ * only when X is the class the file's namespace names. A closure, a dynamic
+ * hook name or an ambiguous function gets no edge. `do_action` fires a hook and
+ * declares nothing.
+ *
+ * Detection: a `wp-config.php` marker, a composer manifest requiring a
+ * WordPress core package or a wpackagist plugin/theme, or a composer manifest
+ * whose `type` is a WordPress plugin, theme or must-use plugin. A plugin or theme
+ * shipping no composer manifest carries no signal and stays undetected.
+ */
+import * as path from 'node:path';
+
+import type { CodeNode } from '../types.js';
+import { markerRoots, union } from './shared/detect.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import { classNode, phpScope, qualify, shortName } from './shared/php.js';
+import type { ConventionProvider, ProjectProbe } from './types.js';
+import type { ResolutionConfig } from '../resolution_tiers.js';
+
+const CORE = /^(?:johnpbloch\/wordpress(?:-core)?|roots\/wordpress(?:-no-content)?|roots\/bedrock|wpackagist-(?:plugin|theme)\/.+)$/;
+const TYPES = new Set(['wordpress-plugin', 'wordpress-theme', 'wordpress-muplugin']);
+
+function detectWordpress(probe: ProjectProbe): string[] {
+    const roots: string[] = [];
+    for (const [p, text] of probe.manifests) {
+        if (path.posix.basename(p) !== 'composer.json') continue;
+        try {
+            const j = JSON.parse(text) as { name?: string; type?: string; require?: Record<string, string>; 'require-dev'?: Record<string, string> };
+            const deps = [...Object.keys(j.require ?? {}), ...Object.keys(j['require-dev'] ?? {})];
+            if (TYPES.has(j.type ?? '') || j.name === 'roots/bedrock' || deps.some((d) => CORE.test(d))) {
+                const d = path.posix.dirname(p);
+                roots.push(d === '.' ? '' : d);
+            }
+        } catch {
+            continue;
+        }
+    }
+    return union(roots, markerRoots(probe, 'wp-config.php'));
+}
+
+const REGISTRATION = /\b(?<fn>add_action|add_filter|add_shortcode)\(\s*(['"])(?<name>[\w\-/.:]+)\2\s*,\s*/g;
+
+function callback(kit: Kit, file: string, src: string, at: number, line: number, functions: Map<string, CodeNode[]>, resolution: ResolutionConfig): string | null {
+    const rest = src.slice(at, at + 300);
+    const fn = /^(['"])\\?(?:[\w\\]+\\)?(?<name>\w+)\1/.exec(rest)?.groups?.['name'];
+    if (fn) {
+        const local = (functions.get(fn) ?? []).filter((n) => n.source_file === file);
+        if (local.length === 1) return (local[0] as CodeNode).id;
+        const all = functions.get(fn) ?? [];
+        return all.length === 1 ? (all[0] as CodeNode).id : null;
+    }
+    const pair = /^(?:\[|array\()\s*(?<recv>\$this|self::class|static::class|__CLASS__|[\\\w]+::class|(['"])[\\\w]+\2)\s*,\s*(['"])(?<member>\w+)\3/.exec(rest);
+    if (!pair?.groups) return null;
+    const recv = pair.groups['recv'] as string;
+    const member = pair.groups['member'] as string;
+    let cls: string | null = null;
+    if (/^(?:\$this|self::class|static::class|__CLASS__)$/.test(recv)) cls = kit.classAt(file, line)?.id ?? null;
+    else {
+        const ref = recv.replace(/::class$/, '').replace(/^['"]|['"]$/g, '');
+        const fq = /^['"]/.test(recv) ? ref.replace(/^\\/, '') : qualify(ref, phpScope(src));
+        cls = classNode(kit, fq, resolution) ?? classByNamespace(kit, fq);
+    }
+    return cls ? kit.methodOf(cls, member) : null;
+}
+
+/** The one class node whose short name and declaring file's namespace spell `fq`. */
+function classByNamespace(kit: Kit, fq: string): string | null {
+    const short = shortName(fq);
+    const hits = kit.nodesNamed(short).filter((n) => {
+        if (n.kind !== 'class') return false;
+        const f = kit.files.find((x) => x.path === n.source_file);
+        const ns = f ? phpScope(f.source).namespace : '';
+        return (ns ? `${ns}\\${short}` : short) === fq;
+    });
+    return hits.length === 1 ? (hits[0] as CodeNode).id : null;
+}
+
+/** `slug[-name].php`, preferring a part under a directory that holds the calling file (its theme). */
+function templatePart(kit: Kit, caller: string, slug: string, name: string | undefined): string | null {
+    for (const rel of name ? [`${slug}-${name}.php`, `${slug}.php`] : [`${slug}.php`]) {
+        const hits = kit.paths.filter((p) => p === rel || p.endsWith(`/${rel}`));
+        const own = hits.filter((p) => caller.startsWith(p.slice(0, p.length - rel.length)));
+        if (own.length === 1) return own[0] as string;
+        if (own.length === 0 && hits.length === 1) return hits[0] as string;
+    }
+    return null;
+}
+
+export const wordpressProvider: ConventionProvider = {
+    id: 'wordpress',
+    markers: ['wp-config.php'],
+    detect: detectWordpress,
+    build: (input) => {
+        const kit = makeKit(input);
+        const functions = new Map<string, CodeNode[]>();
+        for (const n of input.baseNodes) {
+            if (n.kind !== 'function' || !n.source_file.endsWith('.php')) continue;
+            functions.set(n.label, [...(functions.get(n.label) ?? []), n]);
+        }
+        for (const f of kit.filesWithExt('.php')) {
+            const at = lineIndex(f.source);
+            for (const m of f.source.matchAll(REGISTRATION)) {
+                const line = at(m.index as number);
+                const verb = m.groups?.['fn'] === 'add_shortcode' ? 'SHORTCODE' : 'HOOK';
+                const id = kit.route(f.path, verb, m.groups?.['name'] as string, line);
+                const target = callback(kit, f.path, f.source, (m.index as number) + m[0].length, line, functions, input.resolution);
+                if (target) kit.emit(id, target, 'routes-to', 'route-table');
+            }
+            for (const m of f.source.matchAll(/\bget_template_part\(\s*(['"])(?<slug>[\w\-/]+)\1\s*(?:,\s*(['"])(?<name>[\w-]+)\3)?/g)) {
+                const target = templatePart(kit, f.path, m.groups?.['slug'] as string, m.groups?.['name']);
+                if (!target) continue;
+                kit.fileNode(target);
+                kit.emit(kit.enclosing(f.path, at(m.index as number)), target, 'renders', 'directive-scan');
+            }
+        }
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/refresh_cli.ts

@@ -0,0 +1,81 @@
+/**
+ * Which `agent-config` a background refresh may start — shared by the
+ * `code-graph-refresh` session concern and `code-graph auto-refresh on`, so the
+ * opt-in can say at once when nothing usable is installed.
+ *
+ * The executable is never taken from the repository (its root, its
+ * `node_modules/.bin`, a relative PATH entry): the same trust rule the host hook
+ * shim applies before it runs the dispatcher. And it must be able to do the job:
+ * a global install older than the single-flight refresh ignores the flags it
+ * does not know and would build unlocked with an old extractor.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** A file only a package that implements `refresh --single-flight` ships (the published tarball carries `src/scripts/`). */
+const CAPABILITY_FILE = 'src/scripts/code_graph/refresh_lock.ts';
+
+/**
+ * The first `agent-config` on PATH whose real location lies outside `root`.
+ * Relative PATH entries are skipped: they resolve against the repository.
+ */
+export function resolveCli(root: string, envPath: string = process.env['PATH'] ?? ''): string | null {
+    let realRoot: string;
+    try {
+        realRoot = fs.realpathSync(root);
+    } catch {
+        return null;
+    }
+    const inside = (p: string): boolean => {
+        const rel = path.relative(realRoot, p);
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    };
+    for (const dir of envPath.split(path.delimiter)) {
+        if (!path.isAbsolute(dir)) continue;
+        const candidate = path.join(dir, 'agent-config');
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            const real = fs.realpathSync(candidate);
+            if (fs.statSync(real).isFile() && !inside(real) && !inside(path.resolve(dir))) return candidate;
+        } catch {
+            /* not here */
+        }
+    }
+    return null;
+}
+
+/** The installed package a CLI belongs to: the nearest `package.json` above its real path naming this package. */
+export function cliPackage(cli: string): { root: string; version: string } | null {
+    try {
+        for (let dir = path.dirname(fs.realpathSync(cli)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+            const file = path.join(dir, 'package.json');
+            if (!fs.existsSync(file)) continue;
+            const pkg = JSON.parse(fs.readFileSync(file, 'utf-8')) as { name?: string; version?: string };
+            if (pkg.name === '@event4u/agent-config') return { root: dir, version: pkg.version ?? '?' };
+        }
+    } catch {
+        /* unreadable — no package */
+    }
+    return null;
+}
+
+/**
+ * Whether the package a CLI belongs to implements the single-flight refresh.
+ * An installed CLI is `<package>/dist/cli/agent-config.js`; the check is the
+ * presence of a file only such a package ships, so nothing is executed.
+ */
+export function cliIsCapable(cli: string): boolean {
+    // The same package root the version report uses, so a symlinked or hoisted
+    // layout cannot make one call see a package the other does not.
+    const pkg = cliPackage(cli);
+    return pkg !== null && fs.existsSync(path.join(pkg.root, CAPABILITY_FILE));
+}
+
+export type CliVerdict = { cli: string } | { reason: 'no-cli' } | { reason: 'cli-too-old'; cli: string };
+
+/** A trusted `agent-config` that implements the single-flight refresh, or why there is none. */
+export function usableCli(root: string, envPath?: string): CliVerdict {
+    const cli = resolveCli(root, envPath);
+    if (cli === null) return { reason: 'no-cli' };
+    return cliIsCapable(cli) ? { cli } : { reason: 'cli-too-old', cli };
+}