codebase-mcp 0.1.0__py3-none-any.whl

codebase_mcp/watcher.py

@@ -0,0 +1,169 @@
+"""
+File system watcher: monitors the project directory and triggers incremental
+re-index when source files change.
+
+Uses watchdog for cross-platform file watching (Windows ReadDirectoryChangesW,
+Linux inotify, macOS FSEvents). Debounces rapid changes with a 2-second window.
+
+Optional dependency — gracefully fails with a clear message if watchdog is not installed.
+"""
+
+from __future__ import annotations
+import logging
+import queue
+import threading
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import Config
+
+log = logging.getLogger(__name__)
+
+# Global watcher instance (one per process)
+_active_watcher: "CodebaseWatcher | None" = None
+
+
+class WatcherNotAvailable(RuntimeError):
+    pass
+
+
+class CodebaseWatcher:
+    """
+    Background file watcher with debounced incremental re-index.
+
+    Architecture:
+        Main thread: FastMCP / CLI (calls start/stop)
+        Observer thread: watchdog OS-level event loop
+        Debounce thread: waits 2s after last event, then calls run_index
+    """
+
+    def __init__(self, project_root: str, db_path: str, config: "Config"):
+        try:
+            from watchdog.observers import Observer  # type: ignore
+        except ImportError:
+            raise WatcherNotAvailable(
+                "watchdog is not installed. Install it with: pip install 'codebase-mcp[watch]'"
+            )
+
+        self._root = project_root
+        self._db_path = db_path
+        self._config = config
+        self._queue: queue.Queue[str] = queue.Queue()
+        self._observer = Observer()
+        self._running = False
+        self._debounce_thread: threading.Thread | None = None
+        self._stats = {"events": 0, "reindexes": 0, "last_reindex": None}
+
+    def start(self) -> None:
+        from watchdog.events import FileSystemEventHandler, FileSystemEvent  # type: ignore
+
+        config = self._config
+
+        class _ChangeHandler(FileSystemEventHandler):
+            def on_any_event(self, event: FileSystemEvent):
+                if event.is_directory:
+                    return
+                src = getattr(event, "src_path", "")
+                if not src:
+                    return
+                # Only queue files we actually index
+                import os
+                ext = os.path.splitext(src)[1]
+                basename = os.path.basename(src)
+                lang = config.language_for(ext) or config.language_for_basename(basename)
+                if lang:
+                    self.queue.put(src)
+
+        handler = _ChangeHandler()
+        handler.queue = self._queue
+
+        if not __import__("os").path.isdir(self._root):
+            log.warning("Watcher: project root does not exist: %s", self._root)
+            return
+
+        self._observer.schedule(handler, self._root, recursive=True)
+        self._observer.start()
+
+        self._running = True
+        self._debounce_thread = threading.Thread(
+            target=self._debounce_loop, name="codebase-mcp-watcher", daemon=True
+        )
+        self._debounce_thread.start()
+        log.info("File watcher started for %s", self._root)
+
+    def stop(self) -> None:
+        self._running = False
+        self._observer.stop()
+        self._observer.join(timeout=5)
+        log.info("File watcher stopped")
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def stats(self) -> dict:
+        return dict(self._stats)
+
+    def _debounce_loop(self) -> None:
+        from .indexer import run_index
+
+        while self._running:
+            # Block until the first change arrives (poll every 5s to check running)
+            try:
+                self._queue.get(timeout=5.0)
+                self._stats["events"] += 1
+            except queue.Empty:
+                continue
+
+            # Drain for 2 seconds to batch rapid changes (e.g., git checkout)
+            deadline = time.monotonic() + 2.0
+            while time.monotonic() < deadline:
+                try:
+                    self._queue.get_nowait()
+                    self._stats["events"] += 1
+                except queue.Empty:
+                    time.sleep(0.1)
+
+            # Drain any remaining
+            while not self._queue.empty():
+                try:
+                    self._queue.get_nowait()
+                except queue.Empty:
+                    break
+
+            # Run incremental index
+            log.debug("Watcher: triggering incremental re-index")
+            try:
+                result = run_index(self._db_path, self._root, self._config, full_reindex=False)
+                self._stats["reindexes"] += 1
+                self._stats["last_reindex"] = __import__("datetime").datetime.utcnow().isoformat() + "Z"
+                log.info(
+                    "Auto-reindex: %d files changed, %d symbols updated (%.0fms)",
+                    result.files_changed, result.symbols_added, result.duration_ms
+                )
+            except Exception as e:
+                log.error("Auto-reindex failed: %s", e)
+
+
+# ─── Global watcher management ───────────────────────────────────────────────
+
+def start_watcher(project_root: str, db_path: str, config: "Config") -> CodebaseWatcher:
+    global _active_watcher
+    if _active_watcher and _active_watcher.is_running:
+        _active_watcher.stop()
+    _active_watcher = CodebaseWatcher(project_root, db_path, config)
+    _active_watcher.start()
+    return _active_watcher
+
+
+def stop_watcher() -> None:
+    global _active_watcher
+    if _active_watcher:
+        _active_watcher.stop()
+        _active_watcher = None
+
+
+def get_watcher() -> "CodebaseWatcher | None":
+    return _active_watcher