@getmikk/core 2.0.14 → 2.0.15

package/README.md

@@ -75,10 +75,10 @@ One root hash comparison = instant full drift detection. Persisted in SQLite wit
 
 Compiles a `DependencyGraph` + `MikkContract` + parsed files into a `MikkLock`. The lock file is the single source of truth for all MCP tools and CLI commands.
 
-Lock format v1.7.0:
-- Integer-based function index (`fnIndex`) — call graph edges stored as integer references, not repeated strings
-- Compact JSON output — no pretty-printing
-- Backward-compatible hydration for older formats
+Lock format:
+- Integer-based function index (`fnIndex`) — call graph edges stored as integer references
+- Compact JSON output
+- Backward-compatible hydration
 
 ### ContractReader / ContractWriter / LockReader
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmikk/core",
-  "version": "2.0.14",
+  "version": "2.0.15",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -33,6 +33,7 @@
     "eslint": "^9.39.2"
   },
   "dependencies": {
+    "@google/generative-ai": "^0.21.0",
     "better-sqlite3": "^12.6.2",
     "fast-glob": "^3.3.0",
     "tree-sitter-wasms": "^0.1.13",

package/src/analysis/type-flow.ts

@@ -4,7 +4,7 @@
  */
 
 import type { MikkLock, MikkLockFunction } from '../contract/schema.js'
-import type { DependencyGraph, GraphEdge } from '../graph/types.js'
+import type { DependencyGraph } from '../graph/types.js'
 
 // ---------------------------------------------------------------------------
 // Types

package/src/cache/incremental-cache.ts

@@ -1,15 +1,10 @@
-import * as fs from 'node:fs'
+import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 import type { ParsedFile } from '../parser/types.js'
 
-// ---------------------------------------------------------------------------
-// Incremental Analysis Cache — avoids re-parsing unchanged files
-// ---------------------------------------------------------------------------
-
 interface CacheEntry {
   hash: string
   parsedAt: string
-  // Store lightweight metadata instead of full ParsedFile to prevent metadata bloat
   size: number
   lastAccessed: number
 }
@@ -21,75 +16,91 @@ interface CacheMetadata {
 }
 
 const CACHE_VERSION = 1
-const MAX_CACHE_SIZE = 5000 // Max entries before LRU eviction
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+const MAX_CACHE_SIZE = 5000
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
 
 export class IncrementalCache {
   private cacheDir: string
   private metadata: CacheMetadata
   private hits = 0
   private misses = 0
-  // Mutex to prevent race conditions during concurrent access
-  private mutex = Promise.resolve()
+  private queue: Array<() => void> = []
+  private running = false
+  private initialized = false
+  private pendingInit: Promise<void> | null = null
 
-   constructor(projectRoot: string) {
-     this.cacheDir = path.join(projectRoot, '.mikk', 'cache')
-     this.metadata = {
-       version: CACHE_VERSION,
-       entries: new Map(),
-       lastPruned: Date.now(),
-     }
-     this.loadMetadata()
-   }
+  constructor(projectRoot: string) {
+    this.cacheDir = path.join(projectRoot, '.mikk', 'cache')
+    this.metadata = {
+      version: CACHE_VERSION,
+      entries: new Map(),
+      lastPruned: Date.now(),
+    }
+    this.pendingInit = this.loadMetadata()
+  }
 
-   /**
-    * Simple mutex-like protection using a flag for basic race condition prevention
-    * Note: For production, a proper mutex library would be better
-    */
-   private isLocked = false
-   private async withMutex<T>(fn: () => Promise<T>): Promise<T> {
-     while (this.isLocked) {
-       await new Promise(resolve => setTimeout(resolve, 1))
-     }
-     this.isLocked = true
-     try {
-       return await fn()
-     } finally {
-       this.isLocked = false
-     }
-   }
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized) return
+    if (this.pendingInit) {
+      await this.pendingInit
+    }
+  }
+
+  private async withMutex<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.queue.push(async () => {
+        try {
+          await this.ensureInitialized()
+          const result = await fn()
+          resolve(result)
+        } catch (err) {
+          reject(err)
+        }
+      })
+      if (!this.running) {
+        this.processQueue()
+      }
+    })
+  }
+
+  private async processQueue(): Promise<void> {
+    this.running = true
+    while (this.queue.length > 0) {
+      const fn = this.queue.shift()!
+      await fn()
+    }
+    this.running = false
+  }
 
   private getCacheFilePath(hash: string): string {
     return path.join(this.cacheDir, `${hash}.json`)
   }
 
-  private loadMetadata(): void {
+  private async loadMetadata(): Promise<void> {
     const metaPath = path.join(this.cacheDir, 'metadata.json')
     try {
-      if (fs.existsSync(metaPath)) {
-        const raw = fs.readFileSync(metaPath, 'utf-8')
-        const data = JSON.parse(raw)
-        this.metadata.version = data.version ?? CACHE_VERSION
-        this.metadata.lastPruned = data.lastPruned ?? Date.now()
-        // Rebuild entries map
-        this.metadata.entries = new Map(Object.entries(data.entries ?? {}))
-      }
+      const raw = await fs.readFile(metaPath, 'utf-8')
+      const data = JSON.parse(raw)
+      this.metadata.version = data.version ?? CACHE_VERSION
+      this.metadata.lastPruned = data.lastPruned ?? Date.now()
+      this.metadata.entries = new Map(Object.entries(data.entries ?? {}))
+      this.initialized = true
     } catch {
-      // Corrupted metadata — start fresh
       this.metadata.entries = new Map()
+      this.initialized = true
     }
   }
 
-  private saveMetadata(): void {
+  private async saveMetadata(): Promise<void> {
     try {
-      fs.mkdirSync(this.cacheDir, { recursive: true })
+      await fs.mkdir(this.cacheDir, { recursive: true })
       const metaPath = path.join(this.cacheDir, 'metadata.json')
       const serializable = {
         version: this.metadata.version,
         lastPruned: this.metadata.lastPruned,
         entries: Object.fromEntries(this.metadata.entries),
       }
-      fs.writeFileSync(metaPath, JSON.stringify(serializable), 'utf-8')
+      await fs.writeFile(metaPath, JSON.stringify(serializable), 'utf-8')
     } catch {
       // Silently fail — cache is non-critical
     }
@@ -112,7 +123,6 @@ export class IncrementalCache {
         return null
       }
 
-      // Check TTL
       const parsedAt = new Date(entry.parsedAt).getTime()
       if (Date.now() - parsedAt > CACHE_TTL_MS) {
         this.metadata.entries.delete(filePath)
@@ -120,19 +130,14 @@ export class IncrementalCache {
         return null
       }
 
-      // Load from disk and reconstruct ParsedFile
       const cacheFile = this.getCacheFilePath(contentHash)
       try {
-        if (fs.existsSync(cacheFile)) {
-          const raw = fs.readFileSync(cacheFile, 'utf-8')
-          const parsed = JSON.parse(raw) as ParsedFile
-          this.hits++
-          // Update last accessed time
-          entry.lastAccessed = Date.now()
-          return parsed
-        }
+        const raw = await fs.readFile(cacheFile, 'utf-8')
+        const parsed = JSON.parse(raw) as ParsedFile
+        this.hits++
+        entry.lastAccessed = Date.now()
+        return parsed
       } catch (err) {
-        // Corrupted cache entry
         console.warn(`Corrupted cache entry for ${filePath}:`, err)
         this.metadata.entries.delete(filePath)
       }
@@ -147,26 +152,23 @@ export class IncrementalCache {
    */
   async set(filePath: string, contentHash: string, parsed: ParsedFile): Promise<void> {
     return this.withMutex(async () => {
-      // Evict if cache is full
       if (this.metadata.entries.size >= MAX_CACHE_SIZE) {
-        this.evictLRU()
+        await this.evictLRU()
       }
 
       const entry: CacheEntry = {
         hash: contentHash,
         parsedAt: new Date().toISOString(),
-        // Store file size for lightweight tracking instead of full ParsedFile
         size: JSON.stringify(parsed).length,
         lastAccessed: Date.now()
       }
 
       this.metadata.entries.set(filePath, entry)
 
-      // Write to disk
       try {
-        fs.mkdirSync(this.cacheDir, { recursive: true })
+        await fs.mkdir(this.cacheDir, { recursive: true })
         const cacheFile = this.getCacheFilePath(contentHash)
-        fs.writeFileSync(cacheFile, JSON.stringify(parsed), 'utf-8')
+        await fs.writeFile(cacheFile, JSON.stringify(parsed), 'utf-8')
       } catch {
         // Silently fail — cache is non-critical
       }
@@ -182,9 +184,7 @@ export class IncrementalCache {
       if (entry) {
         const cacheFile = this.getCacheFilePath(entry.hash)
         try {
-          if (fs.existsSync(cacheFile)) {
-            fs.unlinkSync(cacheFile)
-          }
+          await fs.unlink(cacheFile)
         } catch { /* ignore */ }
         this.metadata.entries.delete(filePath)
       }
@@ -199,13 +199,11 @@ export class IncrementalCache {
       for (const [, entry] of this.metadata.entries) {
         const cacheFile = this.getCacheFilePath(entry.hash)
         try {
-          if (fs.existsSync(cacheFile)) {
-            fs.unlinkSync(cacheFile)
-          }
+          await fs.unlink(cacheFile)
         } catch { /* ignore */ }
       }
       this.metadata.entries.clear()
-      this.saveMetadata()
+      await this.saveMetadata()
     })
   }
 
@@ -228,15 +226,14 @@ export class IncrementalCache {
    */
   async flush(): Promise<void> {
     return this.withMutex(async () => {
-      this.saveMetadata()
+      await this.saveMetadata()
     })
   }
 
   /**
    * Evict least recently used entries when cache is full.
    */
-  private evictLRU(): void {
-    // Sort by parsedAt (oldest first) and remove oldest 20%
+  private async evictLRU(): Promise<void> {
     const sorted = [...this.metadata.entries.entries()].sort(
       (a, b) => new Date(a[1].parsedAt).getTime() - new Date(b[1].parsedAt).getTime()
     )
@@ -245,9 +242,7 @@ export class IncrementalCache {
       const [filePath, entry] = sorted[i]
       const cacheFile = this.getCacheFilePath(entry.hash)
       try {
-        if (fs.existsSync(cacheFile)) {
-          fs.unlinkSync(cacheFile)
-        }
+        await fs.unlink(cacheFile)
       } catch { /* ignore */ }
       this.metadata.entries.delete(filePath)
     }
@@ -259,14 +254,25 @@ export class IncrementalCache {
   async prune(): Promise<void> {
     return this.withMutex(async () => {
       const now = Date.now()
+      const toDelete: string[] = []
       for (const [filePath, entry] of this.metadata.entries) {
         const parsedAt = new Date(entry.parsedAt).getTime()
         if (now - parsedAt > CACHE_TTL_MS) {
-          this.invalidate(filePath)
+          toDelete.push(filePath)
+        }
+      }
+      for (const filePath of toDelete) {
+        const entry = this.metadata.entries.get(filePath)
+        if (entry) {
+          const cacheFile = this.getCacheFilePath(entry.hash)
+          try {
+            await fs.unlink(cacheFile)
+          } catch { /* ignore */ }
+          this.metadata.entries.delete(filePath)
         }
       }
       this.metadata.lastPruned = now
-      this.saveMetadata()
+      await this.saveMetadata()
     })
   }
 }

package/src/contract/contract-reader.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { MikkContractSchema, type MikkContract } from './schema.js'
 import { ContractNotFoundError } from '../utils/errors.js'
 import { readJsonSafe } from '../utils/json.js'

package/src/contract/lock-compiler.ts

@@ -123,6 +123,7 @@ function capitalise(s: string): string {
  */
 export class LockCompiler {
     private projectRootPath: string | null = null
+    
     /** Main entry -- compile full lock from graph + contract + parsed files */
     compile(
         graph: DependencyGraph,
@@ -132,6 +133,7 @@ export class LockCompiler {
         projectRoot?: string
     ): MikkLock {
         this.projectRootPath = projectRoot ? nodePath.resolve(projectRoot) : null
+        
         const functions = this.compileFunctions(graph, contract)
         const classes = this.compileClasses(graph, contract)
         const generics = this.compileGenerics(graph, contract)
@@ -204,6 +206,11 @@ export class LockCompiler {
             const inEdges = graph.inEdges.get(id) || []
             const outEdges = graph.outEdges.get(id) || []
 
+            const params = metadata.params || []
+            const returnType = metadata.returnType || 'void'
+            const signatureHash = hashContent(`${displayName}(${params.map(p => p.type).join(',')}):${returnType}`)
+            const tokenVector = this.generateTokenVector(displayName, params, returnType, metadata.purpose)
+
             result[id] = {
                 id,
                 name: displayName,
@@ -214,26 +221,94 @@ export class LockCompiler {
                 calls: outEdges.filter(e => e.type === 'calls').map(e => e.to),
                 calledBy: inEdges.filter(e => e.type === 'calls').map(e => e.from),
                 moduleId: moduleId || 'unknown',
-                ...(metadata.params && metadata.params.length > 0
-                    ? { params: metadata.params }
-                    : {}),
+                ...(params.length > 0 ? { params } : {}),
                 ...(metadata.returnType ? { returnType: metadata.returnType } : {}),
                 ...(metadata.isAsync ? { isAsync: true } : {}),
                 ...(metadata.isExported ? { isExported: true } : {}),
                 purpose: metadata.purpose || inferPurpose(
                     displayName,
-                    metadata.params,
-                    metadata.returnType,
+                    params,
+                    returnType,
                     metadata.isAsync,
                 ),
                 edgeCasesHandled: metadata.edgeCasesHandled,
                 errorHandling: metadata.errorHandling,
+                signatureHash,
+                tokenVector,
             }
         }
 
         return result
     }
 
+    private generateTokenVector(
+        name: string,
+        params: Array<{ name: string; type: string; optional?: boolean }>,
+        returnType: string,
+        purpose?: string
+    ): number[] {
+        const tokens: string[] = []
+
+        tokens.push(...name.match(/[A-Z][a-z]+|[a-z]+/g)?.map(t => t.toLowerCase()) || [])
+
+        for (const param of params) {
+            tokens.push(...param.name.match(/[A-Z][a-z]+|[a-z]+/g)?.map(t => t.toLowerCase()) || [])
+        }
+
+        tokens.push(...returnType.match(/[A-Z][a-z]+|[a-z]+/g)?.map(t => t.toLowerCase()) || [])
+
+        if (purpose) {
+            tokens.push(...purpose.match(/[a-z]{3,}/g)?.map(t => t.toLowerCase()) || [])
+        }
+
+        const vocabulary = this.buildVocabulary()
+        const vector = new Array(64).fill(0)
+
+        for (const token of tokens) {
+            if (vocabulary.has(token)) {
+                const idx = vocabulary.get(token)!
+                const hash = this.simpleHash(token)
+                vector[idx % 64] += hash
+            }
+        }
+
+        const magnitude = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0))
+        if (magnitude > 0) {
+            for (let i = 0; i < vector.length; i++) {
+                vector[i] /= magnitude
+            }
+        }
+
+        return vector
+    }
+
+    private buildVocabulary(): Map<string, number> {
+        const common = [
+            'get', 'set', 'add', 'remove', 'create', 'delete', 'update', 'find',
+            'load', 'save', 'parse', 'format', 'validate', 'check', 'handle',
+            'process', 'render', 'display', 'build', 'make', 'init', 'setup',
+            'config', 'user', 'auth', 'login', 'logout', 'token', 'data', 'file',
+            'path', 'config', 'options', 'params', 'args', 'error', 'result',
+            'async', 'promise', 'callback', 'event', 'handler', 'middleware',
+            'database', 'query', 'insert', 'update', 'delete', 'select', 'transaction',
+            'string', 'number', 'boolean', 'array', 'object', 'function', 'class',
+            'interface', 'type', 'enum', 'const', 'var', 'let', 'return', 'void',
+        ]
+
+        const vocab = new Map<string, number>()
+        common.forEach((word, idx) => vocab.set(word, idx))
+        return vocab
+    }
+
+    private simpleHash(str: string): number {
+        let hash = 0
+        for (let i = 0; i < str.length; i++) {
+            hash = ((hash << 5) - hash) + str.charCodeAt(i)
+            hash = hash & hash
+        }
+        return Math.abs(hash % 10)
+    }
+
     private compileClasses(
         graph: DependencyGraph,
         contract: MikkContract
@@ -321,15 +396,22 @@ export class LockCompiler {
     ): Record<string, MikkLock['modules'][string]> {
         const result: Record<string, MikkLock['modules'][string]> = {}
 
+        // Build a map for fast file lookups - O(1) instead of O(n) per module
+        const fileHashMap = new Map<string, string>()
+        for (const file of parsedFiles) {
+            fileHashMap.set(file.path, file.hash)
+        }
+
         for (const module of contract.declared.modules) {
-            const moduleFiles = parsedFiles
-                .filter(f => this.fileMatchesModule(f.path, module.paths))
-                .map(f => f.path)
-
-            const fileHashes = moduleFiles.map(f => {
-                const parsed = parsedFiles.find(pf => pf.path === f)
-                return parsed?.hash ?? ''
-            })
+            const moduleFiles: string[] = []
+
+            for (const file of parsedFiles) {
+                if (this.fileMatchesModule(file.path, module.paths)) {
+                    moduleFiles.push(file.path)
+                }
+            }
+
+            const fileHashes = moduleFiles.map(f => fileHashMap.get(f) ?? '')
 
             result[module.id] = {
                 id: module.id,

package/src/contract/schema.ts

@@ -93,6 +93,8 @@ export const MikkLockFunctionSchema = z.object({
     })).optional(),
     confidence: z.number().optional(),
     riskScore: z.number().optional(),
+    signatureHash: z.string().optional(),
+    tokenVector: z.array(z.number()).optional(),
 })
 
 export const MikkLockModuleSchema = z.object({

package/src/error-handler.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Standardized Error Handling System
  * 
@@ -269,7 +270,7 @@ export function createFileNotFoundError(filePath: string): FileSystemError {
 /**
  * Create a file too large error
  */
-export function createFileTooLargeError(filePath: string, size: number, limit: number): FileSystemError {
+export function createFileTooLargeError(filePath: string, _size: number, _limit: number): FileSystemError {
     return new FileSystemError('FILE_TOO_LARGE', filePath)
 }
 

package/src/graph/cluster-detector.ts

@@ -1,5 +1,4 @@
-import * as path from 'node:path'
-import type { DependencyGraph, ModuleCluster, GraphNode } from './types.js'
+import type { DependencyGraph, ModuleCluster } from './types.js'
 
 // ─── Domain keyword maps for semantic naming ────────────────────────
 // Each entry maps a human-readable domain label to keywords found in
@@ -227,7 +226,6 @@ export class ClusterDetector {
     private computeCouplingMatrix(files: string[]): Map<string, Map<string, number>> {
         const matrix = new Map<string, Map<string, number>>()
         const fileEdgeCounts = new Map<string, number>()
-        const pairCounts = new Map<string, number>()
 
         // Count total edges per file
         for (const fileId of files) {
@@ -450,7 +448,7 @@ export class ClusterDetector {
         }
 
         const result: ModuleCluster[] = []
-        for (const [baseDir, siblings] of byBaseDir) {
+        for (const siblings of byBaseDir.values()) {
             if (siblings.length <= 1) {
                 result.push(...siblings)
                 continue