codespine 1.0.10__tar.gz → 1.0.11__tar.gz

{codespine-1.0.10 → codespine-1.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 1.0.10
+Version: 1.0.11
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -66,7 +66,7 @@ Dynamic: license-file
 
 # CodeSpine
 
-**v1.0.10** — Local Java code intelligence for coding agents, backed by a graph database.
+**v1.0.11** — Local Java code intelligence for coding agents, backed by a graph database.
 
 CodeSpine cuts token burn for coding agents working on Java codebases.
 
@@ -111,6 +111,7 @@ pip install "codespine[ui]"
 ```
 
 The current lite UI is dependency-free and served locally by CodeSpine; the `ui` extra is the stable add-on install target for the browser explorer.
+Quotes are required in zsh: use `pip install "codespine[ui]"`, not `pip install codespine[ui]`.
 
 Everything at once (ml + community detection):
 
@@ -381,7 +382,7 @@ codespine force-reset                        # emergency: delete all data files
 
 `analyse` defaults to incremental mode. Repeat runs only process changed files and are fast.
 
-`analyse` runs in fast mode by default: it indexes the core graph, publishes that read replica from a detached process, then continues communities, flows, dead code, coupling, and cross-module enrichment in the background. Use `codespine tasks` or `codespine ui` to watch that work. Use `--complete --deep` when you want those passes refreshed before the command returns.
+`analyse` runs in fast mode by default: it indexes the core graph, honors the foreground time budget, publishes a read replica, then continues unfinished core indexing or enrichment in the background. Use `codespine background` or `codespine ui` to watch that work. Use `--complete --deep` when you want those passes refreshed before the command returns.
 
 ---
 
@@ -567,7 +568,7 @@ The deep analysis phase covers four passes that are expensive but optional:
 | Dead code | Finds methods with no callers (Java-aware exemptions) | Cleanup audits |
 | Change coupling | Analyses git history for co-changed file pairs | `get_change_coupling`, `related` |
 
-**Fast default:** `codespine analyse` prioritizes a queryable core index. Communities, flows, dead-code, git coupling, and cross-module links are queued in a detached background enrichment job unless you use `--complete`.
+**Fast default:** `codespine analyse` prioritizes a queryable core index and keeps the foreground run inside the configured budget. If core indexing or call/type resolution cannot finish in time, the partial index is published and a background continuation finishes the core graph. Communities, flows, dead-code, git coupling, and cross-module links are queued in a detached background enrichment job unless you use `--complete`.
 
 **Health checks:** every analyse run now performs a small self-test query suite and reports index anomalies such as large projects with zero call edges. Use `codespine health` for the terminal dashboard or `codespine self-test --json` in CI.
 

{codespine-1.0.10 → codespine-1.0.11}/README.md

@@ -1,6 +1,6 @@
 # CodeSpine
 
-**v1.0.10** — Local Java code intelligence for coding agents, backed by a graph database.
+**v1.0.11** — Local Java code intelligence for coding agents, backed by a graph database.
 
 CodeSpine cuts token burn for coding agents working on Java codebases.
 
@@ -45,6 +45,7 @@ pip install "codespine[ui]"
 ```
 
 The current lite UI is dependency-free and served locally by CodeSpine; the `ui` extra is the stable add-on install target for the browser explorer.
+Quotes are required in zsh: use `pip install "codespine[ui]"`, not `pip install codespine[ui]`.
 
 Everything at once (ml + community detection):
 
@@ -315,7 +316,7 @@ codespine force-reset                        # emergency: delete all data files
 
 `analyse` defaults to incremental mode. Repeat runs only process changed files and are fast.
 
-`analyse` runs in fast mode by default: it indexes the core graph, publishes that read replica from a detached process, then continues communities, flows, dead code, coupling, and cross-module enrichment in the background. Use `codespine tasks` or `codespine ui` to watch that work. Use `--complete --deep` when you want those passes refreshed before the command returns.
+`analyse` runs in fast mode by default: it indexes the core graph, honors the foreground time budget, publishes a read replica, then continues unfinished core indexing or enrichment in the background. Use `codespine background` or `codespine ui` to watch that work. Use `--complete --deep` when you want those passes refreshed before the command returns.
 
 ---
 
@@ -501,7 +502,7 @@ The deep analysis phase covers four passes that are expensive but optional:
 | Dead code | Finds methods with no callers (Java-aware exemptions) | Cleanup audits |
 | Change coupling | Analyses git history for co-changed file pairs | `get_change_coupling`, `related` |
 
-**Fast default:** `codespine analyse` prioritizes a queryable core index. Communities, flows, dead-code, git coupling, and cross-module links are queued in a detached background enrichment job unless you use `--complete`.
+**Fast default:** `codespine analyse` prioritizes a queryable core index and keeps the foreground run inside the configured budget. If core indexing or call/type resolution cannot finish in time, the partial index is published and a background continuation finishes the core graph. Communities, flows, dead-code, git coupling, and cross-module links are queued in a detached background enrichment job unless you use `--complete`.
 
 **Health checks:** every analyse run now performs a small self-test query suite and reports index anomalies such as large projects with zero call edges. Use `codespine health` for the terminal dashboard or `codespine self-test --json` in CI.
 

{codespine-1.0.10 → codespine-1.0.11}/codespine/__init__.py

@@ -1,4 +1,4 @@
 """CodeSpine package."""
 
 __all__ = ["__version__"]
-__version__ = "1.0.10"
+__version__ = "1.0.11"

{codespine-1.0.10 → codespine-1.0.11}/codespine/cli.py

@@ -98,6 +98,32 @@ def _spawn_background_enrichment(path: str) -> bool:
         return False
 
 
+def _spawn_background_continuation(path: str) -> bool:
+    """Continue a budget-paused core index in a detached process."""
+    task_id = create_task(
+        "indexing",
+        "Background core indexing",
+        path=path,
+        metadata={"trigger": "analyse-budget"},
+    )
+    try:
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "codespine.cli", "continue-background", path, "--task-id", task_id],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+            cwd=os.getcwd(),
+            env=os.environ.copy(),
+        )
+        update_task(task_id, status="running", phase="spawned", pid=proc.pid)
+        return True
+    except Exception as exc:  # noqa: BLE001
+        finish_task(task_id, "failed", str(exc))
+        LOGGER.warning("Unable to spawn background continuation: %s", exc)
+        return False
+
+
 def _db_size_bytes(path: str) -> int:
     if os.path.isfile(path):
         return os.path.getsize(path)
@@ -373,6 +399,16 @@ def _index_shard_group(
                         f"{files} files, {classes} classes, {methods} methods  ({elapsed_s:.1f}s)",
                     )
                 return
+            if event == "budget_exhausted":
+                files = int(payload.get("files_indexed", 0))
+                total = int(payload.get("total", 0))
+                phase = str(payload.get("phase", "indexing"))
+                with output_lock:
+                    _phase(
+                        f"{prefix}Foreground budget...",
+                        f"paused during {phase} ({files}/{total} files); continuing in background",
+                    )
+                return
             if event in ("resolve_calls_start",):
                 if parse_state["shown"] or db_state["shown"]:
                     with output_lock:
@@ -906,7 +942,16 @@ def analyse(
         recycle = getattr(store, "_recycle_conn", None)
         if callable(recycle):
             recycle()
-    if fast and _spawn_background_enrichment(abs_path):
+    core_partial = any(bool(getattr(result, "partial", False)) for result in all_results)
+    if fast and core_partial:
+        _live_phase(snap_label, "copying partial core")
+        sg.snapshot_all(background=False)
+        _finish_phase(snap_label, "partial index visible")
+        if _spawn_background_continuation(abs_path):
+            _phase("Background indexing...", "core indexing continues; run 'codespine background'")
+        else:
+            _phase("Background indexing...", "not started; rerun 'codespine analyse' to continue")
+    elif fast and _spawn_background_enrichment(abs_path):
         _phase(snap_label, "core snapshot now; enrichment continues in background")
     else:
         _live_phase(snap_label, "copying")
@@ -1023,6 +1068,50 @@ def enrich_background(path: str, task_id: str | None) -> None:
         raise
 
 
+@main.command("continue-background", hidden=True)
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--task-id", default=None, hidden=True)
+def continue_background(path: str, task_id: str | None) -> None:
+    """Continue core indexing after a foreground budget pause."""
+    abs_path = os.path.abspath(path)
+    if task_id is None:
+        task_id = create_task("indexing", "Background core indexing", path=abs_path)
+    update_task(
+        task_id,
+        status="running",
+        phase="core indexing",
+        pid=os.getpid(),
+        progress=0.10,
+        detail="Continuing analyse without the foreground budget",
+    )
+    try:
+        with open(SETTINGS.log_file, "a", encoding="utf-8") as log:
+            proc = subprocess.run(
+                [
+                    sys.executable,
+                    "-m",
+                    "codespine.cli",
+                    "analyse",
+                    abs_path,
+                    "--budget",
+                    "0",
+                    "--allow-running",
+                ],
+                cwd=os.getcwd(),
+                stdout=log,
+                stderr=subprocess.STDOUT,
+                check=False,
+            )
+        if proc.returncode == 0:
+            finish_task(task_id, "succeeded", "Background core indexing complete")
+            return
+        finish_task(task_id, "failed", f"Background analyse exited with code {proc.returncode}")
+        raise click.ClickException(f"Background analyse exited with code {proc.returncode}")
+    except Exception as exc:  # noqa: BLE001
+        finish_task(task_id, "failed", str(exc))
+        raise
+
+
 @main.command()
 @click.argument("query")
 @click.option("--k", default=20, show_default=True, type=int)
@@ -1363,7 +1452,13 @@ def tasks_cmd(include_finished: bool, limit: int, as_json: bool) -> None:
 
 
 @main.command("background")
-@click.option("--all", "include_finished", is_flag=True, help="Include completed and failed tasks.")
+@click.option(
+    "--all/--running-only",
+    "include_finished",
+    default=True,
+    show_default=True,
+    help="Include completed and failed tasks, or show only currently running work.",
+)
 @click.option("--limit", default=20, show_default=True, type=int)
 @click.option("--json", "as_json", is_flag=True)
 def background_cmd(include_finished: bool, limit: int, as_json: bool) -> None:
@@ -1377,7 +1472,10 @@ def _show_background_tasks(include_finished: bool, limit: int, as_json: bool) ->
         _echo_json(tasks, True)
         return
     if not tasks:
-        click.echo("No background tasks.")
+        if include_finished:
+            click.echo("No background tasks recorded.")
+        else:
+            click.echo("No running background tasks.")
         return
     now = time.time()
     header = f"{'ID':<12}  {'Status':<10}  {'Progress':>8}  {'Phase':<26}  {'Age':>7}  Path"

{codespine-1.0.10 → codespine-1.0.11}/codespine/config.py

@@ -30,9 +30,9 @@ class Settings:
     rrf_k: int = 60
     semantic_candidate_pool: int = 2000
     write_batch_size: int = 500
-    index_file_batch_size: int = 200
-    index_method_batch_size: int = 2000
-    index_symbol_batch_size: int = 2000
+    index_file_batch_size: int = 1000
+    index_method_batch_size: int = 10000
+    index_symbol_batch_size: int = 10000
     edge_write_batch_size: int = 5000
     default_coupling_days: int = 5
     default_min_coupling_strength: float = 0.3

{codespine-1.0.10 → codespine-1.0.11}/codespine/indexer/engine.py

@@ -88,6 +88,7 @@ class IndexResult:
     calls_resolved: int
     type_relationships: int
     embeddings_generated: int
+    partial: bool = False
 
 
 class JavaIndexer:
@@ -429,6 +430,7 @@ class JavaIndexer:
             total=_db_total,
             deleted_files=len(deleted_file_ids),
         )
+        budget_exhausted = False
 
         try:
             # ── Chunked DB writes ─────────────────────────────────────────────
@@ -644,26 +646,20 @@ class JavaIndexer:
                         with self.store.transaction():
                             self.store.clear_files_batch(clear_sub)
                         self.store._recycle_conn()
-                _db_phase_holder[0] = "writing files"
+                _db_phase_holder[0] = "writing rows"
                 with self.store.transaction():
                     self.store.upsert_files_batch(file_rows)
-                self.store._recycle_conn()
-                _db_phase_holder[0] = "writing classes"
-                with self.store.transaction():
                     self.store.upsert_classes_batch(class_rows)
-                self.store._recycle_conn()
-                _METHOD_SUB_BATCH = max(1, int(getattr(SETTINGS, "index_method_batch_size", 2000)))
-                _db_phase_holder[0] = "writing methods"
-                for method_sub in self._chunked(method_rows, _METHOD_SUB_BATCH):
-                    with self.store.transaction():
+                    _METHOD_SUB_BATCH = max(1, int(getattr(SETTINGS, "index_method_batch_size", 10000)))
+                    _db_phase_holder[0] = "writing methods"
+                    for method_sub in self._chunked(method_rows, _METHOD_SUB_BATCH):
                         self.store.upsert_methods_batch(method_sub)
-                    self.store._recycle_conn()
-                _SYMBOL_SUB_BATCH = max(1, int(getattr(SETTINGS, "index_symbol_batch_size", 2000)))
-                _db_phase_holder[0] = "writing symbols"
-                for symbol_sub in self._chunked(symbol_rows, _SYMBOL_SUB_BATCH):
-                    with self.store.transaction():
+                    _SYMBOL_SUB_BATCH = max(1, int(getattr(SETTINGS, "index_symbol_batch_size", 10000)))
+                    _db_phase_holder[0] = "writing symbols"
+                    for symbol_sub in self._chunked(symbol_rows, _SYMBOL_SUB_BATCH):
                         self.store.upsert_symbols_batch(symbol_sub)
-                    self.store._recycle_conn()
+                self.store._recycle_conn()
+                _db_phase_holder[0] = "building rows"
                 self._emit(
                     progress,
                     "db_write_progress",
@@ -673,6 +669,16 @@ class JavaIndexer:
                     methods=methods_indexed,
                     phase=_db_phase_holder[0],
                 )
+                if deadline is not None and time.perf_counter() >= max(0.0, deadline - 8.0):
+                    budget_exhausted = True
+                    self._emit(
+                        progress,
+                        "budget_exhausted",
+                        phase="db_write",
+                        files_indexed=files_indexed,
+                        total=_db_total,
+                    )
+                    break
                 _db_phase_holder[0] = "building rows"
         finally:
             _db_hb_stop.set()
@@ -688,7 +694,23 @@ class JavaIndexer:
         )
 
         def _deadline_expired() -> bool:
-            return deadline is not None and time.perf_counter() >= deadline
+            return budget_exhausted or (deadline is not None and time.perf_counter() >= deadline)
+
+        if budget_exhausted:
+            self._emit(progress, "resolve_calls_done", calls_resolved=0, partial=True)
+            self._emit(progress, "resolve_types_done", type_relationships=0, partial=True)
+            self._emit(progress, "di_done", injections=0, interface_bindings=0, partial=True)
+            return IndexResult(
+                project_id=project_id,
+                files_found=len(current_files),
+                files_indexed=files_indexed,
+                classes_indexed=classes_indexed,
+                methods_indexed=methods_indexed,
+                calls_resolved=0,
+                type_relationships=0,
+                embeddings_generated=classes_indexed + methods_indexed if embed else 0,
+                partial=True,
+            )
 
         self._emit(progress, "resolve_calls_start")
 
@@ -770,8 +792,6 @@ class JavaIndexer:
         if _deadline_expired():
             self._emit(progress, "resolve_types_done", type_relationships=0, partial=True)
             self._emit(progress, "di_done", injections=0, interface_bindings=0, partial=True)
-            self._prune_meta_cache(meta_cache, current_file_ids)
-            self._save_file_meta_cache(project_id, meta_cache)
             return IndexResult(
                 project_id=project_id,
                 files_found=len(current_files),
@@ -781,6 +801,7 @@ class JavaIndexer:
                 calls_resolved=calls_resolved,
                 type_relationships=0,
                 embeddings_generated=classes_indexed + methods_indexed if embed else 0,
+                partial=True,
             )
         type_rows = self._build_inheritance_edges(
             class_meta,
@@ -843,6 +864,7 @@ class JavaIndexer:
             calls_resolved=calls_resolved,
             type_relationships=type_relationships,
             embeddings_generated=classes_indexed + methods_indexed if embed else 0,
+            partial=partial_calls,
         )
 
     @staticmethod

{codespine-1.0.10 → codespine-1.0.11}/codespine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 1.0.10
+Version: 1.0.11
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -66,7 +66,7 @@ Dynamic: license-file
 
 # CodeSpine
 
-**v1.0.10** — Local Java code intelligence for coding agents, backed by a graph database.
+**v1.0.11** — Local Java code intelligence for coding agents, backed by a graph database.
 
 CodeSpine cuts token burn for coding agents working on Java codebases.
 
@@ -111,6 +111,7 @@ pip install "codespine[ui]"
 ```
 
 The current lite UI is dependency-free and served locally by CodeSpine; the `ui` extra is the stable add-on install target for the browser explorer.
+Quotes are required in zsh: use `pip install "codespine[ui]"`, not `pip install codespine[ui]`.
 
 Everything at once (ml + community detection):
 
@@ -381,7 +382,7 @@ codespine force-reset                        # emergency: delete all data files
 
 `analyse` defaults to incremental mode. Repeat runs only process changed files and are fast.
 
-`analyse` runs in fast mode by default: it indexes the core graph, publishes that read replica from a detached process, then continues communities, flows, dead code, coupling, and cross-module enrichment in the background. Use `codespine tasks` or `codespine ui` to watch that work. Use `--complete --deep` when you want those passes refreshed before the command returns.
+`analyse` runs in fast mode by default: it indexes the core graph, honors the foreground time budget, publishes a read replica, then continues unfinished core indexing or enrichment in the background. Use `codespine background` or `codespine ui` to watch that work. Use `--complete --deep` when you want those passes refreshed before the command returns.
 
 ---
 
@@ -567,7 +568,7 @@ The deep analysis phase covers four passes that are expensive but optional:
 | Dead code | Finds methods with no callers (Java-aware exemptions) | Cleanup audits |
 | Change coupling | Analyses git history for co-changed file pairs | `get_change_coupling`, `related` |
 
-**Fast default:** `codespine analyse` prioritizes a queryable core index. Communities, flows, dead-code, git coupling, and cross-module links are queued in a detached background enrichment job unless you use `--complete`.
+**Fast default:** `codespine analyse` prioritizes a queryable core index and keeps the foreground run inside the configured budget. If core indexing or call/type resolution cannot finish in time, the partial index is published and a background continuation finishes the core graph. Communities, flows, dead-code, git coupling, and cross-module links are queued in a detached background enrichment job unless you use `--complete`.
 
 **Health checks:** every analyse run now performs a small self-test query suite and reports index anomalies such as large projects with zero call edges. Use `codespine health` for the terminal dashboard or `codespine self-test --json` in CI.
 

{codespine-1.0.10 → codespine-1.0.11}/pyproject.toml

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

{codespine-1.0.10 → codespine-1.0.11}/tests/test_tasks.py

@@ -32,3 +32,15 @@ def test_background_command_shows_progress():
     assert task_id in result.output
     assert "40%" in result.output
     assert "execution flows" in result.output
+
+
+def test_background_command_shows_recent_finished_tasks_by_default():
+    task_id = create_task("indexing", "Background core indexing", path="/tmp/project")
+    finish_task(task_id, "failed", "boom")
+
+    result = CliRunner().invoke(main, ["background"])
+
+    assert result.exit_code == 0
+    assert task_id in result.output
+    assert "failed" in result.output
+    assert "boom" in result.output