@getmikk/core 2.0.13 → 2.0.15

package/src/cache/incremental-cache.ts

@@ -0,0 +1,278 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import type { ParsedFile } from '../parser/types.js'
+
+interface CacheEntry {
+  hash: string
+  parsedAt: string
+  size: number
+  lastAccessed: number
+}
+
+interface CacheMetadata {
+  version: number
+  entries: Map<string, CacheEntry>
+  lastPruned: number
+}
+
+const CACHE_VERSION = 1
+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
+  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.pendingInit = this.loadMetadata()
+  }
+
+  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 async loadMetadata(): Promise<void> {
+    const metaPath = path.join(this.cacheDir, 'metadata.json')
+    try {
+      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 {
+      this.metadata.entries = new Map()
+      this.initialized = true
+    }
+  }
+
+  private async saveMetadata(): Promise<void> {
+    try {
+      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),
+      }
+      await fs.writeFile(metaPath, JSON.stringify(serializable), 'utf-8')
+    } catch {
+      // Silently fail — cache is non-critical
+    }
+  }
+
+  /**
+   * Get cached parse result if content hash matches.
+   * Returns null if cache miss or stale.
+   */
+  async get(filePath: string, contentHash: string): Promise<ParsedFile | null> {
+    return this.withMutex(async () => {
+      const entry = this.metadata.entries.get(filePath)
+      if (!entry) {
+        this.misses++
+        return null
+      }
+
+      if (entry.hash !== contentHash) {
+        this.misses++
+        return null
+      }
+
+      const parsedAt = new Date(entry.parsedAt).getTime()
+      if (Date.now() - parsedAt > CACHE_TTL_MS) {
+        this.metadata.entries.delete(filePath)
+        this.misses++
+        return null
+      }
+
+      const cacheFile = this.getCacheFilePath(contentHash)
+      try {
+        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) {
+        console.warn(`Corrupted cache entry for ${filePath}:`, err)
+        this.metadata.entries.delete(filePath)
+      }
+
+      this.misses++
+      return null
+    })
+  }
+
+  /**
+   * Store parse result in cache.
+   */
+  async set(filePath: string, contentHash: string, parsed: ParsedFile): Promise<void> {
+    return this.withMutex(async () => {
+      if (this.metadata.entries.size >= MAX_CACHE_SIZE) {
+        await this.evictLRU()
+      }
+
+      const entry: CacheEntry = {
+        hash: contentHash,
+        parsedAt: new Date().toISOString(),
+        size: JSON.stringify(parsed).length,
+        lastAccessed: Date.now()
+      }
+
+      this.metadata.entries.set(filePath, entry)
+
+      try {
+        await fs.mkdir(this.cacheDir, { recursive: true })
+        const cacheFile = this.getCacheFilePath(contentHash)
+        await fs.writeFile(cacheFile, JSON.stringify(parsed), 'utf-8')
+      } catch {
+        // Silently fail — cache is non-critical
+      }
+    })
+  }
+
+  /**
+   * Invalidate cache for a specific file.
+   */
+  async invalidate(filePath: string): Promise<void> {
+    return this.withMutex(async () => {
+      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)
+      }
+    })
+  }
+
+  /**
+   * Clear entire cache.
+   */
+  async clear(): Promise<void> {
+    return this.withMutex(async () => {
+      for (const [, entry] of this.metadata.entries) {
+        const cacheFile = this.getCacheFilePath(entry.hash)
+        try {
+          await fs.unlink(cacheFile)
+        } catch { /* ignore */ }
+      }
+      this.metadata.entries.clear()
+      await this.saveMetadata()
+    })
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  getStats(): { hits: number; misses: number; hitRate: number; size: number } {
+    const total = this.hits + this.misses
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+      size: this.metadata.entries.size,
+    }
+  }
+
+  /**
+   * Persist cache metadata to disk.
+   * Call this after batch operations.
+   */
+  async flush(): Promise<void> {
+    return this.withMutex(async () => {
+      await this.saveMetadata()
+    })
+  }
+
+  /**
+   * Evict least recently used entries when cache is full.
+   */
+  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()
+    )
+    const toRemove = Math.ceil(sorted.length * 0.2)
+    for (let i = 0; i < toRemove; i++) {
+      const [filePath, entry] = sorted[i]
+      const cacheFile = this.getCacheFilePath(entry.hash)
+      try {
+        await fs.unlink(cacheFile)
+      } catch { /* ignore */ }
+      this.metadata.entries.delete(filePath)
+    }
+  }
+
+  /**
+   * Prune expired entries from cache.
+   */
+  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) {
+          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
+      await this.saveMetadata()
+    })
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1 @@
+export { IncrementalCache } from './incremental-cache.js'

package/src/contract/contract-generator.ts

@@ -1,6 +1,26 @@
 import type { MikkContract } from './schema.js'
 import type { ModuleCluster } from '../graph/types.js'
 import type { ParsedFile } from '../parser/types.js'
+import { minimatch } from '../utils/minimatch.js'
+
+/** Common vendor directories to exclude from contract generation */
+const VENDOR_PATTERNS = [
+    '**/node_modules/**',
+    '**/venv/**',
+    '**/.venv/**',
+    '**/__pycache__/**',
+    '**/vendor/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.next/**',
+    '**/target/**',
+]
+
+/** Check if a path is from a vendor directory */
+function isVendorPath(filePath: string): boolean {
+    const normalized = filePath.replace(/\\/g, '/')
+    return VENDOR_PATTERNS.some(pattern => minimatch(normalized, pattern))
+}
 
 /** Common entry point filenames across ecosystems (without extensions) */
 const ENTRY_BASENAMES = ['index', 'main', 'app', 'server', 'mod', 'lib', '__init__', 'manage', 'program', 'startup']
@@ -39,7 +59,13 @@ export class ContractGenerator {
         projectName: string,
         packageJsonDescription?: string
     ): MikkContract {
-        const modules = clusters.map(cluster => ({
+        // Filter out vendor files from clusters
+        const filteredClusters = clusters.map(cluster => ({
+            ...cluster,
+            files: cluster.files.filter(f => !isVendorPath(f)),
+        })).filter(cluster => cluster.files.length > 0)
+
+        const modules = filteredClusters.map(cluster => ({
             id: cluster.id,
             name: cluster.suggestedName,
             description: this.inferModuleDescription(cluster, parsedFiles),
@@ -50,14 +76,16 @@ export class ContractGenerator {
 
         // Detect entry points — language-agnostic basename matching
         const entryPoints = parsedFiles
+            .filter(f => !isVendorPath(f.path))
             .filter(f => {
                 const basename = (f.path.split('/').pop() || '').replace(/\.[^.]+$/, '')
                 return ENTRY_BASENAMES.includes(basename)
             })
             .map(f => f.path)
 
-        const detectedLanguage = inferLanguageFromFiles(parsedFiles)
-        const fallbackEntry = parsedFiles[0]?.path ?? 'src/index'
+        const filteredParsedFiles = parsedFiles.filter(f => !isVendorPath(f.path))
+        const detectedLanguage = inferLanguageFromFiles(filteredParsedFiles)
+        const fallbackEntry = filteredParsedFiles[0]?.path ?? 'src/index'
 
         return {
             version: '1.0.0',

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)
@@ -195,12 +197,20 @@ export class LockCompiler {
         for (const [id, node] of graph.nodes) {
             if (node.type !== 'function') continue
 
+            // Skip vendor files
+            if (this.isVendorPath(node.file)) continue
+
             const moduleId = this.findModule(node.file, contract.declared.modules)
             const displayName = node.name ?? ''
             const metadata = node.metadata ?? {}
             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,
@@ -211,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
@@ -238,6 +316,8 @@ export class LockCompiler {
         const result: Record<string, any> = {}
         for (const [id, node] of graph.nodes) {
             if (node.type !== 'class') continue
+            if (this.isVendorPath(node.file)) continue
+            
             const moduleId = this.findModule(node.file, contract.declared.modules)
             const className = node.name ?? ''
             const metadata = node.metadata ?? {}
@@ -267,6 +347,8 @@ export class LockCompiler {
             // Only include exported generics  non-exported types/interfaces are
             // internal implementation details that add noise without value.
             if (!(node.metadata?.isExported)) continue
+            if (this.isVendorPath(node.file)) continue
+            
             const moduleId = this.findModule(node.file, contract.declared.modules)
             const genericName = node.name ?? ''
             const metadata = node.metadata ?? {}
@@ -314,21 +396,29 @@ 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 moduleFiles: string[] = []
+
+            for (const file of parsedFiles) {
+                if (this.fileMatchesModule(file.path, module.paths)) {
+                    moduleFiles.push(file.path)
+                }
+            }
 
-            const fileHashes = moduleFiles.map(f => {
-                const parsed = parsedFiles.find(pf => pf.path === f)
-                return parsed?.hash ?? ''
-            })
+            const fileHashes = moduleFiles.map(f => fileHashMap.get(f) ?? '')
 
             result[module.id] = {
                 id: module.id,
                 files: moduleFiles,
                 hash: computeModuleHash(fileHashes),
                 fragmentPath: `.mikk/fragments/${module.id}.lock`,
+                ...(module.parentId ? { parentId: module.parentId } : {}),
             }
         }
 
@@ -344,6 +434,9 @@ export class LockCompiler {
         const result: Record<string, MikkLock['files'][string]> = {}
 
         for (const file of parsedFiles) {
+            // Skip vendor files entirely
+            if (this.isVendorPath(file.path)) continue
+
             const moduleId = this.findModule(file.path, contract.declared.modules)
 
             // Collect file-level imports from the parsed file info directly
@@ -400,6 +493,9 @@ export class LockCompiler {
 
     /** Check if a file path matches any of the module's path patterns */
     private fileMatchesModule(filePath: string, patterns: string[]): boolean {
+        // Skip vendor paths - never match them to any module
+        if (this.isVendorPath(filePath)) return false
+
         const relativePath = getModuleMatchPath(filePath, this.projectRootPath)
         const normalizedRelative = relativePath.replace(/\\/g, '/').toLowerCase()
         const normalizedAbsolute = filePath.replace(/\\/g, '/').toLowerCase()
@@ -419,4 +515,21 @@ export class LockCompiler {
         }
         return false
     }
+
+    /** Check if a path is from a vendor directory */
+    private isVendorPath(filePath: string): boolean {
+        const normalized = filePath.replace(/\\/g, '/')
+        const vendorPatterns = [
+            '**/node_modules/**',
+            '**/venv/**',
+            '**/.venv/**',
+            '**/__pycache__/**',
+            '**/vendor/**',
+            '**/dist/**',
+            '**/build/**',
+            '**/.next/**',
+            '**/target/**',
+        ]
+        return vendorPatterns.some(pattern => minimatch(normalized, pattern))
+    }
 }

package/src/contract/schema.ts

@@ -10,6 +10,7 @@ export const MikkModuleSchema = z.object({
     owners: z.array(z.string()).optional(),
     paths: z.array(z.string()),
     entryFunctions: z.array(z.string()).optional(),
+    parentId: z.string().optional(),
 })
 
 export const MikkDecisionSchema = z.object({
@@ -92,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({
@@ -99,6 +102,7 @@ export const MikkLockModuleSchema = z.object({
     files: z.array(z.string()),
     hash: z.string(),
     fragmentPath: z.string(),
+    parentId: z.string().optional(),
 })
 
 export const MikkLockImportSchema = 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