@getmikk/core 1.2.0

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@getmikk/core",
+    "version": "1.2.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "bun test",
+        "publish": "npm publish --access public",
+        "dev": "tsc --watch"
+    },
+    "dependencies": {
+        "@types/better-sqlite3": "^7.6.13",
+        "better-sqlite3": "^12.6.2",
+        "fast-glob": "^3.3.0",
+        "zod": "^3.22.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.0",
+        "@types/node": "^22.0.0"
+    }
+}

package/src/contract/contract-generator.ts

@@ -0,0 +1,85 @@
+import type { MikkContract } from './schema.js'
+import type { ModuleCluster } from '../graph/types.js'
+import type { ParsedFile } from '../parser/types.js'
+
+/**
+ * ContractGenerator — generates a mikk.json skeleton from graph analysis.
+ * Takes detected module clusters and produces a human-refinable contract.
+ */
+export class ContractGenerator {
+    /** Generate a full mikk.json contract from detected clusters */
+    generateFromClusters(
+        clusters: ModuleCluster[],
+        parsedFiles: ParsedFile[],
+        projectName: string
+    ): MikkContract {
+        const modules = clusters.map(cluster => ({
+            id: cluster.id,
+            name: cluster.suggestedName,
+            description: `Contains ${cluster.files.length} files with ${cluster.functions.length} functions`,
+            intent: '',
+            paths: this.inferPaths(cluster.files),
+            entryFunctions: this.inferEntryFunctions(cluster, parsedFiles),
+        }))
+
+        // Detect entry points (files with no importedBy)
+        const entryPoints = parsedFiles
+            .filter(f => {
+                const basename = f.path.split('/').pop() || ''
+                return basename === 'index.ts' || basename === 'server.ts' || basename === 'main.ts' || basename === 'app.ts'
+            })
+            .map(f => f.path)
+
+        return {
+            version: '1.0.0',
+            project: {
+                name: projectName,
+                description: '',
+                language: 'typescript',
+                entryPoints: entryPoints.length > 0 ? entryPoints : [parsedFiles[0]?.path ?? 'src/index.ts'],
+            },
+            declared: {
+                modules,
+                constraints: [],
+                decisions: [],
+            },
+            overwrite: {
+                mode: 'never',
+                requireConfirmation: true,
+            },
+        }
+    }
+
+    /** Infer path patterns from a list of files */
+    private inferPaths(files: string[]): string[] {
+        // Find common directory prefix
+        if (files.length === 0) return []
+
+        const dirs = new Set<string>()
+        for (const file of files) {
+            const parts = file.split('/')
+            parts.pop() // Remove filename
+            dirs.add(parts.join('/'))
+        }
+
+        // Use glob patterns for each unique directory
+        return [...dirs].map(dir => `${dir}/**`)
+    }
+
+    /** Find exported functions in a cluster — these are likely entry points */
+    private inferEntryFunctions(cluster: ModuleCluster, parsedFiles: ParsedFile[]): string[] {
+        const clusterFileSet = new Set(cluster.files)
+        const entryFunctions: string[] = []
+
+        for (const file of parsedFiles) {
+            if (!clusterFileSet.has(file.path)) continue
+            for (const fn of file.functions) {
+                if (fn.isExported) {
+                    entryFunctions.push(fn.name)
+                }
+            }
+        }
+
+        return entryFunctions
+    }
+}

package/src/contract/contract-reader.ts

@@ -0,0 +1,28 @@
+import * as fs from 'node:fs/promises'
+import { MikkContractSchema, type MikkContract } from './schema.js'
+import { ContractNotFoundError } from '../utils/errors.js'
+
+/**
+ * ContractReader — reads and validates mikk.json from disk.
+ */
+export class ContractReader {
+    /** Read and validate mikk.json */
+    async read(contractPath: string): Promise<MikkContract> {
+        let content: string
+        try {
+            content = await fs.readFile(contractPath, 'utf-8')
+        } catch {
+            throw new ContractNotFoundError(contractPath)
+        }
+
+        const json = JSON.parse(content)
+        const result = MikkContractSchema.safeParse(json)
+
+        if (!result.success) {
+            const errors = result.error.issues.map(i => `  ${i.path.join('.')}: ${i.message}`).join('\n')
+            throw new Error(`Invalid mikk.json:\n${errors}`)
+        }
+
+        return result.data
+    }
+}

package/src/contract/contract-writer.ts

@@ -0,0 +1,114 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import type { MikkContract } from './schema.js'
+import { hashContent } from '../hash/file-hasher.js'
+
+const VERSION = 'mikk-cli@1.0.0'
+
+export interface UpdateResult {
+    updated: boolean
+    reason?: string
+    requiresConfirmation?: boolean
+    proposedChanges?: object
+}
+
+/**
+ * ContractWriter — writes mikk.json to disk.
+ * Implements the permission model (never / ask / explicit).
+ */
+export class ContractWriter {
+    /** Write a new mikk.json — safe for first write */
+    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')
+    }
+
+    /** Update an existing mikk.json respecting overwrite mode */
+    async update(
+        existing: MikkContract,
+        updates: Partial<MikkContract>,
+        outputPath: string
+    ): Promise<UpdateResult> {
+        const mode = existing.overwrite?.mode ?? 'never'
+
+        if (mode === 'never') {
+            return { updated: false, reason: 'overwrite mode is never' }
+        }
+
+        if (mode === 'ask') {
+            return {
+                updated: false,
+                requiresConfirmation: true,
+                proposedChanges: this.diffContracts(existing, updates),
+            }
+        }
+
+        if (mode === 'explicit') {
+            const updated = this.mergeContracts(existing, updates)
+            updated.overwrite = {
+                ...updated.overwrite,
+                lastOverwrittenBy: VERSION,
+                lastOverwrittenAt: new Date().toISOString(),
+            }
+            await this.writeNew(updated, outputPath)
+            await this.writeAuditLog(existing, updated, outputPath)
+            return { updated: true }
+        }
+
+        return { updated: false, reason: 'unknown mode' }
+    }
+
+    /** Merge two contracts — updates overwrite existing fields */
+    private mergeContracts(existing: MikkContract, updates: Partial<MikkContract>): MikkContract {
+        return {
+            ...existing,
+            ...updates,
+            declared: {
+                ...existing.declared,
+                ...(updates.declared || {}),
+                modules: updates.declared?.modules || existing.declared.modules,
+                constraints: updates.declared?.constraints || existing.declared.constraints,
+                decisions: updates.declared?.decisions || existing.declared.decisions,
+            },
+            project: {
+                ...existing.project,
+                ...(updates.project || {}),
+            },
+        }
+    }
+
+    /** Compute diff between two contracts */
+    private diffContracts(existing: MikkContract, updates: Partial<MikkContract>): object {
+        return {
+            before: existing.declared,
+            after: updates.declared || existing.declared,
+        }
+    }
+
+    /** Write audit log to .mikk/overwrite-history.json */
+    private async writeAuditLog(
+        before: MikkContract,
+        after: MikkContract,
+        contractPath: string
+    ): Promise<void> {
+        const historyPath = path.join(path.dirname(contractPath), '.mikk', 'overwrite-history.json')
+        let history: object[] = []
+
+        try {
+            const existing = await fs.readFile(historyPath, 'utf-8')
+            history = JSON.parse(existing)
+        } catch {
+            // No history file yet
+        }
+
+        history.push({
+            timestamp: new Date().toISOString(),
+            before: before.declared,
+            after: after.declared,
+        })
+
+        await fs.mkdir(path.dirname(historyPath), { recursive: true })
+        await fs.writeFile(historyPath, JSON.stringify(history, null, 2), 'utf-8')
+    }
+}

package/src/contract/index.ts

@@ -0,0 +1,12 @@
+export {
+    MikkContractSchema, MikkLockSchema,
+    MikkModuleSchema, MikkDecisionSchema, MikkOverwriteSchema,
+    MikkLockFunctionSchema, MikkLockModuleSchema, MikkLockFileSchema,
+    type MikkContract, type MikkLock, type MikkModule, type MikkDecision,
+    type MikkLockFunction, type MikkLockModule, type MikkLockFile,
+} from './schema.js'
+export { LockCompiler } from './lock-compiler.js'
+export { ContractWriter, type UpdateResult } from './contract-writer.js'
+export { ContractReader } from './contract-reader.js'
+export { LockReader } from './lock-reader.js'
+export { ContractGenerator } from './contract-generator.js'

package/src/contract/lock-compiler.ts

@@ -0,0 +1,221 @@
+import * as path from 'node:path'
+import { createHash } from 'node:crypto'
+import type { MikkContract, MikkLock } from './schema.js'
+import type { DependencyGraph } from '../graph/types.js'
+import type { ParsedFile } from '../parser/types.js'
+import { hashContent } from '../hash/file-hasher.js'
+import { computeModuleHash, computeRootHash } from '../hash/tree-hasher.js'
+import { minimatch } from '../utils/minimatch.js'
+
+const VERSION = 'mikk-cli@1.0.0'
+
+/**
+ * LockCompiler — takes a DependencyGraph and a MikkContract
+ * and compiles the complete mikk.lock.json.
+ */
+export class LockCompiler {
+    /** Main entry — compile full lock from graph + contract + parsed files */
+    compile(
+        graph: DependencyGraph,
+        contract: MikkContract,
+        parsedFiles: ParsedFile[]
+    ): MikkLock {
+        const functions = this.compileFunctions(graph, contract)
+        const classes = this.compileClasses(graph, contract)
+        const generics = this.compileGenerics(graph, contract)
+        const modules = this.compileModules(contract, parsedFiles)
+        const files = this.compileFiles(parsedFiles, contract)
+
+        const moduleHashes: Record<string, string> = {}
+        for (const [id, mod] of Object.entries(modules)) {
+            moduleHashes[id] = mod.hash
+        }
+
+        const lockData: MikkLock = {
+            version: '1.0.0',
+            generatedAt: new Date().toISOString(),
+            generatorVersion: VERSION,
+            projectRoot: contract.project.name,
+            syncState: {
+                status: 'clean',
+                lastSyncAt: new Date().toISOString(),
+                lockHash: '',
+                contractHash: hashContent(JSON.stringify(contract)),
+            },
+            modules,
+            functions,
+            classes: Object.keys(classes).length > 0 ? classes : undefined,
+            generics: Object.keys(generics).length > 0 ? generics : undefined,
+            files,
+            graph: {
+                nodes: graph.nodes.size,
+                edges: graph.edges.length,
+                rootHash: computeRootHash(moduleHashes),
+            },
+        }
+
+        // Compute overall lock hash from the compiled data
+        lockData.syncState.lockHash = hashContent(JSON.stringify({
+            functions: lockData.functions,
+            classes: lockData.classes,
+            generics: lockData.generics,
+            modules: lockData.modules,
+            files: lockData.files,
+        }))
+
+        return lockData
+    }
+
+    /** Compile function entries, assigning each to its module */
+    private compileFunctions(
+        graph: DependencyGraph,
+        contract: MikkContract
+    ): Record<string, MikkLock['functions'][string]> {
+        const result: Record<string, MikkLock['functions'][string]> = {}
+
+        for (const [id, node] of graph.nodes) {
+            if (node.type !== 'function') continue
+
+            const moduleId = this.findModule(node.file, contract.declared.modules)
+            const inEdges = graph.inEdges.get(id) || []
+            const outEdges = graph.outEdges.get(id) || []
+
+            result[id] = {
+                id,
+                name: node.label,
+                file: node.file,
+                startLine: node.metadata.startLine ?? 0,
+                endLine: node.metadata.endLine ?? 0,
+                hash: node.metadata.hash ?? '',
+                calls: outEdges.filter(e => e.type === 'calls').map(e => e.target),
+                calledBy: inEdges.filter(e => e.type === 'calls').map(e => e.source),
+                moduleId: moduleId || 'unknown',
+                purpose: node.metadata.purpose,
+                edgeCasesHandled: node.metadata.edgeCasesHandled,
+                errorHandling: node.metadata.errorHandling,
+                detailedLines: node.metadata.detailedLines,
+            }
+        }
+
+        return result
+    }
+
+    private compileClasses(
+        graph: DependencyGraph,
+        contract: MikkContract
+    ): Record<string, any> {
+        const result: Record<string, any> = {}
+        for (const [id, node] of graph.nodes) {
+            if (node.type !== 'class') continue
+            const moduleId = this.findModule(node.file, contract.declared.modules)
+            result[id] = {
+                id,
+                name: node.label,
+                file: node.file,
+                startLine: node.metadata.startLine ?? 0,
+                endLine: node.metadata.endLine ?? 0,
+                moduleId: moduleId || 'unknown',
+                isExported: node.metadata.isExported ?? false,
+                purpose: node.metadata.purpose,
+                edgeCasesHandled: node.metadata.edgeCasesHandled,
+                errorHandling: node.metadata.errorHandling,
+            }
+        }
+        return result
+    }
+
+    private compileGenerics(
+        graph: DependencyGraph,
+        contract: MikkContract
+    ): Record<string, any> {
+        const result: Record<string, any> = {}
+        for (const [id, node] of graph.nodes) {
+            if (node.type !== 'generic') continue
+            const moduleId = this.findModule(node.file, contract.declared.modules)
+            result[id] = {
+                id,
+                name: node.label,
+                type: node.metadata.hash ?? 'generic', // we stored type name in hash
+                file: node.file,
+                startLine: node.metadata.startLine ?? 0,
+                endLine: node.metadata.endLine ?? 0,
+                moduleId: moduleId || 'unknown',
+                isExported: node.metadata.isExported ?? false,
+                purpose: node.metadata.purpose,
+            }
+        }
+        return result
+    }
+
+    /** Compile module entries from contract definitions */
+    private compileModules(
+        contract: MikkContract,
+        parsedFiles: ParsedFile[]
+    ): Record<string, MikkLock['modules'][string]> {
+        const result: Record<string, MikkLock['modules'][string]> = {}
+
+        for (const module of contract.declared.modules) {
+            const moduleFiles = parsedFiles
+                .filter(f => this.fileMatchesModule(f.path, module.paths))
+                .map(f => f.path)
+
+            const fileHashes = moduleFiles.map(f => {
+                const parsed = parsedFiles.find(pf => pf.path === f)
+                return parsed?.hash ?? ''
+            })
+
+            result[module.id] = {
+                id: module.id,
+                files: moduleFiles,
+                hash: computeModuleHash(fileHashes),
+                fragmentPath: `.mikk/fragments/${module.id}.lock`,
+            }
+        }
+
+        return result
+    }
+
+    /** Compile file entries */
+    private compileFiles(
+        parsedFiles: ParsedFile[],
+        contract: MikkContract
+    ): Record<string, MikkLock['files'][string]> {
+        const result: Record<string, MikkLock['files'][string]> = {}
+
+        for (const file of parsedFiles) {
+            const moduleId = this.findModule(file.path, contract.declared.modules)
+            result[file.path] = {
+                path: file.path,
+                hash: file.hash,
+                moduleId: moduleId || 'unknown',
+                lastModified: new Date().toISOString(),
+            }
+        }
+
+        return result
+    }
+
+    /** Find which module a file belongs to based on path patterns */
+    private findModule(
+        filePath: string,
+        modules: MikkContract['declared']['modules']
+    ): string | null {
+        for (const module of modules) {
+            if (this.fileMatchesModule(filePath, module.paths)) {
+                return module.id
+            }
+        }
+        return null
+    }
+
+    /** Check if a file path matches any of the module's path patterns */
+    private fileMatchesModule(filePath: string, patterns: string[]): boolean {
+        const normalized = filePath.replace(/\\/g, '/')
+        for (const pattern of patterns) {
+            if (minimatch(normalized, pattern)) {
+                return true
+            }
+        }
+        return false
+    }
+}

package/src/contract/lock-reader.ts

@@ -0,0 +1,34 @@
+import * as fs from 'node:fs/promises'
+import { MikkLockSchema, type MikkLock } from './schema.js'
+import { LockNotFoundError } from '../utils/errors.js'
+
+/**
+ * LockReader — reads and validates mikk.lock.json from disk.
+ */
+export class LockReader {
+    /** Read and validate mikk.lock.json */
+    async read(lockPath: string): Promise<MikkLock> {
+        let content: string
+        try {
+            content = await fs.readFile(lockPath, 'utf-8')
+        } catch {
+            throw new LockNotFoundError()
+        }
+
+        const json = JSON.parse(content)
+        const result = MikkLockSchema.safeParse(json)
+
+        if (!result.success) {
+            const errors = result.error.issues.map(i => `  ${i.path.join('.')}: ${i.message}`).join('\n')
+            throw new Error(`Invalid mikk.lock.json:\n${errors}`)
+        }
+
+        return result.data
+    }
+
+    /** Write lock file to disk */
+    async write(lock: MikkLock, lockPath: string): Promise<void> {
+        const json = JSON.stringify(lock, null, 2)
+        await fs.writeFile(lockPath, json, 'utf-8')
+    }
+}

package/src/contract/schema.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod'
+
+// ─── mikk.json schema ──────────────────────────────────────
+
+export const MikkModuleSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    intent: z.string().optional(),
+    owners: z.array(z.string()).optional(),
+    paths: z.array(z.string()),
+    entryFunctions: z.array(z.string()).optional(),
+})
+
+export const MikkDecisionSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    reason: z.string(),
+    date: z.string(),
+})
+
+export const MikkOverwriteSchema = z.object({
+    mode: z.enum(['never', 'ask', 'explicit']).default('never'),
+    requireConfirmation: z.boolean().default(true),
+    lastOverwrittenBy: z.string().optional(),
+    lastOverwrittenAt: z.string().optional(),
+}).default({ mode: 'never', requireConfirmation: true })
+
+export const MikkContractSchema = z.object({
+    version: z.string(),
+    project: z.object({
+        name: z.string(),
+        description: z.string(),
+        language: z.string(),
+        framework: z.string().optional(),
+        entryPoints: z.array(z.string()),
+    }),
+    declared: z.object({
+        modules: z.array(MikkModuleSchema),
+        constraints: z.array(z.string()).default([]),
+        decisions: z.array(MikkDecisionSchema).default([]),
+    }),
+    overwrite: MikkOverwriteSchema,
+})
+
+export type MikkContract = z.infer<typeof MikkContractSchema>
+export type MikkModule = z.infer<typeof MikkModuleSchema>
+export type MikkDecision = z.infer<typeof MikkDecisionSchema>
+
+// ─── mikk.lock.json schema ─────────────────────────────────
+
+export const MikkLockFunctionSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    file: z.string(),
+    startLine: z.number(),
+    endLine: z.number(),
+    hash: z.string(),
+    calls: z.array(z.string()),
+    calledBy: z.array(z.string()),
+    moduleId: z.string(),
+    purpose: z.string().optional(),
+    edgeCasesHandled: z.array(z.string()).optional(),
+    errorHandling: z.array(z.object({
+        line: z.number(),
+        type: z.enum(['try-catch', 'throw']),
+        detail: z.string(),
+    })).optional(),
+    detailedLines: z.array(z.object({
+        startLine: z.number(),
+        endLine: z.number(),
+        blockType: z.string(),
+    })).optional()
+})
+
+export const MikkLockModuleSchema = z.object({
+    id: z.string(),
+    files: z.array(z.string()),
+    hash: z.string(),
+    fragmentPath: z.string(),
+})
+
+export const MikkLockFileSchema = z.object({
+    path: z.string(),
+    hash: z.string(),
+    moduleId: z.string(),
+    lastModified: z.string(),
+})
+
+export const MikkLockClassSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    file: z.string(),
+    startLine: z.number(),
+    endLine: z.number(),
+    moduleId: z.string(),
+    isExported: z.boolean(),
+    purpose: z.string().optional(),
+    edgeCasesHandled: z.array(z.string()).optional(),
+    errorHandling: z.array(z.object({
+        line: z.number(),
+        type: z.enum(['try-catch', 'throw']),
+        detail: z.string(),
+    })).optional(),
+})
+
+export const MikkLockGenericSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    type: z.string(),
+    file: z.string(),
+    startLine: z.number(),
+    endLine: z.number(),
+    moduleId: z.string(),
+    isExported: z.boolean(),
+    purpose: z.string().optional(),
+})
+
+export const MikkLockSchema = z.object({
+    version: z.string(),
+    generatedAt: z.string(),
+    generatorVersion: z.string(),
+    projectRoot: z.string(),
+    syncState: z.object({
+        status: z.enum(['clean', 'syncing', 'drifted', 'conflict']),
+        lastSyncAt: z.string(),
+        lockHash: z.string(),
+        contractHash: z.string(),
+    }),
+    modules: z.record(MikkLockModuleSchema),
+    functions: z.record(MikkLockFunctionSchema),
+    classes: z.record(MikkLockClassSchema).optional(),
+    generics: z.record(MikkLockGenericSchema).optional(),
+    files: z.record(MikkLockFileSchema),
+    graph: z.object({
+        nodes: z.number(),
+        edges: z.number(),
+        rootHash: z.string(),
+    }),
+})
+
+export type MikkLock = z.infer<typeof MikkLockSchema>
+export type MikkLockFunction = z.infer<typeof MikkLockFunctionSchema>
+export type MikkLockModule = z.infer<typeof MikkLockModuleSchema>
+export type MikkLockFile = z.infer<typeof MikkLockFileSchema>
+export type MikkLockClass = z.infer<typeof MikkLockClassSchema>
+export type MikkLockGeneric = z.infer<typeof MikkLockGenericSchema>