@getmikk/watcher 1.7.0 → 1.8.0

package/README.md

@@ -1,217 +1,92 @@
-# @getmikk/watcher
+# @getmikk/watcher
 
-> Your architecture map, always in sync — zero manual re-analysis.
+> Live file watcher daemon — incremental, debounced, atomic.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/watcher)](https://www.npmjs.com/package/@getmikk/watcher)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-`@getmikk/watcher` keeps `mikk.lock.json` in sync with your source code in real time. It uses Chokidar to watch for file events, batches and debounces changes (so saving 20 files triggers one re-analysis, not twenty), incrementally re-parses only affected files, patches the dependency graph, recomputes Merkle hashes, and writes the lock file atomically — all with a PID-based singleton that prevents duplicate daemon processes.
+Background daemon that keeps `mikk.lock.json` in sync as you edit code. Detects file changes via chokidar, re-parses only what changed, updates the lock atomically, and emits typed events for downstream consumers.
 
-The result: your AI context, impact analysis, and contract validation are always based on the current state of your codebase, not a stale snapshot.
-
-> 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
+## Usage
+
+Started via the CLI:
 
 ```bash
-npm install @getmikk/watcher
-# or
-bun add @getmikk/watcher
+mikk watch
 ```
 
-**Peer dependency:** `@getmikk/core`
-
----
-
-## Quick Start
+Or programmatically:
 
 ```typescript
 import { WatcherDaemon } from '@getmikk/watcher'
 
 const daemon = new WatcherDaemon({
-  projectRoot: process.cwd(),
-  include: ['src/**/*.ts', 'src/**/*.tsx'],
-  exclude: ['node_modules', 'dist', '.mikk'],
+  projectRoot: '/path/to/project',
+  include: ['**/*.ts', '**/*.tsx'],
+  exclude: ['**/node_modules/**', '**/dist/**'],
   debounceMs: 100,
 })
 
 daemon.on((event) => {
-  switch (event.type) {
-    case 'file:changed':
-      console.log(`Changed: ${event.path}`)
-      break
-    case 'graph:updated':
-      console.log('Dependency graph rebuilt')
-      break
-    case 'sync:clean':
-      console.log('Lock file is in sync')
-      break
-    case 'sync:drifted':
-      console.log('Lock file has drifted')
-      break
+  if (event.type === 'graph:updated') {
+    console.log(`Graph updated: ${event.data.changedNodes.length} changed`)
   }
 })
 
 await daemon.start()
-// Lock file is now kept in sync automatically
-
-// Later...
-await daemon.stop()
-```
-
----
-
-## Architecture
-
-```
-Filesystem Events (Chokidar)
-        │
-        ▼
-  ┌─────────────┐
-  │ FileWatcher  │  ← Hash computation, deduplication
-  └──────┬──────┘
-         │  FileChangeEvent[]
-         ▼
-  ┌──────────────────┐
-  │ WatcherDaemon    │  ← Debouncing (100ms), batching
-  └──────┬───────────┘
-         │  Batch of events
-         ▼
-  ┌─────────────────────┐
-  │ IncrementalAnalyzer  │  ← Re-parse, graph patch, hash update
-  └──────────┬──────────┘
-             │
-             ▼
-    Atomic lock file write
 ```
 
 ---
 
-## API Reference
-
-### WatcherDaemon
-
-The main entry point — a long-running process that keeps the lock file in sync.
-
-```typescript
-import { WatcherDaemon } from '@getmikk/watcher'
-
-const daemon = new WatcherDaemon(config)
-```
-
-**`WatcherConfig`:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `projectRoot` | `string` | — | Absolute path to the project |
-| `include` | `string[]` | `['**/*.ts']` | Glob patterns for watched files |
-| `exclude` | `string[]` | `['node_modules']` | Glob patterns to ignore |
-| `debounceMs` | `number` | `100` | Debounce window in milliseconds |
-
-**Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `start()` | Start watching. Creates PID file at `.mikk/watcher.pid` for single-instance enforcement |
-| `stop()` | Stop watching. Cleans up PID file |
-| `on(handler)` | Register event handler |
-
-**Features:**
-
-- **Debouncing** — Batches rapid file changes (e.g., save-all) into a single analysis pass
-- **PID file** — Prevents multiple watcher instances via `.mikk/watcher.pid`
-- **Atomic writes** — Lock file is written atomically to prevent corruption
-- **Sync state** — Emits `sync:clean` or `sync:drifted` after each cycle
-
----
+## How It Works
 
 ### FileWatcher
 
-Lower-level wrapper around Chokidar with hash-based change detection:
+Wraps chokidar. Watches `.ts` and `.tsx` files (configurable). On change:
+1. Computes a SHA-256 hash of the new file content
+2. Compares against the stored hash — skips true no-ops (content unchanged)
+3. Emits a typed `FileChangeEvent` with old hash, new hash, and change type
 
-```typescript
-import { FileWatcher } from '@getmikk/watcher'
+Hash store is seeded at startup from the lock file so first-change dedup works correctly from the beginning.
 
-const watcher = new FileWatcher(config)
-
-watcher.on((event) => {
-  console.log(event.type)       // 'added' | 'changed' | 'deleted'
-  console.log(event.path)       // Absolute file path
-  console.log(event.oldHash)    // Previous content hash (undefined for 'added')
-  console.log(event.newHash)    // New content hash (undefined for 'deleted')
-  console.log(event.timestamp)  // Event timestamp
-  console.log(event.affectedModuleIds) // Modules containing this file
-})
-
-await watcher.start()
-
-// Seed with known hashes to detect only actual content changes
-watcher.setHash('/src/index.ts', 'abc123...')
-
-await watcher.stop()
-```
+### WatcherDaemon
 
-**Hash-based deduplication:** Even if the OS reports a file change, the watcher computes a SHA-256 hash and only emits an event if the content actually changed. This prevents redundant re-analysis from editor auto-saves or format-on-save.
+Orchestrates everything:
 
----
+- **Debounce** — collects file change events for 100ms, then flushes as a batch
+- **Deduplication** — if the same file changes twice in a batch, only the latest event is kept
+- **Batch threshold** — batches under 15 files → incremental analysis; 15+ files → full re-analysis
+- **Atomic writes** — lock file written as temp file then renamed; zero corruption risk on crash
+- **PID file** — `.mikk/watcher.pid` prevents duplicate daemon instances
+- **Sync state** — `.mikk/sync-state.json` tracks `clean | syncing | drifted | conflict`
 
 ### IncrementalAnalyzer
 
-Incrementally updates the dependency graph and lock file for a batch of changed files:
-
-```typescript
-import { IncrementalAnalyzer } from '@getmikk/watcher'
-
-const analyzer = new IncrementalAnalyzer(graph, lock, contract, projectRoot)
-
-const result = await analyzer.analyzeBatch(events)
-
-console.log(result.graph)        // Updated DependencyGraph
-console.log(result.lock)         // Updated MikkLock
-console.log(result.impactResult) // ImpactResult from @getmikk/core
-console.log(result.mode)         // 'incremental' | 'full'
-```
-
-**How it works:**
+Re-parses only changed files, updates graph nodes, and recompiles the lock. O(changed files), not O(whole repo).
 
-1. **Small batches (≤15 files)** → Incremental mode:
-   - Re-parse only changed files
-   - Patch the existing graph (remove old nodes/edges, add new ones)
-   - Recompute affected hashes only
-   - Run impact analysis on changed nodes
+**Race condition handling:** after parsing a file, re-hashes it. If the hash changed during the parse (file was modified while being read), re-parses up to 3 times. Accepts final state after retries are exhausted.
 
-2. **Large batches (>15 files)** → Full re-analysis:
-   - Re-parse all files from scratch
-   - Rebuild entire graph
-   - Recompute all hashes
-
-**Race-condition protection:** After parsing a file, the analyzer re-hashes it. If the hash changed during parsing (the file was modified again), it retries up to 3 times before falling back to the latest parsed version.
+**Full re-analysis path:** triggered when batch size exceeds 15 files (e.g. `git checkout`, bulk rename). Re-parses all changed files in parallel, rebuilds the full graph, recompiles the lock.
 
 ---
 
-### Events
-
-All events emitted through the `on()` handler:
+## Events
 
 ```typescript
 type WatcherEvent =
-  | { type: 'file:changed'; event: FileChangeEvent }
-  | { type: 'module:updated'; moduleId: string }
-  | { type: 'graph:updated'; stats: { nodes: number; edges: number } }
-  | { type: 'sync:clean' }
-  | { type: 'sync:drifted'; driftedModules: string[] }
-```
+  | { type: 'file:changed'; data: FileChangeEvent }
+  | { type: 'graph:updated'; data: { changedNodes: string[]; impactedNodes: string[] } }
+  | { type: 'sync:drifted'; data: { reason: string; affectedModules: string[] } }
 
-**`FileChangeEvent`:**
-
-```typescript
 type FileChangeEvent = {
-  type: 'added' | 'changed' | 'deleted'
-  path: string
-  oldHash?: string
-  newHash?: string
+  type: 'changed' | 'added' | 'deleted'
+  path: string         // relative to project root
+  oldHash: string | null
+  newHash: string | null
   timestamp: number
   affectedModuleIds: string[]
 }
@@ -219,51 +94,15 @@ type FileChangeEvent = {
 
 ---
 
-## Usage with the CLI
-
-The `mikk watch` command starts the watcher daemon:
-
-```bash
-mikk watch
-# Watching src/**/*.ts, src/**/*.tsx...
-# [sync:clean] Lock file is up to date
-# [file:changed] src/auth/login.ts
-# [graph:updated] 142 nodes, 87 edges
-# [sync:clean] Lock file updated
-```
-
-Press `Ctrl+C` to stop.
-
----
-
-## Single-Instance Enforcement
-
-The daemon writes a PID file to `.mikk/watcher.pid` on start and removes it on stop. If another watcher is already running, `start()` will throw an error. This prevents multiple watchers from fighting over the lock file.
-
-```typescript
-try {
-  await daemon.start()
-} catch (err) {
-  if (err.message.includes('already running')) {
-    console.log('Another watcher is already running')
-  }
-}
-```
-
----
-
-## Types
+## Sync State
 
-```typescript
-import type {
-  FileChangeEvent,
-  WatcherConfig,
-  WatcherEvent,
-} from '@getmikk/watcher'
-```
-
----
+Written atomically to `.mikk/sync-state.json` on every transition:
 
-## License
+| Status | Meaning |
+|--------|---------|
+| `clean` | Lock file matches filesystem |
+| `syncing` | Batch in progress |
+| `drifted` | Analysis failed — lock is stale |
+| `conflict` | Manual intervention needed |
 
-[Apache-2.0](../../LICENSE)
+The MCP server reads sync state to surface staleness warnings on every tool call.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/watcher",
-    "version": "1.7.0",
+    "version": "1.8.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -21,7 +21,7 @@
         "dev": "tsc --watch"
     },
     "dependencies": {
-        "@getmikk/core": "^1.7.0",
+        "@getmikk/core": "^1.8.0",
         "chokidar": "^4.0.0"
     },
     "devDependencies": {

package/src/daemon.ts

@@ -70,6 +70,16 @@ export class WatcherDaemon {
             this.analyzer.addParsedFile(file)
         }
 
+        // Seed the file watcher's hash store with initial hashes so the first
+        // change to any file can be properly deduplicated by content.
+        const initialHashes = new Map<string, string>()
+        for (const file of parsedFiles) {
+            if (file.hash) {
+                initialHashes.set(file.path.replace(/\\/g, '/'), file.hash)
+            }
+        }
+        this.watcher.seedHashes(initialHashes)
+
         // Subscribe to file changes with debouncing
         this.watcher.on(async (event: WatcherEvent) => {
             if (event.type === 'file:changed') {

package/src/file-watcher.ts

@@ -4,7 +4,7 @@ import { hashFile } from '@getmikk/core'
 import type { WatcherConfig, WatcherEvent, FileChangeEvent } from './types.js'
 
 /**
- * FileWatcher — wraps Chokidar to watch filesystem for changes.
+ * FileWatcher -- wraps Chokidar to watch filesystem for changes.
  * Computes hash of changed files and emits typed events.
  */
 export class FileWatcher {
@@ -14,27 +14,39 @@ export class FileWatcher {
 
     constructor(private config: WatcherConfig) { }
 
-    /** Start watching — non-blocking */
+    /** Start watching -- non-blocking */
     start(): void {
-        this.watcher = watch(this.config.include, {
-            ignored: this.config.exclude,
+        const excludesRegexes = this.config.exclude.map(
+            pattern => new RegExp(pattern.replace(/\*/g, '.*').replace(/\//g, '[\\\\/]'))
+        )
+        const includeExts = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.go']
+
+        this.watcher = watch(this.config.projectRoot, {
+            ignored: (testPath: string, stats?: import('fs').Stats) => {
+                // Ignore matching exclude patterns
+                if (excludesRegexes.some(r => r.test(testPath))) return true
+                // Keep directories so we can recurse
+                if (!stats || stats.isDirectory()) return false
+                // Ignore non-matching file extensions
+                return !includeExts.some(ext => testPath.endsWith(ext))
+            },
             cwd: this.config.projectRoot,
             ignoreInitial: true,
             persistent: true,
             awaitWriteFinish: {
-                stabilityThreshold: 50,
-                pollInterval: 10,
+                stabilityThreshold: 300,
+                pollInterval: 50,
             },
         })
 
-        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')
+        this.watcher.on('all', (event, relativePath) => {
+            if (event === 'change') {
+                this.handleChange(relativePath, 'changed')
+            } else if (event === 'add') {
+                this.handleChange(relativePath, 'added')
+            } else if (event === 'unlink') {
+                this.handleChange(relativePath, 'deleted')
+            }
         })
     }
 
@@ -49,11 +61,18 @@ export class FileWatcher {
         this.handlers.push(handler)
     }
 
-    /** Set initial hash for a file */
+    /** Seed the initial hash for a file (called at startup for all known files) */
     setHash(filePath: string, hash: string): void {
         this.hashStore.set(filePath, hash)
     }
 
+    /** Bulk-seed hashes for all known files so first-change dedup works correctly */
+    seedHashes(entries: ReadonlyMap<string, string>): void {
+        for (const [p, h] of entries) {
+            this.hashStore.set(p.replace(/\\/g, '/'), h)
+        }
+    }
+
     private async handleChange(relativePath: string, type: FileChangeEvent['type']): Promise<void> {
         const fullPath = path.join(this.config.projectRoot, relativePath)
         const normalizedPath = relativePath.replace(/\\/g, '/')
@@ -68,7 +87,8 @@ export class FileWatcher {
             }
         }
 
-        if (oldHash === newHash) return // Content unchanged
+        // Skip only when both hashes are known and identical (true no-op change)
+        if (oldHash !== null && newHash !== null && oldHash === newHash) return
 
         if (newHash) this.hashStore.set(normalizedPath, newHash)
         if (type === 'deleted') this.hashStore.delete(normalizedPath)

package/src/incremental-analyzer.ts

@@ -44,31 +44,36 @@ export class IncrementalAnalyzer {
             return this.runFullAnalysis(events)
         }
 
-        // Incremental: process each event
-        let combinedChanged: string[] = []
-        let combinedImpacted: string[] = []
+        // Incremental: process each event, collecting changed file paths
+        const changedFilePaths: string[] = []
 
         for (const event of events) {
             if (event.type === 'deleted') {
                 this.parsedFiles.delete(event.path)
-                combinedChanged.push(event.path)
+                changedFilePaths.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))
+                changedFilePaths.push(event.path)
             }
         }
 
-        // Rebuild graph from all parsed files
+        // Rebuild graph from all parsed files BEFORE deriving node IDs,
+        // so newly-added files are present in the graph when we look them up.
         const allParsedFiles = [...this.parsedFiles.values()]
         const builder = new GraphBuilder()
         this.graph = builder.build(allParsedFiles)
 
+        // Map changed file paths → graph node IDs using the updated graph
+        const changedNodeIds = [...new Set(
+            changedFilePaths.flatMap(fp => this.findAffectedNodes(fp))
+        )]
+
         // Run impact analysis on all changed nodes
         const analyzer = new ImpactAnalyzer(this.graph)
-        const impactResult = analyzer.analyze([...new Set(combinedChanged)])
+        const impactResult = analyzer.analyze(changedNodeIds)
 
         // Recompile lock
         const compiler = new LockCompiler()
@@ -111,7 +116,7 @@ export class IncrementalAnalyzer {
             try {
                 const content = await fs.readFile(fullPath, 'utf-8')
                 const parser = getParser(changedFile)
-                const parsedFile = parser.parse(changedFile, content)
+                const parsedFile = await parser.parse(changedFile, content)
 
                 // Race condition check: re-hash after parse
                 try {
@@ -132,7 +137,7 @@ export class IncrementalAnalyzer {
         try {
             const content = await fs.readFile(fullPath, 'utf-8')
             const parser = getParser(changedFile)
-            return parser.parse(changedFile, content)
+            return await parser.parse(changedFile, content)
         } catch {
             return null
         }

package/tests/analyzer.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'bun:test'
+import { IncrementalAnalyzer } from '../src/incremental-analyzer.js'
+import type { MikkLock, ParsedFile } from '@getmikk/core'
+
+describe('IncrementalAnalyzer', () => {
+    it('detects changes correctly without throwing', async () => {
+        const mockLock: MikkLock = {
+            version: '1',
+            lastUpdated: new Date().toISOString(),
+            files: {
+                'src/index.ts': {
+                    hash: 'abc',
+                    lastModified: new Date().toISOString(),
+                    path: 'src/index.ts',
+                    moduleId: 'root',
+                    imports: [],
+                    exports: []
+                }
+            },
+            functions: {},
+            classes: {},
+            modules: {}
+        }
+
+        const analyzer = new IncrementalAnalyzer(
+            { nodes: new Map(), edges: [] },
+            mockLock,
+            {
+                project: { name: 'test', language: 'typescript', framework: null },
+                declared: { modules: [], constraints: [], decisions: [] },
+                overwrite: { mode: 'never', requireConfirmation: false }
+            },
+            '/project'
+        )
+        
+        // This simulates a file change event
+        const result = await analyzer.analyze({ path: 'src/index.ts', type: 'modified' })
+        expect(result.graph).toBeDefined()
+        expect(result.lock).toBeDefined()
+        expect(result.impactResult).toBeDefined()
+    })
+
+    describe('Edge Cases and Batch Processing', () => {
+        const mockLock: MikkLock = {
+            version: '1',
+            lastUpdated: new Date().toISOString(),
+            files: {}, functions: {}, classes: {}, modules: {}
+        }
+        
+        const contract = {
+            project: { name: 'test', language: 'typescript', framework: null },
+            declared: { modules: [], constraints: [], decisions: [] },
+            overwrite: { mode: 'never', requireConfirmation: false }
+        }
+
+        it('handles file deletions by removing nodes from graph and lock', async () => {
+            const analyzer = new IncrementalAnalyzer({ nodes: new Map(), edges: [] }, mockLock, contract, '/project')
+            // First add it
+            analyzer.addParsedFile({ path: 'src/to-delete.ts', language: 'ts', hash: 'foo', parsedAt: Date.now(), functions: [], classes: [], imports: [], exports: [], routes: [] })
+            expect(analyzer.fileCount).toBe(1)
+            
+            // Now send a deleted event
+            await analyzer.analyze({ path: 'src/to-delete.ts', type: 'deleted' })
+            expect(analyzer.fileCount).toBe(0)
+        })
+
+        it('survives analyze events on completely non-existent OS files gracefully', async () => {
+            const analyzer = new IncrementalAnalyzer({ nodes: new Map(), edges: [] }, mockLock, contract, '/project')
+            // Will fail to fs.readFile inside parseWithRaceCheck
+            const result = await analyzer.analyze({ path: 'does/not/exist.ts', type: 'modified' })
+            expect(result.mode).toBeUndefined() // Returns incremental by default
+            expect(result.impactResult).toBeDefined()
+            // Should not have crashed the analyzer
+            expect(analyzer.fileCount).toBe(0) 
+        })
+
+        it('triggers a full re-analysis if file batch exceeds FULL_ANALYSIS_THRESHOLD (15)', async () => {
+            const analyzer = new IncrementalAnalyzer({ nodes: new Map(), edges: [] }, mockLock, contract, '/project')
+            const events = Array.from({ length: 16 }).map((_, i) => ({
+                path: `src/file_${i}.ts`,
+                type: 'modified' as const
+            }))
+            
+            const result = await analyzer.analyzeBatch(events)
+            // It should have hit runFullAnalysis, which returns mode: 'full'
+            expect(result.mode).toBe('full')
+            // It will also have gracefully continued despite the 16 files failing to load off disk
+            expect(result.impactResult.confidence).toBe('low')
+        })
+    })
+})