openlore 2.0.5 → 2.0.6

package/dist/core/services/mcp-watcher.js

@@ -8,14 +8,29 @@
  * The call graph is deliberately excluded — rebuilding it requires full
  * tree-sitter analysis of all call sites and is too expensive for a watch loop.
  * It stays current via the post-commit hook (openlore analyze --force --embed).
+ *
+ * Spec 13.1 (watch-mode performance): freshness is O(change), not O(repo).
+ *   • Per-file events COALESCE into one batched flush (single debounce timer +
+ *     hard max-batch ceiling), so a burst / branch-switch runs the pipeline once,
+ *     not once per file.
+ *   • The patched llm-context is handed to the MCP read cache in place
+ *     (primeContextCache), so the next tool call is a cache HIT — no 2.1 MB
+ *     cold re-parse — even after the disk write.
+ *   • Vector updates are row-level (VectorIndex.updateFiles), not a full-corpus
+ *     read+overwrite, and run on a separate lower-priority lane so signature
+ *     freshness never blocks on embedding.
+ *   • VCS-flood / bulk batches are detected and collapsed to a single refresh.
+ *   • stderr emits one summary line per batch by default (per-file detail behind
+ *     OPENLORE_WATCH_DEBUG).
  */
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile, readdir } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { join, relative } from 'node:path';
 import chokidar from 'chokidar';
 import { extractSignatures, detectLanguage } from '../analyzer/signature-extractor.js';
 import { EdgeStore } from './edge-store.js';
-import { OPENLORE_DIR, OPENLORE_ANALYSIS_SUBDIR, ARTIFACT_LLM_CONTEXT, } from '../../constants.js';
+import { primeContextCache } from './mcp-handlers/utils.js';
+import { OPENLORE_DIR, OPENLORE_ANALYSIS_SUBDIR, ARTIFACT_LLM_CONTEXT, WATCH_DEBOUNCE_MS, WATCH_MAX_BATCH_MS, WATCH_BULK_THRESHOLD, WATCH_EMBED_FILE_CEILING, WATCH_VCS_SETTLE_MS, } from '../../constants.js';
 const CALL_GRAPH_LANGS = new Set([
     'Python', 'TypeScript', 'JavaScript', 'Go', 'Rust', 'Ruby', 'Java', 'C++', 'Swift',
 ]);
@@ -82,20 +97,54 @@ export function isIgnoredRelPath(relPath) {
 export class McpWatcher {
     rootPath;
     outputPath;
+    contextPath;
     debounceMs;
+    maxBatchMs;
+    bulkThreshold;
+    embedFileCeiling;
     extraIgnore;
+    debug;
     fsWatcher;
-    timers = new Map();
-    running = false;
+    gitWatcher;
+    // ── Coalescing queue (Step 1) ──────────────────────────────────────────────
+    pending = new Set(); // absolute paths awaiting a flush
+    debounceTimer;
+    maxBatchTimer;
+    running = false; // single-flight for the signature flush
+    vcsBulkFlag = false; // set by the .git ref watcher
+    // ── Embedding lane (Step 4 — decoupled, lower priority) ─────────────────────
+    embed;
+    embedDegraded = false; // auto-degraded on a too-large tree
+    embedFiles = new Map(); // rel → content awaiting embed
+    embedNodes = new Map(); // id → node awaiting embed
+    embedTimer;
+    embedRunning = false;
+    lastEmbedContext;
     constructor(options) {
         this.rootPath = options.rootPath;
         this.outputPath = options.outputPath
             ?? join(options.rootPath, OPENLORE_DIR, OPENLORE_ANALYSIS_SUBDIR);
-        this.debounceMs = options.debounceMs ?? 400;
+        this.contextPath = join(this.outputPath, ARTIFACT_LLM_CONTEXT);
+        this.debounceMs = options.debounceMs ?? WATCH_DEBOUNCE_MS;
+        this.maxBatchMs = options.maxBatchMs ?? WATCH_MAX_BATCH_MS;
+        this.bulkThreshold = options.bulkThreshold ?? WATCH_BULK_THRESHOLD;
+        this.embedFileCeiling = options.embedFileCeiling ?? WATCH_EMBED_FILE_CEILING;
+        this.embed = options.embed ?? true;
         this.extraIgnore = options.ignore ?? [];
+        this.debug = !!process.env.OPENLORE_WATCH_DEBUG;
     }
     // ── Lifecycle ──────────────────────────────────────────────────────────────
     async start() {
+        // Auto-degrade live embedding on very large trees (Step 4). Counting is
+        // bounded — it stops as soon as the ceiling is exceeded.
+        if (this.embed) {
+            const count = await this.countSourceFiles(this.embedFileCeiling + 1);
+            if (count > this.embedFileCeiling) {
+                this.embedDegraded = true;
+                process.stderr.write(`[mcp-watcher] ${count}+ source files exceed the live-embed ceiling ` +
+                    `(${this.embedFileCeiling}); running signatures-only — embeddings refresh at commit\n`);
+            }
+        }
         await new Promise((resolve, reject) => {
             const extraIgnore = this.extraIgnore;
             const rootPath = this.rootPath;
@@ -115,125 +164,315 @@ export class McpWatcher {
             });
             this.fsWatcher.on('change', (absPath) => {
                 if (SOURCE_EXTENSIONS.test(absPath)) {
-                    this.scheduleChange(absPath);
+                    this.enqueue(absPath);
                 }
             });
             this.fsWatcher.on('ready', () => resolve());
             this.fsWatcher.on('error', (err) => reject(err));
         });
-        process.stderr.write(`[mcp-watcher] watching ${this.rootPath}\n`);
+        // Best-effort VCS-flood detection (Step 5): a branch switch / rebase / merge
+        // bumps these refs. We never recurse into .git (it stays ignored above); we
+        // watch only these specific files, then collapse the churn into one refresh.
+        try {
+            const gitDir = join(this.rootPath, '.git');
+            const refs = ['HEAD', 'index', 'MERGE_HEAD', 'ORIG_HEAD'].map((f) => join(gitDir, f));
+            this.gitWatcher = chokidar.watch(refs, {
+                persistent: true,
+                ignoreInitial: true,
+                followSymlinks: false,
+            });
+            this.gitWatcher.on('all', () => this.onVcsEvent());
+        }
+        catch {
+            // no .git, or watch failed — VCS detection falls back to the batch-size
+            // threshold in handleBatch, which is enough for G3.
+        }
+        process.stderr.write(`[mcp-watcher] watching ${this.rootPath}` +
+            `${this.embed && !this.embedDegraded ? '' : ' (signatures-only)'}\n`);
     }
     async stop() {
-        for (const t of this.timers.values())
-            clearTimeout(t);
-        this.timers.clear();
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        if (this.maxBatchTimer)
+            clearTimeout(this.maxBatchTimer);
+        if (this.embedTimer)
+            clearTimeout(this.embedTimer);
+        this.debounceTimer = this.maxBatchTimer = this.embedTimer = undefined;
+        // Best-effort: persist anything still queued so a save right before shutdown
+        // is not lost.
+        if (this.pending.size > 0 && !this.running) {
+            const batch = Array.from(this.pending);
+            this.pending.clear();
+            try {
+                await this.handleBatch(batch, { syncFlush: true });
+            }
+            catch { /* ignore */ }
+        }
         await this.fsWatcher?.close();
+        await this.gitWatcher?.close();
         process.stderr.write('[mcp-watcher] stopped\n');
     }
-    // ── Debounce ───────────────────────────────────────────────────────────────
-    scheduleChange(absPath) {
-        const existing = this.timers.get(absPath);
-        if (existing)
-            clearTimeout(existing);
-        const t = setTimeout(() => {
-            this.timers.delete(absPath);
-            if (this.running) {
-                // Re-schedule instead of dropping — ensures no changes are lost
-                this.scheduleChange(absPath);
-                return;
+    // ── Coalescing (Step 1) ──────────────────────────────────────────────────────
+    /**
+     * Add a changed path to the pending set and (re)arm a single debounce timer,
+     * plus a one-shot hard ceiling so a continuous stream still flushes.
+     */
+    enqueue(absPath) {
+        this.pending.add(absPath);
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => this.flush(), this.debounceMs);
+        if (!this.maxBatchTimer) {
+            this.maxBatchTimer = setTimeout(() => this.flush(), this.maxBatchMs);
+        }
+    }
+    /** A .git ref changed — settle, then flush whatever changed as one bulk batch. */
+    onVcsEvent() {
+        this.vcsBulkFlag = true;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => this.flush(), WATCH_VCS_SETTLE_MS);
+        if (this.debug) {
+            process.stderr.write('[mcp-watcher] VCS operation detected — coalescing into one refresh\n');
+        }
+    }
+    /**
+     * Drain the pending set into a single batch. Single-flight: if a flush is
+     * already running, leave the new paths in `pending` and reschedule once it
+     * finishes — never interleave two flushes.
+     */
+    flush() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+        if (this.maxBatchTimer) {
+            clearTimeout(this.maxBatchTimer);
+            this.maxBatchTimer = undefined;
+        }
+        if (this.running)
+            return; // a follow-up is scheduled in finally{}
+        if (this.pending.size === 0)
+            return;
+        const batch = Array.from(this.pending);
+        this.pending.clear();
+        this.running = true;
+        this.handleBatch(batch)
+            .catch((err) => process.stderr.write(`[mcp-watcher] error: ${err.message}\n`))
+            .finally(() => {
+            this.running = false;
+            if (this.pending.size > 0) {
+                this.debounceTimer = setTimeout(() => this.flush(), this.debounceMs);
             }
-            this.running = true;
-            this.handleChange(absPath)
-                .catch(err => process.stderr.write(`[mcp-watcher] error: ${err.message}\n`))
-                .finally(() => { this.running = false; });
-        }, this.debounceMs);
-        this.timers.set(absPath, t);
+        });
     }
     // ── Core re-index ──────────────────────────────────────────────────────────
     /**
-     * Re-index a single changed file.
-     * Exposed for unit testing without needing a real file watcher.
+     * Re-index a single changed file. Exposed for unit testing without needing a
+     * real file watcher; flushes synchronously so callers observe the update on
+     * disk immediately. Internally this is just a batch of one.
      */
     async handleChange(absPath) {
-        const rel = relative(this.rootPath, absPath);
-        // Skip test files and unsupported languages
-        if (isTestFile(rel))
-            return;
-        if (detectLanguage(rel) === 'unknown')
-            return;
-        // Read new file content (needed for hash check and re-parse)
-        let content;
-        try {
-            content = await readFile(absPath, 'utf-8');
-        }
-        catch {
-            return; // file may have been deleted between the event and now
+        await this.handleBatch([absPath], { syncFlush: true });
+    }
+    /**
+     * Process a coalesced batch of changed files as ONE pipeline pass:
+     *   • per-file incremental edge update (content-hash skip), all under one open
+     *     EdgeStore;
+     *   • ONE signature patch + ONE llm-context persist + ONE read-cache handoff;
+     *   • ONE vector update (inline when syncFlush, else on the embed lane).
+     */
+    async handleBatch(absPaths, opts = {}) {
+        const t0 = Date.now();
+        const consumedVcsBulk = this.vcsBulkFlag;
+        this.vcsBulkFlag = false;
+        // 1. Resolve + read candidate files (skip tests / unknown langs / deleted).
+        const files = [];
+        for (const abs of absPaths) {
+            const rel = relative(this.rootPath, abs);
+            if (isTestFile(rel))
+                continue;
+            if (detectLanguage(rel) === 'unknown')
+                continue;
+            let content;
+            try {
+                content = await readFile(abs, 'utf-8');
+            }
+            catch {
+                continue; // file may have been deleted between the event and now
+            }
+            files.push({ rel, abs, content });
         }
-        // ── Incremental edge update (CGC _handle_modification algorithm) ──────────
+        if (files.length === 0)
+            return;
+        // 2. Incremental edge update (CGC _handle_modification algorithm), one open
+        //    store for the whole batch. Content-hash skip drops no-op autosaves.
+        const changedFiles = [];
+        const changedNodes = [];
         if (EdgeStore.exists(this.outputPath)) {
             const store = EdgeStore.open(EdgeStore.dbPath(this.outputPath));
             try {
-                // Content hash — skip entirely on no-op IDE autosaves
-                const newHash = createHash('sha256').update(content).digest('hex');
-                if (store.getFileHash(rel) === newHash)
-                    return;
-                // Reverse lookup BEFORE delete so we know which files call into this one
-                // callerFiles are relative paths (DB stores relative paths)
-                const callerFiles = store.getCallerFiles(rel);
-                // Re-parse BEFORE mutating DB — graph stays readable (old state) during parse.
-                // Seed resolution with all known nodes so the re-parsed caller files'
-                // calls into other files don't degrade to `external::` (they would
-                // otherwise, since the subset trie only holds the re-parsed files).
-                const resolutionNodes = store.getAllInternalNodes();
-                const { edges: newEdges, nodes: newNodes } = await buildGraphSubset(rel, content, callerFiles, this.rootPath, resolutionNodes);
-                // Atomic swap: delete stale data and insert fresh data in one transaction
-                // so concurrent MCP reads never see a torn graph
-                store.transaction(() => {
-                    store.deleteEdgesForFile(rel);
-                    for (const cf of callerFiles.slice(0, CALLER_REPARSE_LIMIT)) {
-                        store.deleteOutgoingEdgesForFile(cf);
+                for (const f of files) {
+                    const newHash = createHash('sha256').update(f.content).digest('hex');
+                    if (store.getFileHash(f.rel) === newHash)
+                        continue; // no-op autosave
+                    // Reverse lookup BEFORE delete so we know which files call into this one.
+                    const callerFiles = store.getCallerFiles(f.rel);
+                    // Re-parse BEFORE mutating DB — graph stays readable (old state) during
+                    // parse. Seed resolution with all known nodes so re-parsed callers'
+                    // cross-file calls don't degrade to `external::`.
+                    const resolutionNodes = store.getAllInternalNodes();
+                    const { edges: newEdges, nodes: newNodes } = await buildGraphSubset(f.rel, f.content, callerFiles, this.rootPath, resolutionNodes);
+                    // Atomic swap so concurrent MCP reads never see a torn graph.
+                    store.transaction(() => {
+                        store.deleteEdgesForFile(f.rel);
+                        for (const cf of callerFiles.slice(0, CALLER_REPARSE_LIMIT)) {
+                            store.deleteOutgoingEdgesForFile(cf);
+                        }
+                        store.deleteNodesForFile(f.rel);
+                        store.insertNodes(newNodes);
+                        store.insertEdges(newEdges);
+                        store.setFileHash(f.rel, newHash);
+                    });
+                    changedFiles.push({ rel: f.rel, content: f.content });
+                    for (const n of newNodes)
+                        changedNodes.push(n);
+                    if (this.debug) {
+                        process.stderr.write(`[mcp-watcher] graph: ${f.rel} (+${newNodes.length} nodes, +${newEdges.length} edges, ${callerFiles.length} callers)\n`);
                     }
-                    store.deleteNodesForFile(rel);
-                    store.insertNodes(newNodes);
-                    store.insertEdges(newEdges);
-                    store.setFileHash(rel, newHash);
-                });
-                process.stderr.write(`[mcp-watcher] updated graph: ${rel} (+${newNodes.length} nodes, +${newEdges.length} edges, ${callerFiles.length} callers re-parsed)\n`);
+                }
             }
             finally {
                 store.close();
             }
         }
-        // ── Signature patch ───────────────────────────────────────────────────────
-        const contextPath = join(this.outputPath, ARTIFACT_LLM_CONTEXT);
-        let context;
-        try {
-            const raw = await readFile(contextPath, 'utf-8');
-            context = JSON.parse(raw);
+        else {
+            // No edge store yet — still refresh signatures for every candidate.
+            for (const f of files)
+                changedFiles.push({ rel: f.rel, content: f.content });
         }
-        catch {
-            process.stderr.write(`[mcp-watcher] no context at ${contextPath} — run analyze first\n`);
+        if (changedFiles.length === 0)
+            return; // every event was a no-op autosave
+        // 3. Signatures: load context (shared in-memory cache), patch all changed
+        //    files, then ONE persist + read-cache handoff (Step 2). The handoff
+        //    means the next tool call is a cache HIT — no cold 2.1 MB re-parse.
+        const context = await this.loadContext();
+        if (!context) {
+            process.stderr.write(`[mcp-watcher] no context at ${this.contextPath} — run analyze first\n`);
             return;
         }
-        const newMap = extractSignatures(rel, content);
         if (!context.signatures)
             context.signatures = [];
-        const idx = context.signatures.findIndex(m => m.path === rel);
-        if (idx >= 0) {
-            context.signatures[idx] = newMap;
+        for (const f of changedFiles) {
+            const newMap = extractSignatures(f.rel, f.content);
+            const idx = context.signatures.findIndex((m) => m.path === f.rel);
+            if (idx >= 0)
+                context.signatures[idx] = newMap;
+            else
+                context.signatures.push(newMap);
         }
-        else {
-            context.signatures.push(newMap);
+        await this.persistContext(context);
+        // 4. Vector update — decoupled from signature freshness (Step 4).
+        const isBulk = consumedVcsBulk || changedFiles.length >= this.bulkThreshold;
+        if (this.embed && !this.embedDegraded && context.callGraph) {
+            if (opts.syncFlush) {
+                // Direct handleChange path: inline so callers/tests observe it.
+                await this.updateVectors(context, changedFiles, changedNodes);
+            }
+            else {
+                // Watcher path: schedule on the lower-priority embed lane. On a bulk
+                // event this still collapses to a single deferred pass.
+                this.scheduleEmbed(context, changedFiles, changedNodes);
+            }
+        }
+        // 5. One summary line per batch (Step 6). Per-file detail is behind debug.
+        const n = changedFiles.length;
+        process.stderr.write(`[mcp-watcher] ${isBulk ? `coalesced ${n} changes` : `updated ${n} file${n === 1 ? '' : 's'}`} (${Date.now() - t0}ms)\n`);
+    }
+    // ── llm-context load + persistence + read-cache handoff (Step 2) ─────────────
+    /**
+     * True when this watcher writes to the canonical `<root>/.openlore/analysis`
+     * layout that the MCP read handlers cache against. Only then is the shared
+     * in-memory read cache (primeContextCache) the right channel to prime; a custom
+     * `outputPath` (tests / non-standard installs) writes only to disk.
+     */
+    get usesStandardLayout() {
+        return this.outputPath === join(this.rootPath, OPENLORE_DIR, OPENLORE_ANALYSIS_SUBDIR);
+    }
+    /**
+     * Load the context the watcher is about to patch. This ALWAYS reads fresh from
+     * disk — never through the shared read cache — because the cache is a read-path
+     * (tool-call) optimization, and patching a possibly-stale cached object could
+     * silently drop signatures written by a concurrent `analyze` between events.
+     * The writer reads ground truth; persistContext then primes the read cache with
+     * the result so the next tool call is still a hit (Step 2a, G1).
+     */
+    async loadContext() {
+        try {
+            const raw = await readFile(this.contextPath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async persistContext(context) {
+        // Strip the runtime-only EdgeStore handle before serializing.
+        const { edgeStore: _edgeStore, ...serializable } = context;
+        void _edgeStore;
+        await writeFile(this.contextPath, JSON.stringify(serializable, null, 2), 'utf-8');
+        // Hand the patched object back to the read cache, aligned to the new on-disk
+        // mtime, so the next tool call is a cache hit (no cold re-parse). This is the
+        // fix for root-cause item 2 (mtime bump forcing a full re-read). Only valid
+        // for the canonical layout the read handlers cache against.
+        if (this.usesStandardLayout)
+            await primeContextCache(this.rootPath, context);
+    }
+    // ── Embedding lane (Step 4) ──────────────────────────────────────────────────
+    scheduleEmbed(context, changedFiles, nodes) {
+        for (const f of changedFiles)
+            this.embedFiles.set(f.rel, f.content);
+        for (const node of nodes)
+            this.embedNodes.set(node.id, node);
+        this.lastEmbedContext = context;
+        if (this.embedTimer)
+            clearTimeout(this.embedTimer);
+        // Slightly behind the signature debounce so structural freshness always lands
+        // first and multiple flushes batch into one embed pass.
+        this.embedTimer = setTimeout(() => void this.runEmbedLane(), this.debounceMs);
+    }
+    async runEmbedLane() {
+        if (this.embedRunning) {
+            // Re-arm: drain again once the in-flight pass finishes.
+            this.embedTimer = setTimeout(() => void this.runEmbedLane(), this.debounceMs);
+            return;
+        }
+        if (this.embedFiles.size === 0 || !this.lastEmbedContext)
+            return;
+        const changedFiles = Array.from(this.embedFiles, ([rel, content]) => ({ rel, content }));
+        const nodes = Array.from(this.embedNodes.values());
+        const context = this.lastEmbedContext;
+        this.embedFiles.clear();
+        this.embedNodes.clear();
+        this.embedRunning = true;
+        try {
+            await this.updateVectors(context, changedFiles, nodes);
+        }
+        catch (err) {
+            process.stderr.write(`[mcp-watcher] embed error: ${err.message}\n`);
         }
-        await writeFile(contextPath, JSON.stringify(context, null, 2), 'utf-8');
-        process.stderr.write(`[mcp-watcher] re-indexed signatures: ${rel}\n`);
-        // Incremental vector re-embed — silently skipped if no embedding service available
-        if (context.callGraph) {
-            await this.reEmbed(context, rel, content);
+        finally {
+            this.embedRunning = false;
+            if (this.embedFiles.size > 0) {
+                this.embedTimer = setTimeout(() => void this.runEmbedLane(), this.debounceMs);
+            }
         }
     }
-    // ── Embed step ─────────────────────────────────────────────────────────────
-    async reEmbed(context, rel, content) {
+    /**
+     * Row-level vector update for the changed files only (Step 3). Falls back to a
+     * silent no-op when no embedding service and no index are available.
+     */
+    async updateVectors(context, changedFiles, changedNodes) {
         try {
             const { VectorIndex } = await import('../analyzer/vector-index.js');
             const { EmbeddingService } = await import('../analyzer/embedding-service.js');
@@ -248,24 +487,64 @@ export class McpWatcher {
                 const cfg = await readOpenLoreConfig(this.rootPath);
                 embedSvc = cfg ? EmbeddingService.fromConfig(cfg) : null;
             }
-            // embedSvc may be null: VectorIndex.build then refreshes the BM25-only
-            // corpus rather than re-embedding. Keeps the keyword index live in watch mode.
+            // embedSvc may be null: updateFiles then refreshes the BM25-only corpus
+            // rather than re-embedding, keeping the keyword index live in watch mode.
             const cg = context.callGraph;
-            const hubIds = new Set((cg.hubFunctions ?? []).map(f => f.id));
-            const entryIds = new Set((cg.entryPoints ?? []).map(f => f.id));
-            const fileContents = new Map([[rel, content]]);
-            const { embedded, reused, total, hasEmbeddings } = await VectorIndex.build(this.outputPath, cg.nodes, context.signatures ?? [], hubIds, entryIds, embedSvc, fileContents, 
-            /* incremental */ true);
-            process.stderr.write(hasEmbeddings
-                ? `[mcp-watcher] re-embedded ${rel}: ${embedded} new, ${reused} reused\n`
-                : `[mcp-watcher] refreshed BM25 index for ${rel}: ${total} functions\n`);
+            if (!cg)
+                return;
+            const hubIds = new Set((cg.hubFunctions ?? []).map((f) => f.id));
+            const entryIds = new Set((cg.entryPoints ?? []).map((f) => f.id));
+            const changedFilePaths = new Set(changedFiles.map((f) => f.rel));
+            const fileContents = new Map(changedFiles.map((f) => [f.rel, f.content]));
+            // Prefer the freshly-parsed nodes; fall back to the (possibly stale)
+            // call-graph nodes for the changed files when no edge store seeded them.
+            const nodes = changedNodes.length > 0
+                ? changedNodes
+                : (cg.nodes ?? []).filter((n) => changedFilePaths.has(n.filePath));
+            const { embedded, reused, total, hasEmbeddings } = await VectorIndex.updateFiles(this.outputPath, nodes, changedFilePaths, context.signatures ?? [], hubIds, entryIds, embedSvc, fileContents);
+            if (this.debug) {
+                process.stderr.write(hasEmbeddings
+                    ? `[mcp-watcher] re-embedded ${changedFilePaths.size} file(s): ${embedded} new, ${reused} reused\n`
+                    : `[mcp-watcher] refreshed BM25 index for ${changedFilePaths.size} file(s): ${total} functions\n`);
+            }
         }
         catch (err) {
             process.stderr.write(`[mcp-watcher] embed error: ${err.message}\n`);
         }
     }
+    // ── Helpers ──────────────────────────────────────────────────────────────────
+    /** Bounded count of watched source files; stops early once `cap` is exceeded. */
+    async countSourceFiles(cap) {
+        let count = 0;
+        const walk = async (dir) => {
+            if (count > cap)
+                return;
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (count > cap)
+                    return;
+                const abs = join(dir, entry.name);
+                const rel = relative(this.rootPath, abs);
+                if (entry.isDirectory()) {
+                    if (!isIgnoredRelPath(rel))
+                        await walk(abs);
+                }
+                else if (entry.isFile() && SOURCE_EXTENSIONS.test(entry.name) && !isIgnoredRelPath(rel)) {
+                    count++;
+                }
+            }
+        };
+        await walk(this.rootPath);
+        return count;
+    }
 }
-// ── Helpers ───────────────────────────────────────────────────────────────────
+// ── Module helpers ──────────────────────────────────────────────────────────────
 function isTestFile(relPath) {
     return (relPath.includes('.test.') ||
         relPath.includes('.spec.') ||
@@ -300,7 +579,7 @@ async function buildGraphSubset(changedRel, changedContent, callerFiles, rootDir
     const builder = new CallGraphBuilder();
     const result = await builder.build(files, undefined, undefined, resolutionNodes);
     // Only return nodes from changedFile — callerFiles nodes are already in DB and unchanged
-    const changedNodes = Array.from(result.nodes.values()).filter(n => n.filePath === changedRel);
+    const changedNodes = Array.from(result.nodes.values()).filter((n) => n.filePath === changedRel);
     return { edges: result.edges, nodes: changedNodes };
 }
 //# sourceMappingURL=mcp-watcher.js.map