@event4u/agent-config 14.17.0 → 14.18.0

package/src/scripts/code_graph/build.ts

@@ -20,6 +20,7 @@ import { emitSqliteTwin } from './sqlite_store.js';
 import {
     type CodeEdge,
     type CodeGraph,
+    type EdgeConfidence,
     EXPECTED_GRAMMAR_ABI,
     EXT_LANG,
     type Lang,
@@ -110,6 +111,87 @@ interface SymbolTable {
     classByName: Map<string, string>;
 }
 
+/**
+ * What a resolved name is allowed to BE at a given use site.
+ *
+ * The council that reviewed this repair made the same point from both seats: a
+ * confidence label cannot contain a false edge, only describe one, so the
+ * candidate set has to be filtered by capability BEFORE a confidence is
+ * assigned. A `const` cannot satisfy `foo()`; a `type` alias cannot satisfy
+ * `new T()`. Without this, adding constant/type/enum nodes in 2.1 would feed
+ * the very same-name table that produced the false `path` edge in the first
+ * place.
+ */
+type Capability = 'callable' | 'constructible' | 'any';
+const CALLABLE_KINDS: ReadonlySet<string> = new Set(['function', 'method']);
+const CONSTRUCTIBLE_KINDS: ReadonlySet<string> = new Set(['class']);
+
+function satisfies(kind: string | undefined, want: Capability): boolean {
+    if (kind === undefined) return true; // a file id / external ref — unknown, not disqualified
+    if (want === 'callable') return CALLABLE_KINDS.has(kind);
+    if (want === 'constructible') return CONSTRUCTIBLE_KINDS.has(kind);
+    return true;
+}
+
+/**
+ * One file's name bindings — the thing this engine did not have, and whose
+ * absence is the whole of defect 1.1.
+ *
+ * `locals` is every symbol DECLARED in the file. `imports` is every name the
+ * file BINDS from elsewhere, keyed on the local binding name, carrying whether
+ * the binding was resolved from a module specifier (`exact`) or merely matched
+ * by name (PHP `use`, which names a fully-qualified symbol and is matched on
+ * its base name without checking the namespace).
+ */
+interface FileScope {
+    locals: Map<string, string[]>;
+    imports: Map<string, { target: string; exact: boolean }>;
+}
+
+const REL_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+
+/** POSIX-only join/dirname over graph ids, which are always POSIX-relative. */
+function idDirname(id: string): string {
+    const i = id.lastIndexOf('/');
+    return i === -1 ? '' : id.slice(0, i);
+}
+function idJoin(dir: string, rel: string): string {
+    const parts = (dir === '' ? [] : dir.split('/')).concat(rel.split('/'));
+    const out: string[] = [];
+    for (const p of parts) {
+        if (p === '' || p === '.') continue;
+        if (p === '..') {
+            // A `..` that would escape the root is KEPT, so the caller can see
+            // the specifier points outside the indexed tree rather than
+            // silently resolving to something inside it.
+            if (out.length && out[out.length - 1] !== '..') out.pop();
+            else out.push('..');
+            continue;
+        }
+        out.push(p);
+    }
+    return out.join('/');
+}
+
+/**
+ * A relative module specifier → the id of the file node it names, or `null`
+ * when that file is not in this graph (out of root, or an unsupported
+ * extension). A bare specifier (`node:path`, `js-yaml`) is external by
+ * definition and returns `null` too — the caller distinguishes the two by
+ * looking at the specifier itself.
+ *
+ * TS source imports `./types.js` and the file on disk is `types.ts`, so the
+ * runtime extension is stripped before the candidate list is tried.
+ */
+function resolveSpecifier(fromFile: string, spec: string, fileIds: ReadonlySet<string>): string | null {
+    if (!spec.startsWith('.')) return null;
+    const base = idJoin(idDirname(fromFile), spec);
+    const stem = base.replace(/\.(js|jsx|mjs|cjs)$/, '');
+    const candidates = [base, ...REL_EXTS.map((e) => stem + e), ...REL_EXTS.map((e) => base + '/index' + e)];
+    for (const c of candidates) if (fileIds.has(c)) return c;
+    return null;
+}
+
 function push(map: Map<string, string[]>, k: string, v: string): void {
     const arr = map.get(k);
     if (arr) {
@@ -146,6 +228,11 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
     };
     for (const n of nodes) {
         const lang = nodeLang.get(n.id) ?? null;
+        // `byName` stays the CALLABLE/CONSTRUCTIBLE table it always was. The
+        // kinds 2.1 added (constant / type / enum) are deliberately NOT put in
+        // it: they are reachable through a file's own scope and through
+        // `imports`, and letting them satisfy a bare `foo()` by name is the
+        // defect this roadmap removes, not a feature it adds.
         if (n.kind === 'class' || n.kind === 'interface' || n.kind === 'trait' || n.kind === 'function') {
             push(sym.byName, k(lang, n.label), n.id);
             if (n.kind !== 'function' && !sym.classByName.has(k(lang, n.label)))
@@ -184,6 +271,87 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         return null;
     };
 
+    const nodeKind = new Map(nodes.map((n) => [n.id, n.kind as string]));
+    const fileIds = new Set(nodes.filter((n) => n.kind === 'file').map((n) => n.id));
+    const scopes = new Map<string, FileScope>();
+    for (const ex of extracts) {
+        const locals = new Map<string, string[]>();
+        for (const n of ex.nodes) if (n.kind !== 'file') push(locals, n.label, n.id);
+        const imports = new Map<string, { target: string; exact: boolean }>();
+        for (const r of ex.rawEdges) {
+            if (r.relation !== 'imports') continue;
+            const local = r.localName ?? r.targetName;
+            if (imports.has(local)) continue; // first binding wins, deterministically
+            const spec = r.moduleSpecifier;
+            if (spec === undefined) {
+                // PHP `use A\B\C` — a fully-qualified NAME, not a module path.
+                // Resolved by base name without checking the namespace, so the
+                // binding is a lookup, not a syntactic fact: `exact: false`.
+                const hit =
+                    sym.classByName.get(k(ex.lang, r.targetName)) ??
+                    (sym.byName.get(k(ex.lang, r.targetName)) ?? []).find((id) => id.includes('#') && !id.includes('::'));
+                if (hit) imports.set(local, { target: hit, exact: false });
+                continue;
+            }
+            const file = resolveSpecifier(ex.file, spec, fileIds);
+            if (file === null) {
+                // Bare (`node:path`, `zod`) or relative-but-out-of-root. Either
+                // way the module is real and NAMED, and it is not this
+                // repository's same-named symbol. `import * as path from
+                // 'node:path'` ends here, which is the whole of 1.1.
+                const named = r.importKind === 'named';
+                imports.set(local, { target: named ? `external:${spec}#${r.targetName}` : `external:${spec}`, exact: true });
+                continue;
+            }
+            // A namespace or default import binds the MODULE, never a
+            // same-named export inside it.
+            const member = `${file}#${r.targetName}`;
+            const target = r.importKind === 'named' && nodeKind.has(member) ? member : file;
+            imports.set(local, { target, exact: true });
+        }
+        scopes.set(ex.file, { locals, imports });
+    }
+    const emptyScope: FileScope = { locals: new Map(), imports: new Map() };
+
+    /**
+     * Resolve a bare name at a use site inside `file`, capability-filtered.
+     *
+     * The ladder is the language's own: a LOCAL declaration shadows an import
+     * (both council seats named this, and JS/TS/PHP all agree), an import
+     * resolved from a specifier is next, and only then the repo-wide same-name
+     * table — which is a guess and is labelled as one.
+     */
+    const resolveInScope = (
+        file: string,
+        name: string,
+        want: Capability,
+        lang: Lang,
+        scopeOnly = false,
+    ): { target: string; confidence: EdgeConfidence } | null => {
+        const scope = scopes.get(file) ?? emptyScope;
+        for (const id of scope.locals.get(name) ?? [])
+            if (satisfies(nodeKind.get(id), want)) return { target: id, confidence: 'EXTRACTED' };
+        const bound = scope.imports.get(name);
+        if (bound && satisfies(nodeKind.get(bound.target), want))
+            return { target: bound.target, confidence: bound.exact ? 'EXTRACTED' : 'INFERRED' };
+        if (scopeOnly) return null;
+        const wide =
+            want === 'constructible'
+                ? sym.classByName.get(k(lang, name))
+                : (sym.byName.get(k(lang, name)) ?? []).find(
+                      (id) => id.includes('#') && !id.includes('::') && satisfies(nodeKind.get(id), want),
+                  );
+        // Reached only by matching a name across the whole repository, with no
+        // binding in this file to justify it. That is not a syntactic fact and
+        // no longer claims to be one.
+        if (wide) return { target: wide, confidence: 'INFERRED' };
+        return null;
+    };
+
+    // Deduped the same way emitted edges are, so the count is comparable to
+    // `edges.length` rather than being a raw call-site tally that reads as a
+    // larger loss than the graph actually took.
+    const suppressedKeys = new Set<string>();
     const edges: CodeEdge[] = [];
     const seen = new Set<string>();
     const emit = (e: CodeEdge): void => {
@@ -198,8 +366,13 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
     for (const ex of extracts) {
         // structural inherits edges (same-language resolution)
         for (const inh of ex.inherits) {
-            const parentId = sym.classByName.get(k(ex.lang, inh.parentName)) ?? `symbol:${inh.parentName}`;
-            emit({ source: inh.classId, target: parentId, relation: 'inherits', confidence: 'EXTRACTED' });
+            const hit = resolveInScope(ex.file, inh.parentName, 'constructible', ex.lang);
+            emit({
+                source: inh.classId,
+                target: hit?.target ?? `symbol:${inh.parentName}`,
+                relation: 'inherits',
+                confidence: hit?.confidence ?? 'EXTRACTED',
+            });
         }
         for (const r of ex.rawEdges) resolveRawEdge(r, ex);
     }
@@ -216,50 +389,50 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
             });
             return;
         }
-        if (r.relation === 'imports' || r.relation === 'uses') {
-            // A class name first, which is what `imports` and the pre-existing
-            // `uses` sites emit. Then a FREE FUNCTION, which the registry
-            // literals added by 1.3 point at: `{ foo: handleFoo }` names a
-            // function, not a class, so a class-only lookup left every such edge
-            // at `symbol:<name>` — an edge that exists and resolves nowhere,
-            // which is barely better than the missing edge it replaced.
-            //
-            // Same predicate as the `free` call branch below (`#` and no `::`),
-            // so a function reference and a function call resolve identically
-            // rather than by two rules that can drift.
-            const resolved =
-                sym.classByName.get(k(ex.lang, r.targetName)) ??
-                (sym.byName.get(k(ex.lang, r.targetName)) ?? []).find(
-                    (id) => id.includes('#') && !id.includes('::'),
-                );
+        if (r.relation === 'imports') {
+            // The import's own binding, computed once per file above. A
+            // specifier-resolved binding is a syntactic fact — the file says
+            // where the name comes from — and a PHP `use` matched by base name
+            // is not, and says so.
+            const bound = (scopes.get(ex.file) ?? emptyScope).imports.get(r.localName ?? r.targetName);
             emit({
                 source: r.sourceId,
-                target: resolved ?? `symbol:${r.targetName}`,
-                relation: r.relation,
-                confidence: 'EXTRACTED',
+                target: bound?.target ?? `symbol:${r.targetName}`,
+                relation: 'imports',
+                confidence: bound ? (bound.exact ? 'EXTRACTED' : 'INFERRED') : 'EXTRACTED',
             });
             return;
         }
-        // relation === 'calls'
-        if (r.callStyle === 'new') {
-            const resolved = sym.classByName.get(k(ex.lang, r.targetName));
+        if (r.relation === 'uses') {
+            // A registry literal (`{ foo: handleFoo }`) or an object shorthand
+            // (`{ id, label }`) names something bound IN THIS FILE. It is
+            // resolved through the file's scope and NOWHERE else: a shorthand
+            // property almost always names a local variable, and matching it
+            // against a same-named declaration elsewhere in the repository is
+            // the defect this roadmap removes, applied to a second relation.
+            const hit = resolveInScope(ex.file, r.targetName, 'any', ex.lang, true);
             emit({
                 source: r.sourceId,
-                target: resolved ?? `symbol:${r.targetName}`,
-                relation: 'calls',
-                confidence: 'EXTRACTED',
+                target: hit?.target ?? `symbol:${r.targetName}`,
+                relation: 'uses',
+                confidence: hit?.confidence ?? 'EXTRACTED',
             });
             return;
         }
-        if (r.callStyle === 'free') {
-            const resolved = (sym.byName.get(k(ex.lang, r.targetName)) ?? []).find(
-                (id) => id.includes('#') && !id.includes('::'),
-            );
+        // relation === 'calls'
+        if (r.callStyle === 'new' || r.callStyle === 'free') {
+            const want: Capability = r.callStyle === 'new' ? 'constructible' : 'callable';
+            const hit = resolveInScope(ex.file, r.targetName, want, ex.lang);
             emit({
                 source: r.sourceId,
-                target: resolved ?? `symbol:${r.targetName}`,
+                target: hit?.target ?? `symbol:${r.targetName}`,
                 relation: 'calls',
-                confidence: 'EXTRACTED',
+                // An UNRESOLVED name stays EXTRACTED: `symbol:strlen` claims
+                // nothing about a node, it records that a call to a name this
+                // repository does not declare happened here. What is no longer
+                // EXTRACTED is a claim about a SPECIFIC in-repo node reached by
+                // name alone.
+                confidence: hit?.confidence ?? 'EXTRACTED',
             });
             return;
         }
@@ -287,6 +460,27 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         }
         // scoped (Class::m unresolved / facade) or dynamic ($obj->m) → AMBIGUOUS
         const cands = methodCandidates(r.targetName, ex.lang);
+        if (r.callStyle === 'dynamic' && cands.length === 0) {
+            // `x.push()`, `m.get()`, `s.join()` — a dynamic member call whose
+            // method name matches NO method declared in this repository. The
+            // only target available is `symbol:push`, which is not a node, so
+            // no query verb can reach it: `affected` and `path` resolve seeds
+            // against real nodes and a pseudo-node is never one. It was 257 of
+            // 660 edges on this engine's own source — 39 % of the graph
+            // asserting "a method named push was called somewhere".
+            //
+            // NOT suppressed: a `scoped` call (`Cache::get()`) and a
+            // `hierarchy-unresolved` `$this->missing()` both name a real
+            // unresolved intent inside a known receiver, which a later
+            // resolution pass could settle. This drops only the class where
+            // there is nothing to settle.
+            //
+            // The count is published in `suppressed_edge_counts` — an engine
+            // that silently deletes its worst edges reports a flattering
+            // confidence ratio and no evidence.
+            suppressedKeys.add(`${r.sourceId}\0calls\0symbol:${r.targetName}`);
+            return;
+        }
         emit({
             source: r.sourceId,
             target: ambiguousTarget(cands, r.targetName),
@@ -310,6 +504,7 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
 
     const counts = { EXTRACTED: 0, INFERRED: 0, AMBIGUOUS: 0 };
     for (const e of edges) counts[e.confidence] += 1;
+    const suppressed = { dynamic_no_candidate: suppressedKeys.size };
 
     const languages = [...new Set(extracts.map((e) => e.lang))].sort() as Lang[];
 
@@ -328,6 +523,7 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         languages,
         grammar_abi: EXPECTED_GRAMMAR_ABI,
         edge_confidence_counts: counts,
+        suppressed_edge_counts: suppressed,
         nodes,
         edges,
     };
@@ -370,6 +566,7 @@ export function serializeGraph(g: CodeGraph): string {
         'languages',
         'grammar_abi',
         'edge_confidence_counts',
+        'suppressed_edge_counts',
         'nodes',
         'edges',
     ];

package/src/scripts/code_graph/extract.ts

@@ -36,6 +36,37 @@ export interface RawEdge {
     enclosingClassId?: string;
     /** scope token for `Scope::m()` scoped calls (a class name / self / static). */
     scopeName?: string;
+    /**
+     * `imports` only: the module specifier as written (`'./types.js'`,
+     * `'node:path'`), stripped of its quotes.
+     *
+     * Before this field the extractor read the import CLAUSE and threw the
+     * `from` away, so the build pass had nothing to resolve against but a
+     * repo-wide same-name table — which is how `import * as path from
+     * 'node:path'` came to bind to this repository's own `path()` function in
+     * `query.ts`, at `EXTRACTED`, in four of eleven files. The specifier is the
+     * one piece of evidence that says WHERE the name came from, and it is in
+     * the source text; discarding it turned a syntactic fact into a guess.
+     *
+     * Absent for PHP `use`, which names a fully-qualified symbol rather than a
+     * module path — those still resolve by name, and the build pass labels them
+     * accordingly.
+     */
+    moduleSpecifier?: string;
+    /**
+     * `imports` only: which import form produced this binding. `namespace`
+     * (`import * as x`) and `default` bind the MODULE (or its default export),
+     * never a named export, so neither may be matched against a same-named
+     * symbol inside the target file.
+     */
+    importKind?: 'namespace' | 'named' | 'default';
+    /**
+     * `imports` only: the LOCAL binding name, when it differs from
+     * `targetName` (`import { foo as bar }` → targetName `foo`, localName
+     * `bar`). The file's scope is keyed on the local name; the target file is
+     * searched for the remote one.
+     */
+    localName?: string;
 }
 
 export interface FileExtract {
@@ -245,29 +276,101 @@ function extractPhp(root: TsNode, file: string, out: FileExtract): void {
 
 // ── TypeScript / JavaScript ───────────────────────────────────────────────────
 
+/**
+ * Node types that open a new function or class scope. A `const` inside one of
+ * these is a LOCAL variable, not a module-level declaration, and emitting a
+ * node for it would put every loop counter in the symbol table — the
+ * count-inflation failure `2.1` is explicitly not allowed to cause.
+ */
+const TS_SCOPE_INTRODUCERS = new Set([
+    'arrow_function',
+    'function_expression',
+    'function_declaration',
+    'generator_function',
+    'generator_function_declaration',
+    'method_definition',
+    'class_declaration',
+    'class',
+    'class_body',
+]);
+
 function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
     const fileId = file;
 
-    const walk = (n: TsNode, classId: string | null, scopeId: string): void => {
+    const walk = (n: TsNode, classId: string | null, scopeId: string, topLevel: boolean): void => {
+        // A declaration is module-level until the walk descends through a
+        // function or class scope; from there down it is a local.
+        const inner = topLevel && !TS_SCOPE_INTRODUCERS.has(n.type);
         switch (n.type) {
             case 'import_statement': {
+                const src = n.childForFieldName('source');
+                // The specifier node is a `string`; its text carries the quotes.
+                const specifier = src ? src.text.replace(/^['"`]/, '').replace(/['"`]$/, '') : undefined;
                 const clause = firstNamed(n, new Set(['import_clause']));
+                const emitImport = (
+                    remote: string,
+                    local: string,
+                    importKind: 'namespace' | 'named' | 'default',
+                ): void => {
+                    out.rawEdges.push({
+                        sourceId: fileId,
+                        relation: 'imports',
+                        targetName: baseName(remote),
+                        confidenceHint: 'EXTRACTED',
+                        ...(specifier === undefined ? {} : { moduleSpecifier: specifier }),
+                        importKind,
+                        ...(local === remote ? {} : { localName: local }),
+                    });
+                };
                 if (clause) {
-                    for (const spec of namedChildren(clause)) {
-                        for (const idn of [spec, ...namedChildren(spec)])
-                            if (idn.type === 'identifier' || idn.type === 'import_specifier') {
-                                const nm = idn.type === 'import_specifier' ? nameField(idn) ?? idn.text : idn.text;
-                                out.rawEdges.push({
-                                    sourceId: fileId,
-                                    relation: 'imports',
-                                    targetName: baseName(nm),
-                                    confidenceHint: 'EXTRACTED',
-                                });
+                    for (const child of namedChildren(clause)) {
+                        if (child.type === 'namespace_import') {
+                            // `import * as path from 'node:path'` — the binding
+                            // is the MODULE. Matching `path` against a local
+                            // symbol of the same name is the false edge 1.1
+                            // exists to remove.
+                            const idn = firstNamed(child, new Set(['identifier']));
+                            if (idn) emitImport(idn.text, idn.text, 'namespace');
+                        } else if (child.type === 'named_imports') {
+                            for (const sp of namedChildren(child)) {
+                                if (sp.type !== 'import_specifier') continue;
+                                const nameNode = sp.childForFieldName('name');
+                                const aliasNode = sp.childForFieldName('alias');
+                                const remote = nameNode ? nameNode.text : sp.text;
+                                emitImport(remote, aliasNode ? aliasNode.text : remote, 'named');
                             }
+                        } else if (child.type === 'identifier') {
+                            emitImport(child.text, child.text, 'default');
+                        }
                     }
                 }
                 return;
             }
+            // `const`, `type`, `interface`, `enum` — the shapes the v2 corpus
+            // asks `references` questions about (`EXT_LANG` is a const,
+            // `SettingsClass` a type alias). The extractor used to emit none of
+            // them, which is the named mechanical cause of `references` recall
+            // 0.333 against grep's 1.000.
+            //
+            // The body is not walked: a type or interface position holds no
+            // call sites, and an enum body holds member names rather than
+            // symbols this graph answers questions about.
+            case 'interface_declaration':
+            case 'type_alias_declaration':
+            case 'enum_declaration': {
+                const nmNode = n.childForFieldName('name') ?? firstNamed(n, NAME_TYPES);
+                const nm = nmNode ? nmNode.text : '<anon>';
+                const kind =
+                    n.type === 'interface_declaration'
+                        ? 'interface'
+                        : n.type === 'type_alias_declaration'
+                          ? 'type'
+                          : 'enum';
+                const id = `${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}`;
@@ -280,7 +383,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                             if (idn.type === 'identifier' || idn.type === 'type_identifier')
                                 out.inherits.push({ classId: id, parentName: baseName(idn.text) });
                 const body = n.childForFieldName('body');
-                if (body) for (const c of namedChildren(body)) walk(c, id, id);
+                if (body) for (const c of namedChildren(body)) walk(c, id, id, false);
                 return;
             }
             case 'method_definition': {
@@ -294,7 +397,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                     confidenceHint: 'EXTRACTED',
                 });
                 const body = n.childForFieldName('body');
-                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id, false);
                 return;
             }
             case 'function_declaration': {
@@ -303,7 +406,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                 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');
-                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id, false);
                 return;
             }
             // Modern TS declares most of its functions as bindings, not as
@@ -313,17 +416,58 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
             // 170-vs-13,428 TS/PHP symbol gap: the six handled kinds simply do
             // not cover the dominant declaration form.
             //
-            // Scoped deliberately to bindings whose value IS a function. A
-            // `const x = 3` is data, not a symbol this graph answers questions
-            // about, and emitting a node per constant would inflate the count
-            // without improving recall — which is the cosmetic-improvement
-            // failure the phase falsifier exists to catch.
+            // The scoping note that stood here said a `const x = 3` is "data,
+            // not a symbol this graph answers questions about", and that
+            // emitting a node per constant would raise the count without
+            // improving recall. **The v2 benchmark falsified the first half and
+            // the second half no longer follows.** Two of its three
+            // `references` questions probe exactly this shape — `EXT_LANG` (a
+            // const) and `SettingsClass` (a type alias) — and the class scored
+            // recall 0.333 against grep's 1.000 because neither had a node to
+            // resolve to. The count-inflation worry was real and is answered by
+            // SCOPE rather than by refusal: a binding earns a node only at
+            // MODULE level (`topLevel`), so a loop counter inside a function
+            // body still gets none. The reason is kept rather than deleted,
+            // because a reversed decision whose reason disappears gets re-taken.
             case 'lexical_declaration':
             case 'variable_declaration': {
                 for (const d of namedChildren(n)) {
                     if (d.type !== 'variable_declarator') continue;
                     const value = d.childForFieldName('value');
-                    if (!value || (value.type !== 'arrow_function' && value.type !== 'function_expression')) {
+                    const nmNode = d.childForFieldName('name');
+                    const isFn =
+                        value !== null &&
+                        value !== undefined &&
+                        (value.type === 'arrow_function' || value.type === 'function_expression');
+                    const isClassExpr = value?.type === 'class';
+                    if (!isFn) {
+                        // Only a plain `identifier` name: a destructuring
+                        // pattern (`const { a, b } = x`) binds several names and
+                        // 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}`;
+                            out.nodes.push({
+                                id,
+                                label: nm,
+                                // `const Widget = class {}` IS constructible;
+                                // calling it a constant would let the build pass
+                                // reject a `new Widget()` that is perfectly real.
+                                kind: isClassExpr ? 'class' : 'constant',
+                                source_file: file,
+                                source_location: loc(d),
+                            });
+                            out.rawEdges.push({
+                                sourceId: classId ?? fileId,
+                                relation: 'member',
+                                targetName: nm,
+                                confidenceHint: 'EXTRACTED',
+                            });
+                        }
+                        // Non-function declarators still need walking for their
+                        // calls — returning early on the whole declaration
+                        // silently drops call edges from initialisers.
+                        walk(d, classId, scopeId, inner);
                         continue;
                     }
                     const nm = nameField(d) ?? '<anon>';
@@ -353,16 +497,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                     // can iterate children because a `statement_block` is never
                     // the interesting node; here it often is.
                     const body = value.childForFieldName('body');
-                    if (body) walk(body, classId, id);
-                }
-                // Non-function declarators still need walking for their calls.
-                for (const d of namedChildren(n)) {
-                    if (d.type !== 'variable_declarator') continue;
-                    const value = d.childForFieldName('value');
-                    if (value && (value.type === 'arrow_function' || value.type === 'function_expression')) {
-                        continue;
-                    }
-                    walk(d, classId, scopeId);
+                    if (body) walk(body, classId, id, false);
                 }
                 return;
             }
@@ -388,7 +523,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                         confidenceHint: 'EXTRACTED',
                     });
                     const body = value.childForFieldName('body');
-                    if (body) walk(body, classId, id);
+                    if (body) walk(body, classId, id, false);
                     return;
                 }
                 break;
@@ -481,11 +616,11 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
             default:
                 break;
         }
-        for (const c of namedChildren(n)) walk(c, classId, scopeId);
+        for (const c of namedChildren(n)) walk(c, classId, scopeId, inner);
     };
 
     out.nodes.push({ id: fileId, label: file, kind: 'file', source_file: file, source_location: [] });
-    walk(root, null, fileId);
+    walk(root, null, fileId, true);
 }
 
 /**