codespine 0.5.6__tar.gz → 0.5.8__tar.gz

{codespine-0.5.6 → codespine-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.5.6
+Version: 0.5.8
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -72,6 +72,8 @@ It indexes classes, methods, calls, type relationships, cross-module links, git
 
 It also keeps a separate dirty overlay for uncommitted Java edits, so agents can query current work-in-progress without forcing the committed base index to churn on every save.
 
+The MCP daemon and the indexer run independently. Querying while a full re-index is running no longer causes crashes or memory contention — reads go to an isolated snapshot that is atomically updated when indexing completes.
+
 ## Why It Saves Tokens
 
 - One MCP call can replace many file opens. `get_symbol_context("PaymentService")` returns a resolved neighborhood instead of forcing the agent to read every caller and callee file manually.
@@ -101,6 +103,8 @@ pip install "codespine[ml]"
 - Community detection: structural clusters for architectural context
 - Change coupling: git-history-based file relationships
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
+- Cross-module call linking: signature-based detection of calls between Maven/Gradle modules
+- Concurrent read/write isolation: MCP queries run against a read replica; the indexer writes separately, with no memory contention
 - MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
 ## Editing Without Stale Indexes
@@ -159,15 +163,23 @@ Parsing code...                8/8
 Tracing calls...               847 calls resolved
 Analyzing types...             234 type relationships
 Cross-module linking...        skipped (single module)
+Detecting communities...       loading symbols
+Detecting communities...       623 symbols, 1204 structural edges
+Detecting communities...       persisting 8/8 clusters
 Detecting communities...       8 clusters found
+Detecting execution flows...   34 entry points, tracing
 Detecting execution flows...   34 processes found
 Finding dead code...           12 unreachable symbols
+Analyzing git history...       18 commits, computing co-changes
 Analyzing git history...       18 coupled file pairs
 Generating embeddings...       0 vectors stored
 
 Done in 4.2s - 623 symbols, 1847 edges, 8 clusters, 34 flows (no embeddings; rerun with --embed for semantic search)
+Publishing read replica...     MCP will reload automatically
 ```
 
+Each analysis phase streams live progress in place. The final step publishes a read replica so the MCP daemon picks up the new index without restarting.
+
 Search the index:
 
 ```bash
@@ -284,9 +296,22 @@ When a dirty overlay exists, deep-analysis results intentionally exclude those u
 
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
+## Concurrent Indexing and Querying
+
+The indexer (write) and the MCP daemon (read) use separate database paths:
+
+- The indexer writes to `~/.codespine_db` with a 512 MB buffer pool.
+- When indexing completes, `analyse` atomically copies the database to `~/.codespine_db_read` and touches a sentinel file.
+- The MCP daemon and all read-only CLI commands open `~/.codespine_db_read` with a 128 MB buffer pool.
+- The MCP daemon watches the sentinel file and silently reloads from the new snapshot on the next tool call — no restart needed.
+
+Running `codespine analyse --deep --embed` on one project while querying a different one no longer causes buffer pool OOM or lock contention.
+
 ## Runtime Files
 
-- `~/.codespine_db` - graph database
+- `~/.codespine_db` - graph database (write)
+- `~/.codespine_db_read` - read replica used by MCP and CLI queries
+- `~/.codespine_db_read.updated` - sentinel file; touched after each successful snapshot
 - `~/.codespine.pid` - MCP background server PID
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
@@ -297,8 +322,9 @@ When a dirty overlay exists, deep-analysis results intentionally exclude those u
 
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
 - `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
-- `codespine clear-index` rebuilds the local index database from scratch.
+- `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
+- The first run after upgrading to v0.5.7 will not have a read replica yet. Run `codespine analyse` once to create it.
 
 ## Project Docs
 

{codespine-0.5.6 → codespine-0.5.8}/README.md

@@ -8,6 +8,8 @@ It indexes classes, methods, calls, type relationships, cross-module links, git
 
 It also keeps a separate dirty overlay for uncommitted Java edits, so agents can query current work-in-progress without forcing the committed base index to churn on every save.
 
+The MCP daemon and the indexer run independently. Querying while a full re-index is running no longer causes crashes or memory contention — reads go to an isolated snapshot that is atomically updated when indexing completes.
+
 ## Why It Saves Tokens
 
 - One MCP call can replace many file opens. `get_symbol_context("PaymentService")` returns a resolved neighborhood instead of forcing the agent to read every caller and callee file manually.
@@ -37,6 +39,8 @@ pip install "codespine[ml]"
 - Community detection: structural clusters for architectural context
 - Change coupling: git-history-based file relationships
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
+- Cross-module call linking: signature-based detection of calls between Maven/Gradle modules
+- Concurrent read/write isolation: MCP queries run against a read replica; the indexer writes separately, with no memory contention
 - MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
 ## Editing Without Stale Indexes
@@ -95,15 +99,23 @@ Parsing code...                8/8
 Tracing calls...               847 calls resolved
 Analyzing types...             234 type relationships
 Cross-module linking...        skipped (single module)
+Detecting communities...       loading symbols
+Detecting communities...       623 symbols, 1204 structural edges
+Detecting communities...       persisting 8/8 clusters
 Detecting communities...       8 clusters found
+Detecting execution flows...   34 entry points, tracing
 Detecting execution flows...   34 processes found
 Finding dead code...           12 unreachable symbols
+Analyzing git history...       18 commits, computing co-changes
 Analyzing git history...       18 coupled file pairs
 Generating embeddings...       0 vectors stored
 
 Done in 4.2s - 623 symbols, 1847 edges, 8 clusters, 34 flows (no embeddings; rerun with --embed for semantic search)
+Publishing read replica...     MCP will reload automatically
 ```
 
+Each analysis phase streams live progress in place. The final step publishes a read replica so the MCP daemon picks up the new index without restarting.
+
 Search the index:
 
 ```bash
@@ -220,9 +232,22 @@ When a dirty overlay exists, deep-analysis results intentionally exclude those u
 
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
+## Concurrent Indexing and Querying
+
+The indexer (write) and the MCP daemon (read) use separate database paths:
+
+- The indexer writes to `~/.codespine_db` with a 512 MB buffer pool.
+- When indexing completes, `analyse` atomically copies the database to `~/.codespine_db_read` and touches a sentinel file.
+- The MCP daemon and all read-only CLI commands open `~/.codespine_db_read` with a 128 MB buffer pool.
+- The MCP daemon watches the sentinel file and silently reloads from the new snapshot on the next tool call — no restart needed.
+
+Running `codespine analyse --deep --embed` on one project while querying a different one no longer causes buffer pool OOM or lock contention.
+
 ## Runtime Files
 
-- `~/.codespine_db` - graph database
+- `~/.codespine_db` - graph database (write)
+- `~/.codespine_db_read` - read replica used by MCP and CLI queries
+- `~/.codespine_db_read.updated` - sentinel file; touched after each successful snapshot
 - `~/.codespine.pid` - MCP background server PID
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
@@ -233,8 +258,9 @@ When a dirty overlay exists, deep-analysis results intentionally exclude those u
 
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
 - `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
-- `codespine clear-index` rebuilds the local index database from scratch.
+- `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
+- The first run after upgrading to v0.5.7 will not have a read replica yet. Run `codespine analyse` once to create it.
 
 ## Project Docs
 

{codespine-0.5.6 → codespine-0.5.8}/codespine/__init__.py

@@ -1,4 +1,4 @@
 """CodeSpine package."""
 
 __all__ = ["__version__"]
-__version__ = "0.5.6"
+__version__ = "0.5.8"

{codespine-0.5.6 → codespine-0.5.8}/codespine/cli.py

@@ -319,6 +319,16 @@ def analyse(path: str, full: bool, deep: bool, embed: bool, allow_running: bool)
         fg="green",
     )
 
+    # Publish a read replica so MCP and read-only CLI commands (search, stats…)
+    # run against an isolated snapshot rather than competing with the write
+    # process's buffer pool.  The MCP daemon detects the sentinel file and
+    # hot-reloads without restarting.
+    snap_label = "Publishing read replica..."
+    _live_phase(snap_label, "copying")
+    store._recycle_conn()
+    snapped = GraphStore.snapshot_to_read_replica()
+    _finish_phase(snap_label, "MCP will reload automatically" if snapped else "skipped (source DB not found)")
+
 
 @main.command()
 @click.argument("query")
@@ -462,19 +472,43 @@ def stats(as_json: bool) -> None:
             "MATCH (f:File) WHERE f.project_id = $pid RETURN count(f) as n", {"pid": pid}
         )
         classes = store.query_records(
-            "MATCH (c:Class), (f:File) WHERE c.file_id = f.id AND f.project_id = $pid RETURN count(c) as n",
+            """
+            MATCH (f:File) WHERE f.project_id = $pid
+            WITH f
+            MATCH (c:Class) WHERE c.file_id = f.id
+            RETURN count(c) as n
+            """,
             {"pid": pid},
         )
         methods = store.query_records(
-            "MATCH (m:Method), (c:Class), (f:File) WHERE m.class_id = c.id AND c.file_id = f.id AND f.project_id = $pid RETURN count(m) as n",
+            """
+            MATCH (f:File) WHERE f.project_id = $pid
+            WITH f
+            MATCH (c:Class) WHERE c.file_id = f.id
+            WITH c
+            MATCH (c)-[:HAS_METHOD]->(m:Method)
+            RETURN count(m) as n
+            """,
             {"pid": pid},
         )
         calls = store.query_records(
-            "MATCH (ma:Method)-[:CALLS]->(mb:Method), (ca:Class), (fa:File) WHERE ma.class_id = ca.id AND ca.file_id = fa.id AND fa.project_id = $pid RETURN count(*) as n",
+            """
+            MATCH (f:File) WHERE f.project_id = $pid
+            WITH f
+            MATCH (c:Class) WHERE c.file_id = f.id
+            WITH c
+            MATCH (c)-[:HAS_METHOD]->(m:Method)-[:CALLS]->()
+            RETURN count(*) as n
+            """,
             {"pid": pid},
         )
         emb = store.query_records(
-            "MATCH (s:Symbol), (f:File) WHERE s.file_id = f.id AND f.project_id = $pid AND s.embedding IS NOT NULL RETURN count(s) as n",
+            """
+            MATCH (f:File) WHERE f.project_id = $pid
+            WITH f
+            MATCH (s:Symbol) WHERE s.file_id = f.id AND s.embedding IS NOT NULL
+            RETURN count(s) as n
+            """,
             {"pid": pid},
         )
         rows.append({

{codespine-0.5.6 → codespine-0.5.8}/codespine/config.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 @dataclass(frozen=True)
 class Settings:
     db_path: str = os.path.expanduser("~/.codespine_db")
+    db_snapshot_path: str = os.path.expanduser("~/.codespine_db_read")
     pid_file: str = os.path.expanduser("~/.codespine.pid")
     log_file: str = os.path.expanduser("~/.codespine.log")
     embedding_cache_path: str = os.path.expanduser("~/.codespine_embedding_cache.json")

{codespine-0.5.6 → codespine-0.5.8}/codespine/db/store.py

@@ -18,7 +18,8 @@ from codespine.db.schema import ensure_schema
 
 LOGGER = logging.getLogger(__name__)
 
-_BUFFER_POOL_SIZE = 512 * 1024 * 1024  # 512 MB – room for large community detection
+_WRITE_BUFFER_POOL_SIZE = 512 * 1024 * 1024  # 512 MB – room for large community detection
+_READ_BUFFER_POOL_SIZE = 128 * 1024 * 1024   # 128 MB – point queries only; keep footprint small
 _RECOVERABLE_DB_ERROR_MARKERS = (
     "storage version mismatch",
     "catalog version mismatch",
@@ -35,11 +36,18 @@ class GraphStore:
     read_only: bool = False
 
     def __post_init__(self) -> None:
-        db_path = SETTINGS.db_path
         self._tls: threading.local = threading.local()
         from codespine.overlay.store import OverlayStore
 
         self.overlay_store = OverlayStore()
+
+        # Read-only callers (MCP, CLI reads) use the read replica when available.
+        # This isolates them from the write process's buffer pool and WAL churn.
+        if self.read_only and os.path.exists(SETTINGS.db_snapshot_path):
+            db_path = SETTINGS.db_snapshot_path
+        else:
+            db_path = SETTINGS.db_path
+
         try:
             self.db = self._open_with_recovery(db_path)
         except Exception as exc:
@@ -50,11 +58,12 @@ class GraphStore:
             self._ensure_schema_with_recovery()
 
     def _open_db(self, path: str) -> kuzu.Database:
+        pool = _READ_BUFFER_POOL_SIZE if self.read_only else _WRITE_BUFFER_POOL_SIZE
         # Newer Kuzu versions accept read_only; fall back for older ones.
         try:
-            return kuzu.Database(path, buffer_pool_size=_BUFFER_POOL_SIZE, read_only=self.read_only)
+            return kuzu.Database(path, buffer_pool_size=pool, read_only=self.read_only)
         except TypeError:
-            return kuzu.Database(path, buffer_pool_size=_BUFFER_POOL_SIZE)
+            return kuzu.Database(path, buffer_pool_size=pool)
 
     @staticmethod
     def _is_recoverable_db_error(exc: Exception) -> bool:
@@ -553,6 +562,41 @@ class GraphStore:
             },
         )
 
+    @staticmethod
+    def snapshot_to_read_replica() -> bool:
+        """Atomically copy the write DB to the read-replica path.
+
+        The read replica is used by the MCP daemon and all read-only CLI
+        commands so they never contend with the write process's buffer pool.
+        Returns True on success, False if the source DB does not exist.
+        """
+        src = SETTINGS.db_path
+        dst = SETTINGS.db_snapshot_path
+        if not os.path.exists(src):
+            return False
+        tmp = dst + ".tmp"
+        try:
+            if os.path.exists(tmp):
+                shutil.rmtree(tmp, ignore_errors=True)
+            if os.path.isdir(src):
+                shutil.copytree(src, tmp)
+            else:
+                os.makedirs(os.path.dirname(dst) or ".", exist_ok=True)
+                shutil.copy2(src, tmp)
+            if os.path.exists(dst):
+                shutil.rmtree(dst, ignore_errors=True)
+            os.rename(tmp, dst)
+            # Sentinel: MCP daemon watches this file's mtime to know when to reload.
+            sentinel = dst + ".updated"
+            with open(sentinel, "w", encoding="utf-8") as f:
+                f.write(str(int(time.time())))
+            return True
+        except Exception as exc:
+            LOGGER.warning("Snapshot to read replica failed: %s", exc)
+            if os.path.exists(tmp):
+                shutil.rmtree(tmp, ignore_errors=True)
+            return False
+
     def query_records(self, query: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
         frame = self.execute(query, params or {}).get_as_df()
         if frame.empty:

{codespine-0.5.6 → codespine-0.5.8}/codespine/mcp/server.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import json as _json_mod
+import logging
+import os
 import subprocess
 import sys
 import tempfile
@@ -8,6 +10,10 @@ import time
 
 from fastmcp import FastMCP
 
+from codespine.config import SETTINGS
+
+_LOGGER = logging.getLogger(__name__)
+
 from codespine import __version__
 from codespine.analysis.community import detect_communities, symbol_community
 from codespine.analysis.context import build_symbol_context
@@ -129,7 +135,47 @@ def _staleness_meta(
     return _json(response)
 
 
+class _StoreProxy:
+    """Wraps a GraphStore and hot-reloads from the read replica when the
+    post-analyse sentinel file is touched.
+
+    After `codespine analyse` finishes it copies the write DB to
+    ``~/.codespine_db_read`` and writes ``~/.codespine_db_read.updated``.
+    This proxy checks that sentinel's mtime before every attribute access and
+    silently swaps in a fresh read-only GraphStore so the MCP daemon picks up
+    the new index without restarting.
+    """
+
+    def __init__(self, store) -> None:
+        object.__setattr__(self, "_store", store)
+        object.__setattr__(self, "_sentinel", SETTINGS.db_snapshot_path + ".updated")
+        object.__setattr__(self, "_last_mtime", self._sentinel_mtime())
+
+    def _sentinel_mtime(self) -> float:
+        try:
+            return os.path.getmtime(object.__getattribute__(self, "_sentinel"))
+        except FileNotFoundError:
+            return 0.0
+
+    def _maybe_reload(self) -> None:
+        current = self._sentinel_mtime()
+        if current > object.__getattribute__(self, "_last_mtime"):
+            from codespine.db.store import GraphStore as _GS
+            try:
+                new_store = _GS(read_only=True)
+                object.__setattr__(self, "_store", new_store)
+                object.__setattr__(self, "_last_mtime", current)
+                _LOGGER.info("MCP: hot-reloaded GraphStore from updated snapshot")
+            except Exception as exc:
+                _LOGGER.warning("MCP: hot-reload failed: %s", exc)
+
+    def __getattr__(self, name: str):
+        self._maybe_reload()
+        return getattr(object.__getattribute__(self, "_store"), name)
+
+
 def build_mcp_server(store, repo_path_provider):
+    store = _StoreProxy(store)
     _raw_mcp = FastMCP("codespine")
     overlay_store = getattr(store, "overlay_store", None)
 

{codespine-0.5.6 → codespine-0.5.8}/codespine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.5.6
+Version: 0.5.8
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -72,6 +72,8 @@ It indexes classes, methods, calls, type relationships, cross-module links, git
 
 It also keeps a separate dirty overlay for uncommitted Java edits, so agents can query current work-in-progress without forcing the committed base index to churn on every save.
 
+The MCP daemon and the indexer run independently. Querying while a full re-index is running no longer causes crashes or memory contention — reads go to an isolated snapshot that is atomically updated when indexing completes.
+
 ## Why It Saves Tokens
 
 - One MCP call can replace many file opens. `get_symbol_context("PaymentService")` returns a resolved neighborhood instead of forcing the agent to read every caller and callee file manually.
@@ -101,6 +103,8 @@ pip install "codespine[ml]"
 - Community detection: structural clusters for architectural context
 - Change coupling: git-history-based file relationships
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
+- Cross-module call linking: signature-based detection of calls between Maven/Gradle modules
+- Concurrent read/write isolation: MCP queries run against a read replica; the indexer writes separately, with no memory contention
 - MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
 ## Editing Without Stale Indexes
@@ -159,15 +163,23 @@ Parsing code...                8/8
 Tracing calls...               847 calls resolved
 Analyzing types...             234 type relationships
 Cross-module linking...        skipped (single module)
+Detecting communities...       loading symbols
+Detecting communities...       623 symbols, 1204 structural edges
+Detecting communities...       persisting 8/8 clusters
 Detecting communities...       8 clusters found
+Detecting execution flows...   34 entry points, tracing
 Detecting execution flows...   34 processes found
 Finding dead code...           12 unreachable symbols
+Analyzing git history...       18 commits, computing co-changes
 Analyzing git history...       18 coupled file pairs
 Generating embeddings...       0 vectors stored
 
 Done in 4.2s - 623 symbols, 1847 edges, 8 clusters, 34 flows (no embeddings; rerun with --embed for semantic search)
+Publishing read replica...     MCP will reload automatically
 ```
 
+Each analysis phase streams live progress in place. The final step publishes a read replica so the MCP daemon picks up the new index without restarting.
+
 Search the index:
 
 ```bash
@@ -284,9 +296,22 @@ When a dirty overlay exists, deep-analysis results intentionally exclude those u
 
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
+## Concurrent Indexing and Querying
+
+The indexer (write) and the MCP daemon (read) use separate database paths:
+
+- The indexer writes to `~/.codespine_db` with a 512 MB buffer pool.
+- When indexing completes, `analyse` atomically copies the database to `~/.codespine_db_read` and touches a sentinel file.
+- The MCP daemon and all read-only CLI commands open `~/.codespine_db_read` with a 128 MB buffer pool.
+- The MCP daemon watches the sentinel file and silently reloads from the new snapshot on the next tool call — no restart needed.
+
+Running `codespine analyse --deep --embed` on one project while querying a different one no longer causes buffer pool OOM or lock contention.
+
 ## Runtime Files
 
-- `~/.codespine_db` - graph database
+- `~/.codespine_db` - graph database (write)
+- `~/.codespine_db_read` - read replica used by MCP and CLI queries
+- `~/.codespine_db_read.updated` - sentinel file; touched after each successful snapshot
 - `~/.codespine.pid` - MCP background server PID
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
@@ -297,8 +322,9 @@ When a dirty overlay exists, deep-analysis results intentionally exclude those u
 
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
 - `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
-- `codespine clear-index` rebuilds the local index database from scratch.
+- `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
+- The first run after upgrading to v0.5.7 will not have a read replica yet. Run `codespine analyse` once to create it.
 
 ## Project Docs
 

{codespine-0.5.6 → codespine-0.5.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codespine"
-version = "0.5.6"
+version = "0.5.8"
 description = "Local Java code intelligence indexer backed by a graph database"
 readme = "README.md"
 requires-python = ">=3.10"