@getmikk/core 2.0.13 → 2.0.14

package/src/cache/incremental-cache.ts

@@ -0,0 +1,272 @@
+import * as fs from 'node:fs'
+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
+}
+
+interface CacheMetadata {
+  version: number
+  entries: Map<string, CacheEntry>
+  lastPruned: number
+}
+
+const CACHE_VERSION = 1
+const MAX_CACHE_SIZE = 5000 // Max entries before LRU eviction
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+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()
+
+   constructor(projectRoot: string) {
+     this.cacheDir = path.join(projectRoot, '.mikk', 'cache')
+     this.metadata = {
+       version: CACHE_VERSION,
+       entries: new Map(),
+       lastPruned: Date.now(),
+     }
+     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 getCacheFilePath(hash: string): string {
+    return path.join(this.cacheDir, `${hash}.json`)
+  }
+
+  private loadMetadata(): 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 ?? {}))
+      }
+    } catch {
+      // Corrupted metadata — start fresh
+      this.metadata.entries = new Map()
+    }
+  }
+
+  private saveMetadata(): void {
+    try {
+      fs.mkdirSync(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')
+    } 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
+      }
+
+      // Check TTL
+      const parsedAt = new Date(entry.parsedAt).getTime()
+      if (Date.now() - parsedAt > CACHE_TTL_MS) {
+        this.metadata.entries.delete(filePath)
+        this.misses++
+        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
+        }
+      } catch (err) {
+        // Corrupted cache entry
+        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 () => {
+      // Evict if cache is full
+      if (this.metadata.entries.size >= MAX_CACHE_SIZE) {
+        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 })
+        const cacheFile = this.getCacheFilePath(contentHash)
+        fs.writeFileSync(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 {
+          if (fs.existsSync(cacheFile)) {
+            fs.unlinkSync(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 {
+          if (fs.existsSync(cacheFile)) {
+            fs.unlinkSync(cacheFile)
+          }
+        } catch { /* ignore */ }
+      }
+      this.metadata.entries.clear()
+      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 () => {
+      this.saveMetadata()
+    })
+  }
+
+  /**
+   * Evict least recently used entries when cache is full.
+   */
+  private evictLRU(): void {
+    // Sort by parsedAt (oldest first) and remove oldest 20%
+    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 {
+        if (fs.existsSync(cacheFile)) {
+          fs.unlinkSync(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()
+      for (const [filePath, entry] of this.metadata.entries) {
+        const parsedAt = new Date(entry.parsedAt).getTime()
+        if (now - parsedAt > CACHE_TTL_MS) {
+          this.invalidate(filePath)
+        }
+      }
+      this.metadata.lastPruned = now
+      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/lock-compiler.ts

@@ -195,6 +195,9 @@ 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 ?? {}
@@ -238,6 +241,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 +272,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 ?? {}
@@ -329,6 +336,7 @@ export class LockCompiler {
                 files: moduleFiles,
                 hash: computeModuleHash(fileHashes),
                 fragmentPath: `.mikk/fragments/${module.id}.lock`,
+                ...(module.parentId ? { parentId: module.parentId } : {}),
             }
         }
 
@@ -344,6 +352,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 +411,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 +433,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({
@@ -99,6 +100,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/index.ts

@@ -6,6 +6,8 @@ export * from './graph/index.js'
 export * from './contract/index.js'
 export * from './hash/index.js'
 export * from './search/index.js'
+export * from './cache/index.js'
+export * from './security/index.js'
 export * from './utils/errors.js'
 export * from './utils/logger.js'
 export { MikkError, ErrorHandler, ErrorBuilder, ErrorCategory, FileSystemError, ModuleLoadError, GraphError, TokenBudgetError, ValidationError, createDefaultErrorListener, createFileNotFoundError, createFileTooLargeError, createPermissionDeniedError, createModuleNotFoundError, createModuleLoadFailedError, createGraphBuildFailedError, createNodeNotFoundError, createTokenBudgetExceededError, createValidationError, isMikkError, getRootCause, toMikkError } from './error-handler.js'