feat(analysis): inter-procedural return-type propagation (Phase 8.2) (#1279)

* feat(analysis): inter-procedural return-type propagation (Phase 8.2)

Extends type tracking beyond single-function scope. The JS/TS extractor
now records each function's declared or inferred return type in a new
`returnTypeMap`, then propagates that information to variables assigned
from call expressions before call-edge resolution runs.

Intra-file: `const x = createUser()` resolves x's type when `createUser`
has a TS return annotation or a `return new Constructor()` body. Method
chains (`getService().getRepo()`) are resolved recursively up to three
hops with confidence decaying 0.1 per hop (1.0 → 0.9 → 0.8 → 0.7).

Cross-file: `build-edges.ts` collects unresolved call assignments from
each extractor output and propagates return types from imported files
before both the native and JS call-edge paths run, so both engines
benefit automatically.

Expected impact: +10–15 pp on caller coverage for factory patterns,
builder patterns, and method chains.

* fix(analysis): fix currentClass leak and annotation guard in extractReturnTypeMapWalk

- Pass null as currentClass when recursing into function_declaration and
  method_definition bodies, preventing nested function declarations from
  being stored under the enclosing class name (e.g. ClassName.innerFn)
- Fix annotation guard condition: `1.0 > existing.confidence` was always
  true (since 1.0 is maximum confidence); replace with `existing.confidence < 1.0`
  so the first annotation wins for duplicate function names

* fix(analysis): move cross-file propagation outside transaction, export penalty constant

- Move propagateReturnTypesAcrossFiles call to before computeEdgesTx opens,
  avoiding partial in-memory typeMap mutations if the transaction rolls back
- Export PROPAGATION_HOP_PENALTY from javascript.ts and use it in build-edges.ts
  instead of a hardcoded 0.1 literal
- Add TODO comment to typePropagationDepth config entry clarifying it is not yet
  wired to MAX_PROPAGATION_DEPTH (planned for Phase 8.3)

Author: carlos-alm

src/domain/graph/builder/stages/build-edges.ts

@@ -7,6 +7,8 @@
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { getNodeId } from '../../../../db/index.js';
+import { setTypeMapEntry } from '../../../../extractors/helpers.js';
+import { PROPAGATION_HOP_PENALTY } from '../../../../extractors/javascript.js';
 import { debug } from '../../../../infrastructure/logger.js';
 import { loadNative } from '../../../../infrastructure/native.js';
 import type {
@@ -388,6 +390,64 @@ function buildImportEdgesNative(
   }
 }
 
+// ── Phase 8.2: Cross-file return-type propagation ───────────────────────
+
+/**
+ * Augment each file's typeMap with return types from imported functions.
+ *
+ * The per-file extractor already resolves same-file call assignments (intra-file
+ * propagation). This function handles the cross-file case: when a file imports a
+ * function from another file and assigns its return value to a variable, we look up
+ * the callee's return type in the source file's returnTypeMap and inject it.
+ *
+ * Called once before call-edge building so both the native and JS paths benefit.
+ */
+function propagateReturnTypesAcrossFiles(
+  fileSymbols: Map<string, ExtractorOutput>,
+  ctx: PipelineContext,
+  rootDir: string,
+): void {
+  // Index: filePath → per-file return-type map
+  const returnTypeIndex = new Map<string, Map<string, TypeMapEntry>>();
+  for (const [relPath, symbols] of fileSymbols) {
+    if (symbols.returnTypeMap?.size) returnTypeIndex.set(relPath, symbols.returnTypeMap);
+  }
+  if (returnTypeIndex.size === 0) return;
+
+  // Flat global map for qualified method lookups (TypeName.methodName → entry).
+  // Conflicts resolved by keeping the highest-confidence entry.
+  const globalReturnTypeMap = new Map<string, TypeMapEntry>();
+  for (const rtm of returnTypeIndex.values()) {
+    for (const [name, entry] of rtm) {
+      const existing = globalReturnTypeMap.get(name);
+      if (!existing || entry.confidence > existing.confidence) globalReturnTypeMap.set(name, entry);
+    }
+  }
+
+  for (const [relPath, symbols] of fileSymbols) {
+    if (!symbols.callAssignments?.length) continue;
+    const importedNamesMap = buildImportedNamesMap(ctx, relPath, symbols, rootDir);
+
+    for (const ca of symbols.callAssignments) {
+      if (symbols.typeMap.has(ca.varName)) continue; // already resolved locally
+
+      let returnEntry: TypeMapEntry | undefined;
+      if (ca.receiverTypeName) {
+        returnEntry = globalReturnTypeMap.get(`${ca.receiverTypeName}.${ca.calleeName}`);
+      } else {
+        const importedFrom = importedNamesMap.get(ca.calleeName);
+        if (importedFrom) returnEntry = returnTypeIndex.get(importedFrom)?.get(ca.calleeName);
+      }
+
+      if (returnEntry) {
+        const propagatedConf = returnEntry.confidence - PROPAGATION_HOP_PENALTY;
+        if (propagatedConf > 0)
+          setTypeMapEntry(symbols.typeMap, ca.varName, returnEntry.type, propagatedConf);
+      }
+    }
+  }
+}
+
 // ── Call edges (native engine) ──────────────────────────────────────────
 
 function buildCallEdgesNative(
@@ -864,6 +924,11 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
       batchInsertEdges(db, allEdgeRows);
     }
   });
+  // Phase 8.2: Augment typeMaps with cross-file return-type propagation before
+  // the transaction opens. This is pure in-memory mutation (no DB I/O) and must
+  // run outside the transaction to avoid leaving ctx.fileSymbols in a partial
+  // state if the transaction rolls back unexpectedly.
+  propagateReturnTypesAcrossFiles(ctx.fileSymbols, ctx, ctx.rootDir);
   computeEdgesTx();
 
   // Phase 2: Native rusqlite bulk insert (outside better-sqlite3 transaction