@getmikk/core 1.9.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/core",
-    "version": "1.9.0",
+    "version": "2.0.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -28,11 +28,11 @@
         "oxc-resolver": "^11.19.1",
         "tree-sitter-wasms": "^0.1.13",
         "web-tree-sitter": "0.20.8",
-        "zod": "^3.22.0"
+        "zod": "^3.22.0",
+        "typescript": "^5.7.0"
     },
     "devDependencies": {
         "@types/bun": "^1.3.10",
-        "@types/node": "^22.0.0",
-        "typescript": "^5.7.0"
+        "@types/node": "^22.0.0"
     }
 }

package/src/contract/lock-reader.ts

@@ -77,6 +77,10 @@ function compactifyLock(lock: MikkLock): any {
             // P4: no hash, P6: no moduleId
         }
         // P7: integer calls/calledBy referencing fnIndex positions
+        const { name: parsedName } = parseEntityKey(fn.id, 'fn:')
+        if (fn.name && fn.name !== parsedName) {
+            c.name = fn.name
+        }
         if (fn.calls.length > 0) c.calls = fn.calls.map(id => fnIndexMap.get(id) ?? -1).filter((n: number) => n >= 0)
         if (fn.calledBy.length > 0) c.calledBy = fn.calledBy.map(id => fnIndexMap.get(id) ?? -1).filter((n: number) => n >= 0)
         if (fn.params && fn.params.length > 0) c.params = fn.params
@@ -193,7 +197,8 @@ function hydrateLock(raw: any): any {
     for (const [key, c] of Object.entries(raw.functions || {}) as [string, any][]) {
         // P7: key is integer index -> look up full ID via fnIndex
         const fullId = hasFnIndex ? (fnIndex[parseInt(key)] || key) : key
-        const { name, file } = parseEntityKey(fullId, 'fn:')
+        const { name: parsedName, file } = parseEntityKey(fullId, 'fn:')
+        const name = c.name || parsedName
         const lines = c.lines || [c.startLine || 0, c.endLine || 0]
         // P7: integer calls/calledBy -> resolve to full string IDs (backward compat: strings pass through)
         const calls = (c.calls || []).map((v: any) => typeof v === 'number' ? (fnIndex[v] ?? null) : v).filter(Boolean)

package/src/error-handler.ts

@@ -426,5 +426,7 @@ export function createDefaultErrorListener(): (error: MikkError) => void {
     }
 }
 
-// Initialize default error listener
-ErrorHandler.getInstance().addListener(createDefaultErrorListener())
+// NOTE: Do NOT register listeners at module load time - every import would
+// add a duplicate listener that is never cleaned up. Instead, call:
+//   ErrorHandler.getInstance().addListener(createDefaultErrorListener())
+// once during application bootstrap (CLI entry-point, MCP server startup).

package/src/graph/cluster-detector.ts

@@ -194,14 +194,19 @@ export class ClusterDetector {
         }
         for (const [name, dupes] of nameCount) {
             if (dupes.length <= 1) continue
-            for (const cluster of dupes) {
+            for (let i = 0; i < dupes.length; i++) {
+                const cluster = dupes[i]
                 const segments = cluster.id.split('-')
                     .filter(s => s !== 'packages' && s !== 'apps' && s !== 'src')
                 const suffix = segments
                     .map(s => s.charAt(0).toUpperCase() + s.slice(1))
                     .join(' ')
-                if (suffix && suffix !== name) {
+                
+                if (suffix && suffix.toLowerCase() !== name.toLowerCase()) {
                     cluster.suggestedName = `${name} (${suffix})`
+                } else {
+                    // Force disambiguation using the already-deduplicated cluster.id
+                    cluster.suggestedName = `${name} (${cluster.id})`
                 }
             }
         }

package/src/graph/confidence-engine.ts

@@ -1,60 +1,85 @@
 import type { DependencyGraph } from './types.js'
 
 /**
- * Mikk 2.0: Confidence Engine
- * Computes the reliability of impact paths using a decay-based formula.
- * Base edge confidences (direct call = 1.0, fuzzy match = 0.6) are
- * multiplied along the path to determine full path confidence.
+ * ConfidenceEngine — computes path-confidence for impact analysis results.
+ *
+ * ImpactAnalyzer builds paths by walking BACKWARDS through `inEdges`
+ * (dependent → dependency direction).  After the BFS the paths are
+ * stored in forward-traversal order (changed-node → impacted-node).
+ *
+ * To find the edge between two consecutive path nodes we must therefore
+ * look in `inEdges[next]` for an edge whose `.from === current`, which is
+ * the same as looking in `outEdges[current]` for an edge whose `.to === next`.
+ * We prefer `outEdges` because it gives O(out-degree) scans instead of
+ * O(in-degree), but we fall back to `inEdges` so the engine is correct
+ * regardless of traversal direction stored in the path.
  */
 export class ConfidenceEngine {
     constructor(private graph: DependencyGraph) {}
 
     /**
-     * Compute confidence decay along a specific path of node IDs.
+     * Compute confidence along a specific ordered path of node IDs.
+     *
      * @param pathIds Array of node IDs forming a path (e.g. ['A', 'B', 'C'])
-     * @returns Cumulative confidence score from 0.0 to 1.0
+     *                in forward (caller → callee) order.
+     * @returns Cumulative confidence from 0.0 to 1.0; 1.0 for trivial paths.
      */
-    public calculatePathConfidence(pathIds: string[]): number {
-        if (pathIds.length < 2) return 1.0;
+    calculatePathConfidence(pathIds: string[]): number {
+        if (pathIds.length < 2) return 1.0
 
-        let totalConfidence = 1.0;
+        let totalConfidence = 1.0
 
         for (let i = 0; i < pathIds.length - 1; i++) {
-            const current = pathIds[i];
-            const next = pathIds[i + 1];
-
-            const outEdges = this.graph.outEdges.get(current) || [];
-            // Find the highest confidence edge connecting current -> next
-            let maxEdgeConfidence = 0.0;
-            
-            for (const edge of outEdges) {
-                if (edge.to === next) {
-                    if (edge.confidence > maxEdgeConfidence) {
-                        maxEdgeConfidence = edge.confidence;
+            const current = pathIds[i]
+            const next    = pathIds[i + 1]
+
+            // Prefer outEdges[current] for O(out-degree) look-up
+            const edges = this.graph.outEdges.get(current)
+                ?? this.graph.inEdges.get(next)   // fallback: scan inEdges of the next node
+                ?? []
+
+            let maxEdgeConfidence = 0.0
+            for (const edge of edges) {
+                // outEdges: edge.from === current, edge.to === next
+                // inEdges:  edge.to   === next,    edge.from === current
+                if (edge.to === next && edge.from === current) {
+                    if ((edge.confidence ?? 1.0) > maxEdgeConfidence) {
+                        maxEdgeConfidence = edge.confidence ?? 1.0
+                    }
+                }
+            }
+
+            if (maxEdgeConfidence === 0.0) {
+                // Try inEdges[next] if outEdges produced no match
+                const inbound = this.graph.inEdges.get(next) ?? []
+                for (const edge of inbound) {
+                    if (edge.from === current) {
+                        if ((edge.confidence ?? 1.0) > maxEdgeConfidence) {
+                            maxEdgeConfidence = edge.confidence ?? 1.0
+                        }
                     }
                 }
             }
 
             if (maxEdgeConfidence === 0.0) {
-                return 0.0; // Path is broken or no valid edge
+                // No edge found in either direction — path is broken or unresolvable
+                return 0.0
             }
 
-            totalConfidence *= maxEdgeConfidence;
+            totalConfidence *= maxEdgeConfidence
         }
 
-        return totalConfidence;
+        return totalConfidence
     }
 
     /**
-     * Calculates the overall aggregated confidence for a target node
-     * by averaging the confidence of all paths leading to it.
+     * Average confidence across all paths leading to a target node.
      */
-    public calculateNodeAggregatedConfidence(paths: string[][]): number {
-        if (paths.length === 0) return 1.0;
-        
-        const pathConfidences = paths.map(path => this.calculatePathConfidence(path));
-        const sum = pathConfidences.reduce((a, b) => a + b, 0);
-        
-        return Number((sum / paths.length).toFixed(3));
+    calculateNodeAggregatedConfidence(paths: string[][]): number {
+        if (paths.length === 0) return 1.0
+
+        const pathConfidences = paths.map(p => this.calculatePathConfidence(p))
+        const sum = pathConfidences.reduce((a, b) => a + b, 0)
+        return Number((sum / paths.length).toFixed(3))
     }
 }

package/src/graph/impact-analyzer.ts

@@ -50,8 +50,8 @@ export class ImpactAnalyzer {
 
             const dependents = this.graph.inEdges.get(current) || [];
             for (const edge of dependents) {
-                if (edge.type === 'contains') continue;
-                // Use pathSet (O(1) lookup) instead of path.includes() (O(depth))
+                // Allow 'contains' edges so if a function is changed, the file it belongs to is impacted, 
+                // which then allows traversing 'imports' edges from other files.
                 if (!pathSet.has(edge.from)) {
                     const newPathSet = new Set(pathSet);
                     newPathSet.add(edge.from);
@@ -65,7 +65,9 @@ export class ImpactAnalyzer {
             }
         }
 
-        const impactedIds = Array.from(visited.keys()).filter(id => !changedNodeIds.includes(id));
+        const impactedIds = Array.from(visited.keys()).filter(id => 
+            !changedNodeIds.includes(id) && id.startsWith('fn:')
+        );
         
         let totalRisk = 0;
         let totalConfidence = 0;

package/src/graph/memory-manager.ts

@@ -1,213 +1,136 @@
 /**
- * Memory Manager for Large Graph Operations
- * 
- * Provides memory monitoring, cleanup, and optimization for graph operations
- * that can consume significant amounts of memory in large codebases.
+ * MemoryManager — monitors and limits heap usage during graph operations.
+ *
+ * Design notes:
+ *  - No console.log/warn in production paths. All diagnostics are exposed
+ *    via getMemoryStats() so callers can decide how to surface them.
+ *  - The auto-GC timer is ref-unref'd so it doesn't keep the Node process alive.
+ *  - dispose() must be called when the manager is no longer needed.
  */
 
-// Memory thresholds in bytes
 const MEMORY_THRESHOLDS = {
-    WARNING: 100 * 1024 * 1024,    // 100MB
-    CRITICAL: 200 * 1024 * 1024,   // 200MB
-    EMERGENCY: 400 * 1024 * 1024,  // 400MB
-}
+    WARNING:   100 * 1024 * 1024,   // 100 MB
+    CRITICAL:  200 * 1024 * 1024,   // 200 MB
+    EMERGENCY: 400 * 1024 * 1024,   // 400 MB
+} as const
 
-// Default cleanup configuration
-const DEFAULT_CLEANUP_CONFIG = {
-    maxAge: 30 * 60 * 1000,        // 30 minutes
-    maxNodes: 10000,                // Maximum nodes to keep in memory
-    gcInterval: 60 * 1000,          // GC check interval (1 minute)
-}
+const DEFAULT_CONFIG = {
+    maxAge:     30 * 60 * 1000,     // 30 minutes
+    maxNodes:   10_000,
+    gcInterval: 60 * 1000,          // 1 minute
+} as const
 
 export interface MemoryStats {
-    heapUsed: number
-    heapTotal: number
-    external: number
-    rss: number
+    heapUsed:   number
+    heapTotal:  number
+    external:   number
+    rss:        number
     percentage: number
     status: 'normal' | 'warning' | 'critical' | 'emergency'
 }
 
 export interface MemoryManagerConfig {
-    maxAge?: number
-    maxNodes?: number
-    gcInterval?: number
+    maxAge?:       number
+    maxNodes?:     number
+    gcInterval?:   number
     enableAutoGC?: boolean
 }
 
-/**
- * Memory Manager for graph operations
- */
 export class MemoryManager {
-    private config: Required<MemoryManagerConfig>
-    private lastGC = Date.now()
-    private nodeCache = new Map<string, { data: any; timestamp: number }>()
-    private gcTimer?: NodeJS.Timeout
+    private readonly maxAge:     number
+    private readonly maxNodes:   number
+    private readonly gcInterval: number
+    private nodeCache = new Map<string, { data: unknown; timestamp: number }>()
+    private gcTimer?: ReturnType<typeof setInterval>
 
     constructor(config: MemoryManagerConfig = {}) {
-        this.config = {
-            maxAge: config.maxAge ?? DEFAULT_CLEANUP_CONFIG.maxAge,
-            maxNodes: config.maxNodes ?? DEFAULT_CLEANUP_CONFIG.maxNodes,
-            gcInterval: config.gcInterval ?? DEFAULT_CLEANUP_CONFIG.gcInterval,
-            enableAutoGC: config.enableAutoGC ?? true,
-        }
+        this.maxAge     = config.maxAge     ?? DEFAULT_CONFIG.maxAge
+        this.maxNodes   = config.maxNodes   ?? DEFAULT_CONFIG.maxNodes
+        this.gcInterval = config.gcInterval ?? DEFAULT_CONFIG.gcInterval
 
-        if (this.config.enableAutoGC) {
-            this.startAutoGC()
-        }
+        if (config.enableAutoGC !== false) this.startAutoGC()
     }
 
-    /**
-     * Get current memory statistics
-     */
     getMemoryStats(): MemoryStats {
-        const usage = process.memoryUsage()
-        const percentage = (usage.heapUsed / usage.heapTotal) * 100
+        const u = process.memoryUsage()
+        const percentage = (u.heapUsed / u.heapTotal) * 100
 
         let status: MemoryStats['status'] = 'normal'
-        if (usage.heapUsed > MEMORY_THRESHOLDS.EMERGENCY) {
-            status = 'emergency'
-        } else if (usage.heapUsed > MEMORY_THRESHOLDS.CRITICAL) {
-            status = 'critical'
-        } else if (usage.heapUsed > MEMORY_THRESHOLDS.WARNING) {
-            status = 'warning'
-        }
+        if      (u.heapUsed > MEMORY_THRESHOLDS.EMERGENCY) status = 'emergency'
+        else if (u.heapUsed > MEMORY_THRESHOLDS.CRITICAL)  status = 'critical'
+        else if (u.heapUsed > MEMORY_THRESHOLDS.WARNING)   status = 'warning'
 
-        return {
-            heapUsed: usage.heapUsed,
-            heapTotal: usage.heapTotal,
-            external: usage.external,
-            rss: usage.rss,
-            percentage,
-            status,
-        }
+        return { heapUsed: u.heapUsed, heapTotal: u.heapTotal, external: u.external, rss: u.rss, percentage, status }
     }
 
-    /**
-     * Check if memory usage is critical
-     */
     isMemoryCritical(): boolean {
-        const stats = this.getMemoryStats()
-        return stats.status === 'critical' || stats.status === 'emergency'
+        const { status } = this.getMemoryStats()
+        return status === 'critical' || status === 'emergency'
     }
 
-    /**
-     * Force garbage collection if available
-     */
     forceGC(): void {
-        if (global.gc) {
-            global.gc()
-            this.lastGC = Date.now()
-        }
+        if (typeof global.gc === 'function') global.gc()
     }
 
-    /**
-     * Cache a node with automatic cleanup
-     */
-    cacheNode(id: string, data: any): void {
-        // If we're at the node limit, remove oldest entries
-        if (this.nodeCache.size >= this.config.maxNodes) {
-            this.evictOldestNodes(Math.floor(this.config.maxNodes * 0.1)) // Remove 10%
+    cacheNode(id: string, data: unknown): void {
+        if (this.nodeCache.size >= this.maxNodes) {
+            this.evictOldest(Math.ceil(this.maxNodes * 0.1))
         }
-
-        this.nodeCache.set(id, {
-            data,
-            timestamp: Date.now(),
-        })
+        this.nodeCache.set(id, { data, timestamp: Date.now() })
     }
 
-    /**
-     * Get cached node data
-     */
-    getCachedNode(id: string): any | null {
-        const cached = this.nodeCache.get(id)
-        if (!cached) return null
-
-        // Check if expired
-        if (Date.now() - cached.timestamp > this.config.maxAge) {
+    getCachedNode(id: string): unknown | null {
+        const entry = this.nodeCache.get(id)
+        if (!entry) return null
+        if (Date.now() - entry.timestamp > this.maxAge) {
             this.nodeCache.delete(id)
             return null
         }
-
-        return cached.data
+        return entry.data
     }
 
-    /**
-     * Clear node cache
-     */
     clearCache(): void {
         this.nodeCache.clear()
     }
 
-    /**
-     * Perform comprehensive memory cleanup
-     */
     cleanup(): void {
-        // Clear expired cache entries
         const now = Date.now()
-        for (const [id, cached] of this.nodeCache.entries()) {
-            if (now - cached.timestamp > this.config.maxAge) {
-                this.nodeCache.delete(id)
-            }
+        for (const [id, e] of this.nodeCache) {
+            if (now - e.timestamp > this.maxAge) this.nodeCache.delete(id)
         }
-
-        // Force garbage collection
         this.forceGC()
     }
 
-    /**
-     * Evict oldest nodes from cache
-     */
-    private evictOldestNodes(count: number): void {
-        const entries = Array.from(this.nodeCache.entries())
-            .sort((a, b) => a[1].timestamp - b[1].timestamp)
-
-        for (let i = 0; i < Math.min(count, entries.length); i++) {
-            this.nodeCache.delete(entries[i][0])
-        }
-    }
-
-    /**
-     * Start automatic garbage collection
-     */
-    private startAutoGC(): void {
-        this.gcTimer = setInterval(() => {
-            const stats = this.getMemoryStats()
-            
-            // If memory usage is high, perform cleanup
-            if (stats.status !== 'normal') {
-                this.cleanup()
-            }
-
-            // Periodic cleanup regardless of memory pressure
-            if (Date.now() - this.lastGC > this.config.gcInterval) {
-                this.cleanup()
-            }
-        }, this.config.gcInterval)
-    }
-
-    /**
-     * Stop automatic garbage collection
-     */
     stopAutoGC(): void {
-        if (this.gcTimer) {
-            clearInterval(this.gcTimer)
-            this.gcTimer = undefined
-        }
+        if (this.gcTimer) { clearInterval(this.gcTimer); this.gcTimer = undefined }
     }
 
-    /**
-     * Dispose of memory manager
-     */
     dispose(): void {
         this.stopAutoGC()
         this.clearCache()
         this.forceGC()
     }
+
+    private evictOldest(count: number): void {
+        const sorted = [...this.nodeCache.entries()].sort((a, b) => a[1].timestamp - b[1].timestamp)
+        for (let i = 0; i < Math.min(count, sorted.length); i++) {
+            this.nodeCache.delete(sorted[i][0])
+        }
+    }
+
+    private startAutoGC(): void {
+        this.gcTimer = setInterval(() => {
+            if (this.isMemoryCritical()) this.cleanup()
+        }, this.gcInterval)
+
+        // Don't keep the Node process alive just for GC checks
+        if (this.gcTimer.unref) this.gcTimer.unref()
+    }
 }
 
 /**
- * Memory-aware graph builder wrapper
+ * MemoryAwareGraphBuilder — builds a graph from a lock with memory monitoring.
+ * Builds purely from the in-memory lock; does NOT re-parse source files.
  */
 export class MemoryAwareGraphBuilder {
     private memoryManager: MemoryManager
@@ -216,130 +139,48 @@ export class MemoryAwareGraphBuilder {
         this.memoryManager = new MemoryManager(config)
     }
 
-    /**
-     * Build graph with memory monitoring
-     */
-    buildGraph(lock: any): any {
-        const stats = this.memoryManager.getMemoryStats()
-        
-        // Check memory before starting
-        if (this.memoryManager.isMemoryCritical()) {
-            console.warn('Memory usage is critical, performing cleanup before graph build')
-            this.memoryManager.cleanup()
-        }
+    buildGraph(lock: {
+        functions?: Record<string, { name: string; file: string; moduleId: string; isExported?: boolean; isAsync?: boolean; calls?: string[] }>
+    }) {
+        if (this.memoryManager.isMemoryCritical()) this.memoryManager.cleanup()
 
         try {
-            // Build graph implementation here
-            return this.buildGraphInternal(lock)
+            return this.buildInternal(lock)
         } finally {
-            // Cleanup after build
             this.memoryManager.cleanup()
         }
     }
 
-    /**
-     * Internal graph building implementation
-     */
-    private buildGraphInternal(lock: any): any {
-        const nodes = new Map<string, any>()
-        const edges: any[] = []
-        const outEdges = new Map<string, any[]>()
-        const inEdges = new Map<string, any[]>()
-
-        // Process functions with memory monitoring
-        for (const [id, fn] of Object.entries(lock.functions || {})) {
-            // Check memory periodically
-            if (nodes.size % 1000 === 0) {
-                if (this.memoryManager.isMemoryCritical()) {
-                    console.warn('Memory pressure detected during graph build, forcing cleanup')
-                    this.memoryManager.cleanup()
-                }
-            }
+    getMemoryStats(): MemoryStats { return this.memoryManager.getMemoryStats() }
+    dispose(): void               { this.memoryManager.dispose() }
 
-            const node = {
-                id,
-                name: (fn as any).name,
-                file: (fn as any).file,
-                type: 'function',
-                moduleId: (fn as any).moduleId,
-                metadata: {
-                    isExported: (fn as any).isExported,
-                    isAsync: (fn as any).isAsync,
-                },
-            }
+    private buildInternal(lock: {
+        functions?: Record<string, { name: string; file: string; moduleId: string; isExported?: boolean; isAsync?: boolean; calls?: string[] }>
+    }) {
+        const nodes    = new Map<string, unknown>()
+        const edges:   unknown[] = []
+        const outEdges = new Map<string, unknown[]>()
+        const inEdges  = new Map<string, unknown[]>()
 
-            nodes.set(id, node)
+        for (const [id, fn] of Object.entries(lock.functions ?? {})) {
+            nodes.set(id, {
+                id, name: fn.name, file: fn.file, type: 'function', moduleId: fn.moduleId,
+                metadata: { isExported: fn.isExported, isAsync: fn.isAsync },
+            })
             outEdges.set(id, [])
             inEdges.set(id, [])
         }
 
-        // Process edges
-        for (const [id, fn] of Object.entries(lock.functions || {})) {
-            const calls = (fn as any).calls || []
-            for (const targetId of calls) {
-                if (nodes.has(targetId)) {
-                    const edge = {
-                        from: id,
-                        to: targetId,
-                        type: 'calls',
-                    }
-                    edges.push(edge)
-                    outEdges.get(id)?.push(edge)
-                    inEdges.get(targetId)?.push(edge)
-                }
+        for (const [id, fn] of Object.entries(lock.functions ?? {})) {
+            for (const targetId of fn.calls ?? []) {
+                if (!nodes.has(targetId)) continue
+                const edge = { from: id, to: targetId, type: 'calls', confidence: 1.0 }
+                edges.push(edge)
+                outEdges.get(id)!.push(edge)
+                inEdges.get(targetId)!.push(edge)
             }
         }
 
-        return {
-            nodes,
-            edges,
-            outEdges,
-            inEdges,
-        }
-    }
-
-    /**
-     * Get memory statistics
-     */
-    getMemoryStats(): MemoryStats {
-        return this.memoryManager.getMemoryStats()
-    }
-
-    /**
-     * Dispose of the graph builder
-     */
-    dispose(): void {
-        this.memoryManager.dispose()
-    }
-}
-
-/**
- * Utility function to monitor memory usage during operations
- */
-export function withMemoryMonitoring<T>(
-    operation: () => T,
-    memoryManager?: MemoryManager
-): T {
-    const manager = memoryManager || new MemoryManager({ enableAutoGC: false })
-    
-    const initialStats = manager.getMemoryStats()
-    console.log(`Memory before operation: ${(initialStats.heapUsed / 1024 / 1024).toFixed(1)}MB`)
-
-    try {
-        const result = operation()
-        
-        const finalStats = manager.getMemoryStats()
-        const delta = finalStats.heapUsed - initialStats.heapUsed
-        console.log(`Memory after operation: ${(finalStats.heapUsed / 1024 / 1024).toFixed(1)}MB (${delta >= 0 ? '+' : ''}${(delta / 1024 / 1024).toFixed(1)}MB)`)
-        
-        if (finalStats.status !== 'normal') {
-            console.warn(`Memory status: ${finalStats.status}`)
-        }
-
-        return result
-    } finally {
-        if (!memoryManager) {
-            manager.dispose()
-        }
+        return { nodes, edges, outEdges, inEdges }
     }
 }

package/src/graph/query-engine.ts

@@ -1,79 +1,76 @@
 import type { DependencyGraph } from './types.js'
 
 /**
- * Mikk 2.0: Query Engine
- * Provides high-performance graph traversal and path-finding tools.
- * Focuses on symbol-level precision.
+ * QueryEngine — high-performance graph traversal and path-finding.
+ *
+ * All BFS loops use an index pointer instead of Array.shift() to avoid
+ * the O(n) cost of shifting the underlying array on each dequeue.
  */
 export class QueryEngine {
     constructor(private graph: DependencyGraph) {}
 
-    /** Find all direct dependents (who calls me?) */
-    public getDependents(nodeId: string): string[] {
-        return (this.graph.inEdges.get(nodeId) || [])
+    /** Find all direct dependents (who calls this node?) */
+    getDependents(nodeId: string): string[] {
+        return (this.graph.inEdges.get(nodeId) ?? [])
             .filter(e => e.type !== 'contains')
-            .map(e => e.from);
+            .map(e => e.from)
     }
 
-    /** Find all direct dependencies (who do I call?) */
-    public getDependencies(nodeId: string): string[] {
-        return (this.graph.outEdges.get(nodeId) || [])
+    /** Find all direct dependencies (what does this node call?) */
+    getDependencies(nodeId: string): string[] {
+        return (this.graph.outEdges.get(nodeId) ?? [])
             .filter(e => e.type !== 'contains')
-            .map(e => e.to);
+            .map(e => e.to)
     }
 
-    /** 
+    /**
      * Find the shortest path between two nodes using BFS.
-     * Returns an array of node IDs or null if no path exists.
+     * Returns an ordered array of node IDs, or null if no path exists.
      */
-    public findPath(start: string, end: string): string[] | null {
-        if (!this.graph.nodes.has(start) || !this.graph.nodes.has(end)) return null;
-        if (start === end) return [start];
+    findPath(start: string, end: string): string[] | null {
+        if (!this.graph.nodes.has(start) || !this.graph.nodes.has(end)) return null
+        if (start === end) return [start]
 
-        const queue: { id: string, path: string[] }[] = [{ id: start, path: [start] }];
-        const visited = new Set<string>([start]);
+        const visited = new Set<string>([start])
+        // Each entry: [nodeId, pathSoFar]
+        const queue: Array<[string, string[]]> = [[start, [start]]]
+        let head = 0
 
-        while (queue.length > 0) {
-            const { id, path } = queue.shift()!;
-            
-            const outwardEdges = this.graph.outEdges.get(id) || [];
-            for (const edge of outwardEdges) {
-                if (edge.type === 'contains') continue;
-                
-                if (edge.to === end) {
-                    return [...path, end];
-                }
+        while (head < queue.length) {
+            const [id, path] = queue[head++]
 
+            for (const edge of this.graph.outEdges.get(id) ?? []) {
+                if (edge.type === 'contains') continue
+                if (edge.to === end) return [...path, end]
                 if (!visited.has(edge.to)) {
-                    visited.add(edge.to);
-                    queue.push({ id: edge.to, path: [...path, edge.to] });
+                    visited.add(edge.to)
+                    queue.push([edge.to, [...path, edge.to]])
                 }
             }
         }
 
-        return null;
+        return null
     }
 
-    /** 
-     * Get the full downstream impact (transitive dependents) of a node.
-     * Useful for assessing "What would break if I change X?"
+    /**
+     * Get the full downstream (transitive dependents) of a node.
+     * Answers "What would break if I change X?"
      */
-    public getDownstreamImpact(nodeId: string): string[] {
-        const visited = new Set<string>();
-        const queue: string[] = [nodeId];
+    getDownstreamImpact(nodeId: string): string[] {
+        const visited = new Set<string>()
+        const queue: string[] = [nodeId]
+        let head = 0
 
-        while (queue.length > 0) {
-            const current = queue.shift()!;
-            const dependents = this.getDependents(current);
-            
-            for (const dep of dependents) {
+        while (head < queue.length) {
+            const current = queue[head++]
+            for (const dep of this.getDependents(current)) {
                 if (!visited.has(dep) && dep !== nodeId) {
-                    visited.add(dep);
-                    queue.push(dep);
+                    visited.add(dep)
+                    queue.push(dep)
                 }
             }
         }
 
-        return Array.from(visited);
+        return [...visited]
     }
 }

package/src/index.ts

@@ -8,6 +8,8 @@ export * from './hash/index.js'
 export * from './search/index.js'
 export * from './utils/errors.js'
 export * from './utils/logger.js'
+export { MikkError, ErrorHandler, ErrorBuilder, ErrorCategory, FileSystemError, ModuleLoadError, GraphError, TokenBudgetError, ValidationError, createDefaultErrorListener, createFileNotFoundError, createFileTooLargeError, createPermissionDeniedError, createModuleNotFoundError, createModuleLoadFailedError, createGraphBuildFailedError, createNodeNotFoundError, createTokenBudgetExceededError, createValidationError, isMikkError, getRootCause, toMikkError } from './error-handler.js'
+export type { } from './error-handler.js'
 export { discoverFiles, discoverContextFiles, readFileContent, writeFileContent, fileExists, setupMikkDirectory, readMikkIgnore, parseMikkIgnore, detectProjectLanguage, getDiscoveryPatterns, generateMikkIgnore, updateGitIgnore, cleanupGitIgnore } from './utils/fs.js'
 export type { ContextFile, ContextFileType, ProjectLanguage } from './utils/fs.js'
 export { minimatch } from './utils/minimatch.js'

package/src/parser/index.ts

@@ -100,7 +100,9 @@ export async function parseFiles(
     const goFiles: ParsedFile[] = []
     const treeFiles: ParsedFile[] = []
 
-    const parsePromises = filePaths.map(async (fp) => {
+    // Parse sequentially to avoid races in parser implementations that keep
+    // mutable per-instance state (e.g. language switching/counters).
+    for (const fp of filePaths) {
         const ext = nodePath.extname(fp).toLowerCase()
 
         // Build absolute posix path — this is the single source of truth for all IDs
@@ -111,7 +113,7 @@ export async function parseFiles(
             content = await readFile(absoluteFp)
         } catch {
             // File unreadable — skip silently (deleted, permission error, binary)
-            return
+            continue
         }
 
         try {
@@ -129,9 +131,7 @@ export async function parseFiles(
         } catch {
             // Parser error — skip this file, don't abort the whole run
         }
-    })
-
-    await Promise.all(parsePromises)
+    }
 
     // Resolve imports batch-wise per parser (each has its own resolver)
     let resolvedTreeFiles: ParsedFile[] = treeFiles

package/src/parser/oxc-parser.ts

@@ -12,7 +12,8 @@ import type {
     ParsedExport,
     ParsedParam,
     CallExpression,
-    ParsedGeneric
+    ParsedGeneric,
+    ParsedRoute
 } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -303,6 +304,7 @@ export class OxcParser extends BaseParser {
         const imports: ParsedImport[] = [];
         const exports: ParsedExport[] = [];
         const moduleCalls: CallExpression[] = [];
+        const routes: ParsedRoute[] = [];
 
         const visit = (node: any, parent: any = null): void => {
             if (!node || typeof node !== 'object') return;
@@ -608,8 +610,39 @@ export class OxcParser extends BaseParser {
                 // ── Module-level call expressions ─────────────────────────
                 case 'ExpressionStatement': {
                     if (node.expression?.type === 'CallExpression') {
-                        const calls = extractCalls(node.expression, lineIndex);
+                        const callExpr = node.expression;
+                        const calls = extractCalls(callExpr, lineIndex);
                         moduleCalls.push(...calls);
+                        
+                        // Route detection
+                        const callee = callExpr.callee;
+                        if (callee && (callee.type === 'StaticMemberExpression' || callee.type === 'MemberExpression')) {
+                            const objName = resolveObjectName(callee.object);
+                            const propName = resolvePropertyName(callee.property);
+                            if (objName && propName && /^(router|app|express|.*[Rr]outer.*)$/i.test(objName) && /^(get|post|put|delete|patch|all)$/i.test(propName)) {
+                                const args = callExpr.arguments || [];
+                                const pathArg = args[0];
+                                if (pathArg && (pathArg.type === 'StringLiteral' || pathArg.type === 'Literal' || pathArg.type === 'TemplateLiteral')) {
+                                    const pathVal = pathArg.value || (pathArg.quasis && pathArg.quasis[0]?.value?.raw) || '';
+                                    
+                                    const handlerArg = args[args.length - 1];
+                                    const handlerStr = handlerArg ? content.slice(getSpan(handlerArg).start, getSpan(handlerArg).end).replace(/\s+/g, ' ').trim() : 'unknown';
+                                    
+                                    const middlewares = args.slice(1, -1).map((a: any) => 
+                                        content.slice(getSpan(a).start, getSpan(a).end).replace(/\s+/g, ' ').trim()
+                                    );
+                                    
+                                    routes.push({
+                                        method: propName.toUpperCase() as any,
+                                        path: String(pathVal),
+                                        handler: handlerStr.length > 80 ? handlerStr.slice(0, 80) + '...' : handlerStr,
+                                        middlewares,
+                                        file: normalizedFilePath,
+                                        line: lineIndex.getLine(getSpan(callExpr).start),
+                                    });
+                                }
+                            }
+                        }
                     }
                     break;
                 }
@@ -640,7 +673,7 @@ export class OxcParser extends BaseParser {
             generics,
             imports,
             exports,
-            routes: [],
+            routes,
             calls: moduleCalls,
             hash: hashContent(content),
             parsedAt: Date.now(),

package/src/search/bm25.ts

@@ -95,7 +95,14 @@ export class BM25Index {
 
                 // BM25 score component
                 const tfNorm = (tf * (K1 + 1)) / (tf + K1 * (1 - B + B * (doc.length / this.avgDocLength)))
-                score += idf * tfNorm
+                let termScore = idf * tfNorm
+
+                // Bonus for direct name match in the ID
+                if (doc.id.toLowerCase().includes(term.toLowerCase())) {
+                    termScore += 0.5
+                }
+
+                score += termScore
             }
 
             if (score > 0) {
@@ -181,7 +188,9 @@ export function buildFunctionTokens(fn: {
 
     // Function name tokens (highest signal)
     parts.push(...tokenize(fn.name))
-    parts.push(...tokenize(fn.name)) // Double-weight the name
+    parts.push(...tokenize(fn.name))
+    parts.push(...tokenize(fn.name)) // Triple-weight the name
+    parts.push(`name_exact:${fn.name.toLowerCase()}`)
 
     // File path tokens
     const filename = fn.file.split('/').pop() ?? fn.file