@event4u/agent-config 17.2.1 → 17.4.0

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

@@ -0,0 +1,252 @@
+/**
+ * Mechanics the JavaScript providers share and the five extractors do not
+ * carry: resolving a module specifier and a default import, reading a route
+ * object literal, constructor injection, and the verb functions a route module
+ * exports.
+ *
+ * Same contract as the extractors: an edge only when its target exists; a
+ * specifier that is not relative, or a value built at runtime, gets no edge.
+ */
+import * as path from 'node:path';
+
+import type { CodeNode } from '../../types.js';
+import { joinRoute } from './extractors.js';
+import { type Kit, lineIndex } from './kit.js';
+
+const MODULE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte'];
+
+/** A kit that sees only the code files `keep` accepts (one ORM among several sharing a decorator name). */
+export function scopeKit(kit: Kit, keep: (source: string) => boolean): Kit {
+    const files = kit.files.filter((f) => keep(f.source));
+    return { ...kit, files, filesWithExt: (...exts) => files.filter((f) => exts.some((x) => f.path.endsWith(x))) };
+}
+
+/** The project file a relative specifier written in `file` names; null for a package or alias specifier. */
+export function resolveModule(kit: Kit, file: string, spec: string): string | null {
+    if (!spec.startsWith('./') && !spec.startsWith('../')) return null;
+    const base = path.posix.join(path.posix.dirname(file), spec);
+    if (base.startsWith('..')) return null;
+    const known = (p: string): boolean => kit.fileIds.has(p) || kit.nodeById.has(p) || kit.hasPath(p);
+    if (/\.[A-Za-z0-9]+$/.test(path.posix.basename(base)) && known(base)) return base;
+    for (const c of [...MODULE_EXTS.map((x) => `${base}${x}`), ...MODULE_EXTS.map((x) => `${base}/index${x}`)]) if (known(c)) return c;
+    return null;
+}
+
+function symbolIn(kit: Kit, file: string, name: string): string | null {
+    for (const n of kit.nodesInFile(file)) if (n.label === name && n.kind !== 'method' && n.kind !== 'file') return n.id;
+    return null;
+}
+
+/** A module target: the named symbol inside it when it declares one, else the module file. */
+export function moduleTarget(kit: Kit, file: string, spec: string, member?: string): string | null {
+    const mod = resolveModule(kit, file, spec);
+    if (!mod) return null;
+    const sym = member ? symbolIn(kit, mod, member) : null;
+    if (sym) return sym;
+    kit.fileNode(mod);
+    return mod;
+}
+
+/**
+ * A component name as written in `file`: a same-file or named-import symbol
+ * (`kit.resolveName`), else a default import — the symbol of that name in the
+ * imported module, or the module file itself.
+ */
+export function resolveComponent(kit: Kit, file: string, name: string): string | null {
+    const named = kit.resolveName(file, name);
+    if (named) return named;
+    const src = kit.files.find((f) => f.path === file)?.source ?? '';
+    const esc = name.replace(/\$/g, '\\$');
+    const m = new RegExp(`\\bimport\\s+${esc}\\s*(?:,\\s*\\{[^}]*\\})?\\s+from\\s+(['"])([^'"]+)\\1`).exec(src);
+    return m ? moduleTarget(kit, file, m[2] as string, name) : null;
+}
+
+/**
+ * The object literal around `index`: its bounds, and its own top-level text with
+ * every nested `{}` and `[]` blanked (parentheses kept, so `() => import('./x')`
+ * stays readable). Null when `index` sits inside parentheses or a bracket first.
+ */
+export function objectAt(src: string, index: number): { start: number; end: number; flat: string } | null {
+    let depth = 0;
+    let start = -1;
+    for (let i = index - 1; i >= 0; i--) {
+        const c = src[i];
+        if (c === ')' || c === ']' || c === '}') depth += 1;
+        else if (c === '(' || c === '[' || c === '{') {
+            if (depth === 0) {
+                if (c !== '{') return null;
+                start = i;
+                break;
+            }
+            depth -= 1;
+        }
+    }
+    if (start < 0) return null;
+    const out: string[] = [];
+    const stack: string[] = [];
+    for (let i = start + 1; i < src.length; i++) {
+        const c = src[i] as string;
+        const nested = (): boolean => stack.some((s) => s !== '(');
+        if (c === '{' || c === '[' || c === '(') {
+            const blank = nested() || c !== '(';
+            stack.push(c);
+            out.push(blank ? ' ' : c);
+        } else if (c === '}' || c === ']' || c === ')') {
+            if (stack.length === 0) return { start, end: i, flat: out.join('') };
+            stack.pop();
+            out.push(nested() || c !== ')' ? ' ' : c);
+        } else out.push(nested() ? ' ' : c);
+    }
+    return null;
+}
+
+/** The text of `key: <value>` in a flat object, up to the next top-level comma. */
+export function valueOf(flat: string, key: string): string | null {
+    const m = new RegExp(`(?:^|[\\s,])${key}\\s*:`).exec(flat);
+    if (!m) return null;
+    let depth = 0;
+    const from = m.index + m[0].length;
+    for (let i = from; i < flat.length; i++) {
+        const c = flat[i];
+        if (c === '(') depth += 1;
+        else if (c === ')') depth -= 1;
+        else if (c === ',' && depth === 0) return flat.slice(from, i).trim();
+    }
+    return flat.slice(from).trim();
+}
+
+/** What a component value names: a dynamic import (with an optional `.then(m => m.X)`), a JSX element, or a name. */
+export function componentTarget(kit: Kit, file: string, value: string): string | null {
+    const imp = /\bimport\(\s*(['"`])([^'"`]+)\1\s*\)(?:\s*\.then\(\s*\(?\s*(\w+)\s*\)?\s*=>\s*\3\.(\w+)\s*\))?/.exec(value);
+    if (imp) return moduleTarget(kit, file, imp[2] as string, imp[4]);
+    const jsx = /^<\s*([A-Z][\w$]*)/.exec(value);
+    if (jsx) return resolveComponent(kit, file, jsx[1] as string);
+    if (/^[A-Za-z_$][\w$]*$/.test(value)) return resolveComponent(kit, file, value);
+    return null;
+}
+
+export interface RouteObjectSpec {
+    exts: readonly string[];
+    /** Keys whose value is the component a route renders; a `path` object with none of them is no route. */
+    componentKeys: readonly string[];
+}
+
+/** `{ path: '/x', component: X }` route objects → a PAGE route --routes-to--> the component or lazily imported module. */
+export function routeObjects(kit: Kit, spec: RouteObjectSpec): number {
+    let count = 0;
+    for (const f of kit.filesWithExt(...spec.exts)) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/(?:^|[\s,{])path\s*:\s*(['"`])(?<path>[^'"`$]*)\1/g)) {
+            const obj = objectAt(f.source, m.index as number);
+            if (!obj) continue;
+            const values = spec.componentKeys.map((k) => valueOf(obj.flat, k)).filter((v): v is string => v !== null);
+            if (values.length === 0) continue;
+            const id = kit.route(f.path, 'PAGE', joinRoute(m.groups?.['path']), at(m.index as number));
+            for (const v of values) {
+                const target = componentTarget(kit, f.path, v);
+                if (target) kit.emit(id, target, 'routes-to', 'route-table');
+            }
+            count += 1;
+        }
+    }
+    return count;
+}
+
+function symbolsOf(kit: Kit, file: string, kind: CodeNode['kind']): CodeNode[] {
+    return kit.nodesInFile(file).filter((n) => n.kind === kind);
+}
+
+/** The parameter list of the first `constructor(` in `text`, balanced. */
+function constructorParams(text: string): string[] {
+    const m = /\bconstructor\s*\(/.exec(text);
+    if (!m) return [];
+    let depth = 0;
+    const from = m.index + m[0].length;
+    const parts: string[] = [];
+    let cur = '';
+    for (let i = from; i < text.length; i++) {
+        const c = text[i] as string;
+        if (c === '(' || c === '<' || c === '[' || c === '{') depth += 1;
+        else if (c === ')' || c === '>' || c === ']' || c === '}') {
+            if (depth === 0) break;
+            depth -= 1;
+        }
+        if (c === ',' && depth === 0) {
+            parts.push(cur);
+            cur = '';
+        } else cur += c;
+    }
+    if (cur.trim()) parts.push(cur);
+    return parts;
+}
+
+export interface InjectionSpec {
+    exts: readonly string[];
+    /** A class decorator marking the class as container-managed, searched just above the class. */
+    classDecorator: RegExp;
+    /** How far above the class its decorator may sit, in lines. */
+    reach?: number;
+    /** A field initializer naming the dependency (`inject(X)`); group 1 is the type. */
+    injectCall?: RegExp;
+}
+
+/** `constructor(private readonly s: UsersService)` in a decorated class → class --injects--> UsersService. */
+export function constructorInjection(kit: Kit, spec: InjectionSpec): number {
+    let count = 0;
+    for (const f of kit.filesWithExt(...spec.exts)) {
+        const lines = f.source.split('\n');
+        for (const cls of symbolsOf(kit, f.path, 'class')) {
+            const start = cls.source_location[0] as number;
+            const end = (cls.source_location[2] ?? start) as number;
+            const above = lines.slice(Math.max(0, start - 1 - (spec.reach ?? 6)), start).join('\n');
+            if (!spec.classDecorator.test(above)) continue;
+            const body = lines.slice(start - 1, end).join('\n');
+            const types: string[] = [];
+            for (const p of constructorParams(body)) {
+                const t = /^\s*(?:@\w+\([^)]*\)\s*)*(?:(?:public|private|protected|readonly)\s+)*[A-Za-z_$][\w$]*\??\s*:\s*([A-Za-z_$][\w$]*)/.exec(p);
+                if (t) types.push(t[1] as string);
+            }
+            if (spec.injectCall) for (const m of body.matchAll(spec.injectCall)) types.push(m[1] as string);
+            for (const t of types) {
+                const target = kit.resolveName(f.path, t);
+                if (!target || target === cls.id || kit.nodeById.get(target)?.kind !== 'class') continue;
+                kit.emit(cls.id, target, 'injects', 'di-binding');
+                count += 1;
+            }
+        }
+    }
+    return count;
+}
+
+export const HTTP_VERBS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const;
+
+/** `export async function GET()` · `export const POST = …` in a route module → one route per verb → that function. */
+export function exportedVerbRoutes(kit: Kit, file: string, routePath: string): number {
+    const src = kit.files.find((f) => f.path === file)?.source;
+    if (src === undefined) return 0;
+    const at = lineIndex(src);
+    let count = 0;
+    const re = new RegExp(`\\bexport\\s+(?:async\\s+function|function|const|let)\\s+(${HTTP_VERBS.join('|')})\\b`, 'g');
+    for (const m of src.matchAll(re)) {
+        const verb = m[1] as string;
+        const id = kit.route(file, verb, routePath, at(m.index as number));
+        const target = kit.resolveName(file, verb);
+        if (target) kit.emit(id, target, 'routes-to', 'route-table');
+        count += 1;
+    }
+    return count;
+}
+
+/** `p` relative to the deepest of `roots` it lies under, with that root; null when under none. */
+export function underRoot(roots: readonly string[], p: string): { root: string; rel: string } | null {
+    for (const root of [...roots].sort((a, b) => b.length - a.length)) {
+        if (root === '') return { root, rel: p };
+        if (p.startsWith(`${root}/`)) return { root, rel: p.slice(root.length + 1) };
+    }
+    return null;
+}
+
+/** Route segments as the default pass writes them: groups, slots and `index` dropped. */
+export function cleanRoute(parts: readonly string[]): string {
+    return `/${parts.filter((s) => !/^\(.*\)$/.test(s) && !s.startsWith('@') && s !== 'index').join('/')}`.replace(/\/$/, '') || '/';
+}

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

@@ -0,0 +1,210 @@
+/**
+ * The building blocks every convention provider shares: emitting deduplicated
+ * edges, declaring route and table nodes, finding the symbol a line belongs to
+ * or the one a decorator precedes, and resolving a handler name the way the
+ * file itself states it (same file, then its imports).
+ *
+ * A provider stays a parameter table plus the semantics only it knows; the
+ * mechanics live here once (road-to-graph-providers-for-every-stack 4.1).
+ */
+import * as path from 'node:path';
+
+import type { SourceFile } from '../../build.js';
+import type { CodeEdge, CodeNode, ResolvedVia } from '../../types.js';
+import type { ProviderInput, ProviderResult } from '../types.js';
+
+/** A string matched literally inside a `RegExp` built from a symbol name. */
+export function escapeRe(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Line-start offsets, so many `lineAt` lookups stay linear. */
+export function lineIndex(src: string): (index: number) => number {
+    const starts = [0];
+    for (let i = 0; i < src.length; i++) if (src.charCodeAt(i) === 10) starts.push(i + 1);
+    return (index: number): number => {
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if ((starts[mid] as number) <= index) lo = mid;
+            else hi = mid - 1;
+        }
+        return lo + 1;
+    };
+}
+
+export interface Kit {
+    files: readonly SourceFile[];
+    fileIds: ReadonlySet<string>;
+    nodeById: ReadonlyMap<string, CodeNode>;
+    /** Every project path under the provider's roots, code or not. */
+    paths: readonly string[];
+    /** The package roots the provider was detected in (`''` is the repository root). */
+    roots: readonly string[];
+    /** The code files whose path ends with one of `exts`. */
+    filesWithExt(...exts: string[]): SourceFile[];
+    /** Make sure a file node exists for a non-code target (a template). */
+    fileNode(p: string): void;
+    /** Every base node declared in `file` (indexed once; never a scan of the whole graph). */
+    nodesInFile(file: string): readonly CodeNode[];
+    /** Every base node with this label (indexed once). */
+    nodesNamed(label: string): readonly CodeNode[];
+    /** Whether a project path is in the inventory (indexed once). */
+    hasPath(p: string): boolean;
+    emit(source: string, target: string, relation: CodeEdge['relation'], via: ResolvedVia): void;
+    /** Declare a route node in `file`; returns its id (`<file>#route:<VERB> <path>`, `@n` when repeated). */
+    route(file: string, verb: string, routePath: string, line: number): string;
+    /** Declare (once) the table node `table:<name>`, first seen in `file`. */
+    table(name: string, file: string, line: number): string;
+    /** The innermost function or method node whose span holds `line`, else the file. */
+    enclosing(file: string, line: number): string;
+    /** The first function, method or class node starting at or after `line` (what a decorator decorates). */
+    nextSymbol(file: string, line: number, kinds?: readonly CodeNode['kind'][]): CodeNode | null;
+    /** The class node whose span holds `line`. */
+    classAt(file: string, line: number): CodeNode | null;
+    /**
+     * A name as written in `file`, resolved the way the file states it: a
+     * same-file symbol first, then a symbol an import edge of the file binds.
+     */
+    resolveName(file: string, name: string): string | null;
+    /** A method `member` of the class node `classId`, if the class declares it. */
+    methodOf(classId: string, member: string): string | null;
+    result(): ProviderResult;
+}
+
+export function makeKit(input: ProviderInput): Kit {
+    const files = input.files;
+    const fileIds = new Set(files.map((f) => f.path));
+    const nodeById = new Map(input.baseNodes.map((n) => [n.id, n] as const));
+    const nodes: CodeNode[] = [];
+    const edges: CodeEdge[] = [];
+    const seenEdge = new Set<string>();
+    const seenNode = new Set<string>();
+    const routeOrdinal = new Map<string, number>();
+    let byFile: Map<string, CodeNode[]> | null = null;
+    let byLabel: Map<string, CodeNode[]> | null = null;
+    let pathSet: Set<string> | null = null;
+    const index = (key: (n: CodeNode) => string): Map<string, CodeNode[]> => {
+        const m = new Map<string, CodeNode[]>();
+        for (const n of input.baseNodes) {
+            const k = key(n);
+            const list = m.get(k);
+            if (list) list.push(n);
+            else m.set(k, [n]);
+        }
+        return m;
+    };
+
+    const symbolsByFile = new Map<string, CodeNode[]>();
+    for (const n of input.baseNodes) {
+        if (n.kind === 'file' || n.source_location.length === 0) continue;
+        const list = symbolsByFile.get(n.source_file) ?? [];
+        list.push(n);
+        symbolsByFile.set(n.source_file, list);
+    }
+    for (const list of symbolsByFile.values()) list.sort((a, b) => (a.source_location[0] as number) - (b.source_location[0] as number));
+
+    const importsByFile = new Map<string, Map<string, string>>();
+    for (const e of input.baseEdges) {
+        if (e.relation !== 'imports') continue;
+        const from = nodeById.get(e.source)?.source_file;
+        const to = nodeById.get(e.target);
+        if (!from || !to) continue;
+        const m = importsByFile.get(from) ?? new Map<string, string>();
+        if (!m.has(to.label)) m.set(to.label, to.id);
+        importsByFile.set(from, m);
+    }
+
+    const emit: Kit['emit'] = (source, target, relation, via) => {
+        const key = `${source}\0${relation}\0${target}`;
+        if (seenEdge.has(key)) return;
+        seenEdge.add(key);
+        edges.push({ source, target, relation, confidence: 'EXTRACTED', resolved_via: via, provider: 'native' });
+    };
+    const span = (n: CodeNode): [number, number] => [n.source_location[0] as number, (n.source_location[2] ?? n.source_location[0]) as number];
+
+    return {
+        files,
+        fileIds,
+        nodeById,
+        paths: input.paths,
+        roots: input.roots,
+        nodesInFile: (file) => (byFile ??= index((n) => n.source_file)).get(file) ?? [],
+        nodesNamed: (label) => (byLabel ??= index((n) => n.label)).get(label) ?? [],
+        hasPath: (p) => (pathSet ??= new Set(input.paths)).has(p),
+        filesWithExt: (...exts) => files.filter((f) => exts.some((x) => f.path.endsWith(x))),
+        fileNode(p) {
+            if (nodeById.has(p) || seenNode.has(p)) return;
+            seenNode.add(p);
+            nodes.push({ id: p, label: p, kind: 'file', source_file: p, source_location: [] });
+        },
+        emit,
+        route(file, verb, routePath, line) {
+            const base = `${file}#route:${verb} ${routePath}`;
+            const n = (routeOrdinal.get(base) ?? 0) + 1;
+            routeOrdinal.set(base, n);
+            const id = n === 1 ? base : `${base}@${n}`;
+            nodes.push({ id, label: `${verb} ${routePath}`, kind: 'route', source_file: file, source_location: [line, 1, line, 1] });
+            emit(file, id, 'member', 'same-file');
+            return id;
+        },
+        table(name, file, line) {
+            const id = `table:${name}`;
+            if (!seenNode.has(id)) {
+                seenNode.add(id);
+                nodes.push({ id, label: name, kind: 'table', source_file: file, source_location: [line, 1, line, 1] });
+            }
+            return id;
+        },
+        enclosing(file, line) {
+            let best: CodeNode | null = null;
+            for (const n of symbolsByFile.get(file) ?? []) {
+                if (n.kind !== 'method' && n.kind !== 'function') continue;
+                const [s, e] = span(n);
+                if (s <= line && line <= e && (!best || s >= (best.source_location[0] as number))) best = n;
+            }
+            return best ? best.id : file;
+        },
+        nextSymbol(file, line, kinds = ['method', 'function', 'class']) {
+            for (const n of symbolsByFile.get(file) ?? []) if (kinds.includes(n.kind) && span(n)[0] >= line) return n;
+            return null;
+        },
+        classAt(file, line) {
+            let best: CodeNode | null = null;
+            for (const n of symbolsByFile.get(file) ?? []) {
+                if (n.kind !== 'class') continue;
+                const [s, e] = span(n);
+                if (s <= line && line <= e && (!best || s >= (best.source_location[0] as number))) best = n;
+            }
+            return best;
+        },
+        resolveName(file, name) {
+            const local = (symbolsByFile.get(file) ?? []).find((n) => n.label === name && n.kind !== 'method');
+            if (local) return local.id;
+            return importsByFile.get(file)?.get(name) ?? null;
+        },
+        methodOf(classId, member) {
+            const id = `${classId}::${member}`;
+            return nodeById.has(id) ? id : null;
+        },
+        result: () => ({ nodes, edges }),
+    };
+}
+
+/**
+ * The one symbol named `name` declared by a file in `file`'s own directory with
+ * the same extension — what a language whose package is its directory (Go, a
+ * Java package) sees without an import. Null when none or several declare it.
+ */
+export function packageSymbol(kit: Kit, file: string, name: string, kinds: readonly CodeNode['kind'][]): string | null {
+    const dir = path.posix.dirname(file);
+    const ext = path.posix.extname(file);
+    const hits: string[] = [];
+    for (const n of kit.nodesNamed(name)) {
+        if (!kinds.includes(n.kind)) continue;
+        if (path.posix.dirname(n.source_file) !== dir || path.posix.extname(n.source_file) !== ext) continue;
+        hits.push(n.id);
+    }
+    return hits.length === 1 ? (hits[0] as string) : null;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * PHP name resolution shared by the PHP providers: a class reference read the
+ * way its file states it (namespace + `use` aliases), then located through the
+ * project's PSR-4 map. A reference that resolves to no class node in the graph
+ * resolves to nothing — never to a same-named class in another namespace.
+ */
+import { resolvePsr4, type ResolutionConfig } from '../../resolution_tiers.js';
+import type { Kit } from './kit.js';
+
+export interface PhpScope {
+    namespace: string;
+    uses: Map<string, string>;
+}
+
+export function phpScope(src: string): PhpScope {
+    const ns = /^\s*namespace\s+([\\\w]+)\s*;/m.exec(src)?.[1] ?? '';
+    const uses = new Map<string, string>();
+    for (const m of src.matchAll(/^\s*use\s+([\\\w]+)(?:\s+as\s+(\w+))?\s*;/gm)) {
+        const fq = (m[1] as string).replace(/^\\/, '');
+        uses.set(m[2] ?? fq.split('\\').pop() ?? fq, fq);
+    }
+    return { namespace: ns, uses };
+}
+
+/** Fully-qualified name of a class reference as written under `scope`. */
+export function qualify(ref: string, scope: PhpScope): string {
+    if (ref.startsWith('\\')) return ref.slice(1);
+    const [head, ...rest] = ref.split('\\');
+    const aliased = scope.uses.get(head as string);
+    if (aliased) return [aliased, ...rest].join('\\');
+    return scope.namespace ? `${scope.namespace}\\${ref}` : ref;
+}
+
+export function shortName(fq: string): string {
+    return fq.split('\\').pop() ?? fq;
+}
+
+/** The class node a fully-qualified name names, through PSR-4; null when absent. */
+export function classNode(kit: Kit, fq: string, resolution: ResolutionConfig): string | null {
+    const file = resolvePsr4(fq, resolution, kit.fileIds);
+    const id = file ? `${file}#${shortName(fq)}` : null;
+    return id && kit.nodeById.has(id) ? id : null;
+}
+
+/** Offset of the bracket closing the one at `open` (`(`, `[` or `{`), skipping string literals. */
+export function matchingClose(src: string, open: number): number {
+    const pair: Record<string, string> = { '(': ')', '[': ']', '{': '}' };
+    const o = src[open] as string;
+    const c = pair[o];
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+        const ch = src[i];
+        if (ch === "'" || ch === '"') {
+            for (i += 1; i < src.length && src[i] !== ch; i++) if (src[i] === '\\') i += 1;
+            continue;
+        }
+        if (ch === o) depth += 1;
+        else if (ch === c) {
+            depth -= 1;
+            if (depth === 0) return i;
+        }
+    }
+    return src.length;
+}