@getmikk/core 1.5.0 → 1.6.0

package/README.md

@@ -1,11 +1,15 @@
 # @getmikk/core
 
-> AST parsing, dependency graph construction, Merkle-tree hashing, contract management, and foundational utilities for the Mikk ecosystem.
+> The foundation of the Mikk ecosystem — TypeScript AST parsing, dependency graph construction, Merkle-tree hashing, contract management, and lock file compilation.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/core)](https://www.npmjs.com/package/@getmikk/core)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-`@getmikk/core` is the foundation package that every other Mikk package depends on. It provides the complete pipeline for understanding a TypeScript codebase: parsing source files into structured ASTs, building a full dependency graph, computing Merkle-tree hashes for drift detection, and managing the `mikk.json` contract and `mikk.lock.json` lock file.
+`@getmikk/core` is the foundation every other Mikk package builds on. It owns the complete pipeline for turning raw **TypeScript and Go** source into structured, queryable intelligence: parsing source files into real ASTs (TS Compiler API for TypeScript; regex + stateful scanning for Go; no external toolchain required), building a two-pass dependency graph with O(1) adjacency lookups, computing Merkle-tree SHA-256 hashes at function → file → module → root level, and compiling everything into a `mikk.lock.json` snapshot that every other package reads from.
+
+Every AI context query, impact analysis, contract validation, and diagram generation ultimately runs on the graph and lock file produced here.
+
+> Part of [Mikk](../../README.md) — the codebase nervous system for AI-assisted development.
 
 ---
 
@@ -22,11 +26,11 @@ bun add @getmikk/core
 ## Architecture Overview
 
 ```
-Source Files (.ts/.tsx)
+Source Files (.ts/.tsx/.go)
         │
         ▼
    ┌─────────┐
-   │  Parser  │  ← TypeScriptParser + TypeScriptExtractor
+   │  Parser  │  ← TypeScriptParser / GoParser
    └────┬────┘
         │  ParsedFile[]
         ▼
@@ -96,6 +100,39 @@ const resolver = new TypeScriptResolver()
 const resolved = resolver.resolve(importDecl, fromFilePath, allProjectFiles)
 ```
 
+#### Go Parser
+
+Parses `.go` files without requiring the Go toolchain:
+
+```typescript
+import { GoParser } from '@getmikk/core'
+
+const parser = new GoParser()
+const parsed = parser.parse('service.go', fileContent)
+
+console.log(parsed.functions)  // ParsedFunction[] — name, params with types, return type, calls[]
+console.log(parsed.classes)    // ParsedClass[] — receiver-based methods grouped by type name
+console.log(parsed.imports)    // ParsedImport[] — resolved against go.mod module path
+console.log(parsed.exports)    // ParsedExport[] — uppercase identifiers (Go convention)
+console.log(parsed.routes)     // ParsedRoute[] — Gin, Echo, Chi, Mux, net/http routes
+```
+
+**Features**:
+- Stateful line/character scanning (handles strings, comments, nested braces correctly)
+- Receiver methods grouped with struct types as classes
+- HTTP route detection (Gin/Echo/Chi/Mux/net.http/Fiber patterns)
+- Error handling detection (`if err != nil` patterns)
+- Function call extraction from bodies
+- Grouped parameter expansion (`first, last string` → both typed as `string`)
+- Import resolution via `go.mod` module path
+
+#### Auto-detection by file extension
+
+```typescript
+const parser = getParser('file.ts')    // → TypeScriptParser
+const parser = getParser('service.go') // → GoParser
+```
+
 ---
 
 ### 2. Graph — Dependency Graph Construction
@@ -135,7 +172,8 @@ const impact = analyzer.analyze(['src/utils/math.ts::calculateTotal'])
 console.log(impact.changed)    // string[] — directly changed node IDs
 console.log(impact.impacted)   // string[] — transitively affected nodes
 console.log(impact.depth)      // number — max propagation depth
-console.log(impact.confidence) // number — 0-1 confidence score
+console.log(impact.confidence) // 'high' | 'medium' | 'low'
+console.log(impact.classified) // { critical: [], high: [], medium: [], low: [] }
 ```
 
 #### ClusterDetector
@@ -414,7 +452,7 @@ import type {
   // Parser
   ParsedFile, ParsedFunction, ParsedClass, ParsedImport, ParsedExport, ParsedParam, ParsedGeneric,
   // Graph
-  DependencyGraph, GraphNode, GraphEdge, ImpactResult, NodeType, EdgeType, ModuleCluster,
+  DependencyGraph, GraphNode, GraphEdge, ImpactResult, NodeType, EdgeType, ModuleCluster, ClassifiedImpact, RiskLevel,
   // Contract
   MikkContract, MikkLock, MikkModule, MikkDecision, MikkLockFunction, MikkLockModule, MikkLockFile,
   // Boundary

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/core",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -27,7 +27,8 @@
         "zod": "^3.22.0"
     },
     "devDependencies": {
-        "typescript": "^5.7.0",
-        "@types/node": "^22.0.0"
+        "@types/bun": "^1.3.10",
+        "@types/node": "^22.0.0",
+        "typescript": "^5.7.0"
     }
 }

package/src/contract/adr-manager.ts

@@ -0,0 +1,75 @@
+import * as fs from 'node:fs/promises'
+import type { MikkContract, MikkDecision } from './schema.js'
+import { MikkContractSchema } from './schema.js'
+
+/**
+ * AdrManager — CRUD operations on Architectural Decision Records
+ * stored in the `declared.decisions` array of mikk.json.
+ *
+ * Each ADR has: id, title, reason, date.
+ * Exposed as an MCP tool so AI assistants can read and update ADRs.
+ */
+export class AdrManager {
+    constructor(private contractPath: string) { }
+
+    // ─── Read ──────────────────────────────────────────────────────
+
+    async list(): Promise<MikkDecision[]> {
+        const contract = await this.readContract()
+        return contract.declared.decisions ?? []
+    }
+
+    async get(id: string): Promise<MikkDecision | null> {
+        const decisions = await this.list()
+        return decisions.find(d => d.id === id) ?? null
+    }
+
+    // ─── Write ─────────────────────────────────────────────────────
+
+    async add(decision: MikkDecision): Promise<void> {
+        const contract = await this.readContract()
+        if (!contract.declared.decisions) {
+            contract.declared.decisions = []
+        }
+        // Check for duplicate ID
+        if (contract.declared.decisions.some(d => d.id === decision.id)) {
+            throw new Error(`ADR with id "${decision.id}" already exists. Use update() instead.`)
+        }
+        contract.declared.decisions.push(decision)
+        await this.writeContract(contract)
+    }
+
+    async update(id: string, fields: Partial<Omit<MikkDecision, 'id'>>): Promise<void> {
+        const contract = await this.readContract()
+        const decisions = contract.declared.decisions ?? []
+        const idx = decisions.findIndex(d => d.id === id)
+        if (idx === -1) {
+            throw new Error(`ADR "${id}" not found. Use add() to create a new decision.`)
+        }
+        decisions[idx] = { ...decisions[idx], ...fields, id } // preserve id
+        contract.declared.decisions = decisions
+        await this.writeContract(contract)
+    }
+
+    async remove(id: string): Promise<boolean> {
+        const contract = await this.readContract()
+        const decisions = contract.declared.decisions ?? []
+        const idx = decisions.findIndex(d => d.id === id)
+        if (idx === -1) return false
+        decisions.splice(idx, 1)
+        contract.declared.decisions = decisions
+        await this.writeContract(contract)
+        return true
+    }
+
+    // ─── Helpers ───────────────────────────────────────────────────
+
+    private async readContract(): Promise<MikkContract> {
+        const raw = await fs.readFile(this.contractPath, 'utf-8')
+        return MikkContractSchema.parse(JSON.parse(raw))
+    }
+
+    private async writeContract(contract: MikkContract): Promise<void> {
+        await fs.writeFile(this.contractPath, JSON.stringify(contract, null, 2), 'utf-8')
+    }
+}

package/src/contract/index.ts

@@ -10,3 +10,5 @@ export { ContractWriter, type UpdateResult } from './contract-writer.js'
 export { ContractReader } from './contract-reader.js'
 export { LockReader } from './lock-reader.js'
 export { ContractGenerator } from './contract-generator.js'
+export { AdrManager } from './adr-manager.js'
+

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

@@ -0,0 +1,194 @@
+import type { DependencyGraph } from './types.js'
+import type { MikkLock } from '../contract/schema.js'
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export interface DeadCodeEntry {
+    id: string
+    name: string
+    file: string
+    moduleId?: string
+    type: 'function' | 'class'
+    reason: string
+}
+
+export interface DeadCodeResult {
+    deadFunctions: DeadCodeEntry[]
+    totalFunctions: number
+    deadCount: number
+    deadPercentage: number
+    byModule: Record<string, { dead: number; total: number; items: DeadCodeEntry[] }>
+}
+
+// ─── Exemption patterns ────────────────────────────────────────────
+
+/** Common entry-point function names that are never "dead" even with 0 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
+    /Middleware$/i,
+    /Controller$/i,
+    /^use[A-Z]/,          // React hooks
+    /^handle[A-Z]/,       // Event handlers
+    /^on[A-Z]/,           // Event listeners
+]
+
+/** Common test function patterns */
+const TEST_PATTERNS = [
+    /^(it|describe|test|beforeAll|afterAll|beforeEach|afterEach)$/,
+    /\.test\./,
+    /\.spec\./,
+    /__test__/,
+]
+
+// ─── Detector ──────────────────────────────────────────────────────
+
+/**
+ * DeadCodeDetector — walks the dependency graph and finds functions
+ * with zero incoming `calls` edges after applying multi-pass exemptions.
+ *
+ * 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)
+ */
+export class DeadCodeDetector {
+    private routeHandlers: 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),
+        )
+    }
+
+    detect(): DeadCodeResult {
+        const dead: DeadCodeEntry[] = []
+        let totalFunctions = 0
+        const byModule: DeadCodeResult['byModule'] = {}
+
+        for (const [id, fn] of Object.entries(this.lock.functions)) {
+            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
+            const inEdges = this.graph.inEdges.get(id) || []
+            const hasCallers = inEdges.some(e => e.type === 'calls')
+
+            if (hasCallers) continue // Not dead
+
+            // Apply exemptions
+            if (this.isExempt(fn, id)) continue
+
+            const entry: DeadCodeEntry = {
+                id,
+                name: fn.name,
+                file: fn.file,
+                moduleId,
+                type: 'function',
+                reason: this.inferReason(fn, id),
+            }
+            dead.push(entry)
+            byModule[moduleId].dead++
+            byModule[moduleId].items.push(entry)
+        }
+
+        // Also check classes (if present in lock)
+        if (this.lock.classes) {
+            for (const [id, cls] of Object.entries(this.lock.classes)) {
+                const moduleId = cls.moduleId ?? 'unknown'
+                if (!byModule[moduleId]) {
+                    byModule[moduleId] = { dead: 0, total: 0, items: [] }
+                }
+
+                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
+
+                const entry: DeadCodeEntry = {
+                    id,
+                    name: cls.name,
+                    file: cls.file,
+                    moduleId,
+                    type: 'class',
+                    reason: 'Class has no callers or importers and is not exported',
+                }
+                dead.push(entry)
+                byModule[moduleId].dead++
+                byModule[moduleId].items.push(entry)
+            }
+        }
+
+        return {
+            deadFunctions: dead,
+            totalFunctions,
+            deadCount: dead.length,
+            deadPercentage: totalFunctions > 0
+                ? Math.round((dead.length / totalFunctions) * 1000) / 10
+                : 0,
+            byModule,
+        }
+    }
+
+    // ─── Exemption checks ──────────────────────────────────────────
+
+    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
+
+        return false
+    }
+
+    private isCalledByExportedInSameFile(
+        fn: MikkLock['functions'][string],
+        fnId: string,
+    ): boolean {
+        // Check calledBy — if any caller is exported and in the same file, exempt
+        for (const callerId of fn.calledBy) {
+            const caller = this.lock.functions[callerId]
+            if (caller && caller.isExported && caller.file === fn.file) {
+                return true
+            }
+        }
+        return false
+    }
+
+    private inferReason(fn: MikkLock['functions'][string], id: 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`
+    }
+}

package/src/graph/graph-builder.ts

@@ -121,6 +121,7 @@ export class GraphBuilder {
                     source: file.path,
                     target: imp.resolvedPath,
                     type: 'imports',
+                    confidence: 1.0, // Import edges are always deterministic from AST
                 })
             }
         }
@@ -145,24 +146,27 @@ export class GraphBuilder {
                 // Try to resolve: first check imported names, then local functions
                 const simpleName = call.includes('.') ? call.split('.').pop()! : call
 
-                // Check if it's an imported function
+                // Check if it's an imported function (confidence 0.8 — resolved via import names)
                 const importedId = importedNames.get(simpleName) || importedNames.get(call)
                 if (importedId && graph.nodes.has(importedId)) {
                     graph.edges.push({
                         source: fn.id,
                         target: importedId,
                         type: 'calls',
+                        confidence: 0.8, // Resolved through import names, not direct AST binding
                     })
                     continue
                 }
 
-                // Check if it's a local function in the same file
+                // Check if it's a local function in the same file (confidence 1.0 for exact, 0.5 for fuzzy)
                 const localId = `fn:${file.path}:${simpleName}`
                 if (graph.nodes.has(localId) && localId !== fn.id) {
+                    // Direct local match — high confidence
                     graph.edges.push({
                         source: fn.id,
                         target: localId,
                         type: 'calls',
+                        confidence: simpleName === call ? 1.0 : 0.5, // exact name = 1.0, dot-access strip = 0.5
                     })
                 }
             }

package/src/graph/impact-analyzer.ts

@@ -1,9 +1,15 @@
-import type { DependencyGraph, ImpactResult } from './types.js'
+import type { DependencyGraph, ImpactResult, ClassifiedImpact, RiskLevel } from './types.js'
 
 /**
  * ImpactAnalyzer — Given changed nodes, walks the graph backwards (BFS)
  * to find everything that depends on them.
  * Powers "what breaks if I change X?"
+ *
+ * Now includes 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+
  */
 export class ImpactAnalyzer {
     constructor(private graph: DependencyGraph) { }
@@ -11,13 +17,24 @@ export class ImpactAnalyzer {
     /** 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>()
         const queue: { id: string; depth: number }[] = changedNodeIds.map(id => ({ id, depth: 0 }))
         let maxDepth = 0
 
+        const changedSet = new Set(changedNodeIds)
+
+        // Collect module IDs of the changed nodes
+        const changedModules = new Set<string | undefined>()
+        for (const id of changedNodeIds) {
+            const node = this.graph.nodes.get(id)
+            if (node) changedModules.add(node.moduleId)
+        }
+
         while (queue.length > 0) {
             const { id: current, depth } = queue.shift()!
             if (visited.has(current)) continue
             visited.add(current)
+            depthMap.set(current, depth)
             maxDepth = Math.max(maxDepth, depth)
 
             // Find everything that depends on current (incoming edges)
@@ -29,13 +46,47 @@ export class ImpactAnalyzer {
             }
         }
 
-        const impacted = [...visited].filter(id => !changedNodeIds.includes(id))
+        const impacted = [...visited].filter(id => !changedSet.has(id))
+
+        // Classify each impacted node by risk level
+        const classified: ImpactResult['classified'] = {
+            critical: [],
+            high: [],
+            medium: [],
+            low: [],
+        }
+
+        for (const id of impacted) {
+            const node = this.graph.nodes.get(id)
+            if (!node) continue
+
+            const depth = depthMap.get(id) ?? 999
+            const crossesBoundary = !changedModules.has(node.moduleId)
+
+            const risk: RiskLevel =
+                depth === 1 && crossesBoundary ? 'critical' :
+                    depth === 1 ? 'high' :
+                        depth === 2 ? 'medium' :
+                            'low'
+
+            const entry: ClassifiedImpact = {
+                nodeId: id,
+                label: node.label,
+                file: node.file,
+                moduleId: node.moduleId,
+                risk,
+                depth,
+            }
+
+            classified[risk].push(entry)
+        }
 
         return {
             changed: changedNodeIds,
             impacted,
             depth: maxDepth,
             confidence: this.computeConfidence(impacted.length, maxDepth),
+            classified,
         }
     }
 

package/src/graph/index.ts

@@ -1,4 +1,7 @@
-export type { DependencyGraph, GraphNode, GraphEdge, ImpactResult, NodeType, EdgeType, ModuleCluster } from './types.js'
+export type { DependencyGraph, GraphNode, GraphEdge, ImpactResult, NodeType, EdgeType, ModuleCluster, RiskLevel, ClassifiedImpact } from './types.js'
 export { GraphBuilder } from './graph-builder.js'
 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'
+

package/src/graph/types.ts

@@ -33,6 +33,7 @@ export interface GraphEdge {
     target: string          // "fn:src/utils/jwt.ts:jwtDecode"
     type: EdgeType
     weight?: number         // How often this call happens (for coupling metrics)
+    confidence?: number     // 0.0–1.0: 1.0 = direct AST call, 0.8 = via interface, 0.5 = fuzzy/inferred
 }
 
 /** The full dependency graph */
@@ -43,12 +44,32 @@ export interface DependencyGraph {
     inEdges: Map<string, GraphEdge[]>    // node → [edges coming in]
 }
 
+/** Risk level for an impacted node */
+export type RiskLevel = 'critical' | 'high' | 'medium' | 'low'
+
+/** A single node in the classified impact result */
+export interface ClassifiedImpact {
+    nodeId: string
+    label: string
+    file: string
+    moduleId?: string
+    risk: RiskLevel
+    depth: number           // hops from change
+}
+
 /** Result of impact analysis */
 export interface ImpactResult {
     changed: string[]        // The directly changed nodes
     impacted: string[]       // Everything that depends on changed nodes
     depth: number            // How many hops from change to furthest impact
     confidence: 'high' | 'medium' | 'low'
+    /** Risk-classified breakdown of impacted nodes */
+    classified: {
+        critical: ClassifiedImpact[]
+        high: ClassifiedImpact[]
+        medium: ClassifiedImpact[]
+        low: ClassifiedImpact[]
+    }
 }
 
 /** A cluster of files that naturally belong together */