@event4u/agent-config 17.1.0 → 17.2.0

package/src/scripts/code_graph/cli.ts

@@ -47,6 +47,12 @@
  * 0 ok · 1 not-found / validation-failed / refresh-budget-exceeded ·
  * 2 usage · 3 internal.
  *
+ *   map      [--root P] [--out DIR] [--open]  draw the project map into
+ *            [--no-verify] [--diff <rev>]      agents/map/ (ADR-297); renders it
+ *            [--prs]                           (open PRs by area, via gh)
+ *                                               at three widths when Playwright
+ *                                               is present
+ *
  *   suggest-verb "<question>"                  (Phase 9 D3) print the verb
  *                                               (query/affected/path/explain)
  *                                               a regex table thinks best
@@ -62,10 +68,20 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { resolve_project_root } from '../_lib/agent_settings.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
 import { buildFromRepo, isTestFile, sidecarPath } from './build.js';
-import { computeVerdict, detectSources, type GraphState, graphState, pickSource } from './detect.js';
+import {
+    computeVerdict,
+    detectSources,
+    type GraphState,
+    graphState,
+    NATIVE_CACHE_REL,
+    pickSource,
+} from './detect.js';
 import { suggestVerb } from './intent.js';
+import { buildMap, recordOutcome } from './map.js';
+import { verifyMap } from './map_verify.js';
 import {
     affected,
     explain,
@@ -94,7 +110,16 @@ import {
 
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
-export const DEFAULT_CACHE = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'code-graph-v1.json');
+/**
+ * The cache belongs to the project it describes: `<root>/agents/runtime/state/`,
+ * the path MCP, the context hook and `detect` already read. Anchoring it to
+ * the package tree put a consumer's graph inside `node_modules`, where `npm ci`
+ * deleted it, two projects sharing an install overwrote each other, and MCP
+ * answered "no graph" right after the CLI reported a fresh one.
+ */
+export function cacheFor(root: string): string {
+    return path.join(root, NATIVE_CACHE_REL);
+}
 /** Local `tsx` binary — `refresh` spawns `build` as a child of THIS file
  * through it, so a budget-exceeded kill only ever terminates the child. */
 const TSX_BIN = path.join(REPO_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
@@ -106,47 +131,52 @@ function flag(argv: string[], name: string): string | null {
 }
 
 /**
- * Resolve the repository to operate on. `--root` > `AGENT_CONFIG_PROJECT_ROOT` >
- * this module's own tree.
- *
- * The middle rung is the whole point, and its absence was a confused deputy:
- * `_dispatch.bash` parses `--root` GLOBALLY, strips it from argv, and exports
- * `AGENT_CONFIG_PROJECT_ROOT` (`:1655`) — then this engine read neither and fell
- * back to its own module path. So `agent-config code-graph build --root <other
- * repo>` silently indexed THIS package. The dispatcher made the decision and the
- * engine substituted its own, which is why every consumer-facing invocation was
- * wrong about which repository it had just read.
+ * Resolve the repository to operate on: `--root` > the shared project-root
+ * resolver (`AGENT_CONFIG_PROJECT_ROOT`, then the anchor walk from `cwd`, then
+ * `cwd`). The package tree is never a fallback — in a consumer it is
+ * `node_modules/@event4u/agent-config`, and indexing it answered every
+ * question about the wrong repository.
  *
  * `realpathSync` rather than `resolve` alone: a symlinked root must normalise to
- * what will actually be walked, or the path a caller sees in the output is not
- * the path that was indexed. Fail-loud on a root that does not exist — a silent
- * fallback to the package tree is the defect this function exists to remove, and
- * reintroducing it for a typo'd path would be the same bug wearing a smaller
- * hat.
- *
- * Deliberately NOT touching `DEFAULT_CACHE`, which is anchored to `REPO_ROOT`
- * for the same reason and is a separate decision: it is a WRITE path, with its
- * own ownership, cleanup, concurrency and multi-repo namespacing questions.
- * Council 2026-08-22, both seats, explicitly out of scope here.
+ * what will actually be walked. A root that does not exist is returned
+ * unresolved, so the caller's existence check prints the path it was given.
  */
 function resolveRoot(argv: string[]): string {
     const explicit = flag(argv, '--root');
-    const fromDispatcher = process.env['AGENT_CONFIG_PROJECT_ROOT'];
-    const candidate =
-        explicit ?? (fromDispatcher !== undefined && fromDispatcher !== '' ? fromDispatcher : REPO_ROOT);
+    let candidate: string;
+    if (explicit !== null) {
+        candidate = explicit;
+    } else {
+        try {
+            candidate = resolve_project_root(null)[0];
+        } catch {
+            candidate = process.env['AGENT_CONFIG_PROJECT_ROOT'] ?? process.cwd();
+        }
+    }
     try {
         return fs.realpathSync(path.resolve(candidate));
     } catch {
-        // Returned unresolved on purpose: every caller checks existence and
-        // prints the path it was given, which is more useful in the error than
-        // a normalised form of a path that does not exist.
         return path.resolve(candidate);
     }
 }
 
+/**
+ * A cache an older version wrote inside the package directory is named once
+ * per build, so a consumer can delete it. Never deleted here: the path is
+ * outside the project the user pointed the verb at.
+ */
+function legacyCacheNotice(root: string): string {
+    const legacy = cacheFor(REPO_ROOT);
+    // Only an installed package is a wrong home for a cache; a source checkout
+    // of this repository legitimately keeps its own.
+    if (!REPO_ROOT.split(path.sep).includes('node_modules')) return '';
+    if (path.resolve(REPO_ROOT) === path.resolve(root) || !fs.existsSync(legacy)) return '';
+    return `    note: a stale cache from an older version sits inside the package: ${legacy} — safe to delete\n`;
+}
+
 async function cmdBuild(argv: string[]): Promise<number> {
     const root = resolveRoot(argv);
-    const out = argv.includes('--out') ? flag(argv, '--out') : DEFAULT_CACHE;
+    const out = argv.includes('--out') ? flag(argv, '--out') : cacheFor(root);
     if (!fs.existsSync(root)) {
         process.stderr.write(`code-graph: root not found: ${root}\n`);
         return 1;
@@ -160,7 +190,8 @@ async function cmdBuild(argv: string[]): Promise<number> {
             `    edges: EXTRACTED ${c.EXTRACTED} · INFERRED ${c.INFERRED} · AMBIGUOUS ${c.AMBIGUOUS}\n` +
             `    resolved_via: ${resolvedViaHistogram(graph)}\n` +
             (update ? `    incremental: ${reExtracted} re-extracted · ${reused} reused\n` : '') +
-            (out ? `    cache: ${path.relative(REPO_ROOT, out)}\n` : ''),
+            (out ? `    cache: ${path.relative(root, out)}\n` : '') +
+            legacyCacheNotice(root),
     );
     return 0;
 }
@@ -186,7 +217,8 @@ function resolvedViaHistogram(graph: CodeGraph): string {
 }
 
 function cmdValidate(argv: string[]): number {
-    const p = flag(argv, '--graph') ?? DEFAULT_CACHE;
+    const root = resolveRoot(argv);
+    const p = flag(argv, '--graph') ?? cacheFor(root);
     if (!fs.existsSync(p)) {
         process.stderr.write(`code-graph: graph not found: ${p}\n`);
         return 1;
@@ -215,12 +247,12 @@ function cmdValidate(argv: string[]): number {
     // content-addressed cache key, so agreement here means the twin was emitted
     // from THIS graph and not merely from a graph.
     const twinState = twinChecksumState(p, (parsed as CodeGraph).source_checksum);
-    const rel = path.relative(REPO_ROOT, p);
+    const rel = path.relative(root, p);
     if (twinState.kind === 'mismatch') {
         process.stderr.write(
             `❌  SQLite twin disagrees with the canonical JSON: twin ${twinState.twin} ≠ json ${twinState.json}\n` +
                 '    The twin is derived and disposable — delete it and re-run `code-graph build`.\n' +
-                `    ${path.relative(REPO_ROOT, sqliteTwinPath(p))}\n`,
+                `    ${path.relative(root, sqliteTwinPath(p))}\n`,
         );
         return 1;
     }
@@ -257,13 +289,13 @@ function resolveGraph(argv: string[]): { g: LoadedGraph; note: string } | { err:
     const root = resolveRoot(argv);
     if (explicit) {
         if (!fs.existsSync(explicit)) return { err: `graph not found: ${explicit}` };
-        return { g: loadGraph(explicit, path.relative(REPO_ROOT, explicit)), note: '' };
+        return { g: loadGraph(explicit, path.relative(root, explicit)), note: '' };
     }
-    const picked = pickSource(detectSources(root, DEFAULT_CACHE));
+    const picked = pickSource(detectSources(root, cacheFor(root)));
     if (!picked) return { err: 'no code-graph source found — run `code_graph build` or ship a graph.json' };
-    if (picked.kind === 'scip') return { err: `${picked.note ?? 'SCIP detected'} — pass --graph <json> or install peer tooling` };
+    if (picked.kind === 'scip') return { err: `${picked.note ?? 'SCIP detected'} — run \`code-graph build\` to merge it into the native graph` };
     const staleNote = picked.stale ? ` ⚠ index is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild before trusting` : '';
-    return { g: loadGraph(picked.path, `${picked.kind}:${path.relative(REPO_ROOT, picked.path)}`), note: staleNote };
+    return { g: loadGraph(picked.path, `${picked.kind}:${path.relative(root, picked.path)}`), note: staleNote };
 }
 
 function render(r: QueryResult, staleNote: string): number {
@@ -376,8 +408,8 @@ function isFlagValue(argv: string[], token: string): boolean {
  *
  * `answeredBy` is `resolveGraph`'s own picked path when it has one. Without it
  * the two disagreed on the case `resolveRoot`'s docstring exists for: with
- * `--root <other repo>` the verb answers from `DEFAULT_CACHE` (anchored to the
- * package tree) while `graphState` looked under the OTHER root, so the printed
+ * `--root <other repo>` the verb answered from a cache anchored to the
+ * package tree while `graphState` looked under the OTHER root, so the printed
  * staleness described a cache the answer never came from. An independent review
  * found the `--graph` half fixed and this half open.
  */
@@ -579,17 +611,17 @@ function cmdDetect(argv: string[]): number {
     if (flag(argv, '--format') === 'json') {
         // Machine-readable three-state verdict (Phase 2). Existing human-text
         // output below is unchanged for existing consumers.
-        process.stdout.write(`${JSON.stringify(computeVerdict(root, DEFAULT_CACHE))}\n`);
+        process.stdout.write(`${JSON.stringify(computeVerdict(root, cacheFor(root)))}\n`);
         return 0;
     }
-    const verdicts = detectSources(root, DEFAULT_CACHE);
+    const verdicts = detectSources(root, cacheFor(root));
     if (!verdicts.length) {
         process.stdout.write('no code-graph source detected\n');
         return 1;
     }
     for (const v of verdicts) {
         const fresh = v.stale === undefined ? '' : v.stale ? ` · STALE${v.commits_behind !== undefined ? ` (${v.commits_behind} behind)` : ''}` : ' · fresh';
-        process.stdout.write(`${v.kind.padEnd(9)} ${path.relative(REPO_ROOT, v.path)}${fresh}${v.note ? ` · ${v.note}` : ''}\n`);
+        process.stdout.write(`${v.kind.padEnd(9)} ${path.relative(root, v.path)}${fresh}${v.note ? ` · ${v.note}` : ''}\n`);
     }
     const picked = pickSource(verdicts);
     if (picked) process.stdout.write(`→ query would use: ${picked.kind}\n`);
@@ -644,7 +676,13 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
         }
     }
     const args = ['build', '--root', root, '--out', tmpOut, ...(update ? ['--update'] : [])];
-    const res = spawnSync(TSX_BIN, [_HERE, ...args], {
+    // A hoisted consumer install has no `tsx` under the package's own
+    // `node_modules`; re-entering through this process's own loader flags works
+    // wherever the parent itself started.
+    const [cmd, cmdArgs] = fs.existsSync(TSX_BIN)
+        ? [TSX_BIN, [_HERE, ...args]]
+        : [process.execPath, [...process.execArgv, _HERE, ...args]];
+    const res = spawnSync(cmd, cmdArgs, {
         env: hardenedSpawnEnv(),
         stdio: 'ignore',
         timeout: Math.round(budgetSeconds * 1000),
@@ -670,13 +708,13 @@ function runBudgetedBuild(root: string, out: string, update: boolean, budgetSeco
     fs.renameSync(tmpOut, out); // same-dir → atomic; real cache only ever changes here
     const tmpSidecar = sidecarPath(tmpOut);
     if (fs.existsSync(tmpSidecar)) fs.renameSync(tmpSidecar, sidecarPath(out));
-    process.stdout.write(`✅  code-graph refreshed — cache: ${path.relative(REPO_ROOT, out)}\n`);
+    process.stdout.write(`✅  code-graph refreshed — cache: ${path.relative(root, out)}\n`);
     return 0;
 }
 
 function cmdRefresh(argv: string[]): number {
     const root = resolveRoot(argv);
-    const out = flag(argv, '--out') ?? DEFAULT_CACHE;
+    const out = flag(argv, '--out') ?? cacheFor(root);
     const budgetSeconds = budgetSecondsOf(argv);
     if (!fs.existsSync(root)) {
         process.stderr.write(`code-graph: root not found: ${root}\n`);
@@ -690,6 +728,88 @@ function cmdRefresh(argv: string[]): number {
     return runBudgetedBuild(root, out, v.verdict === 'STALE', budgetSeconds);
 }
 
+/**
+ * `map` — draw the project map into `agents/map/` (ADR-297): `index.html`,
+ * `MAP.md`, one page per area and the `map.json` they are rendered from.
+ * Builds or updates the graph first when it is absent or behind.
+ */
+async function cmdMap(argv: string[]): Promise<number> {
+    const root = resolveRoot(argv);
+    if (!fs.existsSync(root)) {
+        process.stderr.write(`code-graph: root not found: ${root}\n`);
+        return 1;
+    }
+    const out = flag(argv, '--out');
+    const diffRev = flag(argv, '--diff');
+    const r = await buildMap(root, {
+        ...(out ? { outDir: path.resolve(out) } : {}),
+        ...(diffRev !== null ? { diffRev } : {}),
+        ...(argv.includes('--prs') ? { prs: true } : {}),
+        ...(argv.includes('--no-build') ? { noBuild: true } : {}),
+    });
+    const rel = path.relative(process.cwd(), r.outDir) || '.';
+    const largest = r.model.areas.find((a) => a.kind === 'area');
+    process.stdout.write(
+        `✅  code-graph map — ${r.meta.summary}\n` +
+            `    graph: ${r.graphBuilt ? 'rebuilt' : 'reused'} · state ${r.meta.state} · commit ${r.meta.commit}\n` +
+            (largest ? `    largest area: ${largest.name} (${largest.files.length} files)\n` : '') +
+            (r.model.diff
+                ? `    diff ${r.model.diff.rev}: ${r.model.diff.changed.length} changed · ${r.model.diff.impacted.length} linked into them · ${r.model.diff.areas.length} area(s) touched\n`
+                : '') +
+            `    wrote: ${r.written.length} files under ${rel}/ — open ${path.join(rel, 'index.html')}\n`,
+    );
+    let rc = 0;
+    if (argv.includes('--no-verify')) {
+        // A check from an earlier map must not sit beside this one as if it were about it.
+        fs.rmSync(path.join(r.outDir, 'map-render.json'), { force: true });
+    } else {
+        const check = await verifyMap(path.join(r.outDir, 'index.html'));
+        fs.writeFileSync(path.join(r.outDir, 'map-render.json'), `${JSON.stringify(check, null, 2)}\n`);
+        const problems = check.viewports
+            .flatMap((v) => [
+                ...(v.pageErrors ? [`${v.name}: ${v.pageErrors} page error(s)`] : []),
+                ...(v.externalRequests ? [`${v.name}: ${v.externalRequests} network request(s)`] : []),
+                ...(v.horizontalScroll ? [`${v.name}: horizontal scroll`] : []),
+                ...v.views.filter((x) => x.outside || x.overlapping).map((x) => `${v.name}/${x.view}: ${x.outside} label(s) cut off, ${x.overlapping} overlapping`),
+            ])
+            .join('; ');
+        process.stdout.write(
+            `    render check: ${check.verification}` +
+                (check.reason ? ` — ${check.reason}` : '') +
+                (problems ? ` — ${problems}` : check.verification === 'verified' ? ` — ${check.viewports.map((v) => v.name).join(', ')}` : '') +
+                '\n',
+        );
+        if (check.verification === 'failed') rc = 1;
+    }
+    if (argv.includes('--open')) {
+        const { default: open } = await import('open');
+        await open(path.join(r.outDir, 'index.html'));
+    }
+    return rc;
+}
+
+/**
+ * `outcome <path> useful|dead-end` — record, locally, that a session found a
+ * file useful or a dead end. The map draws the time-decayed result as a ring;
+ * nothing leaves the machine and nothing is committed.
+ */
+function cmdOutcome(argv: string[]): number {
+    const [file, outcome] = argv.filter((a) => !a.startsWith('--') && !isFlagValue(argv, a));
+    if (!file || (outcome !== 'useful' && outcome !== 'dead-end')) {
+        process.stderr.write('usage: code_graph/cli.ts outcome <path> useful|dead-end [--root P]\n');
+        return 2;
+    }
+    const root = resolveRoot(argv);
+    try {
+        recordOutcome(root, file, outcome);
+    } catch (e) {
+        process.stderr.write(`code-graph: ${(e as Error).message}\n`);
+        return 2;
+    }
+    process.stdout.write(`recorded: ${file} ${outcome}\n`);
+    return 0;
+}
+
 /**
  * `suggest-verb "<question>"` (Phase 9 D3) — print the `code_graph` verb a
  * pure regex table thinks best answers a free-text structure question. A
@@ -719,9 +839,11 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
         if (sub === 'untested') return cmdUntested(argv.slice(1));
         if (sub === 'dead') return cmdDead(argv.slice(1));
         if (sub === 'suggest-verb') return cmdSuggestVerb(argv.slice(1));
+        if (sub === 'map') return await cmdMap(argv.slice(1));
+        if (sub === 'outcome') return cmdOutcome(argv.slice(1));
         process.stderr.write(
             'usage: code_graph/cli.ts <build|validate|detect|refresh|query|explain|affected|path|' +
-                'impact|tests-for|untested|dead|suggest-verb> [options]\n',
+                'impact|tests-for|untested|dead|suggest-verb|map|outcome> [options]\n',
         );
         return 2;
     } catch (e) {

package/src/scripts/code_graph/detect.ts

@@ -3,9 +3,9 @@
  * query use, and is it fresh?" across three sources:
  *
  *   consumer  — a `graph.json`-shaped artifact the consumer repo ships
- *   scip      — an `index.scip` / `*.scip` (presence only; peer tooling
- *               required — an owned SCIP reader is YAGNI-gated until a
- *               consumer actually ships one)
+ *   scip      — an `index.scip`, read into the native build as a provider of
+ *               compiler-stated edges (`scip_reader.ts`); never queried on
+ *               its own
  *   native    — the suite's own gitignored cache
  *
  * Precedence (ADR-124 § 2): a fresh consumer index wins (interop courtesy);
@@ -156,7 +156,8 @@ export function detectSources(root: string, nativeCache: string): SourceVerdict[
         /* ignore */
     }
     const scip = scipCandidates.find((p) => fs.existsSync(p));
-    if (scip) out.push({ kind: 'scip', path: scip, present: true, note: 'SCIP detected — peer tooling required (no owned reader)' });
+    // Only `index.scip` is read; another `*.scip` is reported, not merged.
+    if (scip) out.push({ kind: 'scip', path: scip, present: true, note: 'SCIP — index.scip merges into the build' });
 
     // native cache
     if (fs.existsSync(nativeCache)) out.push({ kind: 'native', path: nativeCache, present: true, ...freshness(abs, nativeCache, null) });

package/src/scripts/code_graph/docs_layer.ts

@@ -0,0 +1,57 @@
+/**
+ * The docs layer: a Markdown file that names a file gets an edge to it.
+ *
+ * Read by rule, not by a model (road-to-a-map-that-draws-itself 6.3, K10):
+ *
+ *   [text](relative/or/rooted/path)       a link, resolved from the document's directory
+ *   `src/scripts/x.ts` · `x.ts:42`         a backticked path, resolved repo-relative first
+ *
+ * An edge is emitted only when the named file is in the tree, so a link to a
+ * URL, an anchor, or a path that moved away produces nothing rather than a guess.
+ */
+import * as path from 'node:path';
+
+import type { SourceFile } from './build.js';
+import type { CodeEdge, CodeNode } from './types.js';
+import { MAX_FILE_BYTES } from './types.js';
+
+export const DOC_EXTS: ReadonlySet<string> = new Set(['.md', '.mdx']);
+
+function normal(p: string): string {
+    return path.posix.normalize(p).replace(/^\.\//, '');
+}
+
+export function docsLayer(docs: readonly SourceFile[], fileIds: ReadonlySet<string>): { nodes: CodeNode[]; edges: CodeEdge[] } {
+    const nodes: CodeNode[] = [];
+    const edges: CodeEdge[] = [];
+    for (const d of [...docs].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+        nodes.push({ id: d.path, label: d.path, kind: 'file', source_file: d.path, source_location: [] });
+        if (Buffer.byteLength(d.source, 'utf-8') > MAX_FILE_BYTES) continue;
+        const dir = path.posix.dirname(d.path);
+        const targets = new Set<string>();
+        const consider = (raw: string, fromDocDir: boolean): void => {
+            const clean = raw.trim().replace(/[#?].*$/, '').replace(/:\d+(?:-\d+)?$/, '');
+            if (!clean || /^[a-z][a-z0-9+.-]*:/i.test(clean) || clean.includes('*')) return;
+            const candidates = clean.startsWith('/')
+                ? [normal(clean.slice(1))]
+                : fromDocDir
+                  ? [normal(path.posix.join(dir, clean)), normal(clean)]
+                  : [normal(clean), normal(path.posix.join(dir, clean))];
+            const hit = candidates.find((c) => !c.startsWith('..') && fileIds.has(c));
+            if (hit && hit !== d.path) targets.add(hit);
+        };
+        for (const m of d.source.matchAll(/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g)) consider(m[1] as string, true);
+        for (const m of d.source.matchAll(/`([\w@./-]+\/[\w@.-]+\.[A-Za-z0-9]+(?::\d+(?:-\d+)?)?)`/g)) consider(m[1] as string, false);
+        for (const t of [...targets].sort()) {
+            edges.push({
+                source: d.path,
+                target: t,
+                relation: 'documents',
+                confidence: 'EXTRACTED',
+                resolved_via: 'directive-scan',
+                provider: 'native',
+            });
+        }
+    }
+    return { nodes, edges };
+}

package/src/scripts/code_graph/extract.ts

@@ -20,6 +20,7 @@ import {
     MAX_FILE_BYTES,
     type Relation,
 } from './types.js';
+import { extractGo, extractJava, extractPython } from './extract_more.js';
 import { getParser, nodeHasError, type TsNode } from './loader.js';
 
 export type CallStyle = 'new' | 'free' | 'this' | 'self' | 'static' | 'parent' | 'scoped' | 'dynamic';
@@ -89,7 +90,7 @@ export interface FileExtract {
     parseError: boolean;
 }
 
-function loc(n: TsNode): number[] {
+export function loc(n: TsNode): number[] {
     return [
         n.startPosition.row + 1,
         n.startPosition.column + 1,
@@ -98,7 +99,7 @@ function loc(n: TsNode): number[] {
     ];
 }
 
-function namedChildren(n: TsNode): TsNode[] {
+export function namedChildren(n: TsNode): TsNode[] {
     const out: TsNode[] = [];
     for (let i = 0; i < n.namedChildCount; i += 1) {
         const c = n.namedChild(i);
@@ -117,7 +118,7 @@ function firstNamed(n: TsNode, types: ReadonlySet<string>): TsNode | null {
     return null;
 }
 
-function nameField(n: TsNode): string | null {
+export function nameField(n: TsNode): string | null {
     const nm = n.childForFieldName('name');
     if (nm) return nm.text;
     return null;
@@ -131,6 +132,26 @@ function baseName(raw: string): string {
     return parts[parts.length - 1] ?? s;
 }
 
+/**
+ * Ids are `${file}#${name}`, so two same-named declarations in one file — a
+ * `type X` beside a `const X`, a getter and its setter, two nested helpers both
+ * called `walk` — used to share one id. The SQLite twin's PRIMARY KEY then
+ * refused the insert and the index was silently never written. The second and
+ * later declarations get `@2`, `@3`, … in declaration order, which the walk
+ * visits deterministically.
+ */
+const takenIds = new WeakMap<FileExtract, Map<string, number>>();
+export function uniq(out: FileExtract, base: string): string {
+    let seen = takenIds.get(out);
+    if (!seen) {
+        seen = new Map();
+        takenIds.set(out, seen);
+    }
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return n === 1 ? base : `${base}@${n}`;
+}
+
 // ── PHP ──────────────────────────────────────────────────────────────────────
 
 function extractPhp(root: TsNode, file: string, out: FileExtract): void {
@@ -163,7 +184,7 @@ function extractPhp(root: TsNode, file: string, out: FileExtract): void {
                         : n.type === 'interface_declaration'
                           ? 'interface'
                           : 'trait';
-                const id = `${file}#${nm}`;
+                const id = uniq(out, `${file}#${nm}`);
                 out.nodes.push({ id, label: nm, kind, source_file: file, source_location: loc(n) });
                 out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
                 // extends / implements
@@ -198,7 +219,7 @@ function extractPhp(root: TsNode, file: string, out: FileExtract): void {
             case 'method_declaration':
             case 'function_definition': {
                 const nm = nameField(n) ?? '<anon>';
-                const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
                 out.nodes.push({
                     id,
                     label: nm,
@@ -377,14 +398,14 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                         : n.type === 'type_alias_declaration'
                           ? 'type'
                           : 'enum';
-                const id = `${file}#${nm}`;
+                const id = uniq(out, `${file}#${nm}`);
                 out.nodes.push({ id, label: nm, kind, source_file: file, source_location: loc(n) });
                 out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
                 return;
             }
             case 'class_declaration': {
                 const nm = nameField(n) ?? '<anon>';
-                const id = `${file}#${nm}`;
+                const id = uniq(out, `${file}#${nm}`);
                 out.nodes.push({ id, label: nm, kind: 'class', source_file: file, source_location: loc(n) });
                 out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
                 const heritage = firstNamed(n, new Set(['class_heritage']));
@@ -399,7 +420,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
             }
             case 'method_definition': {
                 const nm = nameField(n) ?? '<anon>';
-                const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
                 out.nodes.push({ id, label: nm, kind: 'method', source_file: file, source_location: loc(n) });
                 out.rawEdges.push({
                     sourceId: classId ?? fileId,
@@ -413,7 +434,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
             }
             case 'function_declaration': {
                 const nm = nameField(n) ?? '<anon>';
-                const id = `${file}#${nm}`;
+                const id = uniq(out, `${file}#${nm}`);
                 out.nodes.push({ id, label: nm, kind: 'function', source_file: file, source_location: loc(n) });
                 out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
                 const body = n.childForFieldName('body');
@@ -457,7 +478,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                         // none of them is a declaration this graph can id.
                         if (topLevel && nmNode?.type === 'identifier') {
                             const nm = nmNode.text;
-                            const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                            const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
                             out.nodes.push({
                                 id,
                                 label: nm,
@@ -482,7 +503,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                         continue;
                     }
                     const nm = nameField(d) ?? '<anon>';
-                    const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                    const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
                     out.nodes.push({
                         id,
                         label: nm,
@@ -519,7 +540,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                 const value = n.childForFieldName('value');
                 const nm = nameField(n) ?? '<anon>';
                 if (value && (value.type === 'arrow_function' || value.type === 'function_expression')) {
-                    const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                    const id = uniq(out, classId ? `${classId}::${nm}` : `${file}#${nm}`);
                     out.nodes.push({
                         id,
                         label: nm,
@@ -634,6 +655,27 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
     walk(root, null, fileId, true);
 }
 
+/**
+ * A Vue single-file component reduced to its `<script>` blocks: every
+ * character outside them becomes a space and every newline stays, so the
+ * TypeScript grammar parses the script and every location still points at
+ * the line in the `.vue` file.
+ */
+export function vueScript(source: string): string {
+    const keep = new Array<boolean>(source.length).fill(false);
+    for (const m of source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)) {
+        const start = (m.index as number) + m[0].indexOf('>') + 1;
+        const end = start + (m[1] as string).length;
+        for (let i = start; i < end; i++) keep[i] = true;
+    }
+    let out = '';
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i] as string;
+        out += keep[i] || c === '\n' ? c : ' ';
+    }
+    return out;
+}
+
 /**
  * Extract one file. `source` is the file's UTF-8 content; `relPath` is the
  * repo-relative POSIX path used to build collision-free node ids.
@@ -651,10 +693,13 @@ export async function extractFile(relPath: string, source: string, lang: Lang):
         return out;
     }
     const parser = await getParser(lang);
-    const tree = parser.parse(source);
+    const tree = parser.parse(relPath.endsWith('.vue') ? vueScript(source) : source);
     try {
         out.parseError = nodeHasError(tree.rootNode);
         if (lang === 'php') extractPhp(tree.rootNode, relPath, out);
+        else if (lang === 'python') extractPython(tree.rootNode, relPath, out);
+        else if (lang === 'java') extractJava(tree.rootNode, relPath, out);
+        else if (lang === 'go') extractGo(tree.rootNode, relPath, out);
         else extractTsJs(tree.rootNode, relPath, out);
     } finally {
         tree.delete(); // delete the tree, never the cached parser (loader.ts)