@getmikk/core 2.0.12 → 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/adr-manager.ts

@@ -1,6 +1,7 @@
-import * as fs from 'node:fs/promises'
 import type { MikkContract, MikkDecision } from './schema.js'
 import { MikkContractSchema } from './schema.js'
+import { readJsonSafe } from '../utils/json.js'
+import { writeFileAtomic } from '../utils/atomic-write.js'
 
 /**
  * AdrManager — CRUD operations on Architectural Decision Records
@@ -65,11 +66,11 @@ export class AdrManager {
     // ─── Helpers ───────────────────────────────────────────────────
 
     private async readContract(): Promise<MikkContract> {
-        const raw = await fs.readFile(this.contractPath, 'utf-8')
-        return MikkContractSchema.parse(JSON.parse(raw))
+        const json = await readJsonSafe(this.contractPath, 'mikk.json')
+        return MikkContractSchema.parse(json)
     }
 
     private async writeContract(contract: MikkContract): Promise<void> {
-        await fs.writeFile(this.contractPath, JSON.stringify(contract, null, 2), 'utf-8')
+        await writeFileAtomic(this.contractPath, JSON.stringify(contract, null, 2), { encoding: 'utf-8' })
     }
 }

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-writer.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 import type { MikkContract } from './schema.js'
+import { writeFileAtomic } from '../utils/atomic-write.js'
 
 const VERSION = '@getmikk/cli@1.2.1'
 
@@ -20,7 +21,7 @@ export class ContractWriter {
     async writeNew(contract: MikkContract, outputPath: string): Promise<void> {
         await fs.mkdir(path.dirname(outputPath), { recursive: true })
         const json = JSON.stringify(contract, null, 2)
-        await fs.writeFile(outputPath, json, 'utf-8')
+        await writeFileAtomic(outputPath, json, { encoding: 'utf-8' })
     }
 
     /** Update an existing mikk.json respecting overwrite mode */
@@ -108,6 +109,6 @@ export class ContractWriter {
         })
 
         await fs.mkdir(path.dirname(historyPath), { recursive: true })
-        await fs.writeFile(historyPath, JSON.stringify(history, null, 2), 'utf-8')
+        await writeFileAtomic(historyPath, JSON.stringify(history, null, 2), { encoding: 'utf-8' })
     }
 }

package/src/contract/lock-compiler.ts

@@ -6,6 +6,7 @@ import * as nodePath from 'node:path'
 import { hashContent } from '../hash/file-hasher.js'
 import { computeModuleHash, computeRootHash } from '../hash/tree-hasher.js'
 import { minimatch } from '../utils/minimatch.js'
+import { randomUUID } from 'node:crypto'
 
 const VERSION = '@getmikk/cli@1.2.1'
 
@@ -153,6 +154,8 @@ export class LockCompiler {
                 lastSyncAt: new Date().toISOString(),
                 lockHash: '',
                 contractHash: hashContent(JSON.stringify(contract)),
+                generationId: randomUUID(),
+                writeVersion: 0,
             },
             modules,
             functions,
@@ -192,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 ?? {}
@@ -235,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 ?? {}
@@ -264,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 ?? {}
@@ -326,6 +336,7 @@ export class LockCompiler {
                 files: moduleFiles,
                 hash: computeModuleHash(fileHashes),
                 fragmentPath: `.mikk/fragments/${module.id}.lock`,
+                ...(module.parentId ? { parentId: module.parentId } : {}),
             }
         }
 
@@ -341,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
@@ -397,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()
@@ -416,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/lock-reader.ts

@@ -1,7 +1,13 @@
-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'
+import { writeFileAtomic } from '../utils/atomic-write.js'
+import { randomUUID } from 'node:crypto'
+
+export interface LockWriteOptions {
+    expectedGenerationId?: string
+    expectedWriteVersion?: number
+}
 
 /**
  * LockReader -- reads and validates mikk.lock.json from disk.
@@ -32,11 +38,62 @@ export class LockReader {
         return result.data
     }
 
-    /** Write lock file to disk in compact format */
-    async write(lock: MikkLock, lockPath: string): Promise<void> {
+    serialize(lock: MikkLock): string {
         const compact = compactifyLock(lock)
-        const json = JSON.stringify(compact)
-        await fs.writeFile(lockPath, json, 'utf-8')
+        return JSON.stringify(compact)
+    }
+
+    async prepareForWrite(lock: MikkLock, lockPath: string, options: LockWriteOptions = {}): Promise<MikkLock> {
+        let existing: MikkLock | null = null
+        try {
+            existing = await this.read(lockPath)
+        } catch (err: any) {
+            if (!(err instanceof LockNotFoundError)) {
+                throw err
+            }
+        }
+
+        const prepared: MikkLock = {
+            ...lock,
+            syncState: {
+                ...lock.syncState,
+            },
+        }
+
+        if (existing) {
+            const existingGeneration = existing.syncState.generationId
+            const existingWriteVersion = existing.syncState.writeVersion ?? 0
+
+            if (
+                options.expectedGenerationId &&
+                existingGeneration &&
+                options.expectedGenerationId !== existingGeneration
+            ) {
+                throw new Error('Lock write rejected: generation mismatch (stale writer).')
+            }
+
+            if (
+                typeof options.expectedWriteVersion === 'number' &&
+                options.expectedWriteVersion !== existingWriteVersion
+            ) {
+                throw new Error('Lock write rejected: writeVersion mismatch (stale writer).')
+            }
+
+            prepared.syncState.generationId = existingGeneration || prepared.syncState.generationId || randomUUID()
+            prepared.syncState.writeVersion = existingWriteVersion + 1
+        } else {
+            prepared.syncState.generationId = prepared.syncState.generationId || randomUUID()
+            prepared.syncState.writeVersion = prepared.syncState.writeVersion ?? 0
+        }
+
+        return prepared
+    }
+
+    /** Write lock file to disk in compact format */
+    async write(lock: MikkLock, lockPath: string, options: LockWriteOptions = {}): Promise<void> {
+        const prepared = await this.prepareForWrite(lock, lockPath, options)
+        const json = this.serialize(prepared)
+        await writeFileAtomic(lockPath, json, { encoding: 'utf-8' })
     }
 }
 

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({
@@ -174,6 +176,14 @@ export const MikkLockSchema = z.object({
         lastSyncAt: z.string(),
         lockHash: z.string(),
         contractHash: z.string(),
+        generationId: z.string().optional(),
+        writeVersion: z.number().int().nonnegative().optional(),
+        parseDiagnostics: z.object({
+            requestedFiles: z.number().int().nonnegative(),
+            parsedFiles: z.number().int().nonnegative(),
+            fallbackFiles: z.number().int().nonnegative(),
+            diagnostics: z.number().int().nonnegative(),
+        }).optional(),
     }),
     modules: z.record(MikkLockModuleSchema),
     functions: z.record(MikkLockFunctionSchema),

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'
@@ -13,4 +15,15 @@ export type { } from './error-handler.js'
 export { discoverFiles, discoverContextFiles, readFileContent, writeFileContent, fileExists, setupMikkDirectory, readMikkIgnore, parseMikkIgnore, detectProjectLanguage, getDiscoveryPatterns, generateMikkIgnore, updateGitIgnore, cleanupGitIgnore } from './utils/fs.js'
 export type { ContextFile, ContextFileType, ProjectLanguage } from './utils/fs.js'
 export { minimatch } from './utils/minimatch.js'
-export { scoreFunctions, findFuzzyMatches, levenshtein, splitCamelCase, extractKeywords } from './utils/fuzzy-match.js'
+export { scoreFunctions, findFuzzyMatches, levenshtein, splitCamelCase, extractKeywords } from './utils/fuzzy-match.js'
+export { writeFileAtomic, writeJsonAtomic } from './utils/atomic-write.js'
+export type { AtomicWriteOptions } from './utils/atomic-write.js'
+export {
+	runArtifactWriteTransaction,
+	recoverArtifactWriteTransactions,
+} from './utils/artifact-transaction.js'
+export type {
+	ArtifactWriteInput,
+	ArtifactTransactionOptions,
+	RecoverySummary,
+} from './utils/artifact-transaction.js'