feat(cha): layered base-class resolution recovers cross-file override edges

Measuring the prior ambiguity-skip on real repos showed it was far too conservative: it
dropped a cross-file override edge whenever the base class name was reused ANYWHERE —
~37% of all base-references on Laravel (1034/2810), a large recall loss on exactly the big
namespaced codebases CHA targets.

Replaced the bare same-file-then-skip logic in buildClassNodes with layered,
most-specific-evidence-first resolution:
  1. a class of that name in the child's own file;
  2. the file the child imports the name from (existing importMap, now threaded in —
     covers Java/TS/JS/Python/Go/Rust/Ruby);
  3. a class of that name unique within the child's directory (same package);
  4. a globally-unique class of that name;
  5. otherwise skip (genuinely ambiguous across dirs, no import).
Layers 1-4 each carry real evidence; only truly unresolvable bases are skipped, keeping the
false-negatives-over-false-positives bias.

Dogfooded:
- DesignPatternsPHP 71 -> 87 override edges: recovered the real FactoryMethod/Logger,
  StaticFactory/Formatter, and Bridge/Formatter hierarchies the skip had dropped (each
  implementer resolves to its OWN directory's base); cross-namespace false edges stay gone;
  zero cross-top-directory edges.
- Laravel (1640 files): 1758 override edges / 512 cross-package; an adversarial agent audit
  of all reused-name families (Builder/Grammar/Connection/Driver/Guard/Loader/... incl. all 6
  globally-ambiguous base names) found ZERO false positives — import resolves cross-package
  Contracts/* bases, directory-locality resolves same-namespace siblings (Query vs Schema),
  never cross-wiring. ~100% precision with a large recall gain.

Residual: a globally-duplicated base name neither same-dir-unique nor import-disambiguated is
still skipped (rare). Full FQCN extraction for non-importMap languages (PHP/Kotlin/Swift/Scala/
C#) is the further future enhancement. Tests +1; full suite green (3763). Decision: 320bf215.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: clay-good

openspec/changes/archive/add-type-hierarchy-resolved-dispatch/tasks.md

@@ -95,6 +95,31 @@
 > (`cha.test.ts` Kotlin/PHP/Swift/Scala override + ambiguous-cross-file + Kotlin-qualified-supertype;
 > `graph.test.ts` bfsFromDB DB-path propagation). Full suite green (3762). Languages with CHA hierarchy
 > support: TS/JS, Python, Java, C++, C#, Ruby, Go, Kotlin, PHP, Swift, Scala.
+>
+> **Layered base resolution — recall recovery (follow-up, same PR #155).** Measuring the previous
+> ambiguity-skip on real repos showed it was far too conservative: it dropped a cross-file override
+> edge whenever the base class name was reused ANYWHERE — **~37% of all base-references on Laravel
+> (1,034 of 2,810)**. Replaced the bare same-file-then-skip logic in `buildClassNodes` with layered,
+> most-specific-evidence-first resolution: **(1)** same file → **(2)** the file the child imports the
+> name from (`importMap`, now threaded in — covers Java/TS/JS/Python/Go/Rust/Ruby) → **(3)** unique
+> within the child's directory (same package) → **(4)** globally unique → **(5)** skip (genuinely
+> ambiguous across directories with no import). Layers 1–4 each carry real evidence; only truly
+> unresolvable bases are skipped, preserving the false-negative-over-false-positive bias.
+> Dogfooded:
+> - **DesignPatternsPHP** 71 → 87 override edges: recovered the real `FactoryMethod/Logger`,
+>   `StaticFactory/Formatter`, and `Bridge/Formatter` hierarchies the skip had dropped — each
+>   implementer now resolves to its OWN directory's base — while the cross-namespace false edges stay
+>   gone, and ZERO cross-top-directory edges remain.
+> - **Laravel** (1,640 files): 1,758 override edges, 512 cross-package. An adversarial agent audit of
+>   the riskiest reused names (`Builder`/`Grammar`/`Connection`/`Driver`/`Guard`/`Loader`/… incl. all
+>   6 genuinely globally-ambiguous base names) found **zero false positives** — import resolves the
+>   cross-package `Contracts/*` bases, directory-locality resolves same-namespace siblings (Query vs
+>   Schema `Builder`/`Grammar`), never cross-wiring. Precision held at ~100% with a large recall gain.
+>
+> Residual: a globally-duplicated base name that is neither same-dir-unique NOR import-disambiguated is
+> still skipped (rare; e.g. a non-importMap language using cross-namespace inheritance without same-dir
+> co-location). Tests: +1 (`cha.test.ts` directory-locality recovery resolves to the correct twin).
+> Full suite green (3763).
 
 ## 1. Confirm the surface is purely additive (no type changes)
 - [x] Verify `EdgeConfidence` already includes `'synthesized'` (`call-graph.ts:34`), `CallEdge` already

openspec/specs/analyzer/spec.md

@@ -5571,6 +5571,12 @@ The system SHALL skip cross-file parent resolution when the parent name is ambig
 
 > Decision recorded: d5967a48
 > Date: 2026-06-17
+### Requirement: ResolveChaBaseClassesByLayeredEvidenceSamefileImportSamedirectoryGlobaluniqueInsteadOfBarenamethenskip
+
+The system SHALL resolve CHA base-class references using layered evidence (same-file, import, same-directory, global-unique) before falling back to ambiguity-skip.
+
+> Decision recorded: 320bf215
+> Date: 2026-06-17
 
 ## Technical Notes
 
@@ -6068,3 +6074,13 @@ The polymorphic-dispatch (CHA) feature requires class-hierarchy edges for each s
 When multiple classes share a bare name across different files (e.g. two unrelated `Logger` interfaces in different PHP namespaces), a global first-match would fabricate a false override edge and steal the real one from the correct twin; skipping the resolution entirely is safer for downstream dispatch accuracy.
 
 **Consequences:** Some legitimate cross-file inheritance edges will be missed when name collisions exist; this is an acceptable precision-over-recall tradeoff that avoids polluting the call graph with phantom dispatch targets.
+
+### Resolve CHA base classes by layered evidence (same-file → import → same-directory → global-unique) instead of bare-name-then-skip
+
+**Status:** Approved
+**Date:** 2026-06-17
+**ID:** 320bf215
+
+The prior ambiguity-skip in buildClassNodes dropped cross-file override edges whenever the base class name was reused anywhere in the codebase — measured at ~37% of all base-references on Laravel (1034/2810). Replaced with layered, most-specific-evidence-first resolution: (1) class in child's own file; (2) file the child imports the name from via importMap; (3) class unique within child's directory (same package); (4) globally-unique class; (5) skip. Each layer carries real evidence, so only genuinely-ambiguous cross-directory bases with no import are skipped, preserving the false-negatives-over-false-positives bias while recovering legitimate edges.
+
+**Consequences:** Threads the existing importMap into buildClassNodes (new optional param). Recall recovered substantially with no precision loss: DesignPatternsPHP 71→87 override edges, Laravel 1758 override edges / 512 cross-package at ~100% precision. Residual: globally-duplicated base names without import or same-dir co-location are still skipped. True FQCN/namespace extraction for non-importMap languages (PHP/Kotlin/Swift/Scala/C#) remains a future enhancement.

src/core/analyzer/call-graph.ts

@@ -2905,6 +2905,7 @@ async function extractClassRelationships(
 function buildClassNodes(
   allNodes: Map<string, FunctionNode>,
   relationships: Map<string, { parentClasses: string[]; interfaces: string[] }>,
+  importMap?: ImportMap,
 ): { classes: ClassNode[]; inheritanceEdges: InheritanceEdge[] } {
   // Group FunctionNodes by (filePath, className).
   // Free functions use a synthetic "[basename]" module name keyed by filePath alone.
@@ -2964,19 +2965,33 @@ function buildClassNodes(
   // genuine cross-file inheritance falls back to the global first match.
   const byName = new Map<string, ClassNode>();
   const nameCount = new Map<string, number>();
+  const byNameAndDir = new Map<string, ClassNode[]>(); // `${dir}\0${name}` → classes
+  const dirOf = (p: string): string => { const i = p.lastIndexOf('/'); return i >= 0 ? p.slice(0, i) : ''; };
   for (const cls of classMap.values()) {
     nameCount.set(cls.name, (nameCount.get(cls.name) ?? 0) + 1);
     if (!byName.has(cls.name)) byName.set(cls.name, cls);
+    const dk = `${dirOf(cls.filePath)}\0${cls.name}`;
+    const arr = byNameAndDir.get(dk);
+    if (arr) arr.push(cls); else byNameAndDir.set(dk, [cls]);
   }
+  // Resolve a base/interface NAME to a ClassNode, most-specific evidence first:
+  //   1. same file  2. the file the child imports the name from  3. unique within the
+  //   child's directory (same package)  4. globally unique  5. otherwise SKIP.
+  // Earlier layers carry real evidence (declaration site, import, package); the global-
+  // unique fallback is safe (only one candidate). When the bare name is ambiguous across
+  // directories and no import disambiguates it (e.g. several namespaced `Builder` classes),
+  // skip rather than guess a first-match — false-negatives over false-positives.
   const resolveParent = (parentName: string, childFile: string): ClassNode | undefined => {
     const sameFile = classMap.get(`${childFile}::${parentName}`);
     if (sameFile) return sameFile;
-    // The base is not declared in the child's file and its bare name is AMBIGUOUS
-    // (several classes share it across files — e.g. two unrelated `Logger` interfaces
-    // in different PHP namespaces). A global first-match would both fabricate a false
-    // override edge AND steal the real one from the correct twin, so skip rather than
-    // guess — false-negatives over false-positives.
-    if ((nameCount.get(parentName) ?? 0) > 1) return undefined;
+    const importedFrom = importMap?.get(childFile)?.get(parentName);
+    if (importedFrom) {
+      const viaImport = classMap.get(`${importedFrom}::${parentName}`);
+      if (viaImport) return viaImport;
+    }
+    const sameDir = byNameAndDir.get(`${dirOf(childFile)}\0${parentName}`);
+    if (sameDir && sameDir.length === 1) return sameDir[0];
+    if ((nameCount.get(parentName) ?? 0) > 1) return undefined; // ambiguous across dirs → skip
     return byName.get(parentName);
   };
 
@@ -4764,7 +4779,7 @@ export class CallGraphBuilder {
 
     // Pass 7: Build class hierarchy (inheritance + grouping)
     const relationships = await extractClassRelationships(files);
-    const { classes, inheritanceEdges } = buildClassNodes(allNodes, relationships);
+    const { classes, inheritanceEdges } = buildClassNodes(allNodes, relationships, importMap);
     // Merge IaC module groupings (deduped by id) into the class set.
     const classIds = new Set(classes.map(c => c.id));
     for (const c of iacClasses) if (!classIds.has(c.id)) classes.push(c);

src/core/analyzer/cha.test.ts

@@ -245,6 +245,24 @@ describe('CHA — ambiguous cross-file base names', () => {
   // file AND is ambiguous (several classes share it across files), resolution must
   // skip — guessing a global first-match both fabricates a false override edge and
   // steals the real one. Bias: false-negatives over false-positives.
+  it('recovers a cross-file override edge via same-directory resolution (correct twin)', async () => {
+    // Two same-named `Logger` interfaces in different directories, each with an
+    // implementer in a SEPARATE file within its own directory. Same-directory
+    // resolution must wire each implementer to ITS directory's Logger — recovering
+    // the real edge that the bare-name ambiguity-skip would have dropped, without
+    // cross-wiring to the other directory's twin.
+    const b = await new CallGraphBuilder().build([
+      { path: 'a/Logger.ts', content: `export class Logger { log() { return 1; } }`, language: 'TypeScript' },
+      { path: 'a/FileLogger.ts', content: `import { Logger } from './Logger'; export class FileLogger extends Logger { log() { return 2; } }`, language: 'TypeScript' },
+      { path: 'b/Logger.ts', content: `export class Logger { log() { return 9; } }`, language: 'TypeScript' },
+    ]);
+    const aLog = 'a/Logger.ts::Logger.log';
+    const bLog = 'b/Logger.ts::Logger.log';
+    const fileLog = 'a/FileLogger.ts::FileLogger.log';
+    expect(b.edges.some(e => e.synthesizedBy === 'override' && e.callerId === aLog && e.calleeId === fileLog)).toBe(true);
+    expect(b.edges.some(e => e.synthesizedBy === 'override' && e.callerId === bLog && e.calleeId === fileLog)).toBe(false);
+  });
+
   it('does not synthesize an override edge to an ambiguous cross-file base', async () => {
     const b = await new CallGraphBuilder().build([
       { path: 'a.ts', content: `export class Logger { log() { return 1; } }`, language: 'TypeScript' },