@getmikk/core 2.0.11 → 2.0.13

package/src/utils/artifact-transaction.ts

@@ -0,0 +1,176 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { writeFileAtomic } from './atomic-write.js'
+
+export type ArtifactTransactionStatus = 'begin' | 'staged' | 'commit-ready'
+
+export interface ArtifactWriteInput {
+    targetPath: string
+    content: string
+    encoding?: BufferEncoding
+}
+
+interface ArtifactWriteJournal {
+    targetPath: string
+    stagedPath: string
+    encoding: BufferEncoding
+}
+
+interface ArtifactTransactionJournal {
+    id: string
+    name: string
+    createdAt: string
+    status: ArtifactTransactionStatus
+    writes: ArtifactWriteJournal[]
+    committedAt?: string
+}
+
+export interface ArtifactTransactionOptions {
+    simulateCrashAt?: 'after-begin' | 'after-stage' | 'after-commit-marker'
+}
+
+export interface RecoverySummary {
+    recovered: number
+    rolledBack: number
+    removedJournals: number
+}
+
+function getTransactionDirectory(projectRoot: string): string {
+    return path.join(projectRoot, '.mikk', 'transactions')
+}
+
+async function writeJournal(journalPath: string, journal: ArtifactTransactionJournal): Promise<void> {
+    await writeFileAtomic(journalPath, JSON.stringify(journal, null, 2), { encoding: 'utf-8' })
+}
+
+function makeStagedPath(targetPath: string, id: string): string {
+    const dir = path.dirname(targetPath)
+    const base = path.basename(targetPath)
+    return path.join(dir, `.${base}.txn-${id}.staged`)
+}
+
+export async function runArtifactWriteTransaction(
+    projectRoot: string,
+    name: string,
+    writes: ArtifactWriteInput[],
+    options: ArtifactTransactionOptions = {},
+): Promise<void> {
+    if (writes.length === 0) return
+
+    const txDir = getTransactionDirectory(projectRoot)
+    await fs.mkdir(txDir, { recursive: true })
+
+    const id = `${Date.now()}-${randomUUID().slice(0, 8)}`
+    const journalPath = path.join(txDir, `${id}.journal.json`)
+    const journal: ArtifactTransactionJournal = {
+        id,
+        name,
+        createdAt: new Date().toISOString(),
+        status: 'begin',
+        writes: writes.map((w) => ({
+            targetPath: w.targetPath,
+            stagedPath: makeStagedPath(w.targetPath, id),
+            encoding: w.encoding ?? 'utf-8',
+        })),
+    }
+
+    await writeJournal(journalPath, journal)
+    if (options.simulateCrashAt === 'after-begin') {
+        throw new Error('Simulated crash after begin')
+    }
+
+    for (let i = 0; i < writes.length; i++) {
+        const input = writes[i]
+        const record = journal.writes[i]
+        await fs.mkdir(path.dirname(record.stagedPath), { recursive: true })
+        await writeFileAtomic(record.stagedPath, input.content, { encoding: record.encoding })
+    }
+
+    journal.status = 'staged'
+    await writeJournal(journalPath, journal)
+    if (options.simulateCrashAt === 'after-stage') {
+        throw new Error('Simulated crash after stage')
+    }
+
+    journal.status = 'commit-ready'
+    journal.committedAt = new Date().toISOString()
+    await writeJournal(journalPath, journal)
+    if (options.simulateCrashAt === 'after-commit-marker') {
+        throw new Error('Simulated crash after commit marker')
+    }
+
+    for (const write of journal.writes) {
+        await fs.rename(write.stagedPath, write.targetPath)
+    }
+
+    await fs.unlink(journalPath)
+}
+
+export async function recoverArtifactWriteTransactions(projectRoot: string): Promise<RecoverySummary> {
+    const txDir = getTransactionDirectory(projectRoot)
+    const summary: RecoverySummary = {
+        recovered: 0,
+        rolledBack: 0,
+        removedJournals: 0,
+    }
+
+    let entries: string[] = []
+    try {
+        entries = await fs.readdir(txDir)
+    } catch {
+        return summary
+    }
+
+    const journals = entries.filter((name) => name.endsWith('.journal.json'))
+
+    for (const file of journals) {
+        const journalPath = path.join(txDir, file)
+        let journal: ArtifactTransactionJournal | null = null
+        try {
+            const raw = await fs.readFile(journalPath, 'utf-8')
+            journal = JSON.parse(raw) as ArtifactTransactionJournal
+        } catch {
+            try {
+                await fs.unlink(journalPath)
+                summary.removedJournals += 1
+            } catch {
+                // Ignore broken journal cleanup failures.
+            }
+            continue
+        }
+
+        try {
+            if (journal.status === 'commit-ready') {
+                for (const write of journal.writes) {
+                    try {
+                        await fs.rename(write.stagedPath, write.targetPath)
+                    } catch (err: any) {
+                        if (err?.code !== 'ENOENT') {
+                            throw err
+                        }
+                    }
+                }
+                summary.recovered += 1
+            } else {
+                for (const write of journal.writes) {
+                    try {
+                        await fs.unlink(write.stagedPath)
+                    } catch {
+                        // Ignore missing staged files.
+                    }
+                }
+                summary.rolledBack += 1
+            }
+        } finally {
+            try {
+                await fs.unlink(journalPath)
+                summary.removedJournals += 1
+            } catch {
+                // Ignore missing journal file.
+            }
+        }
+    }
+
+    return summary
+}

package/src/utils/atomic-write.ts

@@ -0,0 +1,131 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+export interface AtomicWriteOptions {
+    encoding?: BufferEncoding
+    mode?: number
+    lockTimeoutMs?: number
+    staleLockMs?: number
+    retryDelayMs?: number
+}
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000
+const DEFAULT_STALE_LOCK_MS = 60_000
+const DEFAULT_RETRY_DELAY_MS = 50
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+async function acquireFileLock(lockPath: string, options: AtomicWriteOptions): Promise<() => Promise<void>> {
+    const lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS
+    const staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS
+    const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
+    const startedAt = Date.now()
+
+    while (true) {
+        try {
+            const fd = await fs.open(lockPath, 'wx')
+            try {
+                const payload = JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() })
+                await fd.writeFile(payload, { encoding: 'utf-8' })
+                await fd.sync()
+            } finally {
+                await fd.close()
+            }
+
+            return async () => {
+                try {
+                    await fs.unlink(lockPath)
+                } catch {
+                    // Ignore missing locks on release.
+                }
+            }
+        } catch (err: any) {
+            if (err?.code !== 'EEXIST') {
+                throw err
+            }
+
+            try {
+                const stat = await fs.stat(lockPath)
+                const ageMs = Date.now() - stat.mtimeMs
+                if (ageMs > staleLockMs) {
+                    await fs.unlink(lockPath)
+                    continue
+                }
+            } catch {
+                // Lock disappeared between stat/unlink checks — retry acquisition.
+            }
+
+            if (Date.now() - startedAt > lockTimeoutMs) {
+                throw new Error(`Timed out acquiring write lock for ${path.basename(lockPath)}`)
+            }
+
+            await sleep(retryDelayMs)
+        }
+    }
+}
+
+/**
+ * Write a file atomically with a lock-file critical section.
+ *
+ * Guarantees:
+ * - Atomicity: write to temp file then rename
+ * - Isolation: one writer at a time via lock file
+ * - Durability: fsync temp file and parent directory (best effort)
+ */
+export async function writeFileAtomic(
+    targetPath: string,
+    content: string,
+    options: AtomicWriteOptions = {}
+): Promise<void> {
+    const directory = path.dirname(targetPath)
+    const baseName = path.basename(targetPath)
+    const lockPath = `${targetPath}.lock`
+    const tempPath = path.join(
+        directory,
+        `.${baseName}.${process.pid}.${Date.now()}.${randomUUID().slice(0, 8)}.tmp`
+    )
+
+    await fs.mkdir(directory, { recursive: true })
+    const releaseLock = await acquireFileLock(lockPath, options)
+
+    try {
+        const fd = await fs.open(tempPath, 'w', options.mode)
+        try {
+            await fd.writeFile(content, { encoding: options.encoding ?? 'utf-8' })
+            await fd.sync()
+        } finally {
+            await fd.close()
+        }
+
+        await fs.rename(tempPath, targetPath)
+
+        // Best-effort directory fsync for rename durability.
+        try {
+            const dirFd = await fs.open(directory, 'r')
+            try {
+                await dirFd.sync()
+            } finally {
+                await dirFd.close()
+            }
+        } catch {
+            // Directory fsync can fail on some platforms/filesystems.
+        }
+    } finally {
+        try {
+            await fs.unlink(tempPath)
+        } catch {
+            // Temp file may already be moved/removed.
+        }
+        await releaseLock()
+    }
+}
+
+export async function writeJsonAtomic(
+    targetPath: string,
+    value: unknown,
+    options: AtomicWriteOptions = {}
+): Promise<void> {
+    const payload = JSON.stringify(value)
+    await writeFileAtomic(targetPath, payload, options)
+}

package/src/utils/fs.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 import fg from 'fast-glob'
+import { getDiscoveryExtensions } from './language-registry.js'
 
 // --- Well-known patterns for schema/config/route files ---------------------
 // These are structural files an AI agent needs but aren't source code.
@@ -275,7 +276,7 @@ function inferContextFileType(filePath: string): ContextFileType {
 }
 
 /** Recognised project language */
-export type ProjectLanguage = 'typescript' | 'javascript' | 'python' | 'go' | 'rust' | 'java' | 'ruby' | 'php' | 'csharp' | 'c' | 'cpp' | 'unknown'
+export type ProjectLanguage = 'typescript' | 'javascript' | 'python' | 'go' | 'rust' | 'java' | 'swift' | 'ruby' | 'php' | 'csharp' | 'c' | 'cpp' | 'unknown'
 
 /** Auto-detect the project's primary language from manifest files */
 export async function detectProjectLanguage(projectRoot: string): Promise<ProjectLanguage> {
@@ -293,6 +294,7 @@ export async function detectProjectLanguage(projectRoot: string): Promise<Projec
     if (await exists('pyproject.toml') || await exists('setup.py') || await exists('requirements.txt')) return 'python'
     if (await exists('Gemfile')) return 'ruby'
     if (await exists('pom.xml') || await exists('build.gradle') || await exists('build.gradle.kts')) return 'java'
+    if (await exists('Package.swift')) return 'swift'
     if (await exists('composer.json')) return 'php'
     if (await hasGlob('*.csproj') || await hasGlob('*.sln')) return 'csharp'
     if (await hasGlob('CMakeLists.txt') || await hasGlob('**/*.cmake') || await hasGlob('*.cpp')) return 'cpp'
@@ -306,66 +308,76 @@ export function getDiscoveryPatterns(language: ProjectLanguage): { patterns: str
     const commonIgnore = [
         '**/.mikk/**', '**/.git/**', '**/coverage/**', '**/build/**',
     ]
+
+    const toPatterns = (lang: ProjectLanguage): string[] => {
+        return getDiscoveryExtensions(lang).map(ext => `**/*${ext}`)
+    }
+
     switch (language) {
         case 'typescript':
             return {
-                patterns: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/node_modules/**', '**/dist/**', '**/.next/**', '**/.nuxt/**', '**/.svelte-kit/**', '**/*.d.ts', '**/*.test.{ts,js,tsx,jsx}', '**/*.spec.{ts,js,tsx,jsx}'],
             }
         case 'javascript':
             return {
-                patterns: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs', '**/*.ts', '**/*.tsx'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/node_modules/**', '**/dist/**', '**/.next/**', '**/*.d.ts', '**/*.test.{ts,js,tsx,jsx}', '**/*.spec.{ts,js,tsx,jsx}'],
             }
         case 'python':
             return {
-                patterns: ['**/*.py'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/__pycache__/**', '**/venv/**', '**/.venv/**', '**/.tox/**', '**/test_*.py', '**/*_test.py'],
             }
         case 'go':
             return {
-                patterns: ['**/*.go'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/vendor/**', '**/*_test.go'],
             }
         case 'rust':
             return {
-                patterns: ['**/*.rs'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/target/**'],
             }
         case 'java':
             return {
-                patterns: ['**/*.java', '**/*.kt'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/target/**', '**/.gradle/**', '**/Test*.java', '**/*Test.java'],
             }
+        case 'swift':
+            return {
+                patterns: toPatterns(language),
+                ignore: [...commonIgnore, '**/.build/**', '**/Tests/**'],
+            }
         case 'ruby':
             return {
-                patterns: ['**/*.rb'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/vendor/**', '**/*_spec.rb', '**/spec/**'],
             }
         case 'php':
             return {
-                patterns: ['**/*.php'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/vendor/**', '**/*Test.php'],
             }
         case 'csharp':
             return {
-                patterns: ['**/*.cs'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/bin/**', '**/obj/**'],
             }
         case 'cpp':
             return {
-                patterns: ['**/*.cpp', '**/*.cc', '**/*.cxx', '**/*.hpp', '**/*.hxx', '**/*.h'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/build/**', '**/cmake-build-*/**'],
             }
         case 'c':
             return {
-                patterns: ['**/*.c', '**/*.h'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/build/**'],
             }
         default:
             // Fallback: discover JS/TS (most common)
             return {
-                patterns: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+                patterns: toPatterns(language),
                 ignore: [...commonIgnore, '**/node_modules/**', '**/dist/**', '**/*.d.ts'],
             }
     }
@@ -550,6 +562,14 @@ const LANGUAGE_IGNORE_TEMPLATES: Record<ProjectLanguage, string[]> = {
         'gradle/',
         '',
     ],
+    swift: [
+        '# Swift artifacts',
+        '.build/',
+        '.swiftpm/',
+        'Packages/',
+        'Tests/',
+        '',
+    ],
     ruby: [
         '# Test files',
         '*_spec.rb',

package/src/utils/language-registry.ts

@@ -0,0 +1,82 @@
+export type ParserKind = 'oxc' | 'go' | 'tree-sitter' | 'unknown'
+
+export type RegistryLanguage =
+    | 'typescript'
+    | 'javascript'
+    | 'python'
+    | 'go'
+    | 'rust'
+    | 'java'
+    | 'kotlin'
+    | 'swift'
+    | 'ruby'
+    | 'php'
+    | 'csharp'
+    | 'c'
+    | 'cpp'
+    | 'unknown'
+
+const OXC_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'] as const
+const GO_EXTENSIONS = ['.go'] as const
+const TREE_SITTER_EXTENSIONS = [
+    '.py', '.java', '.kt', '.kts', '.swift',
+    '.c', '.h', '.cpp', '.cc', '.cxx', '.hpp', '.hxx', '.hh',
+    '.cs', '.rs', '.php', '.rb',
+] as const
+
+const PARSER_EXTENSIONS: Record<Exclude<ParserKind, 'unknown'>, readonly string[]> = {
+    oxc: OXC_EXTENSIONS,
+    go: GO_EXTENSIONS,
+    'tree-sitter': TREE_SITTER_EXTENSIONS,
+}
+
+const LANGUAGE_EXTENSIONS: Record<RegistryLanguage, readonly string[]> = {
+    typescript: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+    javascript: ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'],
+    python: ['.py'],
+    go: ['.go'],
+    rust: ['.rs'],
+    kotlin: ['.kt', '.kts'],
+    java: ['.java', '.kt', '.kts'],
+    swift: ['.swift'],
+    ruby: ['.rb'],
+    php: ['.php'],
+    csharp: ['.cs'],
+    c: ['.c', '.h'],
+    cpp: ['.cpp', '.cc', '.cxx', '.hpp', '.hxx', '.hh', '.h'],
+    unknown: ['.ts', '.tsx', '.js', '.jsx'],
+}
+
+const EXT_TO_PARSER = new Map<string, ParserKind>()
+for (const ext of OXC_EXTENSIONS) EXT_TO_PARSER.set(ext, 'oxc')
+for (const ext of GO_EXTENSIONS) EXT_TO_PARSER.set(ext, 'go')
+for (const ext of TREE_SITTER_EXTENSIONS) EXT_TO_PARSER.set(ext, 'tree-sitter')
+
+const EXT_TO_LANGUAGE = new Map<string, RegistryLanguage>()
+for (const [language, extensions] of Object.entries(LANGUAGE_EXTENSIONS)) {
+    for (const ext of extensions) {
+        if (!EXT_TO_LANGUAGE.has(ext)) {
+            EXT_TO_LANGUAGE.set(ext, language as RegistryLanguage)
+        }
+    }
+}
+
+export function parserKindForExtension(ext: string): ParserKind {
+    return EXT_TO_PARSER.get(ext.toLowerCase()) ?? 'unknown'
+}
+
+export function languageForExtension(ext: string): RegistryLanguage {
+    return EXT_TO_LANGUAGE.get(ext.toLowerCase()) ?? 'unknown'
+}
+
+export function getParserExtensions(kind: Exclude<ParserKind, 'unknown'>): readonly string[] {
+    return PARSER_EXTENSIONS[kind]
+}
+
+export function getDiscoveryExtensions(language: RegistryLanguage): readonly string[] {
+    return LANGUAGE_EXTENSIONS[language]
+}
+
+export function isTreeSitterExtension(ext: string): boolean {
+    return parserKindForExtension(ext) === 'tree-sitter'
+}

package/tests/adr-manager.test.ts

@@ -94,4 +94,10 @@ describe('AdrManager', () => {
         const decisions = await manager.list()
         expect(decisions).toHaveLength(0)
     })
+
+    it('returns false when removing a missing decision', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        const success = await manager.remove('ADR-404')
+        expect(success).toBe(false)
+    })
 })

package/tests/artifact-transaction.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'bun:test'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import {
+    runArtifactWriteTransaction,
+    recoverArtifactWriteTransactions,
+} from '../src/utils/artifact-transaction'
+
+describe('artifact write transactions', () => {
+    it('commits grouped writes atomically', async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'mikk-tx-'))
+        const aPath = path.join(root, 'mikk.lock.json')
+        const bPath = path.join(root, 'claude.md')
+
+        await runArtifactWriteTransaction(root, 'commit-test', [
+            { targetPath: aPath, content: '{"ok":true}' },
+            { targetPath: bPath, content: '# context' },
+        ])
+
+        expect(await fs.readFile(aPath, 'utf-8')).toContain('ok')
+        expect(await fs.readFile(bPath, 'utf-8')).toContain('context')
+
+        await fs.rm(root, { recursive: true, force: true })
+    })
+
+    it('rolls back staged writes after pre-commit crash', async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'mikk-tx-'))
+        const lockPath = path.join(root, 'mikk.lock.json')
+
+        await expect(
+            runArtifactWriteTransaction(
+                root,
+                'rollback-test',
+                [{ targetPath: lockPath, content: '{"v":1}' }],
+                { simulateCrashAt: 'after-stage' },
+            ),
+        ).rejects.toThrow('Simulated crash after stage')
+
+        const summary = await recoverArtifactWriteTransactions(root)
+        expect(summary.rolledBack).toBeGreaterThanOrEqual(1)
+
+        let exists = true
+        try {
+            await fs.access(lockPath)
+        } catch {
+            exists = false
+        }
+        expect(exists).toBe(false)
+
+        await fs.rm(root, { recursive: true, force: true })
+    })
+
+    it('recovers commit-ready journals after post-commit-marker crash', async () => {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'mikk-tx-'))
+        const lockPath = path.join(root, 'mikk.lock.json')
+
+        await expect(
+            runArtifactWriteTransaction(
+                root,
+                'recovery-test',
+                [{ targetPath: lockPath, content: '{"v":2}' }],
+                { simulateCrashAt: 'after-commit-marker' },
+            ),
+        ).rejects.toThrow('Simulated crash after commit marker')
+
+        const summary = await recoverArtifactWriteTransactions(root)
+        expect(summary.recovered).toBeGreaterThanOrEqual(1)
+        expect(await fs.readFile(lockPath, 'utf-8')).toContain('"v":2')
+
+        await fs.rm(root, { recursive: true, force: true })
+    })
+})

package/tests/contract.test.ts

@@ -49,6 +49,18 @@ describe('MikkContractSchema', () => {
             expect(result.data.overwrite.mode).toBe('never')
         }
     })
+
+    it('rejects contract with invalid declared.modules type', () => {
+        const bad = {
+            ...validContract,
+            declared: {
+                ...validContract.declared,
+                modules: 'not-an-array',
+            },
+        }
+        const result = MikkContractSchema.safeParse(bad)
+        expect(result.success).toBe(false)
+    })
 })
 
 describe('LockCompiler', () => {

package/tests/dead-code.test.ts

@@ -131,4 +131,16 @@ describe('DeadCodeDetector', () => {
 
         expect(result.deadFunctions).toHaveLength(0) // InternalHelper is called by exported fn in same file
     })
+
+    it('keeps deadCount aligned with deadFunctions length', () => {
+        const graph = buildTestGraph([
+            ['A', 'nothing'],
+            ['B', 'nothing'],
+        ])
+        const lock = generateDummyLock(graph.nodes)
+
+        const detector = new DeadCodeDetector(graph, lock)
+        const result = detector.detect()
+        expect(result.deadCount).toBe(result.deadFunctions.length)
+    })
 })

package/tests/esm-resolver.test.ts

@@ -73,4 +73,10 @@ describe('OxcResolver - ESM and CJS Resolution', () => {
         const res = await resolver.resolve('./local', path.join(FIXTURE_DIR, 'index.ts'))
         expect(res).toContain('.test-fixture-esm/local.ts')
     })
+
+    it('does not throw for missing package imports', async () => {
+        const resolver = new OxcResolver(FIXTURE_DIR)
+        const res = await resolver.resolve('totally-missing-pkg', path.join(FIXTURE_DIR, 'index.ts'))
+        expect(typeof res).toBe('string')
+    })
 })