cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/pipeline.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Pipeline orchestrator — dependency-ordered ingestion pipeline.
+ *
+ * The pipeline is composed of named phases with explicit dependencies.
+ * Each phase is defined in its own file under `pipeline-phases/`.
+ * The runner in `pipeline-phases/runner.ts` executes phases in
+ * topological order, passing typed outputs from upstream phases as
+ * inputs to downstream phases.
+ *
+ * To add a new phase:
+ * 1. Create a new file in `pipeline-phases/` following the pattern
+ * 2. Export it from `pipeline-phases/index.ts`
+ * 3. Add it to the `ALL_PHASES` array below
+ *
+ * See ARCHITECTURE.md for the full phase dependency diagram.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPipelineFromRepo = void 0;
+exports.buildPhaseList = buildPhaseList;
+const graph_js_1 = require("../graph/graph.js");
+const graph_emit_sink_js_1 = require("../lbug/graph-emit-sink.js");
+const index_js_1 = require("./pipeline-phases/index.js");
+// ── Phase registry ─────────────────────────────────────────────────────────
+/**
+ * All pipeline phases with their dependency relationships.
+ *
+ * Phase dependency graph:
+ *
+ *   scan → structure → springConfig → parse → [routes, tools, rpcEdges, httpApiCalls, orm]
+ *     → crossFile → scopeResolution → [springAutoConfiguration, springAop] → pruneLocalSymbols
+ *     → mro → springAopInheritance → di → communities → processes
+ *
+ *   rpcEdges (deps: parse) and httpApiCalls (deps: parse, rpcEdges) are the
+ *   cross-service contract phases (spec §5.4, §6): they emit RCALLS /
+ *   HTTP_CALLS edges and ExternalService nodes from workspace-config annotations.
+ *
+ * To add a new phase: create a file in pipeline-phases/, export the phase
+ * object, and `.register()` it at the appropriate position below. Opt-in
+ * phases pass an `enabledWhen` predicate (issue #2080 phase-registry seam) —
+ * the legacy `if (!skipGraphPhases)` guard is now expressed that way on the
+ * five graph phases, with no change in behaviour.
+ */
+function buildPhaseList(options) {
+    return (new index_js_1.PhaseRegistry()
+        .register(index_js_1.scanPhase)
+        .register(index_js_1.structurePhase)
+        .register(index_js_1.springConfigPhase)
+        .register(index_js_1.parsePhase)
+        .register(index_js_1.routesPhase)
+        .register(index_js_1.toolsPhase)
+        .register(index_js_1.rpcEdgesPhase)
+        .register(index_js_1.httpApiCallsPhase)
+        .register(index_js_1.ormPhase)
+        .register(index_js_1.crossFilePhase)
+        .register(index_js_1.scopeResolutionPhase)
+        .register(index_js_1.springAutoConfigurationPhase)
+        .register(index_js_1.springAopPhase)
+        .register(index_js_1.pruneLocalSymbolsPhase)
+        .register(index_js_1.mroPhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .register(index_js_1.springAopInheritancePhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .register(index_js_1.diPhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .register(index_js_1.communitiesPhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .register(index_js_1.processesPhase, { enabledWhen: (o) => !o.skipGraphPhases })
+        .build(options ?? {}));
+}
+// ── Pipeline orchestrator ─────────────────────────────────────────────────
+const runPipelineFromRepo = async (repoPath, onProgress, options) => {
+    const graph = (0, graph_js_1.createKnowledgeGraph)();
+    const pipelineStart = Date.now();
+    // Streamed structural emit (#2680). The sink is a write-routing façade over
+    // `graph`; it streams nothing until `beginStreaming()` fires at the parse
+    // boundary.
+    //
+    // A missing `graphEmitCsvDir` is a caller bug, not a reason to quietly skip
+    // streaming: this is on by default, so a programmatic host that builds its own
+    // `PipelineOptions` (eval-server, the MCP daemon, a test) would otherwise ask
+    // for streaming, silently not get it, and still see a successful run. Fail
+    // loudly instead — the whole point of the surrounding work is that a degraded
+    // outcome must never look like a clean one.
+    let graphEmitSink;
+    if (options?.streamGraphEmit === true) {
+        if (options.graphEmitCsvDir === undefined) {
+            throw new Error('streamGraphEmit was requested but graphEmitCsvDir is missing. The caller owns ' +
+                'storage-path resolution (see resolveNativeSafeStorageDir in run-analyze.ts); ' +
+                'pass the directory, or leave streamGraphEmit unset to run without streaming.');
+        }
+        graphEmitSink = new graph_emit_sink_js_1.GraphEmitSink(graph, options.graphEmitCsvDir);
+    }
+    const phases = buildPhaseList(options);
+    let graphEmitManifest;
+    let results;
+    try {
+        results = await (0, index_js_1.runPipeline)(phases, {
+            repoPath,
+            graph: graphEmitSink ?? graph,
+            onProgress,
+            options,
+            pipelineStart,
+            graphEmit: graphEmitSink,
+        });
+        graphEmitManifest = graphEmitSink?.finalize();
+    }
+    finally {
+        // Release per-pair fds when the pipeline threw before finalize ran.
+        graphEmitSink?.close();
+    }
+    // Extract final results for the PipelineResult contract
+    const { totalFiles, usedWorkerPool } = (0, index_js_1.getPhaseOutput)(results, 'parse');
+    let communityResult;
+    let processResult;
+    const scopeResolutionOutput = (0, index_js_1.getPhaseOutput)(results, 'scopeResolution');
+    const resolutionOutcomes = scopeResolutionOutput.resolutionOutcomes;
+    // Presence check, not `!skipGraphPhases`: phases can now be filtered out by
+    // any `enabledWhen` predicate (streamGraphEmit disables communities/processes
+    // too), and `getPhaseOutput` THROWS on a phase that was never resolved. Keying
+    // off the options flag alone made every filtered-out combination crash here
+    // rather than return undefined results.
+    if (results.has('communities') && results.has('processes')) {
+        communityResult = (0, index_js_1.getPhaseOutput)(results, 'communities').communityResult;
+        processResult = (0, index_js_1.getPhaseOutput)(results, 'processes').processResult;
+    }
+    onProgress({
+        phase: 'complete',
+        percent: 100,
+        message: communityResult && processResult
+            ? `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes detected.`
+            : 'Graph complete! (graph phases skipped)',
+        stats: {
+            filesProcessed: totalFiles,
+            totalFiles,
+            nodesCreated: graph.nodeCount,
+        },
+    });
+    return {
+        // The RAW graph, deliberately — NOT `graphEmitSink`. Phases above received
+        // the sink so their reads are complete, but `loadGraphToLbug` feeds this to
+        // `streamAllCSVsToDisk`, and the sink's complete iterator would then emit
+        // every streamed edge a SECOND time on top of the per-pair CSVs the sink
+        // already wrote and the manifest already COPYs. Returning the sink here
+        // silently doubles every streamed relationship in the persisted graph.
+        graph,
+        repoPath,
+        totalFileCount: totalFiles,
+        graphEmitManifest,
+        communityResult,
+        processResult,
+        resolutionOutcomes,
+        usedWorkerPool,
+    };
+};
+exports.runPipelineFromRepo = runPipelineFromRepo;

package/dist/core/code/engine/core/ingestion/process-processor.js

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * Process Detection Processor
+ *
+ * Detects execution flows (Processes) in the code graph by:
+ * 1. Finding entry points (functions with no internal callers)
+ * 2. Tracing forward via CALLS edges (BFS)
+ * 3. Grouping and deduplicating similar paths
+ * 4. Labeling with heuristic names
+ *
+ * Processes help agents understand how features work through the codebase.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processProcesses = void 0;
+const entry_point_scoring_js_1 = require("./entry-point-scoring.js");
+const index_js_1 = require("../../../shared/index.js");
+const env_js_1 = require("./utils/env.js");
+const logger_js_1 = require("../logger.js");
+const DEFAULT_CONFIG = {
+    maxTraceDepth: 10,
+    maxBranching: 4,
+    maxProcesses: 75,
+    minSteps: 3, // 3+ steps = genuine multi-hop flow (2-step is just "A calls B")
+};
+// ============================================================================
+// MAIN PROCESSOR
+// ============================================================================
+/**
+ * Detect processes (execution flows) in the knowledge graph
+ *
+ * This runs AFTER community detection, using CALLS edges to trace flows.
+ */
+const processProcesses = async (knowledgeGraph, memberships, onProgress, config = {}) => {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    onProgress?.('Finding entry points...', 0);
+    // Build lookup maps
+    const membershipMap = new Map();
+    memberships.forEach((m) => membershipMap.set(m.nodeId, m.communityId));
+    const callsEdges = buildCallsGraph(knowledgeGraph);
+    const reverseCallsEdges = buildReverseCallsGraph(knowledgeGraph);
+    const nodeMap = new Map();
+    for (const n of knowledgeGraph.iterNodes())
+        nodeMap.set(n.id, n);
+    // Step 1: Find entry points (functions that call others but have few callers)
+    const entryPoints = findEntryPoints(knowledgeGraph, reverseCallsEdges, callsEdges);
+    onProgress?.(`Found ${entryPoints.length} entry points, tracing flows...`, 20);
+    onProgress?.(`Found ${entryPoints.length} entry points, tracing flows...`, 20);
+    // Step 2: Trace processes from each entry point
+    const allTraces = [];
+    for (let i = 0; i < entryPoints.length && allTraces.length < cfg.maxProcesses * 2; i++) {
+        const entryId = entryPoints[i];
+        const traces = traceFromEntryPoint(entryId, callsEdges, cfg);
+        // Filter out traces that are too short
+        traces.filter((t) => t.length >= cfg.minSteps).forEach((t) => allTraces.push(t));
+        if (i % 10 === 0) {
+            onProgress?.(`Tracing entry point ${i + 1}/${entryPoints.length}...`, 20 + (i / entryPoints.length) * 40);
+        }
+    }
+    onProgress?.(`Found ${allTraces.length} traces, deduplicating...`, 60);
+    // Step 3: Deduplicate similar traces (subset removal)
+    const uniqueTraces = deduplicateTraces(allTraces);
+    // Step 3b: Deduplicate by entry+terminal pair (keep longest path per pair)
+    const endpointDeduped = deduplicateByEndpoints(uniqueTraces);
+    onProgress?.(`Deduped ${uniqueTraces.length} → ${endpointDeduped.length} unique endpoint pairs`, 70);
+    // Step 4: Limit to max processes (prioritize longer traces)
+    const limitedTraces = endpointDeduped
+        .sort((a, b) => b.length - a.length)
+        .slice(0, cfg.maxProcesses);
+    onProgress?.(`Creating ${limitedTraces.length} process nodes...`, 80);
+    // Step 5: Create process nodes
+    const processes = [];
+    const steps = [];
+    limitedTraces.forEach((trace, idx) => {
+        const entryPointId = trace[0];
+        const terminalId = trace[trace.length - 1];
+        // Get communities touched
+        const communitiesSet = new Set();
+        trace.forEach((nodeId) => {
+            const comm = membershipMap.get(nodeId);
+            if (comm)
+                communitiesSet.add(comm);
+        });
+        const communities = Array.from(communitiesSet);
+        // Determine process type
+        const processType = communities.length > 1 ? 'cross_community' : 'intra_community';
+        // Generate label
+        const entryNode = nodeMap.get(entryPointId);
+        const terminalNode = nodeMap.get(terminalId);
+        const entryName = entryNode?.properties.name || 'Unknown';
+        const terminalName = terminalNode?.properties.name || 'Unknown';
+        const heuristicLabel = `${capitalize(entryName)} → ${capitalize(terminalName)}`;
+        const processId = `proc_${idx}_${sanitizeId(entryName)}`;
+        processes.push({
+            id: processId,
+            label: heuristicLabel,
+            heuristicLabel,
+            processType,
+            stepCount: trace.length,
+            communities,
+            entryPointId,
+            terminalId,
+            trace,
+        });
+        // Create step relationships
+        trace.forEach((nodeId, stepIdx) => {
+            steps.push({
+                nodeId,
+                processId,
+                step: stepIdx + 1, // 1-indexed
+            });
+        });
+    });
+    onProgress?.('Process detection complete!', 100);
+    // Calculate stats
+    const crossCommunityCount = processes.filter((p) => p.processType === 'cross_community').length;
+    const avgStepCount = processes.length > 0
+        ? processes.reduce((sum, p) => sum + p.stepCount, 0) / processes.length
+        : 0;
+    return {
+        processes,
+        steps,
+        stats: {
+            totalProcesses: processes.length,
+            crossCommunityCount,
+            avgStepCount: Math.round(avgStepCount * 10) / 10,
+            entryPointsFound: entryPoints.length,
+        },
+    };
+};
+exports.processProcesses = processProcesses;
+/**
+ * Minimum edge confidence for process tracing.
+ * Filters out ambiguous fuzzy-global matches (0.3) that cause
+ * traces to jump across unrelated code areas.
+ */
+const MIN_TRACE_CONFIDENCE = 0.5;
+const buildCallsGraph = (graph) => {
+    const adj = new Map();
+    // Field-wise scan (#2680) — whole-graph walk, four fields, no object needed.
+    graph.forEachRelationshipFields((sourceId, targetId, type, confidence) => {
+        if (type !== 'CALLS' || confidence < MIN_TRACE_CONFIDENCE)
+            return;
+        const existing = adj.get(sourceId);
+        if (existing === undefined)
+            adj.set(sourceId, [targetId]);
+        else
+            existing.push(targetId);
+    });
+    return adj;
+};
+const buildReverseCallsGraph = (graph) => {
+    const adj = new Map();
+    graph.forEachRelationshipFields((sourceId, targetId, type, confidence) => {
+        if (type !== 'CALLS' || confidence < MIN_TRACE_CONFIDENCE)
+            return;
+        const existing = adj.get(targetId);
+        if (existing === undefined)
+            adj.set(targetId, [sourceId]);
+        else
+            existing.push(sourceId);
+    });
+    return adj;
+};
+/**
+ * Find functions/methods that are good entry points for tracing.
+ *
+ * Entry points are scored based on:
+ * 1. Call ratio (calls many, called by few)
+ * 2. Export status (exported/public functions rank higher)
+ * 3. Name patterns (handle*, on*, *Controller, etc.)
+ *
+ * Test files are excluded entirely.
+ */
+const findEntryPoints = (graph, reverseCallsEdges, callsEdges) => {
+    const symbolTypes = new Set(['Function', 'Method']);
+    const entryPointCandidates = [];
+    for (const node of graph.iterNodes()) {
+        if (!symbolTypes.has(node.label))
+            continue;
+        const filePath = node.properties.filePath || '';
+        // Skip test files entirely
+        if ((0, entry_point_scoring_js_1.isTestFile)(filePath))
+            continue;
+        const callers = reverseCallsEdges.get(node.id) || [];
+        const callees = callsEdges.get(node.id) || [];
+        // Must have at least 1 outgoing call to trace forward
+        if (callees.length === 0)
+            continue;
+        // Calculate entry point score using new scoring system
+        const { score: baseScore, reasons } = (0, entry_point_scoring_js_1.calculateEntryPointScore)(node.properties.name, (node.properties.language ?? index_js_1.SupportedLanguages.JavaScript), node.properties.isExported ?? false, callers.length, callees.length, filePath);
+        let score = baseScore;
+        const astFrameworkMultiplier = node.properties.astFrameworkMultiplier ?? 1.0;
+        if (astFrameworkMultiplier > 1.0) {
+            score *= astFrameworkMultiplier;
+            reasons.push(`framework-ast:${node.properties.astFrameworkReason || 'decorator'}`);
+        }
+        if (score > 0) {
+            entryPointCandidates.push({ id: node.id, score, reasons });
+        }
+    }
+    // Sort by score descending and return top candidates
+    const sorted = entryPointCandidates.sort((a, b) => b.score - a.score);
+    // DEBUG: Log top candidates with new scoring details
+    if (sorted.length > 0 && env_js_1.isDev) {
+        logger_js_1.logger.info(`[Process] Top 10 entry point candidates (new scoring):`);
+        sorted.slice(0, 10).forEach((c, i) => {
+            const node = graph.getNode(c.id);
+            const exported = node?.properties.isExported ? '✓' : '✗';
+            const shortPath = node?.properties.filePath?.split('/').slice(-2).join('/') || '';
+            logger_js_1.logger.info(`  ${i + 1}. ${node?.properties.name} [exported:${exported}] (${shortPath})`);
+            logger_js_1.logger.info(`     score: ${c.score.toFixed(2)} = [${c.reasons.join(' × ')}]`);
+        });
+    }
+    return sorted
+        .slice(0, 200) // Limit to prevent explosion
+        .map((c) => c.id);
+};
+// ============================================================================
+// HELPER: Trace from entry point (BFS)
+// ============================================================================
+/**
+ * Trace forward from an entry point using BFS.
+ * Returns all distinct paths up to maxDepth.
+ */
+const traceFromEntryPoint = (entryId, callsEdges, config) => {
+    const traces = [];
+    // BFS with path tracking
+    // Each queue item: [currentNodeId, pathSoFar]
+    const queue = [[entryId, [entryId]]];
+    while (queue.length > 0 && traces.length < config.maxBranching * 3) {
+        const [currentId, path] = queue.shift();
+        // Get outgoing calls
+        const callees = callsEdges.get(currentId) || [];
+        if (callees.length === 0) {
+            // Terminal node - this is a complete trace
+            if (path.length >= config.minSteps) {
+                traces.push([...path]);
+            }
+        }
+        else if (path.length >= config.maxTraceDepth) {
+            // Max depth reached - save what we have
+            if (path.length >= config.minSteps) {
+                traces.push([...path]);
+            }
+        }
+        else {
+            // Continue tracing - limit branching
+            const limitedCallees = callees.slice(0, config.maxBranching);
+            let addedBranch = false;
+            for (const calleeId of limitedCallees) {
+                // Avoid cycles
+                if (!path.includes(calleeId)) {
+                    queue.push([calleeId, [...path, calleeId]]);
+                    addedBranch = true;
+                }
+            }
+            // If all branches were cycles, save current path as terminal
+            if (!addedBranch && path.length >= config.minSteps) {
+                traces.push([...path]);
+            }
+        }
+    }
+    return traces;
+};
+// ============================================================================
+// HELPER: Deduplicate traces
+// ============================================================================
+/**
+ * Merge traces that are subsets of other traces.
+ * Keep longer traces, remove redundant shorter ones.
+ */
+const deduplicateTraces = (traces) => {
+    if (traces.length === 0)
+        return [];
+    // Sort by length descending
+    const sorted = [...traces].sort((a, b) => b.length - a.length);
+    const unique = [];
+    for (const trace of sorted) {
+        // Check if this trace is a subset of any already-added trace
+        const traceKey = trace.join('->');
+        const isSubset = unique.some((existing) => {
+            const existingKey = existing.join('->');
+            return existingKey.includes(traceKey);
+        });
+        if (!isSubset) {
+            unique.push(trace);
+        }
+    }
+    return unique;
+};
+// ============================================================================
+// HELPER: Deduplicate by entry+terminal endpoints
+// ============================================================================
+/**
+ * Keep only the longest trace per unique entry→terminal pair.
+ * Multiple paths between the same two endpoints are redundant for agents.
+ */
+const deduplicateByEndpoints = (traces) => {
+    if (traces.length === 0)
+        return [];
+    const byEndpoints = new Map();
+    // Sort longest first so the first seen per key is the longest
+    const sorted = [...traces].sort((a, b) => b.length - a.length);
+    for (const trace of sorted) {
+        const key = `${trace[0]}::${trace[trace.length - 1]}`;
+        if (!byEndpoints.has(key)) {
+            byEndpoints.set(key, trace);
+        }
+    }
+    return Array.from(byEndpoints.values());
+};
+// ============================================================================
+// HELPER: String utilities
+// ============================================================================
+const capitalize = (s) => {
+    if (!s)
+        return s;
+    return s.charAt(0).toUpperCase() + s.slice(1);
+};
+const sanitizeId = (s) => {
+    return s
+        .replace(/[^a-zA-Z0-9]/g, '_')
+        .substring(0, 20)
+        .toLowerCase();
+};

package/dist/core/code/engine/core/ingestion/resolve-references.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * `resolveReferenceSites` — drain `ReferenceSite[]` from a finalized
+ * `ScopeResolutionIndexes` into a `ReferenceIndex` by routing each site
+ * through the appropriate scope-aware `Registry.lookup` (RFC §3.2 Phase 4).
+ *
+ * This is the missing producer that `emit-references.ts` (#925) was
+ * waiting on. The two together form the registry-primary resolution
+ * pipeline:
+ *
+ *     ScopeResolutionIndexes.referenceSites
+ *        │  resolveReferenceSites
+ *        ▼
+ *     ReferenceIndex
+ *        │  emitReferencesToGraph
+ *        ▼
+ *     graph: CALLS / ACCESSES / INHERITS / USES edges
+ *
+ * ## What this module does
+ *
+ *   - For each `ReferenceSite`, picks the registry by `kind`:
+ *     · `call` / `inherits`        → MethodRegistry / ClassRegistry (call-form aware)
+ *     · `read` / `write`           → FieldRegistry  (falls through to MethodRegistry for free names)
+ *     · `type-reference`           → ClassRegistry
+ *     · `import-use`               → all three (best-effort name-lookup)
+ *   - Calls `Registry.lookup` with the site's `inScope`, optional
+ *     explicit receiver, and arity.
+ *   - Takes the top-ranked `Resolution` (best by confidence + tie-break
+ *     cascade); folds it into a `Reference` record and bins by source scope.
+ *
+ * ## What this module does NOT do
+ *
+ *   - No AST walks. The `ReferenceSite[]` is already extracted.
+ *   - No language switches. Per-language behavior flows through
+ *     `RegistryProviders.arityCompatibility` (see `RegistryContext`).
+ *   - No multi-candidate fan-out. We pick `[0]` per RFC §4.3 ("one-shot
+ *     answer"). The full ranked list is preserved in the per-site
+ *     resolution but not emitted as multiple edges; callers that want
+ *     branch-on-ambiguity behavior should consume the registries directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_KINDS = exports.METHOD_KINDS = exports.CLASS_KINDS = void 0;
+exports.resolveReferenceSites = resolveReferenceSites;
+const index_js_1 = require("../../../shared/index.js");
+Object.defineProperty(exports, "CLASS_KINDS", { enumerable: true, get: function () { return index_js_1.CLASS_KINDS; } });
+Object.defineProperty(exports, "FIELD_KINDS", { enumerable: true, get: function () { return index_js_1.FIELD_KINDS; } });
+Object.defineProperty(exports, "METHOD_KINDS", { enumerable: true, get: function () { return index_js_1.METHOD_KINDS; } });
+/**
+ * Resolve every `ReferenceSite` in `scopes.referenceSites` against the
+ * matching registry and produce a `ReferenceIndex` keyed by source scope
+ * + target def.
+ */
+function resolveReferenceSites(input) {
+    const { scopes } = input;
+    const providers = input.providers ?? {};
+    const ctx = {
+        scopes: scopes.scopeTree,
+        defs: scopes.defs,
+        qualifiedNames: scopes.qualifiedNames,
+        moduleScopes: scopes.moduleScopes,
+        ownedMembersByOwner: input.ownedMembersByOwner,
+        methodDispatch: scopes.methodDispatch,
+        providers,
+    };
+    const classRegistry = (0, index_js_1.buildClassRegistry)(ctx);
+    const methodRegistry = (0, index_js_1.buildMethodRegistry)(ctx);
+    const fieldRegistry = (0, index_js_1.buildFieldRegistry)(ctx);
+    const macroRegistry = (0, index_js_1.buildMacroRegistry)(ctx);
+    // bySourceScope is the canonical index; byTargetDef is derived from it.
+    const bySourceScope = new Map();
+    const byTargetDef = new Map();
+    let sitesProcessed = 0;
+    let referencesEmitted = 0;
+    let unresolved = 0;
+    for (const site of scopes.referenceSites) {
+        // value-ref sites resolve post-finalize (imports live in finalized
+        // bindings the registries can't see — same reason free calls need
+        // `emitFreeCallFallback`). `emitPropertyDispatchCalls` owns their
+        // resolution and emission entirely (#2437).
+        if (site.kind === 'value-ref')
+            continue;
+        sitesProcessed++;
+        const resolutions = lookupForSite(site, classRegistry, methodRegistry, fieldRegistry, macroRegistry);
+        if (resolutions.length === 0) {
+            unresolved++;
+            continue;
+        }
+        const top = resolutions[0];
+        const ref = buildReference(site, top);
+        referencesEmitted++;
+        let bySource = bySourceScope.get(site.inScope);
+        if (bySource === undefined) {
+            bySource = [];
+            bySourceScope.set(site.inScope, bySource);
+        }
+        bySource.push(ref);
+        let byTarget = byTargetDef.get(top.def.nodeId);
+        if (byTarget === undefined) {
+            byTarget = [];
+            byTargetDef.set(top.def.nodeId, byTarget);
+        }
+        byTarget.push(ref);
+    }
+    // Freeze inner arrays so consumers don't accidentally mutate.
+    const frozenBySource = new Map();
+    for (const [k, v] of bySourceScope)
+        frozenBySource.set(k, Object.freeze([...v]));
+    const frozenByTarget = new Map();
+    for (const [k, v] of byTargetDef)
+        frozenByTarget.set(k, Object.freeze([...v]));
+    return {
+        referenceIndex: { bySourceScope: frozenBySource, byTargetDef: frozenByTarget },
+        stats: { sitesProcessed, referencesEmitted, unresolved },
+    };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/**
+ * Pick the right registry for the site's `kind` and call `lookup`.
+ *
+ * The kind→registry mapping mirrors `mapKindToType` in `emit-references.ts`:
+ *
+ *   | site.kind        | primary registry  | acceptedKinds source         |
+ *   |------------------|-------------------|------------------------------|
+ *   | `call`           | MethodRegistry    | METHOD_KINDS (Method/Func/Ctor)
+ *   | `inherits`       | ClassRegistry     | CLASS_KINDS                  |
+ *   | `type-reference` | ClassRegistry     | CLASS_KINDS                  |
+ *   | `read`/`write`   | FieldRegistry     | FIELD_KINDS                  |
+ *   | `import-use`     | tiered fallback   | METHOD ∪ CLASS ∪ FIELD       |
+ *   | `value-ref`      | (skipped here)    | post-finalize walker in `emitPropertyDispatchCalls` |
+ *   | `macro`          | MacroRegistry     | MACRO_KINDS (`Macro` only)   |
+ *
+ * `macro` has its own single-kind registry so a macro invocation
+ * (`log!(…)`) resolves ONLY to a `macro_rules! log` definition and never
+ * to a same-named free function — macros and functions are disjoint
+ * namespaces (the false-`CALLS`-edge class flagged in the #1934 review).
+ *
+ * `import-use` doesn't have a single registry — the imported name might
+ * be a class, a function, or a constant. Try each in priority order and
+ * return the first non-empty result. Provenance still flows through the
+ * scope's `bindings` (Step 1 lexical hit), so the lookup is correct
+ * regardless of which registry surfaces the def.
+ */
+function lookupForSite(site, classRegistry, methodRegistry, fieldRegistry, macroRegistry) {
+    switch (site.kind) {
+        case 'call': {
+            const opts = {
+                ...(site.arity !== undefined ? { callsite: { arity: site.arity } } : {}),
+                ...(site.explicitReceiver !== undefined ? { explicitReceiver: site.explicitReceiver } : {}),
+            };
+            return methodRegistry.lookup(site.name, site.inScope, opts);
+        }
+        case 'inherits':
+        case 'type-reference': {
+            return classRegistry.lookup(site.name, site.inScope);
+        }
+        case 'read':
+        case 'write': {
+            // Try field first; fall through to method then class so bare-name
+            // reads of a function (e.g. `cb = save`) still resolve.
+            const fieldOpts = {
+                ...(site.explicitReceiver !== undefined ? { explicitReceiver: site.explicitReceiver } : {}),
+            };
+            const fieldHits = fieldRegistry.lookup(site.name, site.inScope, fieldOpts);
+            if (fieldHits.length > 0)
+                return fieldHits;
+            const methodHits = methodRegistry.lookup(site.name, site.inScope);
+            if (methodHits.length > 0)
+                return methodHits;
+            return classRegistry.lookup(site.name, site.inScope);
+        }
+        case 'import-use': {
+            // Try class, method, then field. The lexical-hit Step 1 in
+            // `lookupCore` handles the actual binding lookup; the choice of
+            // registry only narrows `acceptedKinds`.
+            const classHits = classRegistry.lookup(site.name, site.inScope);
+            if (classHits.length > 0)
+                return classHits;
+            const methodHits = methodRegistry.lookup(site.name, site.inScope);
+            if (methodHits.length > 0)
+                return methodHits;
+            return fieldRegistry.lookup(site.name, site.inScope);
+        }
+        case 'value-ref': {
+            // Unreachable — filtered before lookup (post-finalize resolution in
+            // `emitPropertyDispatchCalls`, #2437). Kept for switch exhaustiveness.
+            return [];
+        }
+        case 'macro': {
+            // Macro-only namespace: resolves against `Macro`-labeled defs, never
+            // functions. No receiver, no arity — see `MacroRegistry`.
+            return macroRegistry.lookup(site.name, site.inScope);
+        }
+    }
+}
+/** Compose a `Reference` record from a site + its top resolution. */
+function buildReference(site, top) {
+    return {
+        fromScope: site.inScope,
+        toDef: top.def.nodeId,
+        atRange: site.atRange,
+        kind: site.kind,
+        confidence: top.confidence,
+        evidence: top.evidence,
+    };
+}