@getmikk/core 1.8.3 → 1.9.1

package/src/error-handler.ts

@@ -0,0 +1,432 @@
+/**
+ * Standardized Error Handling System
+ * 
+ * Provides consistent error creation, handling, and reporting across the Mikk codebase.
+ * Uses centralized error codes and messages from constants.ts.
+ */
+
+import type { ERROR_CODES } from './constants.js'
+import { ERROR_MESSAGES } from './constants.js'
+type ErrorCodes = keyof typeof ERROR_CODES
+
+// ─── Error Types ─────────────────────────────────────────────────────────────
+
+export class MikkError extends Error {
+    public readonly code: ErrorCodes
+    public readonly category: ErrorCategory
+    public readonly context: Record<string, unknown>
+    public readonly timestamp: Date
+    public readonly stack?: string
+
+    constructor(
+        code: ErrorCodes,
+        message?: string,
+        context: Record<string, unknown> = {},
+        cause?: Error
+    ) {
+        // Get the default message from constants if not provided
+        const defaultMessage = getDefaultErrorMessage(code, context)
+        const finalMessage = message || defaultMessage
+
+        super(finalMessage, { cause })
+        this.name = 'MikkError'
+        this.code = code
+        this.category = categorizeError(code)
+        this.context = context
+        this.timestamp = new Date()
+        
+        // Capture stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, MikkError)
+        }
+    }
+
+    /**
+     * Create a human-readable error summary
+     */
+    toSummary(): string {
+        return `[${this.code}] ${this.message}`
+    }
+
+    /**
+     * Get detailed error information for logging
+     */
+    toDetailed(): string {
+        const contextStr = Object.keys(this.context).length > 0
+            ? `\nContext: ${JSON.stringify(this.context, null, 2)}`
+            : ''
+        const stackStr = this.stack ? `\nStack: ${this.stack}` : ''
+        
+        return `${this.toSummary()}${contextStr}${stackStr}`
+    }
+
+    /**
+     * Convert to JSON for API responses
+     */
+    toJSON(): {
+        code: ErrorCodes
+        message: string
+        category: ErrorCategory
+        context: Record<string, unknown>
+        timestamp: string
+    } {
+        return {
+            code: this.code,
+            message: this.message,
+            category: this.category,
+            context: this.context,
+            timestamp: this.timestamp.toISOString(),
+        }
+    }
+}
+
+export enum ErrorCategory {
+    FILE_SYSTEM = 'FILE_SYSTEM',
+    MODULE_LOADING = 'MODULE_LOADING',
+    GRAPH = 'GRAPH',
+    TOKEN_BUDGET = 'TOKEN_BUDGET',
+    VALIDATION = 'VALIDATION',
+    NETWORK = 'NETWORK',
+    PERFORMANCE = 'PERFORMANCE',
+    UNKNOWN = 'UNKNOWN',
+}
+
+// ─── Error Creation Helpers ───────────────────────────────────────────────────
+
+export class ErrorBuilder {
+    private code?: ErrorCodes
+    private message?: string
+    private context: Record<string, unknown> = {}
+    private cause?: Error
+
+    static create(): ErrorBuilder {
+        return new ErrorBuilder()
+    }
+
+    withCode(code: ErrorCodes): ErrorBuilder {
+        this.code = code
+        return this
+    }
+
+    withMessage(message: string): ErrorBuilder {
+        this.message = message
+        return this
+    }
+
+    withContext(key: string, value: unknown): ErrorBuilder {
+        this.context[key] = value
+        return this
+    }
+
+    withContextObject(context: Record<string, unknown>): ErrorBuilder {
+        this.context = { ...this.context, ...context }
+        return this
+    }
+
+    withCause(cause: Error): ErrorBuilder {
+        this.cause = cause
+        return this
+    }
+
+    build(): MikkError {
+        if (!this.code) {
+            throw new Error('Error code is required')
+        }
+        return new MikkError(this.code, this.message, this.context, this.cause)
+    }
+}
+
+// ─── Error Handler Utility ───────────────────────────────────────────────────
+
+export class ErrorHandler {
+    private static instance: ErrorHandler
+    private errorListeners: ((error: MikkError) => void)[] = []
+
+    static getInstance(): ErrorHandler {
+        if (!ErrorHandler.instance) {
+            ErrorHandler.instance = new ErrorHandler()
+        }
+        return ErrorHandler.instance
+    }
+
+    /**
+     * Add error listener for centralized error handling
+     */
+    addListener(listener: (error: MikkError) => void): void {
+        this.errorListeners.push(listener)
+    }
+
+    /**
+     * Remove error listener
+     */
+    removeListener(listener: (error: MikkError) => void): void {
+        const index = this.errorListeners.indexOf(listener)
+        if (index > -1) {
+            this.errorListeners.splice(index, 1)
+        }
+    }
+
+    /**
+     * Handle an error - notifies all listeners
+     */
+    handleError(error: MikkError): void {
+        for (const listener of this.errorListeners) {
+            try {
+                listener(error)
+            } catch (listenerError) {
+                console.error('Error in error listener:', listenerError)
+            }
+        }
+    }
+
+    /**
+     * Wrap a function with error handling
+     */
+    wrap<T extends (...args: any[]) => any>(
+        fn: T,
+        errorCode: ErrorCodes,
+        context: Record<string, unknown> = {}
+    ): T {
+        return ((...args: any[]) => {
+            try {
+                const result = fn(...args)
+                
+                // Handle async functions
+                if (result && typeof result.catch === 'function') {
+                    return result.catch((error: Error) => {
+                        const mikkError = ErrorBuilder.create()
+                            .withCode(errorCode)
+                            .withCause(error)
+                            .withContextObject(context)
+                            .build()
+                        
+                        this.handleError(mikkError)
+                        throw mikkError
+                    })
+                }
+                
+                return result
+            } catch (error) {
+                const mikkError = ErrorBuilder.create()
+                    .withCode(errorCode)
+                    .withCause(error as Error)
+                    .withContextObject(context)
+                    .build()
+                
+                this.handleError(mikkError)
+                throw mikkError
+            }
+        }) as T
+    }
+}
+
+// ─── Specialized Error Types ─────────────────────────────────────────────────
+
+export class FileSystemError extends MikkError {
+    constructor(code: ErrorCodes, filePath: string, cause?: Error) {
+        super(code, undefined, { filePath }, cause)
+        this.name = 'FileSystemError'
+    }
+}
+
+export class ModuleLoadError extends MikkError {
+    constructor(code: ErrorCodes, moduleName: string, cause?: Error) {
+        super(code, undefined, { moduleName }, cause)
+        this.name = 'ModuleLoadError'
+    }
+}
+
+export class GraphError extends MikkError {
+    constructor(code: ErrorCodes, nodeId?: string, cause?: Error) {
+        super(code, undefined, { nodeId }, cause)
+        this.name = 'GraphError'
+    }
+}
+
+export class TokenBudgetError extends MikkError {
+    constructor(code: ErrorCodes, used: number, budget: number) {
+        super(code, undefined, { used, budget })
+        this.name = 'TokenBudgetError'
+    }
+}
+
+export class ValidationError extends MikkError {
+    constructor(code: ErrorCodes, field: string, value: unknown, message?: string) {
+        super(code, message, { field, value })
+        this.name = 'ValidationError'
+    }
+}
+
+// ─── Error Creation Functions ─────────────────────────────────────────────────
+
+/**
+ * Create a file not found error
+ */
+export function createFileNotFoundError(filePath: string): FileSystemError {
+    return new FileSystemError('FILE_NOT_FOUND', filePath)
+}
+
+/**
+ * Create a file too large error
+ */
+export function createFileTooLargeError(filePath: string, size: number, limit: number): FileSystemError {
+    return new FileSystemError('FILE_TOO_LARGE', filePath)
+}
+
+/**
+ * Create a permission denied error
+ */
+export function createPermissionDeniedError(path: string): FileSystemError {
+    return new FileSystemError('PERMISSION_DENIED', path)
+}
+
+/**
+ * Create a module not found error
+ */
+export function createModuleNotFoundError(moduleName: string): ModuleLoadError {
+    return new ModuleLoadError('MODULE_NOT_FOUND', moduleName)
+}
+
+/**
+ * Create a module load failed error
+ */
+export function createModuleLoadFailedError(moduleName: string, cause?: Error): ModuleLoadError {
+    return new ModuleLoadError('MODULE_LOAD_FAILED', moduleName, cause)
+}
+
+/**
+ * Create a graph build failed error
+ */
+export function createGraphBuildFailedError(reason: string): GraphError {
+    return new GraphError('GRAPH_BUILD_FAILED', undefined, new Error(reason))
+}
+
+/**
+ * Create a node not found error
+ */
+export function createNodeNotFoundError(nodeId: string): GraphError {
+    return new GraphError('NODE_NOT_FOUND', nodeId)
+}
+
+/**
+ * Create a token budget exceeded error
+ */
+export function createTokenBudgetExceededError(used: number, budget: number): TokenBudgetError {
+    return new TokenBudgetError('TOKEN_BUDGET_EXCEEDED', used, budget)
+}
+
+/**
+ * Create a validation error
+ */
+export function createValidationError(field: string, value: unknown, reason?: string): ValidationError {
+    return new ValidationError('INVALID_INPUT', field, value, reason)
+}
+
+// ─── Error Utilities ─────────────────────────────────────────────────────────
+
+/**
+ * Check if an error is a MikkError
+ */
+export function isMikkError(error: unknown): error is MikkError {
+    return error instanceof MikkError
+}
+
+/**
+ * Extract the original cause from an error chain
+ */
+export function getRootCause(error: Error): Error {
+    let current = error
+    while (current.cause && current.cause instanceof Error) {
+        current = current.cause
+    }
+    return current
+}
+
+/**
+ * Convert any error to a MikkError
+ */
+export function toMikkError(error: unknown, defaultCode: ErrorCodes = 'UNKNOWN_ERROR' as ErrorCodes): MikkError {
+    if (isMikkError(error)) {
+        return error
+    }
+    
+    if (error instanceof Error) {
+        return new MikkError(defaultCode, error.message, {}, error)
+    }
+    
+    if (typeof error === 'string') {
+        return new MikkError(defaultCode, error)
+    }
+    
+    return new MikkError(defaultCode, 'Unknown error occurred')
+}
+
+/**
+ * Categorize an error code
+ */
+function categorizeError(code: ErrorCodes): ErrorCategory {
+    if (code.includes('FILE') || code.includes('DIRECTORY')) {
+        return ErrorCategory.FILE_SYSTEM
+    }
+    if (code.includes('MODULE')) {
+        return ErrorCategory.MODULE_LOADING
+    }
+    if (code.includes('GRAPH') || code.includes('NODE')) {
+        return ErrorCategory.GRAPH
+    }
+    if (code.includes('TOKEN')) {
+        return ErrorCategory.TOKEN_BUDGET
+    }
+    if (code.includes('INVALID') || code.includes('VALIDATION')) {
+        return ErrorCategory.VALIDATION
+    }
+    if (code.includes('TIMEOUT')) {
+        return ErrorCategory.PERFORMANCE
+    }
+    
+    return ErrorCategory.UNKNOWN
+}
+
+/**
+ * Get default error message from constants
+ */
+function getDefaultErrorMessage(code: ErrorCodes, context: Record<string, unknown>): string {
+    const template = ERROR_MESSAGES[code] || 'Unknown error occurred'
+    
+    let message = template as string
+    
+    // Replace template variables
+    for (const [key, value] of Object.entries(context)) {
+        message = message.replace(new RegExp(`{${key}}`, 'g'), String(value))
+    }
+    
+    return message
+}
+
+// ─── Default Error Listener ─────────────────────────────────────────────────
+
+/**
+ * Default error listener that logs to console
+ */
+export function createDefaultErrorListener(): (error: MikkError) => void {
+    return (error: MikkError) => {
+        const timestamp = error.timestamp.toISOString()
+        const category = error.category
+        
+        // Use appropriate console method based on category
+        const logMethod = category === ErrorCategory.FILE_SYSTEM || category === ErrorCategory.MODULE_LOADING
+            ? console.error
+            : console.warn
+        
+        logMethod(`[${timestamp}] [${category}] ${error.toSummary()}`)
+        
+        if (process.env.NODE_ENV === 'development') {
+            console.debug(error.toDetailed())
+        }
+    }
+}
+
+// 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,21 +194,28 @@ export class ClusterDetector {
         }
         for (const [name, dupes] of nameCount) {
             if (dupes.length <= 1) continue
-            for (const cluster of dupes) {
-                // Try to find a distinctive directory segment from the cluster ID
-                // e.g. "packages-diagram-generator" → "Diagram Generator"
+            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})`
                 }
             }
         }
 
-        return merged.sort((a, b) => b.confidence - a.confidence)
+        const sorted = merged.sort((a, b) => b.confidence - a.confidence)
+        if (sorted.length <= 1 && files.length > 1) {
+            return this.buildDirectoryClusters(files)
+        }
+        return sorted
     }
 
     // ─── Coupling Matrix ──────────────────────────────────────────
@@ -235,8 +242,8 @@ export class ClusterDetector {
         for (const edge of this.graph.edges) {
             if (edge.type !== 'imports' && edge.type !== 'calls') continue
 
-            const sourceFile = this.getFileForNode(edge.source)
-            const targetFile = this.getFileForNode(edge.target)
+            const sourceFile = this.getFileForNode(edge.from)
+            const targetFile = this.getFileForNode(edge.to)
 
             if (!sourceFile || !targetFile || sourceFile === targetFile) continue
             if (!fileSet.has(sourceFile) || !fileSet.has(targetFile)) continue
@@ -317,7 +324,7 @@ export class ClusterDetector {
             const outEdges = this.graph.outEdges.get(file) || []
             for (const edge of outEdges) {
                 if (edge.type === 'imports') {
-                    if (fileSet.has(edge.target)) {
+                    if (fileSet.has(edge.to)) {
                         internalEdges++
                     } else {
                         externalEdges++
@@ -331,10 +338,10 @@ export class ClusterDetector {
             const containEdges = this.graph.outEdges.get(file) || []
             for (const containEdge of containEdges) {
                 if (containEdge.type === 'contains') {
-                    const fnOutEdges = this.graph.outEdges.get(containEdge.target) || []
+                    const fnOutEdges = this.graph.outEdges.get(containEdge.to) || []
                     for (const callEdge of fnOutEdges) {
                         if (callEdge.type === 'calls') {
-                            const targetNode = this.graph.nodes.get(callEdge.target)
+                            const targetNode = this.graph.nodes.get(callEdge.to)
                             if (targetNode && fileSet.has(targetNode.file)) {
                                 internalEdges++
                             } else if (targetNode) {
@@ -380,7 +387,7 @@ export class ClusterDetector {
             const containEdges = this.graph.outEdges.get(f) || []
             return containEdges
                 .filter(e => e.type === 'contains')
-                .map(e => e.target)
+                .map(e => e.to)
         })
     }
 
@@ -413,18 +420,16 @@ export class ClusterDetector {
      *      "features/auth/api/route.ts"   → "features-auth-api"
      */
     private getDirSegments(filePath: string): string {
-        const parts = filePath.split('/')
-        // Remove filename (last part with an extension)
-        const dirs = parts.filter((p, i) => i < parts.length - 1 || !p.includes('.'))
-        // Drop 'src' prefix — it carries no semantic meaning
-        const meaningful = dirs.filter(d => d !== 'src' && d !== '')
-        if (meaningful.length === 0) {
-            // Fallback: use the filename without extension
-            const last = parts[parts.length - 1]
+        const parts = filePath.replace(/\\/g, '/').split('/')
+        const filtered = parts.filter(part => part && part.toLowerCase() !== 'src')
+        const dirs = filtered.slice(0, -1) // drop filename
+        if (dirs.length === 0) {
+            const last = filtered[filtered.length - 1] || ''
             return last.replace(/\.[^.]+$/, '') || 'unknown'
         }
-        // Take up to 3 segments for a unique but concise ID
-        return meaningful.slice(0, 3).join('-')
+        const sliceStart = Math.max(0, dirs.length - 3)
+        const meaningful = dirs.slice(sliceStart)
+        return meaningful.map(seg => seg.replace(/[^a-zA-Z0-9]+/g, '-').toLowerCase()).join('-') || 'unknown'
     }
 
     // ─── Cluster Merging ──────────────────────────────────────────
@@ -470,6 +475,31 @@ export class ClusterDetector {
         return result
     }
 
+    private buildDirectoryClusters(fileNodes: string[]): ModuleCluster[] {
+        const buckets = new Map<string, string[]>()
+        for (const file of fileNodes) {
+            const bucketId = this.getDirSegments(this.getNodeFile(file))
+            const entry = buckets.get(bucketId) ?? []
+            entry.push(file)
+            buckets.set(bucketId, entry)
+        }
+
+        const clusters: ModuleCluster[] = []
+        for (const [id, bucket] of buckets) {
+            const filePaths = bucket.map(f => this.getNodeFile(f))
+            const functions = this.getFunctionIdsForFiles(bucket)
+            clusters.push({
+                id,
+                files: filePaths,
+                confidence: this.computeClusterConfidence(bucket),
+                suggestedName: this.inferSemanticName(filePaths, functions),
+                functions,
+            })
+        }
+
+        return clusters.sort((a, b) => b.confidence - a.confidence)
+    }
+
     /** Get the base directory (first meaningful segment) for a set of files */
     private getBaseDir(files: string[]): string {
         if (files.length === 0) return 'unknown'
@@ -505,7 +535,7 @@ export class ClusterDetector {
     private inferSemanticName(filePaths: string[], functionIds: string[]): string {
         // Collect words from function names
         const fnLabels = functionIds
-            .map(id => this.graph.nodes.get(id)?.label ?? '')
+            .map(id => this.graph.nodes.get(id)?.name ?? '')
             .filter(Boolean)
 
         // Collect file basenames without extension

package/src/graph/confidence-engine.ts

@@ -0,0 +1,85 @@
+import type { DependencyGraph } from './types.js'
+
+/**
+ * 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 along a specific ordered path of node IDs.
+     *
+     * @param pathIds Array of node IDs forming a path (e.g. ['A', 'B', 'C'])
+     *                in forward (caller → callee) order.
+     * @returns Cumulative confidence from 0.0 to 1.0; 1.0 for trivial paths.
+     */
+    calculatePathConfidence(pathIds: string[]): number {
+        if (pathIds.length < 2) return 1.0
+
+        let totalConfidence = 1.0
+
+        for (let i = 0; i < pathIds.length - 1; i++) {
+            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) {
+                // No edge found in either direction — path is broken or unresolvable
+                return 0.0
+            }
+
+            totalConfidence *= maxEdgeConfidence
+        }
+
+        return totalConfidence
+    }
+
+    /**
+     * Average confidence across all paths leading to a target node.
+     */
+    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))
+    }
+}