@getmikk/core 1.8.0 → 1.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/core",
-    "version": "1.8.0",
+    "version": "1.8.2",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",

package/src/contract/contract-reader.ts

@@ -1,6 +1,6 @@
-import * as fs from 'node:fs/promises'
 import { MikkContractSchema, type MikkContract } from './schema.js'
 import { ContractNotFoundError } from '../utils/errors.js'
+import { readJsonSafe } from '../utils/json.js'
 
 /**
  * ContractReader -- reads and validates mikk.json from disk.
@@ -8,21 +8,21 @@ import { ContractNotFoundError } from '../utils/errors.js'
 export class ContractReader {
     /** Read and validate mikk.json */
     async read(contractPath: string): Promise<MikkContract> {
-        let content: string
+        let json: any
         try {
-            content = await fs.readFile(contractPath, 'utf-8')
-        } catch {
-            throw new ContractNotFoundError(contractPath)
+            json = await readJsonSafe(contractPath, 'mikk.json')
+        } catch (e: any) {
+            if (e.code === 'ENOENT') {
+                throw new ContractNotFoundError(contractPath)
+            }
+            throw e
         }
 
-        const json = JSON.parse(content.replace(/^\uFEFF/, ''))
         const result = MikkContractSchema.safeParse(json)
-
         if (!result.success) {
             const errors = result.error.issues.map(i => `  ${i.path.join('.')}: ${i.message}`).join('\n')
-            throw new Error(`Invalid mikk.json:\n${errors}`)
+            throw new Error(`Invalid mikk.json structure:\n${errors}`)
         }
-
         return result.data
     }
 }

package/src/contract/lock-reader.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises'
 import { MikkLockSchema, type MikkLock } from './schema.js'
 import { LockNotFoundError } from '../utils/errors.js'
+import { readJsonSafe } from '../utils/json.js'
 
 /**
  * LockReader -- reads and validates mikk.lock.json from disk.
@@ -10,20 +11,22 @@ import { LockNotFoundError } from '../utils/errors.js'
 export class LockReader {
     /** Read and validate mikk.lock.json */
     async read(lockPath: string): Promise<MikkLock> {
-        let content: string
+        let json: any
         try {
-            content = await fs.readFile(lockPath, 'utf-8')
-        } catch {
-            throw new LockNotFoundError()
+            json = await readJsonSafe(lockPath, 'mikk.lock.json')
+        } catch (e: any) {
+            if (e.code === 'ENOENT') {
+                throw new LockNotFoundError()
+            }
+            throw e
         }
 
-        const json = JSON.parse(content.replace(/^\uFEFF/, ''))
         const hydrated = hydrateLock(json)
         const result = MikkLockSchema.safeParse(hydrated)
 
         if (!result.success) {
             const errors = result.error.issues.map(i => `  ${i.path.join('.')}: ${i.message}`).join('\n')
-            throw new Error(`Invalid mikk.lock.json:\n${errors}`)
+            throw new Error(`Invalid mikk.lock.json structure:\n${errors}`)
         }
 
         return result.data

package/src/graph/dead-code-detector.ts

@@ -3,6 +3,19 @@ import type { MikkLock } from '../contract/schema.js'
 
 // ─── Types ──────────────────────────────────────────────────────────
 
+/**
+ * Confidence level for a dead code finding.
+ *
+ *  high   — zero callers, no dynamic patterns, no unresolved imports in the file.
+ *           Safe to remove.
+ *  medium — zero callers via graph, but the file has unresolved imports
+ *           (some calls may not have been traced). Review before removing.
+ *  low    — zero graph callers, but the function name or context suggests it
+ *           may be used dynamically (generic names, lifecycle hooks, etc.).
+ *           Do not remove without manual verification.
+ */
+export type DeadCodeConfidence = 'high' | 'medium' | 'low'
+
 export interface DeadCodeEntry {
     id: string
     name: string
@@ -10,6 +23,7 @@ export interface DeadCodeEntry {
     moduleId?: string
     type: 'function' | 'class'
     reason: string
+    confidence: DeadCodeConfidence
 }
 
 export interface DeadCodeResult {
@@ -22,19 +36,19 @@ export interface DeadCodeResult {
 
 // ─── Exemption patterns ────────────────────────────────────────────
 
-/** Common entry-point function names that are never "dead" even with 0 callers */
+/** Entry-point function names that are never "dead" even with 0 graph callers */
 const ENTRY_POINT_PATTERNS = [
     /^(main|bootstrap|start|init|setup|configure|register|mount)$/i,
     /^(app|server|index|mod|program)$/i,
-    /Handler$/i,          // Express/Koa/Hono handlers
+    /Handler$/i,
     /Middleware$/i,
     /Controller$/i,
-    /^use[A-Z]/,          // React hooks
-    /^handle[A-Z]/,       // Event handlers
-    /^on[A-Z]/,           // Event listeners
+    /^use[A-Z]/,       // React hooks
+    /^handle[A-Z]/,    // Event handlers
+    /^on[A-Z]/,        // Event listeners
 ]
 
-/** Common test function patterns */
+/** Test function patterns */
 const TEST_PATTERNS = [
     /^(it|describe|test|beforeAll|afterAll|beforeEach|afterEach)$/,
     /\.test\./,
@@ -42,31 +56,56 @@ const TEST_PATTERNS = [
     /__test__/,
 ]
 
+/**
+ * Names that are commonly used via dynamic dispatch, string-keyed maps, or
+ * framework injection. A function matching these patterns gets LOW confidence
+ * even if no graph callers exist, because static analysis may have missed it.
+ */
+const DYNAMIC_USAGE_PATTERNS = [
+    /^addEventListener$/i,
+    /^removeEventListener$/i,
+    /^on[A-Z]/,
+    /(invoke|dispatch|emit|call|apply)/i,
+    /^ngOnInit$/i,
+    /^componentDidMount$/i,
+    /^componentWillUnmount$/i,
+]
+
 // ─── Detector ──────────────────────────────────────────────────────
 
 /**
- * DeadCodeDetector — walks the dependency graph and finds functions
- * with zero incoming `calls` edges after applying multi-pass exemptions.
+ * DeadCodeDetector — walks the dependency graph to find functions with zero
+ * incoming `calls` edges after applying multi-pass exemptions.
+ *
+ * Exemptions (function is NOT reported as dead):
+ *   1. Exported symbols — may be consumed by external packages
+ *   2. Entry point name patterns — main, handler, middleware, hooks, etc.
+ *   3. Route handlers — detected via HTTP route registrations in the lock
+ *   4. Test functions — describe, it, test, lifecycle hooks
+ *   5. Constructors — called implicitly by `new`
+ *   6. Called by an exported function in the same file (transitive liveness)
  *
- * Exemptions:
- *   1. Exported symbols (may be consumed externally)
- *   2. Entry point patterns (main, handler, middleware, hooks, etc.)
- *   3. Route handlers (detected HTTP routes)
- *   4. Test functions (describe, it, test, etc.)
- *   5. Decorated classes/functions (typically framework-managed)
- *   6. Constructor methods (called implicitly)
+ * Each dead entry includes a confidence level:
+ *   high   — safe to remove
+ *   medium — file has unresolved imports; verify before removing
+ *   low    — dynamic usage patterns detected; manual review required
  */
 export class DeadCodeDetector {
     private routeHandlers: Set<string>
+    /** Files that have at least one unresolved import (empty resolvedPath) */
+    private filesWithUnresolvedImports: Set<string>
 
     constructor(
         private graph: DependencyGraph,
         private lock: MikkLock,
     ) {
-        // Build a set of handler function names from detected routes
         this.routeHandlers = new Set(
             (lock.routes ?? []).map(r => r.handler).filter(Boolean),
         )
+
+        // Pre-compute which files have unresolved imports so confidence can
+        // be lowered for all functions in those files without scanning per-function.
+        this.filesWithUnresolvedImports = this.buildUnresolvedImportFileSet()
     }
 
     detect(): DeadCodeResult {
@@ -78,35 +117,34 @@ export class DeadCodeDetector {
             totalFunctions++
             const moduleId = fn.moduleId ?? 'unknown'
 
-            // Initialize module bucket
             if (!byModule[moduleId]) {
                 byModule[moduleId] = { dead: 0, total: 0, items: [] }
             }
             byModule[moduleId].total++
 
-            // Check if this function has any incoming call edges
+            // Check for incoming call edges in the graph
             const inEdges = this.graph.inEdges.get(id) || []
             const hasCallers = inEdges.some(e => e.type === 'calls')
+            if (hasCallers) continue
 
-            if (hasCallers) continue // Not dead
-
-            // Apply exemptions
             if (this.isExempt(fn, id)) continue
 
+            const confidence = this.inferConfidence(fn)
             const entry: DeadCodeEntry = {
                 id,
                 name: fn.name,
                 file: fn.file,
                 moduleId,
                 type: 'function',
-                reason: this.inferReason(fn, id),
+                reason: this.inferReason(fn),
+                confidence,
             }
             dead.push(entry)
             byModule[moduleId].dead++
             byModule[moduleId].items.push(entry)
         }
 
-        // Also check classes (if present in lock)
+        // Check classes
         if (this.lock.classes) {
             for (const [id, cls] of Object.entries(this.lock.classes)) {
                 const moduleId = cls.moduleId ?? 'unknown'
@@ -116,9 +154,7 @@ export class DeadCodeDetector {
 
                 const inEdges = this.graph.inEdges.get(id) || []
                 const hasCallers = inEdges.some(e => e.type === 'calls' || e.type === 'imports')
-
-                if (hasCallers) continue
-                if (cls.isExported) continue // Exported classes are exempt
+                if (hasCallers || cls.isExported) continue
 
                 const entry: DeadCodeEntry = {
                     id,
@@ -127,6 +163,7 @@ export class DeadCodeDetector {
                     moduleId,
                     type: 'class',
                     reason: 'Class has no callers or importers and is not exported',
+                    confidence: this.filesWithUnresolvedImports.has(cls.file) ? 'medium' : 'high',
                 }
                 dead.push(entry)
                 byModule[moduleId].dead++
@@ -145,50 +182,72 @@ export class DeadCodeDetector {
         }
     }
 
-    // ─── Exemption checks ──────────────────────────────────────────
+    // ─── Private helpers ───────────────────────────────────────────
 
     private isExempt(fn: MikkLock['functions'][string], id: string): boolean {
-        // 1. Exported functions — may be consumed by external packages
         if (fn.isExported) return true
-
-        // 2. Entry point patterns
         if (ENTRY_POINT_PATTERNS.some(p => p.test(fn.name))) return true
-
-        // 3. Route handlers
         if (this.routeHandlers.has(fn.name)) return true
-
-        // 4. Test functions or in test files
         if (TEST_PATTERNS.some(p => p.test(fn.name) || p.test(fn.file))) return true
-
-        // 5. Constructor methods
         if (fn.name === 'constructor' || fn.name === '__init__') return true
-
-        // 6. Functions called by exported functions in the same file
-        // (transitive liveness — if an exported fn calls this, it's alive)
-        if (this.isCalledByExportedInSameFile(fn, id)) return true
-
+        if (this.isCalledByExportedInSameFile(fn)) return true
         return false
     }
 
-    private isCalledByExportedInSameFile(
-        fn: MikkLock['functions'][string],
-        fnId: string,
-    ): boolean {
-        // Check calledBy — if any caller is exported and in the same file, exempt
+    private isCalledByExportedInSameFile(fn: MikkLock['functions'][string]): boolean {
         for (const callerId of fn.calledBy) {
             const caller = this.lock.functions[callerId]
-            if (caller && caller.isExported && caller.file === fn.file) {
-                return true
-            }
+            if (caller && caller.isExported && caller.file === fn.file) return true
         }
         return false
     }
 
-    private inferReason(fn: MikkLock['functions'][string], id: string): string {
+    /**
+     * Assign a confidence level to a dead code finding.
+     *
+     * Priority (first match wins):
+     *  medium — lock.calledBy has entries that didn't become graph edges:
+     *           something references this function but resolution failed.
+     *  medium — file has unresolved imports: the graph may be incomplete.
+     *  low    — function name matches common dynamic-dispatch patterns.
+     *  high   — none of the above: safe to remove.
+     */
+    private inferConfidence(fn: MikkLock['functions'][string]): DeadCodeConfidence {
+        if (fn.calledBy.length > 0) return 'medium'
+        if (this.filesWithUnresolvedImports.has(fn.file)) return 'medium'
+        if (DYNAMIC_USAGE_PATTERNS.some(p => p.test(fn.name))) return 'low'
+        return 'high'
+    }
+
+    private inferReason(fn: MikkLock['functions'][string]): string {
         if (fn.calledBy.length === 0) {
             return 'No callers found anywhere in the codebase'
         }
-        // calledBy has entries but they didn't resolve to graph edges
-        return `${fn.calledBy.length} references exist but none resolved to active call edges`
+        return `${fn.calledBy.length} reference(s) in lock but none resolved to active call edges`
+    }
+
+    /**
+     * Build the set of file paths that have at least one import whose
+     * resolvedPath is empty. Used to downgrade confidence for all dead
+     * findings in those files, since the graph may be incomplete.
+     *
+     * We derive this from the lock's file entries. Each file entry stores
+     * its imports; any import with an empty resolvedPath (or no match in
+     * the graph nodes) indicates an unresolved dependency.
+     */
+    private buildUnresolvedImportFileSet(): Set<string> {
+        const result = new Set<string>()
+        if (!this.lock.files) return result
+
+        for (const [filePath, fileInfo] of Object.entries(this.lock.files)) {
+            const imports = (fileInfo as any).imports ?? []
+            for (const imp of imports) {
+                if (!imp.resolvedPath || imp.resolvedPath === '') {
+                    result.add(filePath)
+                    break // One unresolved import is enough to flag the file
+                }
+            }
+        }
+        return result
     }
 }