@getmikk/core 2.0.12 → 2.0.13

package/README.md

@@ -15,13 +15,16 @@ Foundation package for the Mikk ecosystem. All other packages depend on core —
 
 ### Parsers
 
-Three language parsers, each following the same interface: `parse(filePath, content)` → `ParsedFile`.
+Three parser families follow the same interface: `parse(filePath, content)` → `ParsedFile`.
 
 **TypeScript / TSX**
-Uses the TypeScript Compiler API. Extracts: functions (name, params with types, return type, start/end line, async flag, decorators, generics), classes (methods, properties, inheritance), imports (named, default, namespace, type-only) with full resolution (tsconfig `paths` alias resolution, recursive `extends` chain, index file inference, extension inference). Every extracted function has its exact byte-accurate body location.
+Uses OXC (Rust parser). Extracts: functions (name, params with types, return type, start/end line, async flag, decorators, generics), classes (methods, properties, inheritance), imports (named, default, namespace, type-only) with full resolution (tsconfig `paths` alias resolution, recursive `extends` chain, index file inference, extension inference). Every extracted function has its exact byte-accurate body location.
 
 **JavaScript / JSX**
-Uses the TypeScript Compiler API with `ScriptKind` inference (detects JS/JSX/CJS/MJS). Handles: JSX expression containers, default exports, CommonJS `module.exports`, re-exports via barrel files.
+Uses OXC with `ScriptKind` inference (detects JS/JSX/CJS/MJS). Handles: JSX expression containers, default exports, CommonJS `module.exports`, re-exports via barrel files.
+
+**Polyglot (Tree-sitter)**
+Python, Java, Kotlin (`.kt`, `.kts`), Swift, C/C++ (`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.hh`), C#, Rust, PHP, and Ruby via tree-sitter grammars.
 
 **Go**
 Regex + stateful scanning. No Go toolchain dependency. Extracts: functions, methods (with receiver types), structs, interfaces, package imports. `go.mod` used for project boundary detection.
@@ -81,6 +84,12 @@ Lock format v1.7.0:
 
 Read and write `mikk.json` and `mikk.lock.json`. `LockReader.write()` uses atomic temp-file + rename to prevent corruption.
 
+`AdrManager` writes `mikk.json` atomically as well (temp file + rename + file lock), reducing corruption risk in concurrent agent workflows.
+
+### Parse Diagnostics
+
+`parseFilesWithDiagnostics` returns both parsed files and parser/read/import-resolution diagnostics. This enables strict parse enforcement in CLI commands (`mikk init --strict-parsing`, `mikk analyze --strict-parsing`) for high-assurance pipelines.
+
 ### AdrManager
 
 CRUD for Architectural Decision Records in `mikk.json`. Add, update, remove, list, and get individual decisions. ADRs surface in all AI context queries via the MCP server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmikk/core",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

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-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,

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

@@ -174,6 +174,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

@@ -13,4 +13,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'