@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/code_graph/query.ts

@@ -9,22 +9,135 @@ import * as fs from 'node:fs';
 
 import { LexicalIndex, tokenize } from '../_lib/lexical_index.js';
 import { sanitizeLabel } from './sanitize.js';
-import { emitSqliteTwin, loadSerializedFromTwin } from './sqlite_store.js';
-import type { CodeEdge, CodeGraph } from './types.js';
+import {
+    emitSqliteTwin,
+    type GraphIndex,
+    INDEXED_READ_MIN_EDGES,
+    loadSerializedFromTwin,
+    openGraphIndex,
+} from './sqlite_store.js';
+import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
 import { validateGraph } from './validate.js';
 
 const APPROX_CHARS_PER_TOKEN = 4;
 
+/**
+ * The node/adjacency reads every verb performs.
+ *
+ * Declared as interfaces rather than `Map` so one set of verbs runs over two
+ * stores. `Map` satisfies both structurally, so the in-memory path is unchanged
+ * and needed no edits; the SQLite path supplies objects with the same two
+ * methods that hit an index instead of a heap.
+ */
+export interface NodeLookup {
+    get(id: string): CodeNode | undefined;
+    has(id: string): boolean;
+}
+export interface AdjacencyLookup {
+    get(id: string): CodeEdge[] | undefined;
+}
+
 export interface LoadedGraph {
-    graph: CodeGraph;
+    /**
+     * The whole deserialized graph — `null` on the indexed path, where not
+     * materializing it is the entire point. Nothing in this module reads it;
+     * the two callers that used to (`resolveSeedsTiered`, the CLI's
+     * changed-file seeds) go through `idsByLabel` / `idsInFiles` instead, which
+     * answer the same questions from an index.
+     */
+    graph: CodeGraph | null;
     source: string; // attribution path
-    byId: Map<string, CodeGraph['nodes'][number]>;
-    out: Map<string, CodeEdge[]>;
-    in: Map<string, CodeEdge[]>;
-    lex: LexicalIndex;
+    /**
+     * The on-disk path the answer came from.
+     *
+     * Distinct from `source`, which is a display string (`native:relpath`) and
+     * cannot be handed to a freshness check. A verb that prints staleness has
+     * to describe THIS file, not a conventional cache path — see
+     * `cli.ts::stateOf`.
+     */
+    answeredBy: string;
+    byId: NodeLookup;
+    out: AdjacencyLookup;
+    in: AdjacencyLookup;
+    /** Exact-label resolution. */
+    idsByLabel(label: string, limit: number): string[];
+    /** Non-file nodes declared in any of `files`. */
+    idsInFiles(files: readonly string[]): string[];
+    /**
+     * Every node id, sorted.
+     *
+     * A whole-table read, and unlike {@link LoadedGraph.lex} it is not lazy —
+     * because the one verb that calls it (`dead`, 3.3) is defined over every
+     * node by construction: "zero accepted in-edges" is not a question you can
+     * ask about a frontier. Nothing else may use it; a verb that walks from a
+     * seed has `idsByLabel` / `idsInFiles` for that.
+     */
+    allNodeIds(): string[];
+    /**
+     * BM25 fallback corpus, LAZY.
+     *
+     * A function rather than a field because on the indexed path building it
+     * reads every node — the one whole-table scan left — and a seed that
+     * resolves by exact id or exact label must never pay for it. On the
+     * in-memory path the corpus is already in hand and this just returns it.
+     */
+    lex(): LexicalIndex;
+    /** Release any handle the store holds. No-op for the in-memory path. */
+    close(): void;
+}
+
+/**
+ * A `LoadedGraph` backed by the SQLite index — no `JSON.parse`, no whole-graph
+ * `Map`.
+ *
+ * The adjacency lookups are per-call SQL against `edges_source` / `edges_target`
+ * rather than a materialized map, which is the difference the threshold buys: a
+ * 2-hop `affected` touches the rows for its frontier, not every edge in the
+ * repository. Node reads are memoized per handle because a BFS asks for the
+ * same label repeatedly while rendering edge lines, and that repetition is
+ * cheap to remove and expensive to leave.
+ */
+function indexBackedGraph(index: GraphIndex, source: string, answeredBy: string): LoadedGraph {
+    const nodeCache = new Map<string, CodeNode | undefined>();
+    const readNode = (id: string): CodeNode | undefined => {
+        if (nodeCache.has(id)) return nodeCache.get(id);
+        const n = index.getNode(id);
+        nodeCache.set(id, n);
+        return n;
+    };
+    let lexical: LexicalIndex | null = null;
+    return {
+        graph: null,
+        source,
+        answeredBy,
+        byId: { get: readNode, has: (id) => readNode(id) !== undefined },
+        out: { get: (id) => index.edgesFrom(id) },
+        in: { get: (id) => index.edgesTo(id) },
+        idsByLabel: (labelText, limit) => index.idsByLabel(labelText, limit),
+        idsInFiles: (files) => index.idsInFiles(files),
+        allNodeIds: () => index.allNodeIds(),
+        lex: () => {
+            lexical ??= new LexicalIndex(index.lexicalCorpus());
+            return lexical;
+        },
+        close: () => index.close(),
+    };
 }
 
 export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
+    // Above the threshold, read through the INDEX: the twin's rows answer
+    // per-node and per-edge questions directly, so neither `JSON.parse` nor the
+    // two whole-graph `Map`s below ever run. This is the D6 repair — the twin
+    // used to be preferred and still returned the entire serialization, which
+    // made it a cheaper blob transport rather than an index.
+    const index = openGraphIndex(graphPath);
+    if (index) {
+        if (index.edgeCount >= INDEXED_READ_MIN_EDGES) return indexBackedGraph(index, source, graphPath);
+        // Small graph: the in-memory path is cheaper. Release the handle rather
+        // than leaking a database for the life of the process.
+        index.close();
+    }
+
     // Prefer the derived SQLite twin (ADR-129): checksum/stat-verified against
     // the canonical JSON, byte-identical content, ~1/90 the load cost at
     // consumer scale. Fallback = parse the JSON — and best-effort re-emit the
@@ -51,7 +164,25 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
         add(inM, e.target, e);
     }
     const lex = new LexicalIndex(graph.nodes.map((n) => ({ id: n.id, text: `${n.label} ${n.id}` })));
-    return { graph, source, byId, out: outM, in: inM, lex };
+    return {
+        graph,
+        source,
+        answeredBy: graphPath,
+        byId,
+        out: outM,
+        in: inM,
+        idsByLabel: (labelText, limit) =>
+            graph.nodes.filter((n) => n.label === labelText).slice(0, limit).map((n) => n.id),
+        idsInFiles: (files) => {
+            const set = new Set(files);
+            return graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
+        },
+        allNodeIds: () => graph.nodes.map((n) => n.id).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        lex: () => lex,
+        close: () => {
+            /* nothing held */
+        },
+    };
 }
 
 interface SeedResolution {
@@ -64,9 +195,11 @@ interface SeedResolution {
 /** Resolve a free-text seed to node ids: exact id → exact label → BM25. */
 function resolveSeedsTiered(g: LoadedGraph, seed: string, limit = 5): SeedResolution {
     if (g.byId.has(seed)) return { ids: [seed], weak: false };
-    const exactLabel = g.graph.nodes.filter((n) => n.label === seed).map((n) => n.id);
-    if (exactLabel.length) return { ids: exactLabel.slice(0, limit), weak: false };
-    const ranked = g.lex.rank(tokenize(seed)).filter((r) => r.score > 0);
+    const exactLabel = g.idsByLabel(seed, limit);
+    if (exactLabel.length) return { ids: exactLabel, weak: false };
+    // Only here does the BM25 corpus get built — the one whole-table read on
+    // the indexed path, and unreachable when the seed resolved exactly.
+    const ranked = g.lex().rank(tokenize(seed)).filter((r) => r.score > 0);
     return { ids: ranked.slice(0, limit).map((r) => r.id), weak: true };
 }
 

package/src/scripts/code_graph/resolution_tiers.ts

@@ -0,0 +1,238 @@
+/**
+ * Resolution tiers that run BEFORE the repo-wide name lookup
+ * (road-to-a-graph-that-is-shipped 2.3).
+ *
+ * The extractor's ladder ends in a same-name table across the whole
+ * repository. That rung is a guess and is labelled one — `INFERRED`, via
+ * `name-lookup`. Two configuration files in a normal project state the answer
+ * outright, and reading them turns a guess into a fact:
+ *
+ * · `tsconfig.json` `compilerOptions.paths` — `@shared/x` IS `src/shared/x`,
+ *   because the project says so. Without this tier the specifier is non-relative,
+ *   so `resolveSpecifier` returns null and the import binds to `external:@shared/x`
+ *   — a real module, correctly named, and the wrong one.
+ * · `composer.json` `autoload.psr-4` — `App\Services\Mailer` IS
+ *   `app/Services/Mailer.php`. Without this tier a PHP `use` is matched by BASE
+ *   NAME with the namespace discarded, so two classes called `Mailer` in
+ *   different namespaces are indistinguishable.
+ *
+ * Both are DECLARED mappings, so an edge resolved through one is EXTRACTED, not
+ * INFERRED: the project's own config is as much a syntactic fact as an import
+ * specifier is.
+ *
+ * Deterministic and IO-free at resolution time — the configs are read once by
+ * the caller and passed in, so `buildGraph` stays pure and identical source
+ * plus identical config yields identical bytes.
+ */
+import type { ResolvedVia } from './types.js';
+
+/** Extensions a TS/JS alias target may carry, in resolution order. */
+const ALIAS_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'] as const;
+
+export interface AliasRule {
+    /** The pattern's literal prefix, e.g. `@shared/` for `@shared/*`. */
+    prefix: string;
+    /** Whether the pattern ended in `*` (a prefix rule) or was exact. */
+    wildcard: boolean;
+    /** Repo-relative substitution targets, already joined with `baseUrl`. */
+    targets: string[];
+}
+
+export interface Psr4Rule {
+    /** Namespace prefix WITH its trailing separator, e.g. `App\\`. */
+    prefix: string;
+    /** Repo-relative directories, with a trailing slash. */
+    dirs: string[];
+}
+
+export interface ResolutionConfig {
+    aliases: AliasRule[];
+    psr4: Psr4Rule[];
+}
+
+export const EMPTY_RESOLUTION_CONFIG: ResolutionConfig = { aliases: [], psr4: [] };
+
+/**
+ * Parse JSON that may carry comments and trailing commas.
+ *
+ * `tsconfig.json` is JSONC by convention and this repository's own uses `//`
+ * comments, so `JSON.parse` on it throws. Returning null rather than throwing
+ * is deliberate: an unparseable config must degrade to "no tiers", never break
+ * a build. Strings are walked rather than regex-stripped so a `//` inside a
+ * path value survives.
+ */
+export function parseJsonc(text: string): unknown | null {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i] as string;
+        if (inString) {
+            out += ch;
+            if (escaped) escaped = false;
+            else if (ch === '\\') escaped = true;
+            else if (ch === '"') inString = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n') i += 1;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    // Trailing commas before a closing brace/bracket.
+    out = out.replace(/,(\s*[}\]])/g, '$1');
+    try {
+        return JSON.parse(out) as unknown;
+    } catch {
+        return null;
+    }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Normalise a repo-relative path fragment: no leading `./`, no trailing `/`. */
+function normalizeFragment(p: string): string {
+    return p.replace(/^\.\//, '').replace(/\/+$/, '');
+}
+
+/**
+ * Build the alias tier from a parsed `tsconfig.json`.
+ *
+ * `baseUrl` is resolved relative to the tsconfig's own directory, which for a
+ * root tsconfig is the repo root — so `baseUrl: "./src"` plus `"@shared/*":
+ * ["shared/*"]` yields the repo-relative prefix `src/shared/`.
+ */
+export function aliasRulesFrom(tsconfig: unknown): AliasRule[] {
+    if (!isRecord(tsconfig)) return [];
+    const co = tsconfig['compilerOptions'];
+    if (!isRecord(co)) return [];
+    const paths = co['paths'];
+    if (!isRecord(paths)) return [];
+    const baseUrl = typeof co['baseUrl'] === 'string' ? normalizeFragment(co['baseUrl']) : '';
+    const rules: AliasRule[] = [];
+    for (const [pattern, valueRaw] of Object.entries(paths)) {
+        if (!Array.isArray(valueRaw)) continue;
+        const wildcard = pattern.endsWith('*');
+        const prefix = wildcard ? pattern.slice(0, -1) : pattern;
+        const targets: string[] = [];
+        for (const v of valueRaw) {
+            if (typeof v !== 'string') continue;
+            const tgt = wildcard ? (v.endsWith('*') ? v.slice(0, -1) : v) : v;
+            const joined = baseUrl ? `${baseUrl}/${normalizeFragment(tgt)}` : normalizeFragment(tgt);
+            targets.push(joined.replace(/\/+$/, ''));
+        }
+        if (targets.length) rules.push({ prefix, wildcard, targets });
+    }
+    // Longest prefix first: `@shared/deep/` must beat `@shared/` when both are
+    // declared, which is TypeScript's own rule and not a preference.
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+
+/** Build the PSR-4 tier from a parsed `composer.json`. */
+export function psr4RulesFrom(composer: unknown): Psr4Rule[] {
+    if (!isRecord(composer)) return [];
+    const rules: Psr4Rule[] = [];
+    for (const key of ['autoload', 'autoload-dev']) {
+        const block = composer[key];
+        if (!isRecord(block)) continue;
+        const psr4 = block['psr-4'];
+        if (!isRecord(psr4)) continue;
+        for (const [ns, valueRaw] of Object.entries(psr4)) {
+            const dirsRaw = Array.isArray(valueRaw) ? valueRaw : [valueRaw];
+            const dirs = dirsRaw
+                .filter((d): d is string => typeof d === 'string')
+                .map((d) => {
+                    const n = normalizeFragment(d);
+                    return n === '' ? '' : `${n}/`;
+                });
+            if (dirs.length) rules.push({ prefix: ns, dirs });
+        }
+    }
+    // Longest namespace first — PSR-4's own most-specific-wins rule.
+    rules.sort((a, b) => b.prefix.length - a.prefix.length);
+    return rules;
+}
+
+function firstExisting(candidate: string, fileIds: ReadonlySet<string>): string | null {
+    if (fileIds.has(candidate)) return candidate;
+    // TS source imports `@shared/mailer.js` and the file on disk is
+    // `mailer.ts`, so the RUNTIME extension is stripped before the candidate
+    // list is tried — the same normalisation `resolveSpecifier` does for a
+    // relative specifier. Without it every alias in an ESM-style codebase
+    // misses, which is most of them.
+    const stem = candidate.replace(/\.(js|jsx|mjs|cjs)$/, '');
+    for (const e of ALIAS_EXTS) if (fileIds.has(stem + e)) return stem + e;
+    for (const e of ALIAS_EXTS) if (fileIds.has(`${candidate}/index${e}`)) return `${candidate}/index${e}`;
+    return null;
+}
+
+/**
+ * Resolve a non-relative TS/JS specifier through the alias tier.
+ *
+ * Returns null when no rule matches or the mapped file is not in the graph —
+ * an alias pointing outside the built root is not a hit, and claiming it as one
+ * would be worse than the `external:` binding it replaces.
+ */
+export function resolveAlias(spec: string, config: ResolutionConfig, fileIds: ReadonlySet<string>): string | null {
+    for (const rule of config.aliases) {
+        if (rule.wildcard) {
+            if (!spec.startsWith(rule.prefix)) continue;
+            const rest = spec.slice(rule.prefix.length);
+            for (const t of rule.targets) {
+                const hit = firstExisting(rest ? `${t}/${rest}` : t, fileIds);
+                if (hit) return hit;
+            }
+        } else {
+            if (spec !== rule.prefix) continue;
+            for (const t of rule.targets) {
+                const hit = firstExisting(t, fileIds);
+                if (hit) return hit;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Resolve a fully-qualified PHP class name through the PSR-4 tier.
+ *
+ * `App\Services\Mailer` under `{"App\\": "app/"}` becomes
+ * `app/Services/Mailer.php`. A leading backslash is tolerated because `use
+ * \App\X` is legal and means the same thing.
+ */
+export function resolvePsr4(fqcn: string, config: ResolutionConfig, fileIds: ReadonlySet<string>): string | null {
+    const name = fqcn.replace(/^\\+/, '');
+    for (const rule of config.psr4) {
+        if (!name.startsWith(rule.prefix)) continue;
+        const rest = name.slice(rule.prefix.length).replace(/\\/g, '/');
+        if (!rest) continue;
+        for (const d of rule.dirs) {
+            const candidate = `${d}${rest}.php`;
+            if (fileIds.has(candidate)) return candidate;
+        }
+    }
+    return null;
+}
+
+/** The `resolved_via` value each tier stamps on the edges it produces. */
+export const ALIAS_VIA: ResolvedVia = 'path-alias';
+export const PSR4_VIA: ResolvedVia = 'psr4';