feat: add debouncing to realtime file watcher

codebase_rag/cli_help.py

@@ -49,6 +49,11 @@ class CLICommandName(StrEnum):
 HELP_REPO_PATH_OPTIMIZE = "Path to the repository to optimize"
 HELP_REPO_PATH_WATCH = "Path to the repository to watch."
 
+HELP_DEBOUNCE = "Debounce delay in seconds. Set to 0 to disable debouncing."
+HELP_MAX_WAIT = (
+    "Maximum wait time in seconds before forcing an update during continuous edits."
+)
+
 HELP_UPDATE_GRAPH = "Update the knowledge graph by parsing the repository"
 HELP_CLEAN_DB = "Clean the database before updating (use when adding first repo)"
 HELP_OUTPUT_GRAPH = "Export graph to JSON file after updating (requires --update-graph)"

codebase_rag/constants.py

@@ -691,23 +691,61 @@ class TreeSitterModule(StrEnum):
 # (H) File/directory ignore patterns
 IGNORE_PATTERNS = frozenset(
     {
+        # Version control
         ".git",
+        ".git-local",
+        # Python
         "venv",
         ".venv",
+        "env",
+        "ENV",
         "__pycache__",
-        "node_modules",
-        "build",
-        "dist",
         ".eggs",
         ".pytest_cache",
         ".mypy_cache",
         ".ruff_cache",
-        ".claude",
+        "develop-eggs",
+        ".tox",
+        ".nox",
+        ".coverage",
+        "htmlcov",
+        # Rust
+        "target",
+        ".fingerprint",
+        "incremental",
+        # TypeScript / JavaScript / Node
+        "node_modules",
+        ".npm",
+        ".yarn",
+        ".pnpm-store",
+        # Build outputs
+        "build",
+        "dist",
+        "out",
+        "gen",
+        # Coverage
+        "coverage",
+        "criterion",
+        # IDE / Editor
         ".idea",
         ".vscode",
+        ".fleet",
+        ".history",
+        # AI / Agent tools
+        ".claude",
+        ".waves",
+        ".agents",
+        ".agents2",
+        ".wagents",
+        ".codex",
+        ".opencode",
+        ".sisyphus",
+        # Misc
+        ".tmp",
+        ".pids",
     }
 )
-IGNORE_SUFFIXES = frozenset({".tmp", "~"})
+IGNORE_SUFFIXES = frozenset({".tmp", "~", ".bak", ".swp", ".pyc", ".pyo"})
 
 PAYLOAD_NODE_ID = "node_id"
 PAYLOAD_QUALIFIED_NAME = "qualified_name"
@@ -731,6 +769,10 @@ class EventType(StrEnum):
 WATCHER_SLEEP_INTERVAL = 1
 LOG_LEVEL_INFO = "INFO"
 
+# (H) Debounce settings for realtime watcher
+DEFAULT_DEBOUNCE_SECONDS = 5
+DEFAULT_MAX_WAIT_SECONDS = 30
+
 
 class Architecture(StrEnum):
     X86_64 = "x86_64"

codebase_rag/logs.py

@@ -91,8 +91,25 @@
 
 # (H) File watcher logs
 WATCHER_ACTIVE = "File watcher is now active."
+WATCHER_DEBOUNCE_ACTIVE = (
+    "File watcher active with debouncing (debounce={debounce}s, max_wait={max_wait}s)"
+)
 WATCHER_SKIP_NO_QUERY = "Ingestor does not support querying, skipping real-time update."
 CHANGE_DETECTED = "Change detected: {event_type} on {path}. Updating graph."
+CHANGE_DEBOUNCING = (
+    "Change detected: {event_type} on {name} (debouncing for {debounce}s)"
+)
+DEBOUNCE_RESET = "Reset debounce timer for {path}"
+DEBOUNCE_MAX_WAIT = "Max wait ({max_wait}s) exceeded for {path}, processing now"
+DEBOUNCE_SCHEDULED = (
+    "Scheduled update for {path} in {debounce}s (max wait: {remaining}s remaining)"
+)
+DEBOUNCE_PROCESSING = "Processing debounced change: {path}"
+DEBOUNCE_NO_EVENT = "No pending event for {path}, skipping"
+DEBOUNCE_MAX_WAIT_ADJUSTED = (
+    "max_wait ({max_wait}s) is less than debounce ({debounce}s). "
+    "Setting max_wait to debounce value."
+)
 DELETION_QUERY = "Ran deletion query for path: {path}"
 RECALC_CALLS = "Recalculating all function call relationships for consistency..."
 GRAPH_UPDATED = "Graph updated successfully for change in: {name}"