codespine 0.5.5__tar.gz → 0.5.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.5.5
+Version: 0.5.6
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -70,12 +70,15 @@ Instead of having an agent open dozens of `.java` files to answer one question,
 
 It indexes classes, methods, calls, type relationships, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
 
+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.
+
 ## 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.
 - Search is structure-aware. Agents can ask for a symbol, concept, impact radius, or dead-code candidate without scanning entire packages.
 - Multi-module repos stay scoped. Project-aware IDs and `project=` parameters reduce noise from unrelated modules and workspaces.
 - Repeat sessions get cheaper. Once indexed, the agent reuses the graph instead of re-discovering the same relationships every turn.
+- Active edits stay smooth. Dirty files are kept in an overlay and merged into fast queries until you commit, instead of hammering the main graph DB on each change.
 
 ## Install
 
@@ -100,6 +103,32 @@ pip install "codespine[ml]"
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
 - MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
+## Editing Without Stale Indexes
+
+CodeSpine uses a two-layer model:
+
+- Base index: last committed state
+- Dirty overlay: uncommitted Java changes
+
+Fast tools read merged `base + overlay` state by default:
+
+- `search`
+- `context`
+- `impact`
+- MCP `search_hybrid`
+- MCP `find_symbol`
+- MCP `get_symbol_context`
+- MCP `get_impact`
+
+Deep analyses stay committed-only until promotion:
+
+- `deadcode`
+- `flow`
+- `community`
+- `coupling`
+
+`codespine watch` updates the dirty overlay after a debounce window, then promotes it into the base index when local `HEAD` changes.
+
 ## Quick Start
 
 Index a repo:
@@ -205,6 +234,7 @@ codespine analyse <path> --full
 codespine analyse <path> --deep
 codespine analyse <path> --embed
 codespine watch --path .
+codespine watch --path . --overlay-debounce-ms 1500
 codespine search "query"
 codespine context "symbol"
 codespine impact "symbol"
@@ -215,6 +245,9 @@ codespine coupling
 codespine diff main..feature
 codespine stats
 codespine list
+codespine overlay-status
+codespine overlay-promote
+codespine overlay-clear
 codespine clear-project <project_id>
 codespine clear-index
 ```
@@ -247,6 +280,8 @@ That same project ID can be passed into MCP tools and CLI analysis calls that su
 
 Use it when you want architecture-level context. Skip it when you just need the graph refreshed for search, context, and impact.
 
+When a dirty overlay exists, deep-analysis results intentionally exclude those uncommitted edits until promotion.
+
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
 ## Runtime Files
@@ -256,10 +291,12 @@ Use it when you want architecture-level context. Skip it when you just need the
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
 - `~/.codespine_index_meta/` - incremental file metadata cache
+- `~/.codespine_overlay/` - uncommitted dirty overlay state
 
 ## Notes
 
 - `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.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
 

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

@@ -6,12 +6,15 @@ Instead of having an agent open dozens of `.java` files to answer one question,
 
 It indexes classes, methods, calls, type relationships, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
 
+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.
+
 ## 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.
 - Search is structure-aware. Agents can ask for a symbol, concept, impact radius, or dead-code candidate without scanning entire packages.
 - Multi-module repos stay scoped. Project-aware IDs and `project=` parameters reduce noise from unrelated modules and workspaces.
 - Repeat sessions get cheaper. Once indexed, the agent reuses the graph instead of re-discovering the same relationships every turn.
+- Active edits stay smooth. Dirty files are kept in an overlay and merged into fast queries until you commit, instead of hammering the main graph DB on each change.
 
 ## Install
 
@@ -36,6 +39,32 @@ pip install "codespine[ml]"
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
 - MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
+## Editing Without Stale Indexes
+
+CodeSpine uses a two-layer model:
+
+- Base index: last committed state
+- Dirty overlay: uncommitted Java changes
+
+Fast tools read merged `base + overlay` state by default:
+
+- `search`
+- `context`
+- `impact`
+- MCP `search_hybrid`
+- MCP `find_symbol`
+- MCP `get_symbol_context`
+- MCP `get_impact`
+
+Deep analyses stay committed-only until promotion:
+
+- `deadcode`
+- `flow`
+- `community`
+- `coupling`
+
+`codespine watch` updates the dirty overlay after a debounce window, then promotes it into the base index when local `HEAD` changes.
+
 ## Quick Start
 
 Index a repo:
@@ -141,6 +170,7 @@ codespine analyse <path> --full
 codespine analyse <path> --deep
 codespine analyse <path> --embed
 codespine watch --path .
+codespine watch --path . --overlay-debounce-ms 1500
 codespine search "query"
 codespine context "symbol"
 codespine impact "symbol"
@@ -151,6 +181,9 @@ codespine coupling
 codespine diff main..feature
 codespine stats
 codespine list
+codespine overlay-status
+codespine overlay-promote
+codespine overlay-clear
 codespine clear-project <project_id>
 codespine clear-index
 ```
@@ -183,6 +216,8 @@ That same project ID can be passed into MCP tools and CLI analysis calls that su
 
 Use it when you want architecture-level context. Skip it when you just need the graph refreshed for search, context, and impact.
 
+When a dirty overlay exists, deep-analysis results intentionally exclude those uncommitted edits until promotion.
+
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
 ## Runtime Files
@@ -192,10 +227,12 @@ Use it when you want architecture-level context. Skip it when you just need the
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
 - `~/.codespine_index_meta/` - incremental file metadata cache
+- `~/.codespine_overlay/` - uncommitted dirty overlay state
 
 ## Notes
 
 - `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.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
 

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

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

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

@@ -19,6 +19,15 @@ from codespine.db.schema import ensure_schema
 LOGGER = logging.getLogger(__name__)
 
 _BUFFER_POOL_SIZE = 512 * 1024 * 1024  # 512 MB – room for large community detection
+_RECOVERABLE_DB_ERROR_MARKERS = (
+    "storage version mismatch",
+    "catalog version mismatch",
+    "database version is not supported",
+    "wal version mismatch",
+    "corrupt",
+    "corrupted",
+    "invalid database",
+)
 
 
 @dataclass
@@ -32,13 +41,13 @@ class GraphStore:
 
         self.overlay_store = OverlayStore()
         try:
-            self.db = self._open_db(db_path)
+            self.db = self._open_with_recovery(db_path)
         except Exception as exc:
             fallback = os.path.join("/tmp", ".codespine_db")
             LOGGER.warning("Primary DB path failed (%s). Falling back to %s", exc, fallback)
-            self.db = self._open_db(fallback)
+            self.db = self._open_with_recovery(fallback)
         if not self.read_only:
-            ensure_schema(self._conn())
+            self._ensure_schema_with_recovery()
 
     def _open_db(self, path: str) -> kuzu.Database:
         # Newer Kuzu versions accept read_only; fall back for older ones.
@@ -47,6 +56,42 @@ class GraphStore:
         except TypeError:
             return kuzu.Database(path, buffer_pool_size=_BUFFER_POOL_SIZE)
 
+    @staticmethod
+    def _is_recoverable_db_error(exc: Exception) -> bool:
+        message = str(exc).lower()
+        return any(marker in message for marker in _RECOVERABLE_DB_ERROR_MARKERS)
+
+    @staticmethod
+    def _remove_db_path(path: str) -> None:
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        elif os.path.exists(path):
+            os.remove(path)
+
+    def _open_with_recovery(self, path: str) -> kuzu.Database:
+        try:
+            return self._open_db(path)
+        except Exception as exc:
+            if not self._is_recoverable_db_error(exc):
+                raise
+            LOGGER.warning("Removing corrupted or incompatible Kuzu DB at %s: %s", path, exc)
+            self._remove_db_path(path)
+            self._tls = threading.local()
+            return self._open_db(path)
+
+    def _ensure_schema_with_recovery(self) -> None:
+        try:
+            ensure_schema(self._conn())
+        except Exception as exc:
+            path = getattr(self.db, "database_path", SETTINGS.db_path)
+            if not self._is_recoverable_db_error(exc):
+                raise
+            LOGGER.warning("Rebuilding corrupted or incompatible Kuzu DB at %s during schema init: %s", path, exc)
+            self._remove_db_path(path)
+            self.db = self._open_db(path)
+            self._tls = threading.local()
+            ensure_schema(self._conn())
+
     def _conn(self) -> kuzu.Connection:
         """Return the per-thread Kuzu connection, creating it lazily."""
         if not hasattr(self._tls, "conn") or self._tls.conn is None:
@@ -447,16 +492,10 @@ class GraphStore:
         self._recycle_conn()
         path = SETTINGS.db_path
         try:
-            if os.path.isdir(path):
-                shutil.rmtree(path, ignore_errors=True)
-            elif os.path.exists(path):
-                os.remove(path)
+            self._remove_db_path(path)
         except OSError:
             fallback = os.path.join("/tmp", ".codespine_db")
-            if os.path.isdir(fallback):
-                shutil.rmtree(fallback, ignore_errors=True)
-            elif os.path.exists(fallback):
-                os.remove(fallback)
+            self._remove_db_path(fallback)
             self.db = self._open_db(fallback)
         else:
             self.db = self._open_db(path)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.5.5
+Version: 0.5.6
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -70,12 +70,15 @@ Instead of having an agent open dozens of `.java` files to answer one question,
 
 It indexes classes, methods, calls, type relationships, cross-module links, git coupling, dead-code candidates, and execution flows so agents can work from graph answers first and source files second.
 
+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.
+
 ## 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.
 - Search is structure-aware. Agents can ask for a symbol, concept, impact radius, or dead-code candidate without scanning entire packages.
 - Multi-module repos stay scoped. Project-aware IDs and `project=` parameters reduce noise from unrelated modules and workspaces.
 - Repeat sessions get cheaper. Once indexed, the agent reuses the graph instead of re-discovering the same relationships every turn.
+- Active edits stay smooth. Dirty files are kept in an overlay and merged into fast queries until you commit, instead of hammering the main graph DB on each change.
 
 ## Install
 
@@ -100,6 +103,32 @@ pip install "codespine[ml]"
 - Multi-project and multi-module indexing: workspaces, Maven modules, Gradle subprojects
 - MCP server: structured tools for Claude, Cursor, Cline, Copilot, and similar clients
 
+## Editing Without Stale Indexes
+
+CodeSpine uses a two-layer model:
+
+- Base index: last committed state
+- Dirty overlay: uncommitted Java changes
+
+Fast tools read merged `base + overlay` state by default:
+
+- `search`
+- `context`
+- `impact`
+- MCP `search_hybrid`
+- MCP `find_symbol`
+- MCP `get_symbol_context`
+- MCP `get_impact`
+
+Deep analyses stay committed-only until promotion:
+
+- `deadcode`
+- `flow`
+- `community`
+- `coupling`
+
+`codespine watch` updates the dirty overlay after a debounce window, then promotes it into the base index when local `HEAD` changes.
+
 ## Quick Start
 
 Index a repo:
@@ -205,6 +234,7 @@ codespine analyse <path> --full
 codespine analyse <path> --deep
 codespine analyse <path> --embed
 codespine watch --path .
+codespine watch --path . --overlay-debounce-ms 1500
 codespine search "query"
 codespine context "symbol"
 codespine impact "symbol"
@@ -215,6 +245,9 @@ codespine coupling
 codespine diff main..feature
 codespine stats
 codespine list
+codespine overlay-status
+codespine overlay-promote
+codespine overlay-clear
 codespine clear-project <project_id>
 codespine clear-index
 ```
@@ -247,6 +280,8 @@ That same project ID can be passed into MCP tools and CLI analysis calls that su
 
 Use it when you want architecture-level context. Skip it when you just need the graph refreshed for search, context, and impact.
 
+When a dirty overlay exists, deep-analysis results intentionally exclude those uncommitted edits until promotion.
+
 `--embed` is also optional. Without it, CodeSpine still supports exact, keyword, and fuzzy search. Add embeddings when you need concept-level retrieval.
 
 ## Runtime Files
@@ -256,10 +291,12 @@ Use it when you want architecture-level context. Skip it when you just need the
 - `~/.codespine.log` - server log
 - `~/.codespine_embedding_cache.json` - embedding cache
 - `~/.codespine_index_meta/` - incremental file metadata cache
+- `~/.codespine_overlay/` - uncommitted dirty overlay state
 
 ## Notes
 
 - `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.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
 

{codespine-0.5.5 → codespine-0.5.6}/codespine.egg-info/SOURCES.txt

@@ -53,4 +53,5 @@ tests/test_index_and_hybrid.py
 tests/test_java_parser.py
 tests/test_multimodule_index.py
 tests/test_overlay.py
-tests/test_search_ranking.py
+tests/test_search_ranking.py
+tests/test_store_recovery.py

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

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

codespine-0.5.6/tests/test_store_recovery.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip("kuzu")
+
+from codespine.db.store import GraphStore
+
+
+def test_open_with_recovery_rebuilds_legacy_db(monkeypatch):
+    opened: list[str] = []
+    removed: list[str] = []
+    calls = {"count": 0}
+
+    def fake_open(self, path: str):
+        calls["count"] += 1
+        opened.append(path)
+        if calls["count"] == 1:
+            raise RuntimeError("Storage version mismatch: unsupported database")
+        return object()
+
+    monkeypatch.setattr(GraphStore, "_open_db", fake_open)
+    monkeypatch.setattr(GraphStore, "_remove_db_path", staticmethod(lambda path: removed.append(path)))
+
+    store = GraphStore.__new__(GraphStore)
+    store.read_only = False
+    store._tls = None
+
+    db = GraphStore._open_with_recovery(store, "/tmp/test-codespine-db")
+
+    assert db is not None
+    assert opened == ["/tmp/test-codespine-db", "/tmp/test-codespine-db"]
+    assert removed == ["/tmp/test-codespine-db"]
+
+
+def test_open_with_recovery_does_not_remove_on_permission_error(monkeypatch):
+    removed: list[str] = []
+
+    def fake_open(self, path: str):
+        raise RuntimeError("Operation not permitted")
+
+    monkeypatch.setattr(GraphStore, "_open_db", fake_open)
+    monkeypatch.setattr(GraphStore, "_remove_db_path", staticmethod(lambda path: removed.append(path)))
+
+    store = GraphStore.__new__(GraphStore)
+    store.read_only = False
+    store._tls = None
+
+    with pytest.raises(RuntimeError, match="Operation not permitted"):
+        GraphStore._open_with_recovery(store, "/tmp/test-codespine-db")
+
+    assert removed == []