@event4u/agent-config 17.2.1 → 17.4.0

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

@@ -0,0 +1,204 @@
+/**
+ * Ruby on Rails: the links a Rails application makes by convention.
+ *
+ *   config/routes.rb   get '/x', to: 'users#index' · post 'x' => 'users#create'
+ *                      · root 'pages#home' · resources :users, only:/except:
+ *                      · namespace :admin do … end         route --routes-to--> the action
+ *   app/models         class User < ApplicationRecord     class --persists--> table:users
+ *                      self.table_name = "t" wins; a subclass of a model shares its table (STI)
+ *   app/models         has_many / has_one / belongs_to (class_name: wins)   class --relates--> model
+ *   db/migrate         create_table :t                    file  --migrates--> table:t
+ *   a controller action  app/views/<controller>/<action>.*   action --renders--> the view
+ *
+ * `resources` expands into the seven REST actions the controller actually
+ * defines, within `only:` / `except:`; an explicit route keeps its node when
+ * the action is missing. The table name is the class in snake_case, pluralised
+ * by the common English rules plus Rails' irregulars; an `inflections` file is
+ * not read. Not followed: `resource` (singular), nested `resources` blocks,
+ * `scope` / `constraints`, `concerns`, an explicit `render`, and a model
+ * outside `app/models`.
+ */
+import * as path from 'node:path';
+
+import type { CodeNode } from '../types.js';
+import { gemRoots } from './shared/detect.js';
+import { joinRoute } from './shared/extractors.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const REST: ReadonlyArray<[action: string, verb: string, suffix: string]> = [
+    ['index', 'GET', ''],
+    ['new', 'GET', 'new'],
+    ['create', 'POST', ''],
+    ['show', 'GET', ':id'],
+    ['edit', 'GET', ':id/edit'],
+    ['update', 'PATCH', ':id'],
+    ['destroy', 'DELETE', ':id'],
+];
+const IRREGULAR: Readonly<Record<string, string>> = { person: 'people', man: 'men', woman: 'women', child: 'children', mouse: 'mice' };
+const VERB_ROUTE = /^\s*(get|post|put|patch|delete)\s+['"]([^'"]*)['"]\s*(?:,\s*to:\s*|=>\s*)['"](\w[\w/]*)#(\w+)['"]/;
+const ROOT_ROUTE = /^\s*root\s+(?:to:\s*)?['"](\w[\w/]*)#(\w+)['"]/;
+const RESOURCES = /^\s*resources\s+:(\w+)(.*)$/;
+const NAMESPACE = /^\s*namespace\s+:(\w+)\s+do\b/;
+const OPENS_BLOCK = /\bdo(\s*\|[^|]*\|)?\s*$/;
+
+function snake(name: string): string {
+    return name.replace(/([a-z\d])([A-Z])/g, '$1_$2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').toLowerCase();
+}
+
+function pluralize(word: string): string {
+    const head = word.slice(0, word.lastIndexOf('_') + 1);
+    const last = word.slice(head.length);
+    if (IRREGULAR[last]) return head + IRREGULAR[last];
+    if (/[^aeiou]y$/.test(last)) return head + last.slice(0, -1) + 'ies';
+    if (/(s|x|z|ch|sh)$/.test(last)) return head + last + 'es';
+    return head + last + 's';
+}
+
+function singularize(word: string): string {
+    for (const [one, many] of Object.entries(IRREGULAR)) if (word === many) return one;
+    if (/ies$/.test(word)) return word.slice(0, -3) + 'y';
+    if (/(s|x|z|ch|sh)es$/.test(word)) return word.slice(0, -2);
+    return word.endsWith('s') ? word.slice(0, -1) : word;
+}
+
+function camel(snakeName: string): string {
+    return snakeName.replace(/(^|_)([a-z\d])/g, (_m, _s, c: string) => c.toUpperCase());
+}
+
+/** The action method of the controller `ctrl` (`admin/reports`) under `root`, if the controller defines it. */
+function action(kit: Kit, root: string, ctrl: string, name: string): CodeNode | null {
+    const file = path.posix.join(root, 'app/controllers', `${ctrl}_controller.rb`);
+    return kit.nodesInFile(file).find((n) => n.kind === 'method' && n.label === name) ?? null;
+}
+
+function routes(kit: Kit, root: string): void {
+    const file = path.posix.join(root, 'config/routes.rb');
+    const src = kit.files.find((f) => f.path === file)?.source;
+    if (src === undefined) return;
+    // One frame per open `do` block: a namespace adds a path and a controller
+    // directory; any other block only keeps `end` balanced.
+    const frames: Array<string | null> = [];
+    const ns = (): string[] => frames.filter((f): f is string => f !== null);
+    const declare = (verb: string, routePath: string, ctrl: string, act: string, line: number, keepWithoutAction: boolean): void => {
+        const target = action(kit, root, [...ns(), ctrl].join('/'), act);
+        if (!target && !keepWithoutAction) return;
+        const id = kit.route(file, verb, joinRoute(...ns(), routePath), line);
+        if (target) kit.emit(id, target.id, 'routes-to', 'route-table');
+    };
+    src.split('\n').forEach((raw, i) => {
+        const line = i + 1;
+        // Whole-line comments only: `#` is also the controller#action separator.
+        if (/^\s*#/.test(raw)) return;
+        const text = raw;
+        if (/^\s*end\b/.test(text)) {
+            frames.pop();
+            return;
+        }
+        let m = NAMESPACE.exec(text);
+        if (m) {
+            frames.push(m[1] as string);
+            return;
+        }
+        if ((m = ROOT_ROUTE.exec(text))) declare('GET', '/', m[1] as string, m[2] as string, line, true);
+        else if ((m = VERB_ROUTE.exec(text))) declare((m[1] as string).toUpperCase(), m[2] as string, m[3] as string, m[4] as string, line, true);
+        else if ((m = RESOURCES.exec(text))) {
+            const name = m[1] as string;
+            const opts = m[2] as string;
+            const list = (key: string): string[] | null => {
+                const hit = new RegExp(`\\b${key}:\\s*\\[([^\\]]*)\\]`).exec(opts) ?? new RegExp(`\\b${key}:\\s*:(\\w+)`).exec(opts);
+                return hit ? [...(hit[1] as string).matchAll(/:?(\w+)/g)].map((x) => x[1] as string) : null;
+            };
+            const only = list('only');
+            const except = list('except') ?? [];
+            for (const [act, verb, suffix] of REST) {
+                if ((only && !only.includes(act)) || except.includes(act)) continue;
+                declare(verb, joinRoute(name, suffix), name, act, line, false);
+            }
+        }
+        if (OPENS_BLOCK.test(text)) frames.push(null);
+    });
+}
+
+function models(kit: Kit, root: string): void {
+    const dir = path.posix.join(root, 'app/models') + '/';
+    const files = kit.filesWithExt('.rb').filter((f) => f.path.startsWith(dir));
+    const classes = files.flatMap((f) =>
+        kit.nodesInFile(f.path).filter((n): n is CodeNode => n.kind === 'class').map((node) => {
+            const head = f.source.split('\n')[(node.source_location[0] as number) - 1] ?? '';
+            const parent = /<\s*([\w:]+)/.exec(head)?.[1]?.split('::').pop() ?? '';
+            const span = f.source.split('\n').slice((node.source_location[0] as number) - 1, node.source_location[2] as number).join('\n');
+            return { node, file: f, parent, span };
+        }),
+    );
+    const byName = new Map(classes.map((c) => [c.node.label, c] as const));
+    const tableOf = new Map<string, string | null>();
+    const resolveTable = (name: string, seen: Set<string> = new Set()): string | null => {
+        if (tableOf.has(name)) return tableOf.get(name) as string | null;
+        const c = byName.get(name);
+        if (!c || seen.has(name)) return null;
+        seen.add(name);
+        const explicit = /self\.table_name\s*=\s*['"]([^'"]+)['"]/.exec(c.span)?.[1];
+        const abstract = /self\.abstract_class\s*=\s*true/.test(c.span);
+        let table: string | null = null;
+        if (explicit) table = explicit;
+        else if (abstract) table = null;
+        else if (c.parent === 'ApplicationRecord' || c.parent === 'Base') table = pluralize(snake(name));
+        else if (byName.has(c.parent)) table = resolveTable(c.parent, seen);
+        tableOf.set(name, table);
+        return table;
+    };
+    for (const c of classes) {
+        const table = resolveTable(c.node.label);
+        if (table) kit.emit(c.node.id, kit.table(table, c.file.path, c.node.source_location[0] as number), 'persists', 'schema-call');
+        for (const m of c.span.matchAll(/^\s*(has_many|has_one|belongs_to|has_and_belongs_to_many)\s+:(\w+)([^\n]*)/gm)) {
+            const named = /class_name:\s*['"]([\w:]+)['"]/.exec(m[3] as string)?.[1]?.split('::').pop();
+            const assoc = m[2] as string;
+            const target = byName.get(named ?? camel(m[1] === 'has_many' || m[1] === 'has_and_belongs_to_many' ? singularize(assoc) : assoc));
+            if (target && target.node.id !== c.node.id) kit.emit(c.node.id, target.node.id, 'relates', 'orm-relation');
+        }
+    }
+}
+
+function migrations(kit: Kit, root: string): void {
+    const dir = path.posix.join(root, 'db/migrate') + '/';
+    for (const f of kit.filesWithExt('.rb').filter((x) => x.path.startsWith(dir))) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/\bcreate_table\s+(?::(\w+)|['"]([^'"]+)['"])/g)) {
+            const table = (m[1] ?? m[2]) as string;
+            kit.emit(f.path, kit.table(table, f.path, at(m.index as number)), 'migrates', 'schema-call');
+        }
+    }
+}
+
+function views(kit: Kit, root: string): void {
+    const ctrlDir = path.posix.join(root, 'app/controllers') + '/';
+    const viewDir = path.posix.join(root, 'app/views');
+    for (const f of kit.filesWithExt('.rb').filter((x) => x.path.startsWith(ctrlDir) && x.path.endsWith('_controller.rb'))) {
+        const ctrl = f.path.slice(ctrlDir.length, -'_controller.rb'.length);
+        for (const n of kit.nodesInFile(f.path)) {
+            if (n.kind !== 'method') continue;
+            const prefix = `${viewDir}/${ctrl}/${n.label}.`;
+            const hits = kit.paths.filter((p) => p.startsWith(prefix) && !p.slice(prefix.length).includes('/'));
+            if (hits.length !== 1) continue;
+            const target = hits[0] as string;
+            kit.fileNode(target);
+            kit.emit(n.id, target, 'renders', 'directive-scan');
+        }
+    }
+}
+
+export const railsProvider: ConventionProvider = {
+    id: 'rails',
+    detect: (probe) => gemRoots(probe, 'rails'),
+    build: (input) => {
+        const kit = makeKit(input);
+        for (const root of kit.roots) {
+            routes(kit, root);
+            models(kit, root);
+            migrations(kit, root);
+            views(kit, root);
+        }
+        return kit.result();
+    },
+};

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

@@ -0,0 +1,58 @@
+/**
+ * React Router: `<Route path="/x" element={<X />} />` (or `component={X}`) and
+ * route objects `{ path: '/x', element: <X />, Component: X, lazy: () => import('./x') }`
+ * → a PAGE route --routes-to--> the component the file names or the module it
+ * imports lazily. A `<Route>` without `path` (an index or layout route) and an
+ * object without a component key are no routes. Nested `children` paths are
+ * not joined to their parent's.
+ */
+import { npmRoots } from './shared/detect.js';
+import { joinRoute } from './shared/extractors.js';
+import { componentTarget, routeObjects } from './shared/js.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const EXTS = ['.tsx', '.jsx', '.ts', '.js'];
+
+/** The attribute text of a JSX tag opened at `from`, up to its `>` outside braces. */
+function attributes(src: string, from: number): string {
+    let depth = 0;
+    for (let i = from; i < src.length && i < from + 2000; i++) {
+        const c = src[i];
+        if (c === '{') depth += 1;
+        else if (c === '}') depth -= 1;
+        else if (c === '>' && depth === 0) return src.slice(from, i);
+    }
+    return '';
+}
+
+function jsxRoutes(kit: Kit): number {
+    let count = 0;
+    for (const f of kit.filesWithExt('.tsx', '.jsx', '.js')) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/<Route\b/g)) {
+            const attrs = attributes(f.source, (m.index as number) + m[0].length);
+            const p = /\bpath\s*=\s*\{?\s*(['"`])([^'"`$]*)\1/.exec(attrs);
+            if (!p) continue;
+            const id = kit.route(f.path, 'PAGE', joinRoute(p[2]), at(m.index as number));
+            const el = /\belement\s*=\s*\{\s*(<\s*[A-Z][\w$]*)/.exec(attrs);
+            const comp = /\b(?:component|Component)\s*=\s*\{\s*([A-Za-z_$][\w$]*)\s*\}/.exec(attrs);
+            const value = el?.[1] ?? comp?.[1];
+            const target = value ? componentTarget(kit, f.path, value) : null;
+            if (target) kit.emit(id, target, 'routes-to', 'route-table');
+            count += 1;
+        }
+    }
+    return count;
+}
+
+export const reactRouterProvider: ConventionProvider = {
+    id: 'react-router',
+    detect: (probe) => npmRoots(probe, ['react-router', 'react-router-dom']),
+    build: (input) => {
+        const kit = makeKit(input);
+        jsxRoutes(kit);
+        routeObjects(kit, { exts: EXTS, componentKeys: ['element', 'Component', 'lazy'] });
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/providers/shared/detect.ts

@@ -0,0 +1,78 @@
+/**
+ * Detection by manifest, per package root. Every helper returns the sorted
+ * roots (`''` for the repository root) whose manifest declares one of the
+ * named packages — never a guess from file suffixes.
+ */
+import * as path from 'node:path';
+
+import type { ProjectProbe } from '../types.js';
+
+function rootOf(p: string): string {
+    const d = path.posix.dirname(p);
+    return d === '.' ? '' : d;
+}
+
+function rootsWhere(probe: ProjectProbe, basename: RegExp, declares: (text: string) => boolean): string[] {
+    const roots = new Set<string>();
+    for (const [p, text] of probe.manifests) if (basename.test(path.posix.basename(p)) && declares(text)) roots.add(rootOf(p));
+    return [...roots].sort();
+}
+
+function jsonDeps(text: string, keys: readonly string[]): string[] {
+    try {
+        const j = JSON.parse(text) as Record<string, Record<string, string> | undefined>;
+        return keys.flatMap((k) => Object.keys(j[k] ?? {}));
+    } catch {
+        return [];
+    }
+}
+
+const matches = (names: readonly (string | RegExp)[], dep: string): boolean =>
+    names.some((n) => (typeof n === 'string' ? n === dep : n.test(dep)));
+
+/** `package.json` dependencies, devDependencies or peerDependencies. */
+export function npmRoots(probe: ProjectProbe, names: readonly (string | RegExp)[]): string[] {
+    return rootsWhere(probe, /^package\.json$/, (t) =>
+        jsonDeps(t, ['dependencies', 'devDependencies', 'peerDependencies']).some((d) => matches(names, d)),
+    );
+}
+
+/** `composer.json` require or require-dev. */
+export function composerRoots(probe: ProjectProbe, names: readonly (string | RegExp)[]): string[] {
+    return rootsWhere(probe, /^composer\.json$/, (t) => jsonDeps(t, ['require', 'require-dev']).some((d) => matches(names, d)));
+}
+
+/** `pyproject.toml` or a `requirements*.txt` naming the distribution. */
+export function pythonRoots(probe: ProjectProbe, names: readonly string[]): string[] {
+    const re = new RegExp(`(^|["'\\s\\[,])(${names.map((n) => n.replace(/[-_.]/g, '[-_.]')).join('|')})(?=[\\s"'<>=~!;\\[,]|$)`, 'im');
+    return rootsWhere(probe, /^(pyproject\.toml|requirements[\w.-]*\.txt)$/, (t) => re.test(t));
+}
+
+/** A Maven `pom.xml` or Gradle build file naming the artifact. */
+export function jvmRoots(probe: ProjectProbe, artifact: RegExp): string[] {
+    return rootsWhere(probe, /^(pom\.xml|build\.gradle(\.kts)?)$/, (t) => artifact.test(t));
+}
+
+/** A `go.mod` requiring the module. */
+export function goRoots(probe: ProjectProbe, modules: readonly string[]): string[] {
+    return rootsWhere(probe, /^go\.mod$/, (t) => modules.some((m) => t.includes(m)));
+}
+
+/** A `*.csproj` referencing the SDK or package. */
+export function dotnetRoots(probe: ProjectProbe, marker: RegExp): string[] {
+    return rootsWhere(probe, /\.csproj$/, (t) => marker.test(t));
+}
+
+/** A `Gemfile` declaring the gem. */
+export function gemRoots(probe: ProjectProbe, gem: string): string[] {
+    return rootsWhere(probe, /^Gemfile$/, (t) => new RegExp(`^\\s*gem\\s+['"]${gem}['"]`, 'm').test(t));
+}
+
+/** Marker files present in the probe, by basename, as roots. */
+export function markerRoots(probe: ProjectProbe, basename: string): string[] {
+    return [...new Set([...probe.markers].filter((p) => path.posix.basename(p) === basename).map(rootOf))].sort();
+}
+
+export function union(...lists: string[][]): string[] {
+    return [...new Set(lists.flat())].sort();
+}

package/src/scripts/code_graph/providers/shared/extractors.ts

@@ -0,0 +1,249 @@
+/**
+ * The five shared mechanisms most providers are a parameter table for
+ * (road-to-graph-providers-for-every-stack 4.1):
+ *
+ *   annotationRoutes   @Get('/x') · @app.get("/x") · #[Route('/x')] · [HttpGet("x")]  route → the method below it
+ *   callRoutes         app.get('/x', h) · path('x/', views.h) · r.GET("/x", h)          route → the handler named
+ *   fsRoutes           a page module whose path is its route                         route → the module
+ *   tableMapping       @Table(name = "t") · __tablename__ · $table · conventions      model → table, migration → table
+ *   templateRoots      render('a/b.html') · render_template('x.html') · View("Name")  code → the template file
+ *
+ * Every edge is emitted only when its target exists; what a rule cannot settle
+ * (a closure, a name built at runtime) gets no edge rather than a guess.
+ */
+import * as path from 'node:path';
+
+import type { SourceFile } from '../../build.js';
+import type { CodeNode } from '../../types.js';
+import { type Kit, lineIndex } from './kit.js';
+
+export function joinRoute(...parts: Array<string | undefined>): string {
+    const joined = parts
+        .filter((p): p is string => typeof p === 'string' && p.length > 0)
+        .map((p) => p.replace(/^\/+|\/+$/g, ''))
+        .filter(Boolean)
+        .join('/');
+    return `/${joined}`;
+}
+
+export interface AnnotationRouteSpec {
+    exts: readonly string[];
+    /** A route decorator; named groups `verb` (optional) and `path` (optional). */
+    route: RegExp;
+    /** HTTP verb when the decorator carries it in its name; `ANY` otherwise. */
+    verb?: (m: RegExpMatchArray) => string;
+    /** A class-level prefix decorator just above the class; named group `path`. */
+    prefix?: RegExp;
+    /** How far above a class its prefix decorator may sit, in lines. */
+    prefixReach?: number;
+}
+
+export function annotationRoutes(kit: Kit, spec: AnnotationRouteSpec): number {
+    let count = 0;
+    for (const f of kit.filesWithExt(...spec.exts)) {
+        const at = lineIndex(f.source);
+        const prefixes = spec.prefix
+            ? [...f.source.matchAll(spec.prefix)].map((m) => ({ line: at(m.index as number), path: m.groups?.['path'] ?? '' }))
+            : [];
+        for (const m of f.source.matchAll(spec.route)) {
+            const index = m.index as number;
+            // A decorator inside a line comment is prose, not a route. A docblock
+            // line (` * @Route`) is not skipped: annotation-routed frameworks read it.
+            const lineStart = f.source.lastIndexOf('\n', index - 1) + 1;
+            if (/\/\/|^\s*#(?!\[)/.test(f.source.slice(lineStart, index))) continue;
+            const line = at(index);
+            const handler = kit.nextSymbol(f.path, line, ['method', 'function']);
+            const cls = handler ? kit.classAt(f.path, handler.source_location[0] as number) : null;
+            const reach = spec.prefixReach ?? 6;
+            const clsLine = cls ? (cls.source_location[0] as number) : -1;
+            const prefix = cls ? prefixes.filter((p) => p.line <= clsLine && p.line >= clsLine - reach).pop()?.path : undefined;
+            const verb = (spec.verb ? spec.verb(m) : (m.groups?.['verb'] ?? 'ANY')).toUpperCase();
+            const id = kit.route(f.path, verb, joinRoute(prefix, m.groups?.['path']), line);
+            if (handler) kit.emit(id, handler.id, 'routes-to', 'route-table');
+            count += 1;
+        }
+    }
+    return count;
+}
+
+export interface CallRouteSpec {
+    exts: readonly string[];
+    /**
+     * A route registration; named groups `verb` (optional), `path`, `rest` (the
+     * text after the path). Capture `rest` inside a lookahead —
+     * `(?=(?<rest>[\s\S]{0,300}))` — or it swallows the next registration.
+     */
+    call: RegExp;
+    verb?: (m: RegExpMatchArray) => string;
+    /** Resolve the handler from `rest`; the default reads the last argument as a name or `obj.member`. */
+    handler?: (kit: Kit, file: string, rest: string) => string | null;
+}
+
+/** The last argument of a call's remaining text, if it is a plain name or `obj.member`. */
+export function lastArgName(rest: string): string | null {
+    let depth = 0;
+    let end = rest.length;
+    for (let i = 0; i < rest.length; i++) {
+        const c = rest[i];
+        if (c === '(' || c === '[' || c === '{') depth += 1;
+        else if (c === ')' || c === ']' || c === '}') {
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+            depth -= 1;
+        }
+    }
+    const args = rest.slice(0, end).split(',').map((a) => a.trim()).filter(Boolean);
+    const last = args[args.length - 1];
+    return last && /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?$/.test(last) ? last : null;
+}
+
+export function defaultHandler(kit: Kit, file: string, rest: string): string | null {
+    const name = lastArgName(rest);
+    if (!name) return null;
+    const [head, member] = name.split('.') as [string, string | undefined];
+    const resolved = kit.resolveName(file, head);
+    if (!member) return resolved;
+    if (resolved) return kit.methodOf(resolved, member) ?? kit.resolveName(path.posix.join(path.posix.dirname(file), head), member);
+    return null;
+}
+
+export function callRoutes(kit: Kit, spec: CallRouteSpec): number {
+    let count = 0;
+    for (const f of kit.filesWithExt(...spec.exts)) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(spec.call)) {
+            const line = at(m.index as number);
+            const verb = (spec.verb ? spec.verb(m) : (m.groups?.['verb'] ?? 'ANY')).toUpperCase();
+            const id = kit.route(f.path, verb, joinRoute(m.groups?.['path']), line);
+            const target = (spec.handler ?? defaultHandler)(kit, f.path, m.groups?.['rest'] ?? '');
+            if (target) kit.emit(id, target, 'routes-to', 'route-table');
+            count += 1;
+        }
+    }
+    return count;
+}
+
+export interface FsRouteSpec {
+    /** The route of a path, or null when it is no page module. */
+    route: (p: string) => { verb: string; path: string } | null;
+}
+
+export function fsRoutes(kit: Kit, spec: FsRouteSpec): number {
+    let count = 0;
+    for (const p of kit.paths) {
+        const r = spec.route(p);
+        if (!r) continue;
+        kit.fileNode(p);
+        const id = kit.route(p, r.verb, r.path, 1);
+        kit.emit(id, p, 'routes-to', 'route-table');
+        count += 1;
+    }
+    return count;
+}
+
+export interface TableMappingSpec {
+    exts: readonly string[];
+    /** Marks the class it precedes or opens as mapped to a table. */
+    entity: RegExp;
+    /** The explicit table name, searched in the entity's declaration region; named group `name`. */
+    tableName?: RegExp;
+    /** The table a mapped class gets when nothing names one. */
+    convention?: (className: string) => string;
+    /** A migration or schema statement creating a table; named group `name`. */
+    migration?: { files: (p: string) => boolean; create: RegExp };
+}
+
+export function snakePlural(name: string): string {
+    const snake = name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+    if (/[^aeiou]y$/.test(snake)) return `${snake.slice(0, -1)}ies`;
+    if (/(s|x|z|ch|sh)$/.test(snake)) return `${snake}es`;
+    return `${snake}s`;
+}
+
+export function tableMapping(kit: Kit, spec: TableMappingSpec): number {
+    let count = 0;
+    if (spec.migration) {
+        for (const f of kit.files.filter((x) => spec.migration?.files(x.path))) {
+            const at = lineIndex(f.source);
+            for (const m of f.source.matchAll(spec.migration.create)) {
+                const name = m.groups?.['name'];
+                if (!name) continue;
+                kit.emit(f.path, kit.table(name, f.path, at(m.index as number)), 'migrates', 'schema-call');
+            }
+        }
+    }
+    for (const f of kit.filesWithExt(...spec.exts)) {
+        const at = lineIndex(f.source);
+        const lines = f.source.split('\n');
+        for (const m of f.source.matchAll(spec.entity)) {
+            const line = at(m.index as number);
+            const cls = kit.classAt(f.path, line) ?? kit.nextSymbol(f.path, line, ['class']);
+            if (!cls || cls.kind !== 'class') continue;
+            const start = cls.source_location[0] as number;
+            const end = (cls.source_location[2] ?? start) as number;
+            // Up to four lines of decorators above the class — but never past the
+            // end of the class before it, whose own table name would be read.
+            let floor = 0;
+            for (const n of kit.nodesInFile(f.path)) {
+                if (n.kind !== 'class' || n.id === cls.id) continue;
+                const nEnd = (n.source_location[2] ?? n.source_location[0]) as number;
+                if (nEnd < start && nEnd > floor) floor = nEnd;
+            }
+            const region = lines.slice(Math.max(floor, Math.min(line, start) - 1 - 4), end).join('\n');
+            const explicit = spec.tableName ? spec.tableName.exec(region)?.groups?.['name'] : undefined;
+            const name = explicit ?? spec.convention?.(cls.label);
+            if (!name) continue;
+            kit.emit(cls.id, kit.table(name, f.path, start), 'persists', 'schema-call');
+            count += 1;
+        }
+    }
+    return count;
+}
+
+export interface TemplateRootSpec {
+    exts: readonly string[];
+    /** A render call; named group `name` is the template as written. */
+    call: RegExp;
+    /** Directories templates live under, repo- or package-root-relative. */
+    roots: readonly string[];
+    /** Extensions tried when the name carries none. */
+    extensions: readonly string[];
+    /** Rewrite a name before lookup (`a.b` → `a/b`). */
+    normalize?: (name: string) => string;
+    /** Further template directories for one file, repo-relative (a folder its own source declares). */
+    rootsFor?: (file: SourceFile) => readonly string[];
+}
+
+export function templateRoots(kit: Kit, spec: TemplateRootSpec): number {
+    const inventory = new Set(kit.paths);
+    let count = 0;
+    for (const f of kit.filesWithExt(...spec.exts)) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(spec.call)) {
+            const raw = m.groups?.['name'];
+            if (!raw) continue;
+            const name = spec.normalize ? spec.normalize(raw) : raw;
+            const hasExt = /\.[A-Za-z0-9]+$/.test(path.posix.basename(name));
+            const hits = new Set<string>();
+            const dirs = [...kit.roots.flatMap((r) => spec.roots.map((t) => path.posix.join(r, t))), ...(spec.rootsFor?.(f) ?? [])];
+            for (const root of new Set(dirs)) {
+                for (const c of hasExt ? [path.posix.join(root, name)] : spec.extensions.map((x) => path.posix.join(root, `${name}${x}`))) {
+                    if (inventory.has(c)) hits.add(c);
+                }
+            }
+            if (hits.size !== 1) continue;
+            const target = [...hits][0] as string;
+            kit.fileNode(target);
+            kit.emit(kit.enclosing(f.path, at(m.index as number)), target, 'renders', 'directive-scan');
+            count += 1;
+        }
+    }
+    return count;
+}
+
+/** The class a node belongs to, for a method id `<file>#<Class>::<m>`. */
+export function classOf(n: CodeNode): string {
+    return n.id.split('::')[0] as string;
+}