gitnexus 1.4.1 → 1.4.6

package/dist/core/ingestion/pipeline.js

@@ -1,17 +1,21 @@
 import { createKnowledgeGraph } from '../graph/graph.js';
 import { processStructure } from './structure-processor.js';
 import { processParsing } from './parsing-processor.js';
-import { processImports, processImportsFromExtracted, createImportMap, buildImportResolutionContext } from './import-processor.js';
+import { processImports, processImportsFromExtracted, buildImportResolutionContext } from './import-processor.js';
 import { processCalls, processCallsFromExtracted, processRoutesFromExtracted } from './call-processor.js';
 import { processHeritage, processHeritageFromExtracted } from './heritage-processor.js';
+import { computeMRO } from './mro-processor.js';
 import { processCommunities } from './community-processor.js';
 import { processProcesses } from './process-processor.js';
-import { createSymbolTable } from './symbol-table.js';
+import { createResolutionContext } from './resolution-context.js';
 import { createASTCache } from './ast-cache.js';
 import { walkRepositoryPaths, readFileContents } from './filesystem-walker.js';
 import { getLanguageFromFilename } from './utils.js';
 import { isLanguageAvailable } from '../tree-sitter/parser-loader.js';
 import { createWorkerPool } from './workers/worker-pool.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 const isDev = process.env.NODE_ENV === 'development';
 /** Max bytes of source content to load per parse chunk. Each chunk's source +
  *  parsed ASTs + extracted records + worker serialization overhead all live in
@@ -20,14 +24,14 @@ const isDev = process.env.NODE_ENV === 'development';
 const CHUNK_BYTE_BUDGET = 20 * 1024 * 1024; // 20MB
 /** Max AST trees to keep in LRU cache */
 const AST_CACHE_CAP = 50;
-export const runPipelineFromRepo = async (repoPath, onProgress) => {
+export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const graph = createKnowledgeGraph();
-    const symbolTable = createSymbolTable();
+    const ctx = createResolutionContext();
+    const symbolTable = ctx.symbols;
     let astCache = createASTCache(AST_CACHE_CAP);
-    const importMap = createImportMap();
     const cleanup = () => {
         astCache.clear();
-        symbolTable.clear();
+        ctx.clear();
     };
     try {
         // ── Phase 1: Scan paths only (no content read) ─────────────────────
@@ -87,6 +91,14 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
             console.warn(`Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`);
         }
         const totalParseable = parseableScanned.length;
+        if (totalParseable === 0) {
+            onProgress({
+                phase: 'parsing',
+                percent: 82,
+                message: 'No parseable files found — skipping parsing phase',
+                stats: { filesProcessed: 0, totalFiles: 0, nodesCreated: graph.nodeCount },
+            });
+        }
         // Build byte-budget chunks
         const chunks = [];
         let currentChunk = [];
@@ -113,14 +125,30 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
             message: `Parsing ${totalParseable} files in ${numChunks} chunk${numChunks !== 1 ? 's' : ''}...`,
             stats: { filesProcessed: 0, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
         });
+        // Don't spawn workers for tiny repos — overhead exceeds benefit
+        const MIN_FILES_FOR_WORKERS = 15;
+        const MIN_BYTES_FOR_WORKERS = 512 * 1024;
+        const totalBytes = parseableScanned.reduce((s, f) => s + f.size, 0);
         // Create worker pool once, reuse across chunks
         let workerPool;
-        try {
-            const workerUrl = new URL('./workers/parse-worker.js', import.meta.url);
-            workerPool = createWorkerPool(workerUrl);
-        }
-        catch (err) {
-            // Worker pool creation failed — sequential fallback
+        if (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS) {
+            try {
+                let workerUrl = new URL('./workers/parse-worker.js', import.meta.url);
+                // When running under vitest, import.meta.url points to src/ where no .js exists.
+                // Fall back to the compiled dist/ worker so the pool can spawn real worker threads.
+                const thisDir = fileURLToPath(new URL('.', import.meta.url));
+                if (!fs.existsSync(fileURLToPath(workerUrl))) {
+                    const distWorker = path.resolve(thisDir, '..', '..', '..', 'dist', 'core', 'ingestion', 'workers', 'parse-worker.js');
+                    if (fs.existsSync(distWorker)) {
+                        workerUrl = pathToFileURL(distWorker);
+                    }
+                }
+                workerPool = createWorkerPool(workerUrl);
+            }
+            catch (err) {
+                if (isDev)
+                    console.warn('Worker pool creation failed, using sequential fallback:', err.message);
+            }
         }
         let filesParsedSoFar = 0;
         // AST cache sized for one chunk (sequential fallback uses it for import/call/heritage)
@@ -155,24 +183,53 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
                         stats: { filesProcessed: globalCurrent, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
                     });
                 }, workerPool);
+                const chunkBasePercent = 20 + ((filesParsedSoFar / totalParseable) * 62);
                 if (chunkWorkerData) {
                     // Imports
-                    await processImportsFromExtracted(graph, allPathObjects, chunkWorkerData.imports, importMap, undefined, repoPath, importCtx);
-                    // Calls — resolve immediately, then free the array
-                    if (chunkWorkerData.calls.length > 0) {
-                        await processCallsFromExtracted(graph, chunkWorkerData.calls, symbolTable, importMap);
-                    }
-                    // Heritage — resolve immediately, then free
-                    if (chunkWorkerData.heritage.length > 0) {
-                        await processHeritageFromExtracted(graph, chunkWorkerData.heritage, symbolTable);
-                    }
-                    // Routes — resolve immediately (Laravel route→controller CALLS edges)
-                    if (chunkWorkerData.routes && chunkWorkerData.routes.length > 0) {
-                        await processRoutesFromExtracted(graph, chunkWorkerData.routes, symbolTable, importMap);
-                    }
+                    await processImportsFromExtracted(graph, allPathObjects, chunkWorkerData.imports, ctx, (current, total) => {
+                        onProgress({
+                            phase: 'parsing',
+                            percent: Math.round(chunkBasePercent),
+                            message: `Resolving imports (chunk ${chunkIdx + 1}/${numChunks})...`,
+                            detail: `${current}/${total} files`,
+                            stats: { filesProcessed: filesParsedSoFar, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
+                        });
+                    }, repoPath, importCtx);
+                    // Calls + Heritage + Routes — resolve in parallel (no shared mutable state between them)
+                    // This is safe because each writes disjoint relationship types into idempotent id-keyed Maps,
+                    // and the single-threaded event loop prevents races between synchronous addRelationship calls.
+                    await Promise.all([
+                        processCallsFromExtracted(graph, chunkWorkerData.calls, ctx, (current, total) => {
+                            onProgress({
+                                phase: 'parsing',
+                                percent: Math.round(chunkBasePercent),
+                                message: `Resolving calls (chunk ${chunkIdx + 1}/${numChunks})...`,
+                                detail: `${current}/${total} files`,
+                                stats: { filesProcessed: filesParsedSoFar, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
+                            });
+                        }, chunkWorkerData.constructorBindings),
+                        processHeritageFromExtracted(graph, chunkWorkerData.heritage, ctx, (current, total) => {
+                            onProgress({
+                                phase: 'parsing',
+                                percent: Math.round(chunkBasePercent),
+                                message: `Resolving heritage (chunk ${chunkIdx + 1}/${numChunks})...`,
+                                detail: `${current}/${total} records`,
+                                stats: { filesProcessed: filesParsedSoFar, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
+                            });
+                        }),
+                        processRoutesFromExtracted(graph, chunkWorkerData.routes ?? [], ctx, (current, total) => {
+                            onProgress({
+                                phase: 'parsing',
+                                percent: Math.round(chunkBasePercent),
+                                message: `Resolving routes (chunk ${chunkIdx + 1}/${numChunks})...`,
+                                detail: `${current}/${total} routes`,
+                                stats: { filesProcessed: filesParsedSoFar, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
+                            });
+                        }),
+                    ]);
                 }
                 else {
-                    await processImports(graph, chunkFiles, astCache, importMap, undefined, repoPath, allPaths);
+                    await processImports(graph, chunkFiles, astCache, ctx, undefined, repoPath, allPaths);
                     sequentialChunkPaths.push(chunkPaths);
                 }
                 filesParsedSoFar += chunkFiles.length;
@@ -191,120 +248,139 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
                 .filter(p => chunkContents.has(p))
                 .map(p => ({ path: p, content: chunkContents.get(p) }));
             astCache = createASTCache(chunkFiles.length);
-            await processCalls(graph, chunkFiles, astCache, symbolTable, importMap);
-            await processHeritage(graph, chunkFiles, astCache, symbolTable);
+            const rubyHeritage = await processCalls(graph, chunkFiles, astCache, ctx);
+            await processHeritage(graph, chunkFiles, astCache, ctx);
+            if (rubyHeritage.length > 0) {
+                await processHeritageFromExtracted(graph, rubyHeritage, ctx);
+            }
             astCache.clear();
         }
+        // Log resolution cache stats
+        if (isDev) {
+            const rcStats = ctx.getStats();
+            const total = rcStats.cacheHits + rcStats.cacheMisses;
+            const hitRate = total > 0 ? ((rcStats.cacheHits / total) * 100).toFixed(1) : '0';
+            console.log(`🔍 Resolution cache: ${rcStats.cacheHits} hits, ${rcStats.cacheMisses} misses (${hitRate}% hit rate)`);
+        }
         // Free import resolution context — suffix index + resolve cache no longer needed
         // (allPathObjects and importCtx hold ~94MB+ for large repos)
         allPathObjects.length = 0;
         importCtx.resolveCache.clear();
         importCtx.suffixIndex = null;
         importCtx.normalizedFileList = null;
-        if (isDev) {
-            let importsCount = 0;
-            for (const r of graph.iterRelationships()) {
-                if (r.type === 'IMPORTS')
-                    importsCount++;
+        let communityResult;
+        let processResult;
+        if (!options?.skipGraphPhases) {
+            // ── Phase 4.5: Method Resolution Order ──────────────────────────────
+            onProgress({
+                phase: 'parsing',
+                percent: 81,
+                message: 'Computing method resolution order...',
+                stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
+            });
+            const mroResult = computeMRO(graph);
+            if (isDev && mroResult.entries.length > 0) {
+                console.log(`🔀 MRO: ${mroResult.entries.length} classes analyzed, ${mroResult.ambiguityCount} ambiguities found, ${mroResult.overrideEdges} OVERRIDES edges`);
             }
-            console.log(`📊 Pipeline: graph has ${importsCount} IMPORTS, ${graph.relationshipCount} total relationships`);
-        }
-        // ── Phase 5: Communities ───────────────────────────────────────────
-        onProgress({
-            phase: 'communities',
-            percent: 82,
-            message: 'Detecting code communities...',
-            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
-        });
-        const communityResult = await processCommunities(graph, (message, progress) => {
-            const communityProgress = 82 + (progress * 0.10);
+            // ── Phase 5: Communities ───────────────────────────────────────────
             onProgress({
                 phase: 'communities',
-                percent: Math.round(communityProgress),
-                message,
+                percent: 82,
+                message: 'Detecting code communities...',
                 stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
             });
-        });
-        if (isDev) {
-            console.log(`🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`);
-        }
-        communityResult.communities.forEach(comm => {
-            graph.addNode({
-                id: comm.id,
-                label: 'Community',
-                properties: {
-                    name: comm.label,
-                    filePath: '',
-                    heuristicLabel: comm.heuristicLabel,
-                    cohesion: comm.cohesion,
-                    symbolCount: comm.symbolCount,
-                }
+            communityResult = await processCommunities(graph, (message, progress) => {
+                const communityProgress = 82 + (progress * 0.10);
+                onProgress({
+                    phase: 'communities',
+                    percent: Math.round(communityProgress),
+                    message,
+                    stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
+                });
             });
-        });
-        communityResult.memberships.forEach(membership => {
-            graph.addRelationship({
-                id: `${membership.nodeId}_member_of_${membership.communityId}`,
-                type: 'MEMBER_OF',
-                sourceId: membership.nodeId,
-                targetId: membership.communityId,
-                confidence: 1.0,
-                reason: 'leiden-algorithm',
+            if (isDev) {
+                console.log(`🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`);
+            }
+            communityResult.communities.forEach(comm => {
+                graph.addNode({
+                    id: comm.id,
+                    label: 'Community',
+                    properties: {
+                        name: comm.label,
+                        filePath: '',
+                        heuristicLabel: comm.heuristicLabel,
+                        cohesion: comm.cohesion,
+                        symbolCount: comm.symbolCount,
+                    }
+                });
             });
-        });
-        // ── Phase 6: Processes ─────────────────────────────────────────────
-        onProgress({
-            phase: 'processes',
-            percent: 94,
-            message: 'Detecting execution flows...',
-            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
-        });
-        let symbolCount = 0;
-        graph.forEachNode(n => { if (n.label !== 'File')
-            symbolCount++; });
-        const dynamicMaxProcesses = Math.max(20, Math.min(300, Math.round(symbolCount / 10)));
-        const processResult = await processProcesses(graph, communityResult.memberships, (message, progress) => {
-            const processProgress = 94 + (progress * 0.05);
+            communityResult.memberships.forEach(membership => {
+                graph.addRelationship({
+                    id: `${membership.nodeId}_member_of_${membership.communityId}`,
+                    type: 'MEMBER_OF',
+                    sourceId: membership.nodeId,
+                    targetId: membership.communityId,
+                    confidence: 1.0,
+                    reason: 'leiden-algorithm',
+                });
+            });
+            // ── Phase 6: Processes ─────────────────────────────────────────────
             onProgress({
                 phase: 'processes',
-                percent: Math.round(processProgress),
-                message,
+                percent: 94,
+                message: 'Detecting execution flows...',
                 stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
             });
-        }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 });
-        if (isDev) {
-            console.log(`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`);
-        }
-        processResult.processes.forEach(proc => {
-            graph.addNode({
-                id: proc.id,
-                label: 'Process',
-                properties: {
-                    name: proc.label,
-                    filePath: '',
-                    heuristicLabel: proc.heuristicLabel,
-                    processType: proc.processType,
-                    stepCount: proc.stepCount,
-                    communities: proc.communities,
-                    entryPointId: proc.entryPointId,
-                    terminalId: proc.terminalId,
-                }
+            let symbolCount = 0;
+            graph.forEachNode(n => { if (n.label !== 'File')
+                symbolCount++; });
+            const dynamicMaxProcesses = Math.max(20, Math.min(300, Math.round(symbolCount / 10)));
+            processResult = await processProcesses(graph, communityResult.memberships, (message, progress) => {
+                const processProgress = 94 + (progress * 0.05);
+                onProgress({
+                    phase: 'processes',
+                    percent: Math.round(processProgress),
+                    message,
+                    stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
+                });
+            }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 });
+            if (isDev) {
+                console.log(`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`);
+            }
+            processResult.processes.forEach(proc => {
+                graph.addNode({
+                    id: proc.id,
+                    label: 'Process',
+                    properties: {
+                        name: proc.label,
+                        filePath: '',
+                        heuristicLabel: proc.heuristicLabel,
+                        processType: proc.processType,
+                        stepCount: proc.stepCount,
+                        communities: proc.communities,
+                        entryPointId: proc.entryPointId,
+                        terminalId: proc.terminalId,
+                    }
+                });
             });
-        });
-        processResult.steps.forEach(step => {
-            graph.addRelationship({
-                id: `${step.nodeId}_step_${step.step}_${step.processId}`,
-                type: 'STEP_IN_PROCESS',
-                sourceId: step.nodeId,
-                targetId: step.processId,
-                confidence: 1.0,
-                reason: 'trace-detection',
-                step: step.step,
+            processResult.steps.forEach(step => {
+                graph.addRelationship({
+                    id: `${step.nodeId}_step_${step.step}_${step.processId}`,
+                    type: 'STEP_IN_PROCESS',
+                    sourceId: step.nodeId,
+                    targetId: step.processId,
+                    confidence: 1.0,
+                    reason: 'trace-detection',
+                    step: step.step,
+                });
             });
-        });
+        }
         onProgress({
             phase: 'complete',
             percent: 100,
-            message: `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes detected.`,
+            message: communityResult && processResult
+                ? `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes detected.`
+                : 'Graph complete! (graph phases skipped)',
             stats: {
                 filesProcessed: totalFiles,
                 totalFiles,

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

@@ -10,6 +10,7 @@
  * Processes help agents understand how features work through the codebase.
  */
 import { calculateEntryPointScore, isTestFile } from './entry-point-scoring.js';
+import { SupportedLanguages } from '../../config/supported-languages.js';
 const isDev = process.env.NODE_ENV === 'development';
 const DEFAULT_CONFIG = {
     maxTraceDepth: 10,
@@ -178,7 +179,7 @@ const findEntryPoints = (graph, reverseCallsEdges, callsEdges) => {
         if (callees.length === 0)
             continue;
         // Calculate entry point score using new scoring system
-        const { score: baseScore, reasons } = calculateEntryPointScore(node.properties.name, node.properties.language || 'javascript', node.properties.isExported ?? false, callers.length, callees.length, filePath // Pass filePath for framework detection
+        const { score: baseScore, reasons } = calculateEntryPointScore(node.properties.name, node.properties.language ?? SupportedLanguages.JavaScript, node.properties.isExported ?? false, callers.length, callees.length, filePath // Pass filePath for framework detection
         );
         let score = baseScore;
         const astFrameworkMultiplier = node.properties.astFrameworkMultiplier ?? 1.0;

package/dist/core/ingestion/resolution-context.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Resolution Context
+ *
+ * Single implementation of tiered name resolution. Replaces the duplicated
+ * tier-selection logic previously split between symbol-resolver.ts and
+ * call-processor.ts.
+ *
+ * Resolution tiers (highest confidence first):
+ * 1. Same file (lookupExactFull — authoritative)
+ * 2a-named. Named binding chain (walkBindingChain via NamedImportMap)
+ * 2a. Import-scoped (lookupFuzzy filtered by ImportMap)
+ * 2b. Package-scoped (lookupFuzzy filtered by PackageMap)
+ * 3. Global (all candidates — consumers must check candidate count)
+ */
+import type { SymbolTable, SymbolDefinition } from './symbol-table.js';
+import type { NamedImportBinding } from './import-processor.js';
+/** Resolution tier for tracking, logging, and test assertions. */
+export type ResolutionTier = 'same-file' | 'import-scoped' | 'global';
+/** Tier-selected candidates with metadata. */
+export interface TieredCandidates {
+    readonly candidates: readonly SymbolDefinition[];
+    readonly tier: ResolutionTier;
+}
+/** Confidence scores per resolution tier. */
+export declare const TIER_CONFIDENCE: Record<ResolutionTier, number>;
+export type ImportMap = Map<string, Set<string>>;
+export type PackageMap = Map<string, Set<string>>;
+export type NamedImportMap = Map<string, Map<string, NamedImportBinding>>;
+export interface ResolutionContext {
+    /**
+     * The only resolution API. Returns all candidates at the winning tier.
+     *
+     * Tier 3 ('global') returns ALL candidates regardless of count —
+     * consumers must check candidates.length and refuse ambiguous matches.
+     */
+    resolve(name: string, fromFile: string): TieredCandidates | null;
+    /** Symbol table — used by parsing-processor to populate symbols. */
+    readonly symbols: SymbolTable;
+    /** Raw maps — used by import-processor to populate import data. */
+    readonly importMap: ImportMap;
+    readonly packageMap: PackageMap;
+    readonly namedImportMap: NamedImportMap;
+    enableCache(filePath: string): void;
+    clearCache(): void;
+    getStats(): {
+        fileCount: number;
+        globalSymbolCount: number;
+        cacheHits: number;
+        cacheMisses: number;
+    };
+    clear(): void;
+}
+export declare const createResolutionContext: () => ResolutionContext;

package/dist/core/ingestion/resolution-context.js

@@ -0,0 +1,132 @@
+/**
+ * Resolution Context
+ *
+ * Single implementation of tiered name resolution. Replaces the duplicated
+ * tier-selection logic previously split between symbol-resolver.ts and
+ * call-processor.ts.
+ *
+ * Resolution tiers (highest confidence first):
+ * 1. Same file (lookupExactFull — authoritative)
+ * 2a-named. Named binding chain (walkBindingChain via NamedImportMap)
+ * 2a. Import-scoped (lookupFuzzy filtered by ImportMap)
+ * 2b. Package-scoped (lookupFuzzy filtered by PackageMap)
+ * 3. Global (all candidates — consumers must check candidate count)
+ */
+import { createSymbolTable } from './symbol-table.js';
+import { isFileInPackageDir } from './import-processor.js';
+import { walkBindingChain } from './named-binding-extraction.js';
+/** Confidence scores per resolution tier. */
+export const TIER_CONFIDENCE = {
+    'same-file': 0.95,
+    'import-scoped': 0.9,
+    'global': 0.5,
+};
+export const createResolutionContext = () => {
+    const symbols = createSymbolTable();
+    const importMap = new Map();
+    const packageMap = new Map();
+    const namedImportMap = new Map();
+    // Per-file cache state
+    let cacheFile = null;
+    let cache = null;
+    let cacheHits = 0;
+    let cacheMisses = 0;
+    // --- Core resolution (single implementation of tier logic) ---
+    const resolveUncached = (name, fromFile) => {
+        // Tier 1: Same file — authoritative match
+        const localDef = symbols.lookupExactFull(fromFile, name);
+        if (localDef) {
+            return { candidates: [localDef], tier: 'same-file' };
+        }
+        // Get all global definitions for subsequent tiers
+        const allDefs = symbols.lookupFuzzy(name);
+        // Tier 2a-named: Check named bindings BEFORE empty-allDefs early return
+        // because aliased imports mean lookupFuzzy('U') returns empty but we
+        // can resolve via the exported name.
+        const chainResult = walkBindingChain(name, fromFile, symbols, namedImportMap, allDefs);
+        if (chainResult && chainResult.length > 0) {
+            return { candidates: chainResult, tier: 'import-scoped' };
+        }
+        if (allDefs.length === 0)
+            return null;
+        // Tier 2a: Import-scoped — definition in a file imported by fromFile
+        const importedFiles = importMap.get(fromFile);
+        if (importedFiles) {
+            const importedDefs = allDefs.filter(def => importedFiles.has(def.filePath));
+            if (importedDefs.length > 0) {
+                return { candidates: importedDefs, tier: 'import-scoped' };
+            }
+        }
+        // Tier 2b: Package-scoped — definition in a package dir imported by fromFile
+        const importedPackages = packageMap.get(fromFile);
+        if (importedPackages) {
+            const packageDefs = allDefs.filter(def => {
+                for (const dirSuffix of importedPackages) {
+                    if (isFileInPackageDir(def.filePath, dirSuffix))
+                        return true;
+                }
+                return false;
+            });
+            if (packageDefs.length > 0) {
+                return { candidates: packageDefs, tier: 'import-scoped' };
+            }
+        }
+        // Tier 3: Global — pass all candidates through.
+        // Consumers must check candidate count and refuse ambiguous matches.
+        return { candidates: allDefs, tier: 'global' };
+    };
+    const resolve = (name, fromFile) => {
+        // Check cache (only when enabled AND fromFile matches cached file)
+        if (cache && cacheFile === fromFile) {
+            if (cache.has(name)) {
+                cacheHits++;
+                return cache.get(name);
+            }
+            cacheMisses++;
+        }
+        const result = resolveUncached(name, fromFile);
+        // Store in cache if active and file matches
+        if (cache && cacheFile === fromFile) {
+            cache.set(name, result);
+        }
+        return result;
+    };
+    // --- Cache lifecycle ---
+    const enableCache = (filePath) => {
+        cacheFile = filePath;
+        if (!cache)
+            cache = new Map();
+        else
+            cache.clear();
+    };
+    const clearCache = () => {
+        cacheFile = null;
+        // Reuse the Map instance — just clear entries to reduce GC pressure at scale.
+        cache?.clear();
+    };
+    const getStats = () => ({
+        ...symbols.getStats(),
+        cacheHits,
+        cacheMisses,
+    });
+    const clear = () => {
+        symbols.clear();
+        importMap.clear();
+        packageMap.clear();
+        namedImportMap.clear();
+        clearCache();
+        cacheHits = 0;
+        cacheMisses = 0;
+    };
+    return {
+        resolve,
+        symbols,
+        importMap,
+        packageMap,
+        namedImportMap,
+        enableCache,
+        clearCache,
+        getStats,
+        clear,
+    };
+};

package/dist/core/ingestion/resolvers/csharp.d.ts

@@ -0,0 +1,22 @@
+/**
+ * C# namespace import resolution.
+ * Handles using-directive resolution via .csproj root namespace stripping.
+ */
+import type { SuffixIndex } from './utils.js';
+/** C# project config parsed from .csproj files */
+export interface CSharpProjectConfig {
+    /** Root namespace from <RootNamespace> or assembly name (default: project directory name) */
+    rootNamespace: string;
+    /** Directory containing the .csproj file */
+    projectDir: string;
+}
+/**
+ * Resolve a C# using-directive import path to matching .cs files.
+ * Tries single-file match first, then directory match for namespace imports.
+ */
+export declare function resolveCSharpImport(importPath: string, csharpConfigs: CSharpProjectConfig[], normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string[];
+/**
+ * Compute the directory suffix for a C# namespace import (for PackageMap).
+ * Returns a suffix like "/ProjectDir/Models/" or null if no config matches.
+ */
+export declare function resolveCSharpNamespaceDir(importPath: string, csharpConfigs: CSharpProjectConfig[]): string | null;