@getmikk/watcher 1.2.0

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "@getmikk/watcher",
+    "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": {
+        "@getmikk/core": "workspace:*",
+        "chokidar": "^4.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.0",
+        "@types/node": "^22.0.0"
+    }
+}

package/src/daemon.ts

@@ -0,0 +1,232 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs/promises'
+import {
+    GraphBuilder, LockCompiler, LockReader, ContractReader,
+    parseFiles, readFileContent, discoverFiles, logger,
+    type DependencyGraph, type MikkLock, type MikkContract
+} from '@getmikk/core'
+import { FileWatcher } from './file-watcher.js'
+import { IncrementalAnalyzer } from './incremental-analyzer.js'
+import type { WatcherConfig, WatcherEvent, FileChangeEvent } from './types.js'
+
+/** Sync state persisted to .mikk/sync-state.json */
+interface SyncState {
+    status: 'clean' | 'syncing' | 'drifted' | 'conflict'
+    lastUpdated: number
+    filesInFlight?: number
+    rootHash?: string
+    error?: string
+}
+
+/**
+ * WatcherDaemon — long-running background process.
+ * Starts the FileWatcher, handles the IncrementalAnalyzer,
+ * writes updates to the lock file, and manages sync state.
+ *
+ * Features:
+ * - Debounces file changes (100ms window)
+ * - Batch threshold: if > 15 files in a batch, runs full analysis
+ * - PID file for single-instance enforcement
+ * - Atomic sync state writes
+ */
+export class WatcherDaemon {
+    private watcher: FileWatcher
+    private analyzer: IncrementalAnalyzer | null = null
+    private lock: MikkLock | null = null
+    private contract: MikkContract | null = null
+    private handlers: ((event: WatcherEvent) => void)[] = []
+    private pendingEvents: FileChangeEvent[] = []
+    private debounceTimer: ReturnType<typeof setTimeout> | null = null
+    private processing = false
+
+    constructor(private config: WatcherConfig) {
+        this.watcher = new FileWatcher(config)
+    }
+
+    async start(): Promise<void> {
+        // Write PID file for single-instance enforcement
+        await this.writePidFile()
+
+        // Load existing contract and lock
+        const contractReader = new ContractReader()
+        const lockReader = new LockReader()
+        const contractPath = path.join(this.config.projectRoot, 'mikk.json')
+        const lockPath = path.join(this.config.projectRoot, 'mikk.lock.json')
+
+        this.contract = await contractReader.read(contractPath)
+        this.lock = await lockReader.read(lockPath)
+
+        // Parse all files to populate the analyzer
+        const filePaths = await discoverFiles(this.config.projectRoot)
+        const parsedFiles = await parseFiles(filePaths, this.config.projectRoot, (fp) =>
+            readFileContent(fp)
+        )
+        const graph = new GraphBuilder().build(parsedFiles)
+
+        this.analyzer = new IncrementalAnalyzer(graph, this.lock, this.contract, this.config.projectRoot)
+
+        // Add all parsed files to the analyzer
+        for (const file of parsedFiles) {
+            this.analyzer.addParsedFile(file)
+        }
+
+        // Subscribe to file changes with debouncing
+        this.watcher.on(async (event: WatcherEvent) => {
+            if (event.type === 'file:changed') {
+                this.enqueueChange(event.data)
+            }
+            // Forward events to external handlers
+            for (const handler of this.handlers) {
+                handler(event)
+            }
+        })
+
+        this.watcher.start()
+        await this.writeSyncState({ status: 'clean', lastUpdated: Date.now() })
+        logger.info('Mikk watcher started', { watching: this.config.include })
+    }
+
+    async stop(): Promise<void> {
+        await this.watcher.stop()
+        if (this.debounceTimer) clearTimeout(this.debounceTimer)
+        await this.removePidFile()
+        logger.info('Mikk watcher stopped')
+    }
+
+    on(handler: (event: WatcherEvent) => void): void {
+        this.handlers.push(handler)
+    }
+
+    // ─── Debounce & Batch Processing ──────────────────────────────
+
+    private enqueueChange(event: FileChangeEvent): void {
+        this.pendingEvents.push(event)
+
+        // Reset the debounce timer
+        if (this.debounceTimer) clearTimeout(this.debounceTimer)
+        this.debounceTimer = setTimeout(() => {
+            this.flushPendingEvents()
+        }, this.config.debounceMs || 100)
+    }
+
+    private async flushPendingEvents(): Promise<void> {
+        if (this.processing || this.pendingEvents.length === 0) return
+        this.processing = true
+
+        const events = [...this.pendingEvents]
+        this.pendingEvents = []
+
+        // Deduplicate by path (keep latest event per file)
+        const byPath = new Map<string, FileChangeEvent>()
+        for (const event of events) {
+            byPath.set(event.path, event)
+        }
+        const dedupedEvents = [...byPath.values()]
+
+        await this.writeSyncState({
+            status: 'syncing',
+            lastUpdated: Date.now(),
+            filesInFlight: dedupedEvents.length,
+        })
+
+        try {
+            await this.processBatch(dedupedEvents)
+            await this.writeSyncState({
+                status: 'clean',
+                lastUpdated: Date.now(),
+            })
+        } catch (err: any) {
+            await this.writeSyncState({
+                status: 'drifted',
+                lastUpdated: Date.now(),
+                error: err.message,
+            })
+        } finally {
+            this.processing = false
+
+            // If more events arrived during processing, flush again
+            if (this.pendingEvents.length > 0) {
+                this.flushPendingEvents()
+            }
+        }
+    }
+
+    private async processBatch(events: FileChangeEvent[]): Promise<void> {
+        if (!this.analyzer || !this.lock) return
+
+        try {
+            const result = await this.analyzer.analyzeBatch(events)
+            this.lock = result.lock
+
+            // Write updated lock
+            const lockPath = path.join(this.config.projectRoot, 'mikk.lock.json')
+            await fs.writeFile(lockPath, JSON.stringify(this.lock, null, 2), 'utf-8')
+
+            // Log batch info
+            if (result.mode === 'full') {
+                logger.info('Full re-analysis completed', {
+                    filesChanged: events.length,
+                    reason: 'Large batch detected (> 15 files)',
+                })
+            }
+
+            // Emit graph:updated event
+            for (const handler of this.handlers) {
+                handler({
+                    type: 'graph:updated',
+                    data: {
+                        changedNodes: result.impactResult.changed,
+                        impactedNodes: result.impactResult.impacted,
+                    },
+                })
+            }
+
+            logger.info('Lock file updated', {
+                filesChanged: events.length,
+                mode: result.mode,
+                impactedNodes: result.impactResult.impacted.length,
+            })
+        } catch (err: any) {
+            logger.error('Failed to analyze file changes', {
+                files: events.map(e => e.path),
+                error: err.message,
+            })
+            for (const handler of this.handlers) {
+                handler({
+                    type: 'sync:drifted',
+                    data: {
+                        reason: err.message,
+                        affectedModules: events.flatMap(e => e.affectedModuleIds),
+                    },
+                })
+            }
+            throw err
+        }
+    }
+
+    // ─── Sync State ───────────────────────────────────────────────
+
+    /** Write sync state atomically (write to temp, then rename) */
+    private async writeSyncState(state: SyncState): Promise<void> {
+        const mikkDir = path.join(this.config.projectRoot, '.mikk')
+        await fs.mkdir(mikkDir, { recursive: true })
+        const statePath = path.join(mikkDir, 'sync-state.json')
+        const tmpPath = statePath + '.tmp'
+        await fs.writeFile(tmpPath, JSON.stringify(state, null, 2), 'utf-8')
+        await fs.rename(tmpPath, statePath)
+    }
+
+    // ─── PID File ─────────────────────────────────────────────────
+
+    private async writePidFile(): Promise<void> {
+        const mikkDir = path.join(this.config.projectRoot, '.mikk')
+        await fs.mkdir(mikkDir, { recursive: true })
+        const pidPath = path.join(mikkDir, 'watcher.pid')
+        await fs.writeFile(pidPath, String(process.pid), 'utf-8')
+    }
+
+    private async removePidFile(): Promise<void> {
+        const pidPath = path.join(this.config.projectRoot, '.mikk', 'watcher.pid')
+        try { await fs.unlink(pidPath) } catch { /* ignore if missing */ }
+    }
+}

package/src/file-watcher.ts

@@ -0,0 +1,93 @@
+import * as path from 'node:path'
+import { watch } from 'chokidar'
+import { hashFile } from '@getmikk/core'
+import type { WatcherConfig, WatcherEvent, FileChangeEvent } from './types.js'
+
+/**
+ * FileWatcher — wraps Chokidar to watch filesystem for changes.
+ * Computes hash of changed files and emits typed events.
+ */
+export class FileWatcher {
+    private watcher: ReturnType<typeof watch> | null = null
+    private handlers: ((event: WatcherEvent) => void)[] = []
+    private hashStore = new Map<string, string>()
+
+    constructor(private config: WatcherConfig) { }
+
+    /** Start watching — non-blocking */
+    start(): void {
+        this.watcher = watch(this.config.include, {
+            ignored: this.config.exclude,
+            cwd: this.config.projectRoot,
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 50,
+                pollInterval: 10,
+            },
+        })
+
+        this.watcher.on('change', (relativePath: string) => {
+            this.handleChange(relativePath, 'changed')
+        })
+        this.watcher.on('add', (relativePath: string) => {
+            this.handleChange(relativePath, 'added')
+        })
+        this.watcher.on('unlink', (relativePath: string) => {
+            this.handleChange(relativePath, 'deleted')
+        })
+    }
+
+    /** Stop watching */
+    async stop(): Promise<void> {
+        await this.watcher?.close()
+        this.watcher = null
+    }
+
+    /** Register an event handler */
+    on(handler: (event: WatcherEvent) => void): void {
+        this.handlers.push(handler)
+    }
+
+    /** Set initial hash for a file */
+    setHash(filePath: string, hash: string): void {
+        this.hashStore.set(filePath, hash)
+    }
+
+    private async handleChange(relativePath: string, type: FileChangeEvent['type']): Promise<void> {
+        const fullPath = path.join(this.config.projectRoot, relativePath)
+        const normalizedPath = relativePath.replace(/\\/g, '/')
+        const oldHash = this.hashStore.get(normalizedPath) || null
+
+        let newHash: string | null = null
+        if (type !== 'deleted') {
+            try {
+                newHash = await hashFile(fullPath)
+            } catch {
+                return // File might have been deleted before we could read it
+            }
+        }
+
+        if (oldHash === newHash) return // Content unchanged
+
+        if (newHash) this.hashStore.set(normalizedPath, newHash)
+        if (type === 'deleted') this.hashStore.delete(normalizedPath)
+
+        const event: FileChangeEvent = {
+            type,
+            path: normalizedPath,
+            oldHash,
+            newHash,
+            timestamp: Date.now(),
+            affectedModuleIds: [], // filled by IncrementalAnalyzer
+        }
+
+        this.emit({ type: 'file:changed', data: event })
+    }
+
+    private emit(event: WatcherEvent): void {
+        for (const handler of this.handlers) {
+            handler(event)
+        }
+    }
+}

package/src/incremental-analyzer.ts

@@ -0,0 +1,192 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import {
+    getParser, GraphBuilder, ImpactAnalyzer, LockCompiler, hashFile,
+    type ParsedFile, type DependencyGraph, type MikkLock, type MikkContract, type ImpactResult
+} from '@getmikk/core'
+import type { FileChangeEvent } from './types.js'
+
+/** Threshold: if batch size exceeds this, run full re-analysis */
+const FULL_ANALYSIS_THRESHOLD = 15
+
+/** Max retries for race-condition re-hash check */
+const MAX_RETRIES = 3
+
+/**
+ * IncrementalAnalyzer — re-parses only changed files, updates graph nodes,
+ * and recomputes affected module hashes. O(changed files) not O(whole repo).
+ *
+ * Supports batch analysis: if > 15 files change at once (e.g. git checkout),
+ * runs a full re-analysis instead of incremental.
+ *
+ * Race condition handling: after parsing, re-hashes the file and re-parses
+ * if the content changed during parsing (up to 3 retries).
+ */
+export class IncrementalAnalyzer {
+    private parsedFiles: Map<string, ParsedFile> = new Map()
+
+    constructor(
+        private graph: DependencyGraph,
+        private lock: MikkLock,
+        private contract: MikkContract,
+        private projectRoot: string
+    ) { }
+
+    /** Handle a batch of file change events (debounced by daemon) */
+    async analyzeBatch(events: FileChangeEvent[]): Promise<{
+        graph: DependencyGraph
+        lock: MikkLock
+        impactResult: ImpactResult
+        mode: 'incremental' | 'full'
+    }> {
+        // If too many changes at once, run full analysis
+        if (events.length > FULL_ANALYSIS_THRESHOLD) {
+            return this.runFullAnalysis(events)
+        }
+
+        // Incremental: process each event
+        let combinedChanged: string[] = []
+        let combinedImpacted: string[] = []
+
+        for (const event of events) {
+            if (event.type === 'deleted') {
+                this.parsedFiles.delete(event.path)
+                combinedChanged.push(event.path)
+            } else {
+                const parsed = await this.parseWithRaceCheck(event.path)
+                if (parsed) {
+                    this.parsedFiles.set(event.path, parsed)
+                }
+                combinedChanged.push(...this.findAffectedNodes(event.path))
+            }
+        }
+
+        // Rebuild graph from all parsed files
+        const allParsedFiles = [...this.parsedFiles.values()]
+        const builder = new GraphBuilder()
+        this.graph = builder.build(allParsedFiles)
+
+        // Run impact analysis on all changed nodes
+        const analyzer = new ImpactAnalyzer(this.graph)
+        const impactResult = analyzer.analyze([...new Set(combinedChanged)])
+
+        // Recompile lock
+        const compiler = new LockCompiler()
+        this.lock = compiler.compile(this.graph, this.contract, allParsedFiles)
+
+        return { graph: this.graph, lock: this.lock, impactResult, mode: 'incremental' }
+    }
+
+    /** Handle a single file change event */
+    async analyze(event: FileChangeEvent): Promise<{
+        graph: DependencyGraph
+        lock: MikkLock
+        impactResult: ImpactResult
+    }> {
+        const result = await this.analyzeBatch([event])
+        return { graph: result.graph, lock: result.lock, impactResult: result.impactResult }
+    }
+
+    /** Add a parsed file to the tracker */
+    addParsedFile(file: ParsedFile): void {
+        this.parsedFiles.set(file.path, file)
+    }
+
+    /** Get the current parsed file count */
+    get fileCount(): number {
+        return this.parsedFiles.size
+    }
+
+    // ─── Private ──────────────────────────────────────────────────
+
+    /**
+     * Parse a file with race-condition detection.
+     * After parsing, re-hash the file. If the hash differs from what we started with,
+     * the file changed during parsing — re-parse (up to MAX_RETRIES).
+     */
+    private async parseWithRaceCheck(changedFile: string): Promise<ParsedFile | null> {
+        const fullPath = path.join(this.projectRoot, changedFile)
+
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                const content = await fs.readFile(fullPath, 'utf-8')
+                const parser = getParser(changedFile)
+                const parsedFile = parser.parse(changedFile, content)
+
+                // Race condition check: re-hash after parse
+                try {
+                    const postParseHash = await hashFile(fullPath)
+                    if (postParseHash === parsedFile.hash) {
+                        return parsedFile // Content stable
+                    }
+                    // Content changed during parse — retry
+                } catch {
+                    return parsedFile // File may have been deleted, return what we have
+                }
+            } catch {
+                return null // File unreadable
+            }
+        }
+
+        // Exhausted retries — parse one final time and accept
+        try {
+            const content = await fs.readFile(fullPath, 'utf-8')
+            const parser = getParser(changedFile)
+            return parser.parse(changedFile, content)
+        } catch {
+            return null
+        }
+    }
+
+    /** Run a full re-analysis (for large batches like git checkout) */
+    private async runFullAnalysis(events: FileChangeEvent[]): Promise<{
+        graph: DependencyGraph
+        lock: MikkLock
+        impactResult: ImpactResult
+        mode: 'full'
+    }> {
+        // Remove deleted files
+        for (const event of events) {
+            if (event.type === 'deleted') {
+                this.parsedFiles.delete(event.path)
+            }
+        }
+
+        // Re-parse all non-deleted changed files
+        const nonDeleted = events.filter(e => e.type !== 'deleted')
+        await Promise.all(nonDeleted.map(async (event) => {
+            const parsed = await this.parseWithRaceCheck(event.path)
+            if (parsed) {
+                this.parsedFiles.set(event.path, parsed)
+            }
+        }))
+
+        // Full rebuild
+        const allParsedFiles = [...this.parsedFiles.values()]
+        const builder = new GraphBuilder()
+        this.graph = builder.build(allParsedFiles)
+
+        const compiler = new LockCompiler()
+        this.lock = compiler.compile(this.graph, this.contract, allParsedFiles)
+
+        const changedPaths = events.map(e => e.path)
+
+        return {
+            graph: this.graph,
+            lock: this.lock,
+            impactResult: {
+                changed: changedPaths,
+                impacted: [],
+                depth: 0,
+                confidence: 'low', // Full rebuild = can't determine precise impact
+            },
+            mode: 'full',
+        }
+    }
+
+    private findAffectedNodes(filePath: string): string[] {
+        return [...this.graph.nodes.values()]
+            .filter(n => n.file === filePath)
+            .map(n => n.id)
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { FileWatcher } from './file-watcher.js'
+export { IncrementalAnalyzer } from './incremental-analyzer.js'
+export { WatcherDaemon } from './daemon.js'
+export type { FileChangeEvent, WatcherConfig, WatcherEvent } from './types.js'

package/src/types.ts

@@ -0,0 +1,25 @@
+/** File change event emitted when a source file is added, changed, or deleted */
+export interface FileChangeEvent {
+    type: 'added' | 'changed' | 'deleted'
+    path: string
+    oldHash: string | null
+    newHash: string | null
+    timestamp: number
+    affectedModuleIds: string[]
+}
+
+/** Configuration for the watcher */
+export interface WatcherConfig {
+    projectRoot: string
+    include: string[]    // ["src/**/*.ts"]
+    exclude: string[]    // ["node_modules", ".mikk", "dist"]
+    debounceMs: number   // 100
+}
+
+/** Typed watcher events */
+export type WatcherEvent =
+    | { type: 'file:changed'; data: FileChangeEvent }
+    | { type: 'module:updated'; data: { moduleId: string; newHash: string } }
+    | { type: 'graph:updated'; data: { changedNodes: string[]; impactedNodes: string[] } }
+    | { type: 'sync:clean'; data: { rootHash: string } }
+    | { type: 'sync:drifted'; data: { reason: string; affectedModules: string[] } }

package/tests/smoke.test.ts

@@ -0,0 +1,5 @@
+import { expect, test } from "bun:test";
+
+test("smoke test - watcher", () => {
+    expect(true).toBe(true);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src"
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "tests"
+    ]
+}