@getmikk/core 1.8.3 → 1.9.1

package/src/graph/impact-analyzer.ts

@@ -1,144 +1,157 @@
-import type { DependencyGraph, GraphEdge, ImpactResult, ClassifiedImpact, RiskLevel } from './types.js'
+import type { DependencyGraph, ImpactResult, ClassifiedImpact } from './types.js'
+import { RiskEngine } from './risk-engine.js'
+import { ConfidenceEngine } from './confidence-engine.js'
 
 /**
- * ImpactAnalyzer — Given changed nodes, walks the graph backwards (BFS)
- * to find everything that depends on them.
- * Powers "what breaks if I change X?"
- *
- * Risk classification:
- *   CRITICAL = direct caller (depth 1) that crosses a module boundary
- *   HIGH     = direct caller (depth 1) within the same module
- *   MEDIUM   = depth 2
- *   LOW      = depth 3+
- *
- * Confidence is derived from the quality of resolved edges in the traversal
- * path, not from the size of the result set. A small impact set built from
- * low-confidence (unresolved/fuzzy) edges is still LOW confidence.
+ * Mikk 2.0: Impact Analyzer
+ * Given changed nodes, walks the graph backwards (reverse dependency)
+ * to find everything impacted, computing quantitative risk and confidence.
  */
 export class ImpactAnalyzer {
-    constructor(private graph: DependencyGraph) { }
+    private riskEngine: RiskEngine;
+    private confidenceEngine: ConfidenceEngine;
+
+    constructor(private graph: DependencyGraph) {
+        this.riskEngine = new RiskEngine(graph);
+        this.confidenceEngine = new ConfidenceEngine(graph);
+    }
 
     /** Given a list of changed node IDs, find everything impacted */
-    analyze(changedNodeIds: string[]): ImpactResult {
-        const visited = new Set<string>()
-        const depthMap = new Map<string, number>()
-        // Track the minimum confidence seen along the path to each node
-        const pathConfidence = new Map<string, number>()
-
-        const queue: { id: string; depth: number; confidence: number }[] =
-            changedNodeIds.map(id => ({ id, depth: 0, confidence: 1.0 }))
-        // Use an index pointer instead of queue.shift() to avoid O(n) cost per dequeue.
-        let queueHead = 0
-        let maxDepth = 0
-
-        const changedSet = new Set(changedNodeIds)
-
-        // Collect module IDs of the changed nodes — filter out undefined so that
-        // nodes without a moduleId don't accidentally match every other unmoduled node
-        // and cause everything to appear "same module".
-        const changedModules = new Set<string>()
-        for (const id of changedNodeIds) {
-            const node = this.graph.nodes.get(id)
-            if (node?.moduleId) changedModules.add(node.moduleId)
-        }
+    public analyze(changedNodeIds: string[]): ImpactResult {
+        // depth and shortest-path tracking per visited node
+        const visited = new Map<string, { depth: number, paths: string[][] }>();
+        // Use an index pointer instead of queue.shift() to avoid O(n) dequeue cost.
+        const queue: { id: string, depth: number, path: string[], pathSet: Set<string> }[] =
+            changedNodeIds.map(id => ({ id, depth: 0, path: [id], pathSet: new Set([id]) }));
+        let queueHead = 0;
+
+        let maxDepth = 0;
+        const entryPoints = new Set<string>();
+        const criticalModules = new Set<string>();
 
         while (queueHead < queue.length) {
-            const { id: current, depth, confidence: pathConf } = queue[queueHead++]
-            if (visited.has(current)) continue
-            visited.add(current)
-            depthMap.set(current, depth)
-            pathConfidence.set(current, pathConf)
-            maxDepth = Math.max(maxDepth, depth)
-
-            // Find everything that depends on current (incoming edges)
-            const dependents = this.graph.inEdges.get(current) || []
-            for (const edge of dependents) {
-                if (!visited.has(edge.source) && edge.type !== 'contains') {
-                    // Propagate the minimum confidence seen so far on this path.
-                    // A chain is only as trustworthy as its weakest link.
-                    const edgeConf = edge.confidence ?? 1.0
-                    const newPathConf = Math.min(pathConf, edgeConf)
-                    queue.push({ id: edge.source, depth: depth + 1, confidence: newPathConf })
+            const { id: current, depth, path, pathSet } = queue[queueHead++];
+
+            if (!visited.has(current)) {
+                visited.set(current, { depth, paths: [path] });
+            } else {
+                visited.get(current)!.paths.push(path);
+                if (depth < visited.get(current)!.depth) {
+                    visited.get(current)!.depth = depth;
                 }
             }
-        }
 
-        const impacted = [...visited].filter(id => !changedSet.has(id))
+            maxDepth = Math.max(maxDepth, depth);
+            const node = this.graph.nodes.get(current);
 
-        // Classify each impacted node by risk level
-        const classified: ImpactResult['classified'] = {
-            critical: [],
-            high: [],
-            medium: [],
-            low: [],
-        }
+            if (node?.metadata?.isExported) {
+                entryPoints.add(current);
+            }
 
-        for (const id of impacted) {
-            const node = this.graph.nodes.get(id)
-            if (!node) continue
+            const dependents = this.graph.inEdges.get(current) || [];
+            for (const edge of dependents) {
+                // 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);
+                    queue.push({
+                        id: edge.from,
+                        depth: depth + 1,
+                        path: [...path, edge.from],
+                        pathSet: newPathSet,
+                    });
+                }
+            }
+        }
 
-            const depth = depthMap.get(id) ?? 999
-            // A node crosses a module boundary when its module differs from ALL changed modules.
-            // If the node has no moduleId, treat it as crossing a boundary (unknown module ≠ known).
-            const crossesBoundary = !node.moduleId || !changedModules.has(node.moduleId)
+        const impactedIds = Array.from(visited.keys()).filter(id => 
+            !changedNodeIds.includes(id) && id.startsWith('fn:')
+        );
+        
+        let totalRisk = 0;
+        let totalConfidence = 0;
+
+        const classified = {
+            critical: [] as ClassifiedImpact[],
+            high: [] as ClassifiedImpact[],
+            medium: [] as ClassifiedImpact[],
+            low: [] as ClassifiedImpact[]
+        };
+
+        for (const id of impactedIds) {
+            const context = visited.get(id)!;
+            const node = this.graph.nodes.get(id);
+            let risk = this.riskEngine.scoreNode(id);
+
+            // Path reversal for confidence calculation (since BFS walks backwards)
+            const reversedPaths = context.paths.map(p => [...p].reverse());
+            const confidence = this.confidenceEngine.calculateNodeAggregatedConfidence(reversedPaths);
+
+            // Mikk 2.0 Hybrid Risk: Boost if boundary crossed at depth 1
+            // Check if ANY changed node crosses module boundary (not just first one)
+            if (context.depth === 1 && node?.moduleId) {
+                const crossesBoundary = changedNodeIds.some(id => {
+                    const changedNode = this.graph.nodes.get(id);
+                    // Add proper null checks for module IDs
+                    if (!changedNode?.moduleId || !node.moduleId) {
+                        return false;
+                    }
+                    return changedNode.moduleId !== node.moduleId;
+                });
+                if (crossesBoundary) {
+                    risk = Math.max(risk, 80);
+                }
+            }
 
-            const risk: RiskLevel =
-                depth === 1 && crossesBoundary ? 'critical' :
-                depth === 1                    ? 'high'     :
-                depth === 2                    ? 'medium'   :
-                                                 'low'
+            totalRisk += risk;
+            totalConfidence += confidence;
 
-            const entry: ClassifiedImpact = {
+            const impactEntry: ClassifiedImpact = {
                 nodeId: id,
-                label: node.label,
-                file: node.file,
-                moduleId: node.moduleId,
-                risk,
-                depth,
+                label: node?.name || 'unknown',
+                file: node?.file || 'unknown',
+                risk: (risk >= 80 ? 'CRITICAL' : risk >= 60 ? 'HIGH' : risk >= 40 ? 'MEDIUM' : 'LOW'),
+                riskScore: risk,
+                depth: context.depth
+            };
+
+            if (risk >= 80) classified.critical.push(impactEntry);
+            else if (risk >= 60) classified.high.push(impactEntry);
+            else if (risk >= 40) classified.medium.push(impactEntry);
+            else classified.low.push(impactEntry);
+
+            if (risk > 70 && node?.moduleId) {
+                criticalModules.add(node.moduleId);
             }
-
-            classified[risk].push(entry)
-        }
-
-        return {
-            changed: changedNodeIds,
-            impacted,
-            depth: maxDepth,
-            confidence: this.computeConfidence(impacted, pathConfidence),
-            classified,
         }
-    }
 
-    /**
-     * Derive confidence from the actual quality of edges traversed, not from
-     * result size. A small result built from fuzzy/unresolved edges is LOW
-     * confidence; a large result built from high-confidence AST edges is HIGH.
-     *
-     * Algorithm:
-     *   - Compute the average minimum-path-confidence across all impacted nodes.
-     *   - Penalise for deep chains (they amplify uncertainty).
-     *   - Map the combined score to HIGH / MEDIUM / LOW.
-     */
-    private computeConfidence(
-        impacted: string[],
-        pathConfidence: Map<string, number>,
-    ): 'high' | 'medium' | 'low' {
-        if (impacted.length === 0) return 'high'
-
-        // Average path confidence across all impacted nodes
-        let total = 0
-        for (const id of impacted) {
-            total += pathConfidence.get(id) ?? 1.0
-        }
-        const avgConf = total / impacted.length
+        const avgConfidence = impactedIds.length > 0 
+            ? totalConfidence / impactedIds.length 
+            : 1.0;
 
-        // Penalise for large impact sets: confidence erodes with result size
-        const sizePenalty = impacted.length > 20 ? 0.15 : impacted.length > 10 ? 0.08 : 0
+        const riskScore = impactedIds.length > 0
+            ? Math.min(Math.max(totalRisk / impactedIds.length, 0), 100)
+            : 0;
 
-        const score = avgConf - sizePenalty
+        const allImpacted: ClassifiedImpact[] = [
+            ...classified.critical,
+            ...classified.high,
+            ...classified.medium,
+            ...classified.low
+        ];
 
-        if (score >= 0.75) return 'high'
-        if (score >= 0.50) return 'medium'
-        return 'low'
+        return {
+            changed: changedNodeIds,
+            impacted: impactedIds,
+            allImpacted,
+            depth: maxDepth,
+            entryPoints: Array.from(entryPoints),
+            criticalModules: Array.from(criticalModules),
+            paths: Array.from(visited.values()).flatMap(v => v.paths),
+            confidence: Number(avgConfidence.toFixed(3)),
+            riskScore: Math.round(riskScore),
+            classified
+        };
     }
 }

package/src/graph/index.ts

@@ -4,4 +4,8 @@ export { ImpactAnalyzer } from './impact-analyzer.js'
 export { ClusterDetector } from './cluster-detector.js'
 export { DeadCodeDetector } from './dead-code-detector.js'
 export type { DeadCodeResult, DeadCodeEntry } from './dead-code-detector.js'
+export { RiskEngine } from './risk-engine.js'
+export type { RiskContext, RiskModifiers } from './risk-engine.js'
+export { ConfidenceEngine } from './confidence-engine.js'
+export { QueryEngine } from './query-engine.js'
 

package/src/graph/memory-manager.ts

@@ -0,0 +1,186 @@
+/**
+ * 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.
+ */
+
+const MEMORY_THRESHOLDS = {
+    WARNING:   100 * 1024 * 1024,   // 100 MB
+    CRITICAL:  200 * 1024 * 1024,   // 200 MB
+    EMERGENCY: 400 * 1024 * 1024,   // 400 MB
+} as const
+
+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
+    percentage: number
+    status: 'normal' | 'warning' | 'critical' | 'emergency'
+}
+
+export interface MemoryManagerConfig {
+    maxAge?:       number
+    maxNodes?:     number
+    gcInterval?:   number
+    enableAutoGC?: boolean
+}
+
+export class MemoryManager {
+    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.maxAge     = config.maxAge     ?? DEFAULT_CONFIG.maxAge
+        this.maxNodes   = config.maxNodes   ?? DEFAULT_CONFIG.maxNodes
+        this.gcInterval = config.gcInterval ?? DEFAULT_CONFIG.gcInterval
+
+        if (config.enableAutoGC !== false) this.startAutoGC()
+    }
+
+    getMemoryStats(): MemoryStats {
+        const u = process.memoryUsage()
+        const percentage = (u.heapUsed / u.heapTotal) * 100
+
+        let status: MemoryStats['status'] = 'normal'
+        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: u.heapUsed, heapTotal: u.heapTotal, external: u.external, rss: u.rss, percentage, status }
+    }
+
+    isMemoryCritical(): boolean {
+        const { status } = this.getMemoryStats()
+        return status === 'critical' || status === 'emergency'
+    }
+
+    forceGC(): void {
+        if (typeof global.gc === 'function') global.gc()
+    }
+
+    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() })
+    }
+
+    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 entry.data
+    }
+
+    clearCache(): void {
+        this.nodeCache.clear()
+    }
+
+    cleanup(): void {
+        const now = Date.now()
+        for (const [id, e] of this.nodeCache) {
+            if (now - e.timestamp > this.maxAge) this.nodeCache.delete(id)
+        }
+        this.forceGC()
+    }
+
+    stopAutoGC(): void {
+        if (this.gcTimer) { clearInterval(this.gcTimer); this.gcTimer = undefined }
+    }
+
+    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()
+    }
+}
+
+/**
+ * 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
+
+    constructor(config?: MemoryManagerConfig) {
+        this.memoryManager = new MemoryManager(config)
+    }
+
+    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 {
+            return this.buildInternal(lock)
+        } finally {
+            this.memoryManager.cleanup()
+        }
+    }
+
+    getMemoryStats(): MemoryStats { return this.memoryManager.getMemoryStats() }
+    dispose(): void               { this.memoryManager.dispose() }
+
+    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[]>()
+
+        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, [])
+        }
+
+        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 }
+    }
+}

package/src/graph/query-engine.ts

@@ -0,0 +1,76 @@
+import type { DependencyGraph } from './types.js'
+
+/**
+ * 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 this node?) */
+    getDependents(nodeId: string): string[] {
+        return (this.graph.inEdges.get(nodeId) ?? [])
+            .filter(e => e.type !== 'contains')
+            .map(e => e.from)
+    }
+
+    /** 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)
+    }
+
+    /**
+     * Find the shortest path between two nodes using BFS.
+     * Returns an ordered array of node IDs, or null if no path exists.
+     */
+    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 visited = new Set<string>([start])
+        // Each entry: [nodeId, pathSoFar]
+        const queue: Array<[string, string[]]> = [[start, [start]]]
+        let head = 0
+
+        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([edge.to, [...path, edge.to]])
+                }
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Get the full downstream (transitive dependents) of a node.
+     * Answers "What would break if I change X?"
+     */
+    getDownstreamImpact(nodeId: string): string[] {
+        const visited = new Set<string>()
+        const queue: string[] = [nodeId]
+        let head = 0
+
+        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)
+                }
+            }
+        }
+
+        return [...visited]
+    }
+}

package/src/graph/risk-engine.ts

@@ -0,0 +1,86 @@
+import type { DependencyGraph, GraphNode } from './types.js'
+
+export interface RiskContext {
+    connectedNodesCount: number;
+    dependencyDepth: number;
+}
+
+export interface RiskModifiers {
+    isAuthOrSecurity: boolean;
+    isDatabaseOrState: boolean;
+    isPublicAPI: boolean;
+}
+
+/**
+ * Mikk 2.0: Risk Engine
+ * Computes risk scores based on a quantitative mathematical model.
+ */
+export class RiskEngine {
+    constructor(private graph: DependencyGraph) {}
+
+    /**
+     * Compute the absolute risk score (0-100) for modifying a specific node.
+     * Formula: Base Risk = (Connected Nodes * 1.5) + (Depth * 2) + Modifiers
+     */
+    public scoreNode(nodeId: string): number {
+        const node = this.graph.nodes.get(nodeId);
+        if (!node) return 0;
+
+        const context = this.analyzeContext(nodeId);
+        const modifiers = this.analyzeModifiers(node);
+
+        let score = (context.connectedNodesCount * 1.5) + (context.dependencyDepth * 2);
+
+        // Apply strict modifiers
+        if (modifiers.isAuthOrSecurity) score += 30;
+        if (modifiers.isDatabaseOrState) score += 20;
+        if (modifiers.isPublicAPI) score += 15;
+
+        return Math.min(Math.max(score, 0), 100);
+    }
+
+    private analyzeContext(nodeId: string): RiskContext {
+        const visited = new Set<string>();
+        let maxDepth = 0;
+
+        // Use index pointer instead of queue.shift() — avoids O(n) array shift per pop.
+        const queue: Array<{ id: string, depth: number }> = [{ id: nodeId, depth: 0 }];
+        let queueHead = 0;
+        visited.add(nodeId);
+
+        let connectedNodesCount = 0;
+
+        while (queueHead < queue.length) {
+            const current = queue[queueHead++];
+            maxDepth = Math.max(maxDepth, current.depth);
+
+            const inEdges = this.graph.inEdges.get(current.id) || [];
+            connectedNodesCount += inEdges.length;
+
+            for (const edge of inEdges) {
+                if (!visited.has(edge.from)) {
+                    visited.add(edge.from);
+                    queue.push({ id: edge.from, depth: current.depth + 1 });
+                }
+            }
+        }
+
+        return {
+            connectedNodesCount,
+            dependencyDepth: maxDepth
+        };
+    }
+
+    private analyzeModifiers(node: GraphNode): RiskModifiers {
+        const nameAndFile = `${node.name} ${node.file}`.toLowerCase();
+        
+        const authKeywords = ['auth', 'login', 'jwt', 'verify', 'token', 'crypt', 'hash', 'password'];
+        const dbKeywords = ['db', 'query', 'sql', 'insert', 'update', 'delete', 'redis', 'cache', 'transaction'];
+        
+        return {
+            isAuthOrSecurity: authKeywords.some(kw => nameAndFile.includes(kw)),
+            isDatabaseOrState: dbKeywords.some(kw => nameAndFile.includes(kw)),
+            isPublicAPI: !!node.metadata?.isExported
+        };
+    }
+}