codespine 0.5.4__tar.gz → 0.5.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.5.4
+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.4 → 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.4 → codespine-0.5.6}/codespine/__init__.py

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

{codespine-0.5.4 → codespine-0.5.6}/codespine/analysis/impact.py

@@ -2,22 +2,36 @@ from __future__ import annotations
 
 from collections import defaultdict, deque
 
+from codespine.overlay.merge import merged_call_edges, merged_method_records, merged_symbol_records
+
 
 def _resolve_symbol_ids(store, symbol_query: str, project: str | None = None) -> list[str]:
-    project_clause = "AND f.project_id = $proj" if project else ""
-    params: dict = {"q": symbol_query}
-    if project:
-        params["proj"] = project
-    recs = store.query_records(
-        f"""
-        MATCH (s:Symbol), (f:File)
-        WHERE s.file_id = f.id {project_clause}
-        AND (s.id = $q OR lower(s.name) = lower($q) OR lower(s.fqname) = lower($q) OR lower(s.fqname) CONTAINS lower($q))
-        RETURN s.id as id
-        LIMIT 50
-        """,
-        params,
-    )
+    overlay_store = getattr(store, "overlay_store", None)
+    if overlay_store is not None:
+        recs = []
+        needle = symbol_query.lower()
+        for rec in merged_symbol_records(store, overlay_store, project=project):
+            name = str(rec.get("name") or "").lower()
+            fqname = str(rec.get("fqname") or "").lower()
+            if rec.get("id") == symbol_query or name == needle or fqname == needle or needle in fqname:
+                recs.append({"id": rec["id"]})
+                if len(recs) >= 50:
+                    break
+    else:
+        project_clause = "AND f.project_id = $proj" if project else ""
+        params: dict = {"q": symbol_query}
+        if project:
+            params["proj"] = project
+        recs = store.query_records(
+            f"""
+            MATCH (s:Symbol), (f:File)
+            WHERE s.file_id = f.id {project_clause}
+            AND (s.id = $q OR lower(s.name) = lower($q) OR lower(s.fqname) = lower($q) OR lower(s.fqname) CONTAINS lower($q))
+            RETURN s.id as id
+            LIMIT 50
+            """,
+            params,
+        )
     return [r["id"] for r in recs]
 
 
@@ -30,15 +44,21 @@ def _resolve_method_metadata(store, method_ids: list[str]) -> dict[str, dict]:
     """
     if not method_ids:
         return {}
-    recs = store.query_records(
-        """
-        MATCH (m:Method), (c:Class), (f:File)
-        WHERE m.id IN $ids AND m.class_id = c.id AND c.file_id = f.id
-        RETURN m.id as id, m.name as name, m.signature as fqname,
-               c.fqcn as class_fqcn, f.path as file_path, f.project_id as project_id
-        """,
-        {"ids": method_ids},
-    )
+    overlay_store = getattr(store, "overlay_store", None)
+    if overlay_store is not None:
+        recs = [r for r in merged_method_records(store, overlay_store) if r.get("id") in set(method_ids)]
+        for rec in recs:
+            rec["fqname"] = rec.get("signature")
+    else:
+        recs = store.query_records(
+            """
+            MATCH (m:Method), (c:Class), (f:File)
+            WHERE m.id IN $ids AND m.class_id = c.id AND c.file_id = f.id
+            RETURN m.id as id, m.name as name, m.signature as fqname,
+                   c.fqcn as class_fqcn, f.path as file_path, f.project_id as project_id
+            """,
+            {"ids": method_ids},
+        )
     return {r["id"]: r for r in recs}
 
 
@@ -47,16 +67,33 @@ def analyze_impact(store, symbol_query: str, max_depth: int = 4, project: str |
     if not target_symbol_ids:
         return {"target": symbol_query, "depth_groups": {"1": [], "2": [], "3+": []}}
 
-    symbol_to_method = {
-        r["sid"]: r["mid"]
-        for r in store.query_records(
-            """
-            MATCH (s:Symbol),(m:Method)
-            WHERE s.kind = 'method' AND s.fqname CONTAINS m.signature
-            RETURN s.id as sid, m.id as mid
-            """
-        )
-    }
+    overlay_store = getattr(store, "overlay_store", None)
+    if overlay_store is not None:
+        methods = merged_method_records(store, overlay_store, project=project)
+        symbols = merged_symbol_records(store, overlay_store, project=project)
+        fqname_and_file_to_method = {
+            (f"{rec.get('class_fqcn')}#{rec.get('signature')}", rec.get("file_id")): rec["id"]
+            for rec in methods
+        }
+        symbol_to_method = {}
+        for rec in symbols:
+            if rec.get("kind") != "method":
+                continue
+            method_key = (rec.get("fqname"), rec.get("file_id"))
+            method_id = fqname_and_file_to_method.get(method_key)
+            if method_id:
+                symbol_to_method[rec["id"]] = method_id
+    else:
+        symbol_to_method = {
+            r["sid"]: r["mid"]
+            for r in store.query_records(
+                """
+                MATCH (s:Symbol),(m:Method)
+                WHERE s.kind = 'method' AND s.fqname CONTAINS m.signature
+                RETURN s.id as sid, m.id as mid
+                """
+            )
+        }
 
     target_method_ids = [symbol_to_method[sid] for sid in target_symbol_ids if sid in symbol_to_method]
     if not target_method_ids:
@@ -64,14 +101,19 @@ def analyze_impact(store, symbol_query: str, max_depth: int = 4, project: str |
 
     # Load all call edges – cross-project callers are included intentionally so
     # impact analysis surfaces inter-module dependencies.
-    edges = store.query_records(
-        """
-        MATCH (a:Method)-[r:CALLS]->(b:Method)
-        RETURN a.id as src, b.id as dst, 'CALLS' as edge_type,
-               coalesce(r.confidence, 0.5) as confidence,
-               coalesce(r.reason, 'unknown') as reason
-        """
-    )
+    if overlay_store is not None:
+        edges = merged_call_edges(store, overlay_store, project=project)
+        for edge in edges:
+            edge["edge_type"] = "CALLS"
+    else:
+        edges = store.query_records(
+            """
+            MATCH (a:Method)-[r:CALLS]->(b:Method)
+            RETURN a.id as src, b.id as dst, 'CALLS' as edge_type,
+                   coalesce(r.confidence, 0.5) as confidence,
+                   coalesce(r.reason, 'unknown') as reason
+            """
+        )
 
     reverse_adj: dict[str, list[dict]] = defaultdict(list)
     for edge in edges:

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

@@ -24,7 +24,7 @@ from codespine.diff.branch_diff import compare_branches
 from codespine.indexer.engine import JavaIndexer
 from codespine.mcp.server import build_mcp_server
 from codespine.search.hybrid import hybrid_search
-from codespine.watch.watcher import run_watch_mode
+from codespine.watch.watcher import clear_overlay, get_overlay_status, promote_overlay, run_watch_mode
 
 logging.basicConfig(filename=SETTINGS.log_file, level=logging.INFO)
 LOGGER = logging.getLogger(__name__)
@@ -414,10 +414,23 @@ def coupling(months: int, min_strength: float, min_cochanges: int, as_json: bool
 @main.command()
 @click.option("--path", default=".", show_default=True, type=click.Path(exists=True))
 @click.option("--global-interval", default=30, show_default=True, type=int)
-def watch(path: str, global_interval: int) -> None:
+@click.option(
+    "--overlay-debounce-ms",
+    default=SETTINGS.default_overlay_debounce_ms,
+    show_default=True,
+    type=int,
+)
+@click.option("--promote-on-commit/--no-promote-on-commit", default=True, show_default=True)
+def watch(path: str, global_interval: int, overlay_debounce_ms: int, promote_on_commit: bool) -> None:
     """Live re-indexing and periodic global analysis refresh."""
     store = GraphStore(read_only=False)
-    run_watch_mode(store, os.path.abspath(path), global_interval=global_interval)
+    run_watch_mode(
+        store,
+        os.path.abspath(path),
+        global_interval=global_interval,
+        overlay_debounce_ms=overlay_debounce_ms,
+        promote_on_commit=promote_on_commit,
+    )
 
 
 @main.command()
@@ -521,6 +534,8 @@ def status(as_json: bool) -> None:
                 pid = int(f.read().strip())
         except Exception:
             pid = None
+    store = GraphStore(read_only=True)
+    overlay = get_overlay_status(store)
     payload = {
         "running": running,
         "pid": pid,
@@ -528,10 +543,41 @@ def status(as_json: bool) -> None:
         "db_path": SETTINGS.db_path,
         "db_size_bytes": _db_size_bytes(SETTINGS.db_path),
         "log_file": SETTINGS.log_file,
+        "overlay_dir": SETTINGS.overlay_dir,
+        "overlay_projects": overlay,
     }
     _echo_json(payload, as_json)
 
 
+@main.command("overlay-status")
+@click.option("--project", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def overlay_status_cmd(project: str | None, as_json: bool) -> None:
+    """Show dirty overlay status by project/module."""
+    store = GraphStore(read_only=True)
+    _echo_json(get_overlay_status(store, project=project), as_json)
+
+
+@main.command("overlay-clear")
+@click.option("--project", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def overlay_clear_cmd(project: str | None, as_json: bool) -> None:
+    """Clear dirty overlay data without touching the committed base index."""
+    store = GraphStore(read_only=False)
+    result = {"cleared": clear_overlay(store, project=project)}
+    _echo_json(result, as_json)
+
+
+@main.command("overlay-promote")
+@click.option("--project", default=None)
+@click.option("--json", "as_json", is_flag=True)
+def overlay_promote_cmd(project: str | None, as_json: bool) -> None:
+    """Promote dirty overlay changes into the committed base index now."""
+    store = GraphStore(read_only=False)
+    result = {"promoted": promote_overlay(store, project=project, require_head_change=False)}
+    _echo_json(result, as_json)
+
+
 @main.command()
 @click.argument("query")
 @click.option("--json", "as_json", is_flag=True)
@@ -552,7 +598,7 @@ def clean(force: bool) -> None:
     if not force and not click.confirm("Remove local CodeSpine DB, PID, and logs?"):
         click.echo("Aborted.")
         return
-    for path in [SETTINGS.pid_file, SETTINGS.log_file, SETTINGS.db_path]:
+    for path in [SETTINGS.pid_file, SETTINGS.log_file, SETTINGS.db_path, SETTINGS.overlay_dir]:
         if not os.path.exists(path):
             continue
         if os.path.isdir(path):
@@ -591,6 +637,7 @@ def clear_project_cmd(project_id: str, allow_running: bool) -> None:
     project_path = recs[0].get("path", "")
     store.clear_analysis_artifacts()
     store.clear_project(project_id)
+    store.overlay_store.clear_project(project_id)
     meta_path = JavaIndexer._meta_cache_path(project_id)
     if os.path.exists(meta_path):
         try:
@@ -615,6 +662,7 @@ def clear_index_cmd(allow_running: bool) -> None:
     store = GraphStore(read_only=False)
     projects = store.query_records("MATCH (p:Project) RETURN p.id as id")
     store.rebuild_empty_db()
+    store.overlay_store.clear_all()
     for p in projects:
         meta_path = JavaIndexer._meta_cache_path(p["id"])
         if os.path.exists(meta_path):

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

@@ -9,15 +9,19 @@ class Settings:
     log_file: str = os.path.expanduser("~/.codespine.log")
     embedding_cache_path: str = os.path.expanduser("~/.codespine_embedding_cache.json")
     index_meta_dir: str = os.path.expanduser("~/.codespine_index_meta")
+    overlay_dir: str = os.path.expanduser("~/.codespine_overlay")
     embedding_model: str = "BAAI/bge-small-en-v1.5"
     vector_dim: int = 384
     rrf_k: int = 60
     semantic_candidate_pool: int = 2000
     write_batch_size: int = 500
+    index_file_batch_size: int = 64
+    edge_write_batch_size: int = 2000
     default_coupling_months: int = 6
     default_min_coupling_strength: float = 0.3
     default_min_cochanges: int = 3
     default_global_interval_s: int = 30
+    default_overlay_debounce_ms: int = 1500
 
 
 SETTINGS = Settings()

{codespine-0.5.4 → codespine-0.5.6}/codespine/db/schema.py

@@ -10,7 +10,7 @@ NODE_TABLES: list[tuple[str, str]] = [
     ("SchemaMeta", "CREATE NODE TABLE SchemaMeta(key STRING, value STRING, PRIMARY KEY (key))"),
     (
         "Project",
-        "CREATE NODE TABLE Project(id STRING, path STRING, language STRING, indexed_at STRING, PRIMARY KEY (id))",
+        "CREATE NODE TABLE Project(id STRING, path STRING, language STRING, indexed_at STRING, indexed_commit STRING, overlay_dirty BOOL, PRIMARY KEY (id))",
     ),
     (
         "File",
@@ -81,5 +81,8 @@ def ensure_schema(conn) -> None:
 
     _safe_execute(
         conn,
-        "MERGE (s:SchemaMeta {key: 'schema_version'}) SET s.value = '3'",
+        "MERGE (s:SchemaMeta {key: 'schema_version'}) SET s.value = '4'",
     )
+
+    _safe_execute(conn, "ALTER TABLE Project ADD indexed_commit STRING DEFAULT ''")
+    _safe_execute(conn, "ALTER TABLE Project ADD overlay_dirty BOOL DEFAULT false")