@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/code_graph/build.ts

@@ -217,7 +217,21 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
             return;
         }
         if (r.relation === 'imports' || r.relation === 'uses') {
-            const resolved = sym.classByName.get(k(ex.lang, r.targetName));
+            // 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('::'),
+                );
             emit({
                 source: r.sourceId,
                 target: resolved ?? `symbol:${r.targetName}`,
@@ -258,9 +272,14 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
                 const cands = methodCandidates(r.targetName, ex.lang);
                 emit({
                     source: r.sourceId,
-                    target: cands[0] ?? `symbol:${r.targetName}`,
+                    target: ambiguousTarget(cands, r.targetName),
                     relation: 'calls',
                     confidence: 'AMBIGUOUS',
+                    // The enclosing class extends a base outside this
+                    // repository, so the method is not findable HERE — a
+                    // different cause from a call whose receiver is unknown,
+                    // and the two need different fixes.
+                    ambiguity_reason: 'hierarchy-unresolved',
                     ...(cands.length ? { candidates: cands } : {}),
                 });
             }
@@ -270,9 +289,13 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
         const cands = methodCandidates(r.targetName, ex.lang);
         emit({
             source: r.sourceId,
-            target: cands[0] ?? `symbol:${r.targetName}`,
+            target: ambiguousTarget(cands, r.targetName),
             relation: 'calls',
             confidence: 'AMBIGUOUS',
+            // Receiver type unknown: `$obj->m()` or an unresolved `C::m()`.
+            // Resolving this needs type inference the extractor does not do,
+            // which is exactly what 1.2 has to decide about rather than assume.
+            ambiguity_reason: 'receiver-unknown',
             ...(cands.length ? { candidates: cands } : {}),
         });
     }
@@ -311,6 +334,35 @@ export function buildGraph(files: readonly SourceFile[], extracts: readonly File
 }
 
 /** Stable JSON with sorted keys — the byte-equality anchor. */
+/**
+ * The `target` of an AMBIGUOUS edge.
+ *
+ * `road-to-inbox-harvest-2026-08-f-code-graph-evidence-refresh` 1.2. The rule
+ * that was here — `candidates[0] ?? symbol:<name>` — is the false positive the
+ * roadmap names verbatim: `discoverTurboGenerators --calls--> LruCache::set`,
+ * measured across three files, produced by a generic `.set(...)` call whose
+ * first alphabetical candidate happened to be a cache class in a bench fixture.
+ *
+ * **The defect is not the ambiguity, it is the ARBITRARY WINNER.** Every
+ * consumer that reads `target` and ignores `confidence` sees a specific method
+ * on a specific class — and the taxonomy's own acceptance rule is that an
+ * AMBIGUOUS edge is correct when the true target is *among the candidates*,
+ * which says plainly that no single one of them is the answer.
+ *
+ * So: ONE candidate is a real resolution and is kept as the target; MORE than
+ * one is a choice the extractor cannot make, and the target becomes the
+ * unresolved symbol while `candidates` carries every option. Nothing is lost —
+ * the list was already emitted — and the graph stops asserting a method call
+ * that does not happen.
+ *
+ * Measured effect on this repository: 8,960 AMBIGUOUS edges carried candidates,
+ * of which 8,939 had more than one and therefore an arbitrary target.
+ */
+function ambiguousTarget(candidates: readonly string[], targetName: string): string {
+    if (candidates.length === 1) return candidates[0] as string;
+    return `symbol:${targetName}`;
+}
+
 export function serializeGraph(g: CodeGraph): string {
     const key_order: (keyof CodeGraph)[] = [
         'schema_version',
@@ -335,6 +387,11 @@ export function serializeGraph(g: CodeGraph): string {
             relation: e.relation,
             confidence: e.confidence,
         };
+        // Ordered before `candidates` deliberately: the reason is the coarser
+        // axis and a reader scanning the serialized graph sees WHY before HOW
+        // MANY. Both are omitted when absent, so an EXTRACTED edge is byte-for-
+        // byte what it was before this field existed.
+        if (e.ambiguity_reason) base['ambiguity_reason'] = e.ambiguity_reason;
         if (e.candidates) base['candidates'] = e.candidates;
         return base;
     };

package/src/scripts/code_graph/extract.ts

@@ -405,6 +405,50 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                     });
                 break;
             }
+            // A static registry literal — `const registry = { foo: handleFoo }`.
+            //
+            // road-to-inbox-harvest-2026-08-f-code-graph-evidence-refresh 1.3.
+            // Before this, such a table produced NO edge at all: the value is an
+            // identifier reference rather than a call, so nothing in the walker
+            // saw it, and every dispatch table in the tree was invisible to the
+            // graph. That is a real gap rather than an honest absence — the
+            // reference is statically resolvable, with no inference involved.
+            //
+            // Scope is deliberately the shape that needs no inference: a
+            // shorthand or `key: identifier` property whose value is a bare
+            // identifier. A computed key, a call, an arrow function or a spread
+            // is left alone, because resolving those DOES need inference and
+            // guessing there is how the arbitrary-winner defect 1.2 removed got
+            // in. Emitted as `references` rather than `calls`, because a table
+            // naming a handler is not a call site — the call happens wherever
+            // the table is looked up, and claiming otherwise would assert a
+            // control-flow edge that does not exist. `uses` is the existing
+            // relation for exactly that, so the union is not widened — a new
+            // relation would be a schema change reaching the validator, the
+            // query surface and every consumer, for a distinction `uses`
+            // already draws.
+            case 'pair':
+            case 'shorthand_property_identifier': {
+                if (n.type === 'shorthand_property_identifier') {
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'uses',
+                        targetName: n.text,
+                        confidenceHint: 'EXTRACTED',
+                    });
+                    break;
+                }
+                const val = n.childForFieldName('value');
+                if (val?.type === 'identifier') {
+                    out.rawEdges.push({
+                        sourceId: scopeId,
+                        relation: 'uses',
+                        targetName: val.text,
+                        confidenceHint: 'EXTRACTED',
+                    });
+                }
+                break;
+            }
             case 'call_expression': {
                 const fn = n.childForFieldName('function');
                 if (fn) {

package/src/scripts/code_graph/types.ts

@@ -38,6 +38,30 @@ export interface CodeEdge {
      * among these (the honest-taxonomy acceptance rule).
      */
     candidates?: string[];
+    /**
+     * Present only on AMBIGUOUS edges: WHY the target did not resolve.
+     *
+     * Added by `road-to-inbox-harvest-2026-08-f-code-graph-evidence-refresh`
+     * 1.1. Before it, 43 % of this graph's edges carried AMBIGUOUS with no
+     * recorded cause, so "resolve the largest class" was not a question the
+     * artifact could answer — you had to re-run the extractor with a bespoke
+     * script to find out what the classes even were.
+     *
+     * The taxonomy is the extractor's own branch structure, not a guess:
+     *
+     * · `receiver-unknown` — a dynamic (`$obj->m()`) or scoped (`C::m()`) call
+     *   whose receiver type is not known. Resolving this needs type inference
+     *   the extractor does not do.
+     * · `hierarchy-unresolved` — a `this`/`self`/`static`/`parent` call inside a
+     *   class whose hierarchy does not contain the method, i.e. the base class
+     *   is outside the repository. Not resolvable from this tree at all.
+     *
+     * And the second axis, which decides whether resolution is even possible:
+     * an edge with `candidates` has same-named methods to choose between; one
+     * without has NO in-repo candidate, so no amount of inference would find a
+     * target.
+     */
+    ambiguity_reason?: 'receiver-unknown' | 'hierarchy-unresolved';
 }
 
 export interface CodeGraph {