@getmikk/core 1.7.1 → 1.8.0

package/README.md

@@ -1,469 +1,139 @@
-# @getmikk/core
+# @getmikk/core
 
-> The foundation of the Mikk ecosystem — TypeScript AST parsing, dependency graph construction, Merkle-tree hashing, contract management, and lock file compilation.
+> AST parsing, dependency graph, Merkle hashing, contract management, boundary enforcement.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/core)](https://www.npmjs.com/package/@getmikk/core)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-`@getmikk/core` is the foundation every other Mikk package builds on. It owns the complete pipeline for turning raw **TypeScript and Go** source into structured, queryable intelligence: parsing source files into real ASTs (TS Compiler API for TypeScript; regex + stateful scanning for Go; no external toolchain required), building a two-pass dependency graph with O(1) adjacency lookups, computing Merkle-tree SHA-256 hashes at function → file → module → root level, and compiling everything into a `mikk.lock.json` snapshot that every other package reads from.
+Foundation package for the Mikk ecosystem. All other packages depend on core — nothing in core depends on them.
 
-Every AI context query, impact analysis, contract validation, and diagram generation ultimately runs on the graph and lock file produced here.
-
-> Part of [Mikk](../../README.md) — the codebase nervous system for AI-assisted development.
+> Part of [Mikk](../../README.md) — live architectural context for your AI agent.
 
 ---
 
-## Installation
+## What is in core
 
-```bash
-npm install @getmikk/core
-# or
-bun add @getmikk/core
-```
-
----
-
-## Architecture Overview
-
-```
-Source Files (.ts/.tsx/.go)
-        │
-        ▼
-   ┌─────────┐
-   │  Parser  │  ← TypeScriptParser / GoParser
-   └────┬────┘
-        │  ParsedFile[]
-        ▼
-  ┌──────────────┐
-  │ GraphBuilder  │  ← Two-pass: nodes → edges
-  └──────┬───────┘
-         │  DependencyGraph
-         ▼
-  ┌────────────────┐
-  │ LockCompiler   │  ← Merkle-tree hashes
-  └───────┬────────┘
-          │  MikkLock
-          ▼
-  ┌─────────────────┐
-  │ ContractWriter   │  ← Permission model (never/ask/explicit)
-  └─────────────────┘
-```
+### Parsers
 
----
+Three language parsers, each following the same interface: `parse(filePath, content)` → `ParsedFile`.
 
-## Modules
+**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.
 
-### 1. Parser — Source Code Analysis
+**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.
 
-The parser module turns raw TypeScript/TSX files into structured `ParsedFile` objects using the TypeScript Compiler API.
+**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.
 
-```typescript
-import { TypeScriptParser, getParser, parseFiles } from '@getmikk/core'
+### GraphBuilder
 
-// Parse a single file
-const parser = new TypeScriptParser()
-const parsed = parser.parse('/src/utils/math.ts', fileContent)
+Two-pass O(n) dependency graph construction:
+1. **Pass 1** — create all nodes (functions, files)
+2. **Pass 2** — wire all edges (import edges, call edges, containment edges)
 
-console.log(parsed.functions)  // ParsedFunction[] — name, params, returnType, startLine, endLine, calls[]
-console.log(parsed.classes)    // ParsedClass[] — name, methods[], properties[], decorators[]
-console.log(parsed.imports)    // ParsedImport[] — source, specifiers, isTypeOnly
-console.log(parsed.exports)    // ParsedExport[] — name, isDefault, isTypeOnly
-console.log(parsed.generics)   // ParsedGeneric[] — interfaces, types, const declarations
+Result: `DependencyGraph` with forward `outEdges` and reverse `inEdges` maps for O(1) lookups in both directions.
 
-// Factory — auto-selects parser by file extension
-const parser = getParser('component.tsx') // returns TypeScriptParser
+### ImpactAnalyzer
 
-// Batch parse with import resolution
-const files = await parseFiles(filePaths, projectRoot, readFileFn)
-// Returns ParsedFile[] with all import paths resolved to absolute paths
-```
+BFS backward walk from a set of changed nodes. Returns:
+- `changed` — directly modified nodes
+- `impacted` — all transitively affected upstream callers
+- `classified` — impacted nodes sorted into `critical | high | medium | low` by proximity
+- `depth` — max blast radius depth
+- `confidence` — `high | medium | low` based on analysis mode
 
-#### TypeScriptExtractor
+### ClusterDetector
 
-The extractor walks the TypeScript AST and pulls out detailed metadata:
+Groups files into logical modules via greedy agglomeration. Produces clusters with a `confidence` score (0–1). Used by `mikk init` to auto-generate `mikk.json` from an unknown codebase.
 
-- **Functions**: name, parameters (with types & defaults), return type, line range, internal calls, `async`/generator flags, decorators, type parameters
-- **Classes**: name, methods (with full function metadata), properties, decorators, `extends`/`implements`, type parameters
-- **Generics**: interfaces, type aliases, const declarations, enums
-- **Imports**: named, default, namespace, type-only imports
-- **Exports**: named, default, re-exports
+### BoundaryChecker
 
-#### TypeScriptResolver
+Runs all declared constraint rules against the lock file. For each violation, returns: the source function, target function, which rule was violated, and severity. Used live by `mikk_before_edit` and `mikk ci`.
 
-Resolves import paths against the actual project filesystem:
+**Constraint types:**
+- `no-import` — module A must not import from module B
+- `must-use` — module A must use dependency B
+- `no-call` — specific functions must not call specific targets
+- `layer` — layered architecture enforcement (can only import from lower-numbered layers)
+- `naming` — function or file naming pattern via regex
+- `max-files` — maximum file count per module
 
-```typescript
-import { TypeScriptResolver } from '@getmikk/core'
+### Merkle Hashing
 
-const resolver = new TypeScriptResolver()
-// Resolves: relative paths, path aliases (tsconfig paths), index files, extension inference (.ts/.tsx/.js)
-const resolved = resolver.resolve(importDecl, fromFilePath, allProjectFiles)
+SHA-256 at every level:
 ```
-
-#### Go Parser
-
-Parses `.go` files without requiring the Go toolchain:
-
-```typescript
-import { GoParser } from '@getmikk/core'
-
-const parser = new GoParser()
-const parsed = parser.parse('service.go', fileContent)
-
-console.log(parsed.functions)  // ParsedFunction[] — name, params with types, return type, calls[]
-console.log(parsed.classes)    // ParsedClass[] — receiver-based methods grouped by type name
-console.log(parsed.imports)    // ParsedImport[] — resolved against go.mod module path
-console.log(parsed.exports)    // ParsedExport[] — uppercase identifiers (Go convention)
-console.log(parsed.routes)     // ParsedRoute[] — Gin, Echo, Chi, Mux, net/http routes
+function hash → file hash → module hash → root hash
 ```
 
-**Features**:
-- Stateful line/character scanning (handles strings, comments, nested braces correctly)
-- Receiver methods grouped with struct types as classes
-- HTTP route detection (Gin/Echo/Chi/Mux/net.http/Fiber patterns)
-- Error handling detection (`if err != nil` patterns)
-- Function call extraction from bodies
-- Grouped parameter expansion (`first, last string` → both typed as `string`)
-- Import resolution via `go.mod` module path
+One root hash comparison = instant full drift detection. Persisted in SQLite with WAL mode for zero-contention concurrent reads.
 
-#### Auto-detection by file extension
+### LockCompiler
 
-```typescript
-const parser = getParser('file.ts')    // → TypeScriptParser
-const parser = getParser('service.go') // → GoParser
-```
-
----
+Compiles a `DependencyGraph` + `MikkContract` + parsed files into a `MikkLock`. The lock file is the single source of truth for all MCP tools and CLI commands.
 
-### 2. Graph — Dependency Graph Construction
+Lock format v1.7.0:
+- Integer-based function index (`fnIndex`) — call graph edges stored as integer references, not repeated strings
+- Compact JSON output — no pretty-printing
+- Backward-compatible hydration for older formats
 
-The graph module builds a complete dependency graph from parsed files.
+### ContractReader / ContractWriter / LockReader
 
-```typescript
-import { GraphBuilder, ImpactAnalyzer, ClusterDetector } from '@getmikk/core'
-
-// Build the graph
-const builder = new GraphBuilder()
-const graph = builder.build(parsedFiles)
-
-console.log(graph.nodes)     // Map<string, GraphNode> — file, function, class, generic nodes
-console.log(graph.edges)     // GraphEdge[] — import, call, containment, implements edges
-console.log(graph.adjacency) // Map<string, string[]> — forward adjacency
-console.log(graph.reverse)   // Map<string, string[]> — reverse adjacency
-```
+Read and write `mikk.json` and `mikk.lock.json`. `LockReader.write()` uses atomic temp-file + rename to prevent corruption.
 
-#### GraphBuilder
+### AdrManager
 
-Two-pass construction:
-1. **Pass 1 — Nodes**: Creates nodes for every file, function, class, and generic declaration
-2. **Pass 2 — Edges**: Creates edges for imports, function calls, class containment, and cross-file references
+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.
 
-Node types: `file`, `function`, `class`, `generic`  
-Edge types: `import`, `call`, `containment`, `implements`
+### DeadCodeDetector
 
-#### ImpactAnalyzer
+Identifies functions with zero callers after exempting: exported functions, entry points, detected route handlers, test functions, and constructors. Returns per-module breakdown.
 
-BFS backward walk to find everything affected by a change:
-
-```typescript
-const analyzer = new ImpactAnalyzer(graph)
-const impact = analyzer.analyze(['src/utils/math.ts::calculateTotal'])
-
-console.log(impact.changed)    // string[] — directly changed node IDs
-console.log(impact.impacted)   // string[] — transitively affected nodes
-console.log(impact.depth)      // number — max propagation depth
-console.log(impact.confidence) // 'high' | 'medium' | 'low'
-console.log(impact.classified) // { critical: [], high: [], medium: [], low: [] }
-```
-
-#### ClusterDetector
-
-Greedy agglomeration algorithm for automatic module discovery:
-
-```typescript
-const detector = new ClusterDetector(graph, /* minClusterSize */ 3, /* minCouplingScore */ 0.1)
-const clusters = detector.detect()
-
-// Returns ModuleCluster[] with:
-// - id, label (auto-generated from common paths)
-// - nodeIds[] — functions/classes in this cluster
-// - cohesion — internal coupling score (0-1)
-// - coupling — Map<clusterId, score> — external coupling
-```
+### Route Detection
 
-The algorithm starts with one cluster per file, then iteratively merges the pair with the highest coupling score until no pair exceeds the threshold.
+Detects HTTP route definitions in Express, Koa, and Hono patterns. Extracts: HTTP method, path string, handler function reference, middleware chain, file, and line number.
 
 ---
 
-### 3. Contract — mikk.json & mikk.lock.json
-
-The contract module manages the two core Mikk files using Zod validation.
-
-#### Schemas
-
-All schemas are exported as Zod objects for runtime validation:
+## Key Types
 
 ```typescript
-import {
-  MikkContractSchema,   // mikk.json validation
-  MikkLockSchema,       // mikk.lock.json validation
-  MikkModuleSchema,     // Module definition
-  MikkDecisionSchema,   // Architecture decision record
-} from '@getmikk/core'
-
-// Validate a contract
-const result = MikkContractSchema.safeParse(rawJson)
-if (!result.success) console.error(result.error.issues)
-```
-
-#### mikk.json (Contract)
-
-Defines the project's architectural rules:
-
-```typescript
-type MikkContract = {
-  name: string
-  version: string
-  modules: Record<string, MikkModule>  // Module definitions with intent, public API, constraints
-  decisions: MikkDecision[]            // Architecture Decision Records (ADRs)
-  overwrite: {
-    permission: 'never' | 'ask' | 'explicit'
-    lastOverwrittenBy?: string
-    lastOverwrittenAt?: string
-  }
-}
-```
-
-#### mikk.lock.json (Lock File)
-
-Auto-generated snapshot of the entire codebase:
-
-```typescript
-type MikkLock = {
-  generatorVersion: string
-  generatedAt: string
-  rootHash: string                    // Merkle root of entire project
-  modules: Record<string, MikkLockModule>
-}
-
-type MikkLockModule = {
-  hash: string                        // Merkle hash of all files in module
-  files: Record<string, MikkLockFile>
-}
-
-type MikkLockFile = {
+interface ParsedFile {
+  path: string
   hash: string
-  functions: Record<string, MikkLockFunction>
-  classes: Record<string, MikkLockClass>
-  generics: Record<string, MikkLockGeneric>
+  language: string
+  functions: ParsedFunction[]
+  imports: ParsedImport[]
+  exports: ParsedExport[]
+  classes: ParsedClass[]
+  routes: ParsedRoute[]
 }
-```
-
-#### ContractReader / LockReader
-
-```typescript
-import { ContractReader, LockReader } from '@getmikk/core'
-
-const contractReader = new ContractReader()
-const contract = await contractReader.read('./mikk.json')
-
-const lockReader = new LockReader()
-const lock = await lockReader.read('./mikk.lock.json')
-await lockReader.write(updatedLock, './mikk.lock.json')
-```
-
-#### ContractWriter — Permission Model
-
-```typescript
-import { ContractWriter } from '@getmikk/core'
-
-const writer = new ContractWriter()
-
-// First-time write
-await writer.writeNew(contract, './mikk.json')
-
-// Update with permission model
-const result = await writer.update(existingContract, updates, './mikk.json')
-// result.updated — boolean
-// result.requiresConfirmation — true if permission is 'ask'
-// result.proposedChanges — diff object when confirmation needed
-```
-
-Permission levels:
-- **`never`** — Contract is read-only, updates are rejected
-- **`ask`** — Returns `requiresConfirmation: true` with proposed changes
-- **`explicit`** — Auto-applies updates with audit trail
 
-#### LockCompiler
-
-Compiles the full lock file from graph + contract + parsed files:
-
-```typescript
-import { LockCompiler } from '@getmikk/core'
-
-const compiler = new LockCompiler()
-const lock = compiler.compile(graph, contract, parsedFiles)
-// Computes Merkle-tree hashes at every level:
-// function → file → module → root
-```
-
-#### ContractGenerator
-
-Auto-generates a `mikk.json` skeleton from detected clusters:
-
-```typescript
-import { ContractGenerator } from '@getmikk/core'
-
-const generator = new ContractGenerator()
-const contract = generator.generateFromClusters(clusters, parsedFiles, 'my-project')
-```
-
-#### BoundaryChecker
-
-CI-ready enforcement layer:
-
-```typescript
-import { BoundaryChecker } from '@getmikk/core'
-
-const checker = new BoundaryChecker(contract, lock)
-const result = checker.check()
-
-if (!result.pass) {
-  for (const v of result.violations) {
-    console.error(`${v.severity}: ${v.message}`)
-    // severity: 'error' | 'warning'
-    // type: 'boundary-crossing' | 'constraint-violation'
-  }
-  process.exit(1)
+interface DependencyGraph {
+  nodes: Map<string, GraphNode>
+  edges: GraphEdge[]
+  outEdges: Map<string, GraphEdge[]>
+  inEdges: Map<string, GraphEdge[]>
 }
-```
-
----
-
-### 4. Hash — Merkle-Tree Integrity
-
-```typescript
-import { hashContent, hashFile, hashFunctionBody, computeModuleHash, computeRootHash } from '@getmikk/core'
-
-// Hash raw content (SHA-256)
-const h1 = hashContent('function foo() {}')
-
-// Hash a file from disk
-const h2 = await hashFile('/src/index.ts')
-
-// Hash a specific line range (function body)
-const h3 = hashFunctionBody(fileContent, 10, 25)
-
-// Merkle tree
-const moduleHash = computeModuleHash(['fileHash1', 'fileHash2'])
-const rootHash = computeRootHash(['moduleHash1', 'moduleHash2'])
-```
-
-#### HashStore — SQLite Persistence
-
-```typescript
-import { HashStore } from '@getmikk/core'
-
-const store = new HashStore('/project/.mikk/hashes.db')
-
-store.set('src/index.ts', 'abc123...', 4096)
-const entry = store.get('src/index.ts')
-// { path, hash, size, updatedAt }
-
-const changed = store.getChangedSince(Date.now() - 60_000)
-store.delete('src/old-file.ts')
-
-// Batch operations use SQLite transactions for performance
-const allPaths = store.getAllPaths()
-```
 
-Uses SQLite in WAL mode for concurrent read access and fast writes.
-
----
-
-### 5. Utilities
-
-#### Error Hierarchy
-
-```typescript
-import {
-  MikkError,                  // Base error class
-  ParseError,                 // File parsing failures
-  ContractNotFoundError,      // mikk.json not found
-  LockNotFoundError,          // mikk.lock.json not found
-  UnsupportedLanguageError,   // Unsupported file extension
-  OverwritePermissionError,   // Contract overwrite denied
-  SyncStateError,             // Lock file out of sync
-} from '@getmikk/core'
-```
-
-#### Logging
-
-```typescript
-import { logger, setLogLevel } from '@getmikk/core'
-
-setLogLevel('debug') // 'debug' | 'info' | 'warn' | 'error' | 'silent'
-
-logger.info('Analysis complete', { files: 42, duration: '1.2s' })
-// Outputs structured JSON to stderr
-```
-
-#### File Utilities
-
-```typescript
-import { discoverFiles, readFileContent, writeFileContent, fileExists, setupMikkDirectory } from '@getmikk/core'
-
-// Discover TypeScript files
-const files = await discoverFiles('/project', ['src/**/*.ts'], ['node_modules'])
-
-// Read/write
-const content = await readFileContent('/src/index.ts')
-await writeFileContent('/output/result.json', jsonString) // auto-creates directories
-
-// Initialize .mikk/ directory structure
-await setupMikkDirectory('/project')
-```
-
-#### Fuzzy Matching
-
-```typescript
-import { scoreFunctions, findFuzzyMatches, levenshtein } from '@getmikk/core'
-
-// Score lock file functions against a natural-language prompt
-const matches = scoreFunctions('calculate the total price', lock, 10)
-// Returns FuzzyMatch[] sorted by relevance score
-
-// "Did you mean?" suggestions
-const suggestions = findFuzzyMatches('calcualteTotal', lock, 5)
-// Returns closest function names by Levenshtein distance
-
-// Raw edit distance
-const dist = levenshtein('kitten', 'sitting') // 3
+interface MikkLock {
+  version: string
+  lockDate: string
+  project: { name: string; language: string }
+  fnIndex: string[]          // all function IDs — edges reference by integer index
+  functions: Record<string, LockFunction>
+  files: Record<string, LockFile>
+  routes: LockRoute[]
+  syncState: { status: string; lastUpdated: number }
+}
 ```
 
 ---
 
-## Types
+## Test Coverage
 
-All types are exported and can be imported directly:
+196 tests across: TypeScript parser, JavaScript parser, Go parser, dependency graph, impact analysis, hash store, contract validation, dead code detection, fuzzy matching, filesystem utilities.
 
-```typescript
-import type {
-  // Parser
-  ParsedFile, ParsedFunction, ParsedClass, ParsedImport, ParsedExport, ParsedParam, ParsedGeneric,
-  // Graph
-  DependencyGraph, GraphNode, GraphEdge, ImpactResult, NodeType, EdgeType, ModuleCluster, ClassifiedImpact, RiskLevel,
-  // Contract
-  MikkContract, MikkLock, MikkModule, MikkDecision, MikkLockFunction, MikkLockModule, MikkLockFile,
-  // Boundary
-  BoundaryViolation, BoundaryCheckResult, ViolationSeverity,
-  // Writer
-  UpdateResult,
-} from '@getmikk/core'
+```bash
+bun test
 ```
-
----
-
-## License
-
-[Apache-2.0](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/core",
-    "version": "1.7.1",
+    "version": "1.8.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -24,6 +24,8 @@
         "@types/better-sqlite3": "^7.6.13",
         "better-sqlite3": "^12.6.2",
         "fast-glob": "^3.3.0",
+        "tree-sitter-wasms": "^0.1.13",
+        "web-tree-sitter": "0.20.8",
         "zod": "^3.22.0"
     },
     "devDependencies": {

package/src/contract/contract-reader.ts

@@ -3,7 +3,7 @@ import { MikkContractSchema, type MikkContract } from './schema.js'
 import { ContractNotFoundError } from '../utils/errors.js'
 
 /**
- * ContractReader — reads and validates mikk.json from disk.
+ * ContractReader -- reads and validates mikk.json from disk.
  */
 export class ContractReader {
     /** Read and validate mikk.json */
@@ -15,7 +15,7 @@ export class ContractReader {
             throw new ContractNotFoundError(contractPath)
         }
 
-        const json = JSON.parse(content)
+        const json = JSON.parse(content.replace(/^\uFEFF/, ''))
         const result = MikkContractSchema.safeParse(json)
 
         if (!result.success) {

package/src/contract/lock-compiler.ts

@@ -1,4 +1,4 @@
-import * as path from 'node:path'
+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'
@@ -10,22 +10,22 @@ import { minimatch } from '../utils/minimatch.js'
 
 const VERSION = '@getmikk/cli@1.2.1'
 
-// ─── Heuristic purpose inference ────────────────────────────────────
+//  Heuristic purpose inference 
 // When JSDoc is missing we derive a short purpose string from:
-//   1. camelCase / PascalCase function name → natural language
+//   1. camelCase / PascalCase function name -> natural language
 //   2. parameter names (context clue)
 //   3. return type (if present)
 //
 // Examples:
-//   "getUserProjectRole" + params:["userId","projectId"] → "Get user project role (userId, projectId)"
-//   "DashboardPage"      + returnType:"JSX.Element"       → "Dashboard page component"
-// ────────────────────────────────────────────────────────────────────
+//   "getUserProjectRole" + params:["userId","projectId"] -> "Get user project role (userId, projectId)"
+//   "DashboardPage"      + returnType:"JSX.Element"       -> "Dashboard page component"
+// 
 
 /** Split camelCase/PascalCase identifier into lowercase words */
 function splitIdentifier(name: string): string[] {
     return name
         .replace(/([a-z0-9])([A-Z])/g, '$1 $2')  // camelCase boundary
-        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ABCDef → ABC Def
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ABCDef -> ABC Def
         .split(/[\s_-]+/)
         .map(w => w.toLowerCase())
         .filter(Boolean)
@@ -85,11 +85,11 @@ function inferPurpose(
         const subject = words.slice(1).join(' ')
         base = `Check ${firstWord === 'is' || firstWord === 'has' || firstWord === 'can' ? 'if' : ''} ${subject}`.replace(/  +/g, ' ')
     } else {
-        // Generic — just humanise the name
+        // Generic  just humanise the name
         base = capitalise(words.join(' '))
     }
 
-    // Append param hint if ≤3 params and they have meaningful names
+    // Append param hint if <=3 params and they have meaningful names
     if (params && params.length > 0 && params.length <= 3) {
         const meaningful = params
             .map(p => p.name)
@@ -107,16 +107,17 @@ function capitalise(s: string): string {
 }
 
 /**
- * LockCompiler — takes a DependencyGraph and a MikkContract
+ * 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 */
+    /** Main entry -- compile full lock from graph + contract + parsed files */
     compile(
         graph: DependencyGraph,
         contract: MikkContract,
         parsedFiles: ParsedFile[],
-        contextFiles?: ContextFile[]
+        contextFiles?: ContextFile[],
+        projectRoot?: string
     ): MikkLock {
         const functions = this.compileFunctions(graph, contract)
         const classes = this.compileClasses(graph, contract)
@@ -134,7 +135,7 @@ export class LockCompiler {
             version: '1.7.0',
             generatedAt: new Date().toISOString(),
             generatorVersion: VERSION,
-            projectRoot: contract.project.name,
+            projectRoot: projectRoot ?? contract.project.name,
             syncState: {
                 status: 'clean',
                 lastSyncAt: new Date().toISOString(),
@@ -244,7 +245,7 @@ export class LockCompiler {
         const raw: Record<string, any> = {}
         for (const [id, node] of graph.nodes) {
             if (node.type !== 'generic') continue
-            // Only include exported generics — non-exported types/interfaces are
+            // Only include exported generics  non-exported types/interfaces are
             // internal implementation details that add noise without value.
             if (!node.metadata.isExported) continue
             const moduleId = this.findModule(node.file, contract.declared.modules)