synap-git 2.1.7__tar.gz → 2.2.0__tar.gz

{synap_git-2.1.7 → synap_git-2.2.0}/.gitignore

@@ -29,3 +29,6 @@ config.json
 status.json
 fix_exc.py
 test_embed.py
+.vscode/
+.idea/
+*.log

{synap_git-2.1.7 → synap_git-2.2.0}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-08-03
+
+### Added
+- **AST Symbol Parser Expansion (AUD-02)**: Implemented Tree-sitter AST symbol extraction handlers for C#, PHP, Kotlin, Scala, and C.
+- **Event-Driven File Watcher (AUD-03)**: Replaced continuous 2s subprocess polling with `watchdog` filesystem event tracking, reducing idle CPU usage to near-zero.
+- **Daemon REST API Diagnostic Checks (AUD-06)**: Added daemon port availability and REST API endpoint status checks to `synap doctor`.
+- **Wiki Task Requeue Subcommand (AUD-08)**: Added `synap wiki retry` CLI subcommand and `retry_failed_wiki_queue` storage method to requeue permanently failed wiki tasks back to pending state.
+
+### Changed
+- **CLI `synap start` Control Flow (AUD-01)**: Fixed `synap start` so it exits cleanly when a daemon is already running unless `--foreground` is explicitly passed.
+- **SQLite WAL Performance Rationale (AUD-07)**: Documented `PRAGMA synchronous=NORMAL` in WAL mode as an intentional architectural tradeoff balancing write throughput and self-healing index recovery.
+
+### Fixed
+- **Graceful Embedding Provider Fallback (AUD-04)**: Configured Anthropic and OpenRouter providers to log a warning and return empty embedding vectors instead of raising unhandled `NotImplementedError`.
+- **Symbol Preservation on File Renames (AUD-05)**: Added `-M` rename detection to `git diff-tree` in incremental indexing to preserve file symbol history and edges across renames.
+
 ## [2.1.7] - 2026-07-29
 
 ### Added

{synap_git-2.1.7 → synap_git-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: synap-git
-Version: 2.1.7
+Version: 2.2.0
 Summary: Persistent structural context infrastructure for AI coding agents.
 Project-URL: Homepage, https://github.com/saahilpal/synapse
 Project-URL: Repository, https://github.com/saahilpal/synapse
@@ -37,6 +37,7 @@ Requires-Dist: tree-sitter-languages==1.10.2
 Requires-Dist: tree-sitter==0.20.4
 Requires-Dist: typer==0.15.1
 Requires-Dist: uvicorn==0.34.0
+Requires-Dist: watchdog>=6.0.0
 Provides-Extra: dev
 Requires-Dist: bandit==1.8.3; extra == 'dev'
 Requires-Dist: mypy==1.15.0; extra == 'dev'

{synap_git-2.1.7 → synap_git-2.2.0}/pyproject.toml

@@ -37,6 +37,7 @@ dependencies = [
   "tree-sitter-languages==1.10.2",
   "typer==0.15.1",
   "uvicorn==0.34.0",
+  "watchdog>=6.0.0",
 ]
 
 [project.urls]

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "2.1.7"
+__version__ = "2.2.0"

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/cli/main.py

@@ -652,6 +652,12 @@ def _detect_install_method() -> str:
 @app.command()
 def start(
     path: Annotated[str, typer.Argument(help="Repository path to watch.")] = ".",
+    foreground: Annotated[
+        bool,
+        typer.Option(
+            "--foreground", help="Run FastMCP stdio server in foreground after starting daemon."
+        ),
+    ] = False,
 ) -> None:
     """Start the Synap daemon in the background."""
     _verify_is_git(path)
@@ -676,6 +682,8 @@ def start(
                 if hb and "port" in hb:
                     console.print(f"[green]✓ UI available at http://127.0.0.1:{hb['port']}[/green]")
                 is_running = True
+                if not foreground:
+                    return
             else:
                 pid_file.unlink()
         except Exception as e:
@@ -739,7 +747,10 @@ def start(
             )
             raise typer.Exit(1)
 
-    # 3. Start MCP Server in the foreground
+        if not foreground:
+            return
+
+    # 3. Start MCP Server in the foreground if --foreground flag passed
     settings = _settings(path, json_output=True)
     runtime = SynapRuntime(settings)
     server = SynapMCPServer(runtime)
@@ -1496,40 +1507,52 @@ def doctor(
                 task_prov, completed=1, description=f"[red]✗ Unexpected error: {e}[/red]"
             )
 
-        task_daemon = progress.add_task("Checking Daemon Status...", total=1)
+        task_daemon = progress.add_task("Checking Daemon & REST API Status...", total=1)
         try:
+            import socket
+
+            import httpx
+
             daemon_info = _read_daemon_heartbeat(settings.repository_path)
-            if daemon_info:
-                status_str = daemon_info["status"].upper()
-                if status_str == "HEALTHY":
-                    progress.update(
-                        task_daemon,
-                        completed=1,
-                        description=f"[green]✓ Daemon active and healthy (PID {daemon_info['pid']}, uptime {daemon_info['uptime_seconds']}s)[/green]",
-                    )
-                elif status_str == "STARTING":
-                    progress.update(
-                        task_daemon,
-                        completed=1,
-                        description=f"[green]✓ Daemon is active and currently starting/indexing (PID {daemon_info['pid']})[/green]",
-                    )
-                elif status_str == "STALE":
-                    progress.update(
-                        task_daemon,
-                        completed=1,
-                        description="[yellow]⚠ Daemon heartbeat file exists but is stale (not running?)[/yellow]",
-                    )
-                else:
+            port = daemon_info.get("port", 9876) if daemon_info else 9876
+
+            # Test port availability
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.settimeout(0.5)
+                port_in_use = s.connect_ex(("127.0.0.1", port)) == 0
+
+            if daemon_info and port_in_use:
+                try:
+                    r = httpx.get(f"http://127.0.0.1:{port}/api/status", timeout=2.0)
+                    if r.status_code == 200:
+                        progress.update(
+                            task_daemon,
+                            completed=1,
+                            description=f"[green]✓ Daemon active & REST API healthy (PID {daemon_info['pid']}, port {port})[/green]",
+                        )
+                    else:
+                        progress.update(
+                            task_daemon,
+                            completed=1,
+                            description=f"[yellow]⚠ Daemon running on port {port} but REST API returned HTTP {r.status_code}[/yellow]",
+                        )
+                except Exception as ex:
                     progress.update(
                         task_daemon,
                         completed=1,
-                        description=f"[red]✗ Daemon degraded: {daemon_info.get('last_error')}[/red]",
+                        description=f"[yellow]⚠ Daemon running on port {port} but API check failed: {ex}[/yellow]",
                     )
+            elif daemon_info:
+                progress.update(
+                    task_daemon,
+                    completed=1,
+                    description=f"[yellow]⚠ Heartbeat found for PID {daemon_info['pid']} but port {port} is not listening[/yellow]",
+                )
             else:
                 progress.update(
                     task_daemon,
                     completed=1,
-                    description="[yellow]⚠ Daemon inactive (not running). Start it using `synap start`[/yellow]",
+                    description=f"[yellow]⚠ Daemon inactive (port {port} available). Start using `synap start`[/yellow]",
                 )
         except Exception as e:
             progress.update(
@@ -2173,3 +2196,16 @@ def wiki_show(
 
     content = wiki_path.read_text(encoding="utf-8")
     console.print(Markdown(content))
+
+
+@wiki_app.command("retry")
+def wiki_retry(
+    path: Annotated[str, typer.Argument(help="Repository path.")] = ".",
+) -> None:
+    """Requeue all permanently failed wiki tasks back to pending state."""
+    runtime = SynapRuntime(_settings(path))
+    count = runtime.store.retry_failed_wiki_queue()
+    if count > 0:
+        console.print(f"[green]✓ Requeued {count} failed wiki tasks to pending state.[/green]")
+    else:
+        console.print("[yellow]No failed wiki tasks found in queue.[/yellow]")

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/indexer/daemon.py

@@ -35,6 +35,8 @@ class RuntimeDaemon:
         self._last_metrics_time: float = 0.0
         self._last_cpu_time: float = 0.0
         self._last_prune_time: float = 0.0
+        self._fs_changed = False
+        self._observer: Any = None
 
     async def start(self) -> None:
         self.runtime.initialize_storage()
@@ -91,6 +93,44 @@ class RuntimeDaemon:
         self._write_heartbeat(status="healthy")
         self._install_signal_handlers()
 
+        # Start watchdog file observer for event-driven git indexing
+        self._fs_changed = False
+        self._observer = None
+        try:
+            from watchdog.events import FileSystemEventHandler
+            from watchdog.observers import Observer
+
+            daemon_ref = self
+
+            class _WatcherHandler(FileSystemEventHandler):
+                def on_any_event(self, event: Any) -> None:
+                    path_str = str(getattr(event, "src_path", ""))
+                    if any(
+                        ignored in path_str
+                        for ignored in (
+                            ".synap",
+                            ".git",
+                            ".venv",
+                            "__pycache__",
+                            "node_modules",
+                            ".next",
+                            "dist",
+                            "build",
+                        )
+                    ):
+                        return
+                    daemon_ref._fs_changed = True
+
+            self._observer = Observer()
+            self._observer.schedule(
+                _WatcherHandler(), str(self.settings.repository_path), recursive=True
+            )
+            self._observer.start()
+            self.logger.info("watchdog_observer_started")
+        except Exception as e:
+            self.logger.warning("watchdog_observer_init_failed", error=str(e))
+            self._observer = None
+
         # Launch Uvicorn and Wiki Worker in background
         server_task = asyncio.create_task(self._ui_server.serve())
         wiki_worker_task = asyncio.create_task(self._wiki_worker_loop())
@@ -98,6 +138,13 @@ class RuntimeDaemon:
         try:
             await self._poll_git_loop()
         finally:
+            if self._observer:
+                try:
+                    self._observer.stop()
+                    self._observer.join(timeout=1.0)
+                except Exception:
+                    pass
+
             self._running = False
             self.logger.info("daemon_shutting_down")
             self._ui_server.should_exit = True
@@ -258,60 +305,70 @@ class RuntimeDaemon:
                 structlog.get_logger().error("suppressed_error_caught", error=str(e))
 
     async def _poll_git_loop(self) -> None:
+        backstop_interval = 30.0
+        poll_step = 0.5
+        elapsed = backstop_interval  # Force initial check on loop start
+
         while not self._stop_event.is_set():
-            try:
-                # Periodic pruning (once per hour)
-                now = time.time()
-                if now - self._last_prune_time > 3600:
-                    self._last_prune_time = now
-                    count = await asyncio.to_thread(self.runtime.store.prune_expired_lessons)
-                    if count > 0:
-                        self.logger.info("lessons_pruned", count=count)
-                        print(f"\n[Synapse] Pruned {count} expired lessons.")
-
-                state = self.git.state()
-                change = self.git.classify(self._last_git_state, state)
-                self._last_git_state = state
-
-                if change.kind == "commit":
-                    self.logger.info("git_commit_detected")
-                    await asyncio.to_thread(self.runtime.handle_commit, state)
-                elif change.kind in ("branch", "checkout"):
-                    self.logger.info("git_branch_switch_detected")
-                    await asyncio.to_thread(self.runtime.handle_branch_switch, state)
-                elif change.kind == "merge":
-                    self.logger.info("git_merge_detected")
-                    await asyncio.to_thread(self.runtime.handle_merge, state)
-                elif change.kind == "revert":
-                    self.logger.info("git_revert_detected")
-                    await asyncio.to_thread(self.runtime.handle_revert, self._last_git_state, state)
-                elif change.kind not in ("initial", "unchanged"):
-                    self.logger.info("git_change_detected", kind=change.kind)
-                    await asyncio.to_thread(self.runtime.index_repository, git_state=state)
-
-                self._write_heartbeat(status="healthy")
-            except Exception as e:
-                self.logger.error("daemon_loop_error", error=str(e))
-                self._recovery_attempts += 1
-                self._write_heartbeat(status="degraded", last_error=str(e))
+            if self._fs_changed or elapsed >= backstop_interval:
+                self._fs_changed = False
+                elapsed = 0.0
 
-                # Database recovery if corrupted
                 try:
-                    is_wiped = await asyncio.to_thread(self.runtime.store.recover_if_corrupted)
-                    if is_wiped:
-                        self.logger.warning("daemon_rebuilding_corrupted_db")
-                        await asyncio.to_thread(self.runtime.bootstrap, force=True)
-                except Exception as ex:
-                    self.logger.error("daemon_self_healing_failed", error=str(ex))
+                    # Periodic pruning (once per hour)
+                    now = time.time()
+                    if now - self._last_prune_time > 3600:
+                        self._last_prune_time = now
+                        count = await asyncio.to_thread(self.runtime.store.prune_expired_lessons)
+                        if count > 0:
+                            self.logger.info("lessons_pruned", count=count)
+                            print(f"\n[Synapse] Pruned {count} expired lessons.")
+
+                    state = self.git.state()
+                    change = self.git.classify(self._last_git_state, state)
+                    self._last_git_state = state
+
+                    if change.kind == "commit":
+                        self.logger.info("git_commit_detected")
+                        await asyncio.to_thread(self.runtime.handle_commit, state)
+                    elif change.kind in ("branch", "checkout"):
+                        self.logger.info("git_branch_switch_detected")
+                        await asyncio.to_thread(self.runtime.handle_branch_switch, state)
+                    elif change.kind == "merge":
+                        self.logger.info("git_merge_detected")
+                        await asyncio.to_thread(self.runtime.handle_merge, state)
+                    elif change.kind == "revert":
+                        self.logger.info("git_revert_detected")
+                        await asyncio.to_thread(
+                            self.runtime.handle_revert, self._last_git_state, state
+                        )
+                    elif change.kind not in ("initial", "unchanged"):
+                        self.logger.info("git_change_detected", kind=change.kind)
+                        await asyncio.to_thread(self.runtime.index_repository, git_state=state)
+
+                    self._write_heartbeat(status="healthy")
+                except Exception as e:
+                    self.logger.error("daemon_loop_error", error=str(e))
+                    self._recovery_attempts += 1
+                    self._write_heartbeat(status="degraded", last_error=str(e))
+
+                    # Database recovery if corrupted
+                    try:
+                        is_wiped = await asyncio.to_thread(self.runtime.store.recover_if_corrupted)
+                        if is_wiped:
+                            self.logger.warning("daemon_rebuilding_corrupted_db")
+                            await asyncio.to_thread(self.runtime.bootstrap, force=True)
+                    except Exception as ex:
+                        self.logger.error("daemon_self_healing_failed", error=str(ex))
 
             try:
                 await asyncio.wait_for(
                     self._stop_event.wait(),
-                    timeout=self.settings.daemon_poll_interval_seconds,
+                    timeout=poll_step,
                 )
                 break  # Stop event was set, exit loop
             except TimeoutError:
-                pass  # Normal poll interval elapsed, continue loop
+                elapsed += poll_step
 
     def _install_signal_handlers(self) -> None:
         loop = asyncio.get_running_loop()

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/indexer/engine.py

@@ -474,6 +474,7 @@ class SynapRuntime:
                     "git",
                     "diff-tree",
                     "-r",
+                    "-M",
                     "--no-commit-id",
                     "--name-status",
                     previous_commit,

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/parser/registry.py

@@ -217,6 +217,52 @@ class CodeParserRegistry:
                 if kind in ("class", "module", "method"):
                     name = extract_text(node.child_by_field_name("name"))
 
+            elif lang_name == "c_sharp":
+                if kind in (
+                    "class_declaration",
+                    "method_declaration",
+                    "interface_declaration",
+                    "struct_declaration",
+                    "enum_declaration",
+                ):
+                    name = extract_text(node.child_by_field_name("name"))
+
+            elif lang_name == "php":
+                if kind in (
+                    "class_declaration",
+                    "function_definition",
+                    "method_declaration",
+                    "interface_declaration",
+                    "trait_declaration",
+                ):
+                    name = extract_text(node.child_by_field_name("name"))
+
+            elif lang_name == "kotlin":
+                if kind in (
+                    "class_declaration",
+                    "function_declaration",
+                    "object_declaration",
+                    "interface_declaration",
+                ):
+                    name = extract_text(node.child_by_field_name("name"))
+
+            elif lang_name == "scala":
+                if kind in (
+                    "class_definition",
+                    "object_definition",
+                    "function_definition",
+                    "trait_definition",
+                ):
+                    name = extract_text(node.child_by_field_name("name"))
+
+            elif lang_name == "c":
+                if kind in ("function_definition", "struct_specifier", "enum_specifier"):
+                    name = extract_text(node.child_by_field_name("name"))
+                    if not name:
+                        declarator = node.child_by_field_name("declarator")
+                        if declarator:
+                            name = extract_text(declarator.child_by_field_name("declarator"))
+
             if name:
                 # Compute hash of the node's subtree for change detection
                 ast_content = extract_text(node) or ""

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/provider/anthropic.py

@@ -123,12 +123,13 @@ class AnthropicProvider(LLMProvider):
         *,
         model: str | None = None,
     ) -> list[float]:
-        # Anthropic does not have a public embedding endpoint as of mid 2024.
-        # Typically developers use Voyage or OpenAI for embeddings when using Anthropic.
-        # We will throw a clear error.
-        raise NotImplementedError(
-            "Anthropic does not provide a native embeddings API. Please configure SYNAP_EMBED_PROVIDER=ollama or openai."
+        import structlog
+
+        structlog.get_logger().warning(
+            "anthropic_embedding_not_supported_degrading_to_fts",
+            provider="anthropic",
         )
+        return []
 
     def count_tokens(self, text: str) -> int:
         import tiktoken

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/provider/openrouter.py

@@ -120,6 +120,10 @@ class OpenRouterProvider(OpenAIProvider):
         *,
         model: str | None = None,
     ) -> list[float]:
-        raise NotImplementedError(
-            "OpenRouter does not support embeddings. Configure OpenAI or Ollama for embeddings."
+        import structlog
+
+        structlog.get_logger().warning(
+            "openrouter_embedding_not_supported_degrading_to_fts",
+            provider="openrouter",
         )
+        return []

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/retrieval/engine.py

@@ -122,10 +122,15 @@ class HybridRetrievalEngine:
         if self.embed_provider:
             try:
                 query_vector = self.embed_provider.embed(query)
-                symbols = self.store.get_similar_symbols(query_vector, limit=50)
-                for rank, sym in enumerate(symbols):
-                    sid = sym["symbol_id"]
-                    semantic_candidates[sid] = {**sym, "reason": "semantic", "semantic_rank": rank}
+                if query_vector:
+                    symbols = self.store.get_similar_symbols(query_vector, limit=50)
+                    for rank, sym in enumerate(symbols):
+                        sid = sym["symbol_id"]
+                        semantic_candidates[sid] = {
+                            **sym,
+                            "reason": "semantic",
+                            "semantic_rank": rank,
+                        }
             except Exception as e:
                 import structlog
 

{synap_git-2.1.7 → synap_git-2.2.0}/src/synap_git/storage/sqlite.py

@@ -44,6 +44,11 @@ class SynapStore:
     def initialize(self) -> None:
         self.path.parent.mkdir(parents=True, exist_ok=True)
         with self.connect() as conn:
+            # ARCHITECTURAL DECISION (AUD-07):
+            # PRAGMA synchronous=NORMAL in WAL mode is an intentional tradeoff:
+            # It avoids fsync() on every transaction commit, providing a 5-10x throughput boost for bulk AST indexing.
+            # In the rare event of an OS power-loss crash during a write, SQLite WAL recovery or Synapse's automatic
+            # self-healing (`recover_if_corrupted()`) safely reconstructs the deterministic local index.
             conn.execute("PRAGMA journal_mode=WAL")
             conn.execute("PRAGMA synchronous=NORMAL")
             conn.execute("PRAGMA foreign_keys=ON")
@@ -854,6 +859,15 @@ class SynapStore:
         with self.connect() as conn:
             conn.execute("DELETE FROM wiki_queue")
 
+    def retry_failed_wiki_queue(self) -> int:
+        now = int(datetime.now(UTC).timestamp())
+        with self.connect() as conn:
+            cursor = conn.execute(
+                "UPDATE wiki_queue SET status = 'pending', attempts = 0, updated_at = ? WHERE status = 'failed'",
+                (now,),
+            )
+            return cursor.rowcount
+
     def get_llm_calls(self) -> list[dict[str, Any]]:
         with self.connect() as conn:
             rows = conn.execute("SELECT * FROM llm_calls ORDER BY created_at DESC").fetchall()