codebrain 0.3.5__tar.gz → 0.4.1__tar.gz

{codebrain-0.3.5 → codebrain-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebrain
-Version: 0.3.5
+Version: 0.4.1
 Summary: Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.
 Author: CodeBrain Contributors
 License: MIT License

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain/__init__.py

@@ -7,4 +7,4 @@ try:
 except PackageNotFoundError:
     # Source checkout without installation (e.g. running from a worktree).
     # Keep in sync with [project.version] in pyproject.toml.
-    __version__ = "0.3.5"
+    __version__ = "0.4.1"

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain/cli.py

@@ -58,9 +58,17 @@ def _require_index(repo_root: Path) -> Path:
         import gc
         gc.collect()  # Release any lingering connections
         try:
-            db.unlink(missing_ok=True)
-            for wal in db.parent.glob(f"{db.name}-*"):
-                wal.unlink(missing_ok=True)
+            # Prefer rebuilding in place — deleting the file fails on
+            # Windows while any MCP server holds it open. Only fall back
+            # to file replacement when the DB is unreadable.
+            try:
+                from codebrain.graph.store import GraphStore
+                with GraphStore(db) as _store:
+                    _store.clear_all()
+            except Exception:
+                db.unlink(missing_ok=True)
+                for wal in db.parent.glob(f"{db.name}-*"):
+                    wal.unlink(missing_ok=True)
             from codebrain.indexer import full_index
             full_index(repo_root, db)
             click.echo(click.style("Database rebuilt successfully.", fg="green"), err=True)
@@ -1618,33 +1626,37 @@ def reindex(ctx: click.Context, yes: bool, as_json: bool) -> None:
     db = _db_path(repo_root)
 
     if not yes and not as_json:
-        if not click.confirm("This will delete and rebuild the entire index. Continue?"):
+        if not click.confirm("This will rebuild the entire index. Continue?"):
             click.echo("Aborted.")
             return
 
+    # Rebuild IN PLACE (clear tables, re-fill) rather than deleting the DB
+    # file. Deleting fails on Windows whenever any MCP server holds the DB
+    # open — and with session-long server lifetimes that is "always". WAL
+    # mode makes the in-place rebuild safe with readers attached, so reindex
+    # never needs to find, kill, or wait for other processes.
     if db.exists():
+        from codebrain.graph.store import GraphStore
         try:
-            db.unlink()
-        except PermissionError:
-            from codebrain.mcp_lifecycle import find_db_lock_holder, kill_pid
-            holder = find_db_lock_holder(repo_root)
-            if holder is None:
-                click.echo(
-                    "  Database is locked but no recorded MCP holder.\n"
-                    "  Find the holder with `Get-Process python` (Windows) or `lsof` (Unix) and stop it."
-                )
+            with GraphStore(db) as _store:
+                _store.clear_all()
+        except Exception as exc:
+            # Corrupted beyond clearing — replacing the file is the only
+            # option left. This fails if another process holds it open.
+            click.echo(click.style(
+                f"  Index unreadable ({exc}); replacing the database file.", fg="yellow",
+            ))
+            try:
+                db.unlink()
+                for wal in db.parent.glob(f"{db.name}-*"):
+                    wal.unlink(missing_ok=True)
+            except PermissionError:
+                click.echo(click.style(
+                    "  The corrupted database is held open by a running MCP server.\n"
+                    "  Close Claude Code sessions for this project (or run "
+                    "`brain doctor --kill-stale-mcps`) and retry.", fg="red",
+                ))
                 raise
-            should_kill = yes or as_json or click.confirm(
-                f"Database locked by CodeBrain MCP server PID {holder}. Terminate it and continue?"
-            )
-            if not should_kill:
-                click.echo("Aborted.")
-                return
-            status = kill_pid(holder)
-            click.echo(f"  Killed MCP PID {holder}: {status}")
-            import time as _time
-            _time.sleep(1)
-            db.unlink()
 
     files = discover_files(repo_root)
 
@@ -1847,6 +1859,13 @@ def repair(ctx: click.Context) -> None:
             break
         except PermissionError:
             _time.sleep(0.2)
+    else:
+        click.echo(click.style(
+            "Could not replace the corrupted database — a running MCP server "
+            "holds it open.\nClose Claude Code sessions for this project (or "
+            "run `brain doctor --kill-stale-mcps`) and retry.", fg="red",
+        ))
+        sys.exit(1)
     # Also clean up WAL/SHM files
     for suffix in ("-wal", "-shm"):
         wal = db.parent / (db.name + suffix)

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain/graph/store.py

@@ -22,11 +22,18 @@ class GraphStore:
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
         _log.debug("Opening database %s", self.db_path)
         self.conn = sqlite3.connect(str(self.db_path), timeout=30, check_same_thread=False)
-        self.conn.row_factory = sqlite3.Row
-        self.conn.execute("PRAGMA journal_mode=WAL")
-        self.conn.execute("PRAGMA synchronous=NORMAL")
-        self.conn.execute("PRAGMA foreign_keys=OFF")
-        migrate_db(self.conn)
+        try:
+            self.conn.row_factory = sqlite3.Row
+            self.conn.execute("PRAGMA journal_mode=WAL")
+            self.conn.execute("PRAGMA synchronous=NORMAL")
+            self.conn.execute("PRAGMA foreign_keys=OFF")
+            migrate_db(self.conn)
+        except Exception:
+            # A corrupted/garbage file makes the pragmas raise AFTER the OS
+            # handle is open. Without this close, the dangling handle keeps
+            # the file locked on Windows and recovery-by-replacement fails.
+            self.conn.close()
+            raise
 
     def close(self) -> None:
         _log.debug("Closing database %s", self.db_path)
@@ -95,6 +102,20 @@ class GraphStore:
             self.conn.execute("DELETE FROM nodes WHERE file_path = ?", (path,))
             self.conn.execute("DELETE FROM files WHERE path = ?", (path,))
 
+    def remove_files(self, paths: list[str]) -> None:
+        """Delete many files and their nodes/edges in ONE transaction.
+
+        Per-file transactions take minutes when thousands of rows go stale
+        (e.g. a venv that used to be indexed); this takes well under a second.
+        """
+        if not paths:
+            return
+        params = [(p,) for p in paths]
+        with self.conn:
+            self.conn.executemany("DELETE FROM edges WHERE file_path = ?", params)
+            self.conn.executemany("DELETE FROM nodes WHERE file_path = ?", params)
+            self.conn.executemany("DELETE FROM files WHERE path = ?", params)
+
     def clear_all(self) -> None:
         """Delete all data from the graph (files, nodes, edges).
 

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain/indexer.py

@@ -490,6 +490,43 @@ def full_index(
     }
 
 
+def scan_stale(
+    repo_root: Path,
+    store: GraphStore,
+    settings: "Settings | None" = None,
+) -> tuple[list[Path], list[Path]]:
+    """Cheap staleness scan: which files changed since they were indexed?
+
+    Returns ``(changed_candidates, deleted)``. Uses an mtime-vs-last_indexed
+    prefilter so no file contents are read here — false candidates are fine
+    because :func:`incremental_update` hash-checks before re-parsing. This is
+    the fast freshness layer (milliseconds on a warm FS cache); the exhaustive
+    hash-everything pass lives in the watcher's startup catch-up sync.
+    """
+    rows = store.conn.execute("SELECT path, last_indexed FROM files").fetchall()
+    stored = {row["path"]: row["last_indexed"] for row in rows}
+
+    changed: list[Path] = []
+    seen: set[str] = set()
+    # Files modified within this window before indexing finished may have
+    # raced the indexer — treat them as candidates (hash check disambiguates).
+    slack = 2.0
+    for file_path in discover_files(repo_root, settings):
+        rel = normalize_path(file_path, repo_root)
+        seen.add(rel)
+        last_indexed = stored.get(rel)
+        if last_indexed is None:
+            changed.append(file_path)  # new file
+            continue
+        try:
+            if file_path.stat().st_mtime > last_indexed - slack:
+                changed.append(file_path)
+        except OSError:
+            continue
+    deleted = [repo_root / rel for rel in stored if rel not in seen]
+    return changed, deleted
+
+
 def incremental_update(
     repo_root: Path,
     changed_files: list[Path],
@@ -505,10 +542,15 @@ def incremental_update(
     removed = 0
     errors: list[str] = []
 
-    for file_path in deleted_files:
-        rel = normalize_path(file_path, repo_root)
-        store.remove_file(rel)
-        removed += 1
+    deleted_rels = [normalize_path(fp, repo_root) for fp in deleted_files]
+    store.remove_files(deleted_rels)
+    removed = len(deleted_rels)
+
+    # tree-sitter can hang holding the GIL on Windows — isolate those
+    # extensions in a subprocess, same as full_index. A hang here would
+    # otherwise freeze the watcher/catch-up thread while it holds the DB
+    # lock, silently stopping auto-indexing for the rest of the session.
+    _NEEDS_ISOLATION = frozenset({".ts", ".tsx", ".js", ".jsx"})
 
     for file_path in changed_files:
         rel = normalize_path(file_path, repo_root)
@@ -519,9 +561,16 @@ def incremental_update(
             if current_hash == stored_hash:
                 continue
 
-            pf = _parse_file(file_path, repo_root)
-            store.upsert_file(pf)
-            updated += 1
+            if sys.platform == "win32" and file_path.suffix in _NEEDS_ISOLATION:
+                pf, err = _parse_with_timeout(file_path, repo_root, timeout=30)
+                if err:
+                    errors.append(err)
+                    continue
+            else:
+                pf = _parse_file(file_path, repo_root)
+            if pf is not None:
+                store.upsert_file(pf)
+                updated += 1
         except Exception as exc:
             errors.append(f"{rel}: {exc}")
 

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain/mcp_lifecycle.py

@@ -79,39 +79,43 @@ def _read_pid_file(pid_file: Path) -> int | None:
         return None
 
 
-def _predecessor_has_live_host(pid: int) -> bool:
-    """True if ``pid``'s ancestor chain contains a live host (claude/cursor/...).
-
-    Such a predecessor belongs to a *concurrent* sibling Claude session and
-    must not be terminated — its disappearance would silently break that
-    session's MCP. Without psutil we cannot tell, so be safe and assume yes.
+def _predecessor_host_pid(pid: int) -> int | None:
+    """Return the PID of the live IDE host (claude/cursor/...) in ``pid``'s
+    ancestor chain, or None if there is none.
+
+    A predecessor with a live host belongs to *some* Claude session — but
+    whether it must be spared depends on WHICH session: a different host PID
+    means a concurrent sibling window (killing it would silently break that
+    session's MCP); the SAME host PID as ours means it is our own session's
+    orphaned predecessor left behind by a transport disconnect/reconnect,
+    and it must die or two servers fight over the SQLite DB.
     """
     try:
         import psutil
     except ImportError:
-        return True
+        return None
     try:
         proc = psutil.Process(pid)
     except (psutil.NoSuchProcess, psutil.AccessDenied):
-        return False
+        return None
     for _ in range(ANCESTOR_WALK_DEPTH):
         try:
             parent = proc.parent()
         except (psutil.NoSuchProcess, psutil.AccessDenied):
-            return False
+            return None
         if parent is None:
-            return False
+            return None
         try:
             name = (parent.name() or "").lower()
         except (psutil.NoSuchProcess, psutil.AccessDenied):
-            return False
+            return None
         if any(hint in name for hint in HOST_PROCESS_NAME_HINTS):
-            return True
+            return parent.pid
         proc = parent
-    return False
+    return None
 
 
-def _kill_stale_predecessor(pid_file: Path) -> None:
+def _kill_stale_predecessor(pid_file: Path, own_host_pid: int | None = None) -> None:
     if not pid_file.exists():
         return
     old_pid = _read_pid_file(pid_file)
@@ -128,12 +132,27 @@ def _kill_stale_predecessor(pid_file: Path) -> None:
         # PID was reused by an unrelated process. Don't touch.
         _log.debug("PID %d reused by unrelated process; leaving alone", old_pid)
         return
-    if _predecessor_has_live_host(old_pid):
-        # Concurrent sibling Claude session is still using this MCP — leave it.
-        # Without this, two Claude windows on the same repo race each other and
-        # whichever started last kills the other's MCP.
-        _log.debug("PID %d has a live IDE host; sibling MCP, leaving alone", old_pid)
+    pred_host = _predecessor_host_pid(old_pid)
+    if pred_host is not None and pred_host != own_host_pid:
+        # Live IDE host that is NOT ours → concurrent sibling Claude session
+        # is still using this MCP — leave it. Without this, two Claude
+        # windows on the same repo race each other and whichever started
+        # last kills the other's MCP.
+        _log.debug(
+            "PID %d has live IDE host %d (ours: %s); sibling MCP, leaving alone",
+            old_pid, pred_host, own_host_pid,
+        )
         return
+    if pred_host is not None:
+        # Same host as ours → our own session reconnected and left the old
+        # server behind with a dead stdio transport. It will never exit on
+        # its own (parent still alive, idle timer disabled when anchored)
+        # and holds the SQLite DB — kill it.
+        _log.warning(
+            "Predecessor PID %d shares our IDE host %d — duplicate from a "
+            "transport reconnect, terminating it",
+            old_pid, pred_host,
+        )
     try:
         proc = psutil.Process(old_pid)
         _log.warning("Killing stale CodeBrain MCP predecessor PID %d", old_pid)
@@ -300,17 +319,23 @@ def install_watchdogs(repo_root: Path | None = None) -> None:
     start = time.time()
     mark_activity()
 
+    # Resolve our own IDE host FIRST — the predecessor check needs it to
+    # distinguish "our own session's orphan after a transport reconnect"
+    # (kill) from "a concurrent sibling window's server" (spare).
+    immediate_ppid = os.getppid()
+    initial_ppid, initial_create_time, host_anchored = _find_watch_target(immediate_ppid)
+    idle_timeout = _effective_idle_timeout(host_anchored)
+
     if repo_root is not None:
         from codebrain.config import CODEBRAIN_DIR
         pid_file = repo_root / CODEBRAIN_DIR / PID_FILE_NAME
-        _kill_stale_predecessor(pid_file)
+        _kill_stale_predecessor(
+            pid_file,
+            own_host_pid=initial_ppid if host_anchored else None,
+        )
         _write_pid_file(pid_file)
         atexit.register(_remove_pid_file, pid_file)
 
-    immediate_ppid = os.getppid()
-    initial_ppid, initial_create_time, host_anchored = _find_watch_target(immediate_ppid)
-    idle_timeout = _effective_idle_timeout(host_anchored)
-
     _log.info(
         "MCP watchdogs installed (ppid=%d via=%d, host_anchored=%s, "
         "idle_timeout=%ds, max_lifetime=%ds)",

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain/mcp_server.py

@@ -110,6 +110,111 @@ def _make_store():
     return GraphStore(_find_db())
 
 
+# ---------------------------------------------------------------------------
+# Freshness-on-read
+#
+# Correctness must not depend on which background processes happen to be
+# alive. The watcher (instant) and the startup catch-up sync (thorough) are
+# optimizations; THIS is the guarantee: before serving a tool call, cheaply
+# verify the index matches the working tree and sync the difference. Even if
+# every watcher thread is dead, the answer the agent gets reflects current
+# code.
+# ---------------------------------------------------------------------------
+
+import threading as _threading
+import time as _time
+
+# Default 30s: the watcher handles live edits instantly; this gate is the
+# convergence safety net. Measured walk cost is ~2-5s on a midsize repo —
+# a 5s interval would burn most of a core just rescanning.
+FRESHNESS_INTERVAL_SECONDS = float(os.environ.get("CODEBRAIN_FRESHNESS_INTERVAL", "30"))
+
+_freshness_lock = _threading.Lock()
+_last_freshness_check: dict[str, float] = {}
+
+# Tools that must NOT trigger a freshness sync:
+# - validators compare new/written content against the PRE-change graph;
+#   syncing first would erase the baseline and the structural gate would
+#   silently pass everything
+# - reindex_codebase rebuilds anyway
+# - project/memory tools don't read graph data
+_FRESHNESS_EXEMPT_TOOLS = frozenset({
+    "validate_change",
+    "validate_changes",
+    "validate_after_write",
+    "propose_change",
+    "diff_impact",
+    "get_validation_status",
+    "reindex_codebase",
+    "set_project",
+    "get_project",
+    "save_memory",
+    "recall_memories",
+    "list_memories",
+    "update_memory",
+    "delete_memory",
+})
+
+
+def _ensure_fresh() -> None:
+    """Schedule a background freshness sync if one is due.
+
+    NEVER does disk walks, hashing, or parsing on the tool path. v0.4.0
+    ran the staleness scan inline and on large or venv-polluted repos the
+    walk alone exceeded the tool deadline — every query timed out. The
+    contract is: tool calls never wait; the index converges within
+    seconds via the background worker (single-flight, throttled per DB).
+    """
+    if FRESHNESS_INTERVAL_SECONDS <= 0:
+        return
+    try:
+        db_path = _find_db()
+    except FileNotFoundError:
+        return
+    key = str(db_path)
+    now = _time.monotonic()
+    if now - _last_freshness_check.get(key, 0.0) < FRESHNESS_INTERVAL_SECONDS:
+        return
+    # Single-flight: the lock is held for the WHOLE background operation
+    # and released by the worker. Without this, slow syncs pile up — a
+    # repo with thousands of stale rows spawned a new mega-sync every
+    # interval while the first was still running.
+    if not _freshness_lock.acquire(blocking=False):
+        return  # a sync is already in flight
+    _last_freshness_check[key] = now
+    _threading.Thread(
+        target=_freshness_worker,
+        args=(db_path,),
+        name="cb-freshness-sync",
+        daemon=True,
+    ).start()
+
+
+def _freshness_worker(db_path: Path) -> None:
+    """Owns _freshness_lock; scans and syncs, then releases."""
+    try:
+        from codebrain.graph.store import GraphStore
+        from codebrain.indexer import incremental_update, scan_stale
+
+        repo_root = db_path.parent.parent
+        with GraphStore(db_path) as store:
+            changed, deleted = scan_stale(repo_root, store)
+            if not changed and not deleted:
+                return
+            result = incremental_update(repo_root, changed, deleted, store)
+            if result["files_updated"] or result["files_removed"]:
+                _log.info(
+                    "Freshness sync: updated %d, removed %d (%.3fs)",
+                    result["files_updated"],
+                    result["files_removed"],
+                    result["elapsed_seconds"],
+                )
+    except Exception as exc:
+        _log.debug("Freshness sync skipped: %s", exc)
+    finally:
+        _freshness_lock.release()
+
+
 def _safe_tool(fn):  # noqa: ANN001, ANN201
     """Wrap an MCP tool so it cooperates with MCP cancellation.
 
@@ -214,6 +319,10 @@ def _run_sync_protected(fn, args, kwargs):  # noqa: ANN001, ANN202
     saved_stdout = sys.stdout
     sys.stdout = sys.stderr
     try:
+        # Freshness gate: sync index drift before answering. Skip for tools
+        # that rebuild or don't read the graph state being synced.
+        if fn.__name__ not in _FRESHNESS_EXEMPT_TOOLS:
+            _ensure_fresh()
         return fn(*args, **kwargs)
     finally:
         sys.stdout = saved_stdout

{codebrain-0.3.5 → codebrain-0.4.1}/codebrain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebrain
-Version: 0.3.5
+Version: 0.4.1
 Summary: Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.
 Author: CodeBrain Contributors
 License: MIT License

{codebrain-0.3.5 → codebrain-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codebrain"
-version = "0.3.5"
+version = "0.4.1"
 description = "Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required."
 readme = "README.md"
 license = {file = "LICENSE"}

{codebrain-0.3.5 → codebrain-0.4.1}/tests/test_cli.py

@@ -411,6 +411,25 @@ class TestReindex:
         data = json.loads(result.output)
         assert "files_parsed" in data
 
+    def test_reindex_works_while_db_held_open(self, indexed_project):
+        """Reindex must succeed while an MCP server holds the DB open.
+
+        This is the everyday case: session-long MCP servers always have the
+        SQLite file open. The old implementation deleted the DB file, which
+        fails on Windows with WinError 32 whenever anyone is attached.
+        Rebuild must happen in place.
+        """
+        repo_root, store = indexed_project
+        # `store` stays OPEN — it plays the role of a running MCP server.
+        runner = CliRunner()
+        result = _invoke(runner, ["reindex", "--yes"], str(repo_root))
+        assert result.exit_code == 0, result.output
+        assert "Done" in result.output
+        # The still-attached holder sees the rebuilt data (WAL, same file)
+        count = store.conn.execute("SELECT COUNT(*) FROM files").fetchone()[0]
+        assert count > 0
+        store.close()
+
 
 class TestDoctor:
     def test_doctor_text(self, indexed_project):

{codebrain-0.3.5 → codebrain-0.4.1}/tests/test_indexer.py

@@ -113,3 +113,57 @@ class TestIncrementalUpdate:
         )
         assert result["files_updated"] == 0
         store.close()
+
+
+class TestScanStale:
+    """Cheap mtime-based staleness scan used by freshness-on-read."""
+
+    def _indexed(self, simple_project):
+        db = simple_project / CODEBRAIN_DIR / DB_FILENAME
+        full_index(simple_project, db)
+        return GraphStore(db)
+
+    def test_clean_index_reports_nothing(self, simple_project: Path) -> None:
+        from codebrain.indexer import scan_stale
+        with self._indexed(simple_project) as store:
+            changed, deleted = scan_stale(simple_project, store)
+            # slack window may flag just-indexed files; hash check downstream
+            # makes that harmless — but nothing may be reported deleted.
+            assert deleted == []
+
+    def test_detects_modified_file(self, simple_project: Path) -> None:
+        import os, time
+        from codebrain.indexer import scan_stale
+        with self._indexed(simple_project) as store:
+            target = simple_project / "mypackage" / "core.py"
+            target.write_text(target.read_text() + "\n# touched\n")
+            future = time.time() + 10  # ensure mtime beats last_indexed + slack
+            os.utime(target, (future, future))
+            changed, _ = scan_stale(simple_project, store)
+            assert target in changed
+
+    def test_detects_new_file(self, simple_project: Path) -> None:
+        from codebrain.indexer import scan_stale
+        with self._indexed(simple_project) as store:
+            new = simple_project / "mypackage" / "fresh_module.py"
+            new.write_text("def fresh():\n    return 42\n")
+            changed, _ = scan_stale(simple_project, store)
+            assert new in changed
+
+    def test_detects_deleted_file(self, simple_project: Path) -> None:
+        from codebrain.indexer import scan_stale
+        with self._indexed(simple_project) as store:
+            victim = simple_project / "mypackage" / "core.py"
+            victim.unlink()
+            _, deleted = scan_stale(simple_project, store)
+            assert victim in deleted
+
+    def test_untouched_old_file_not_candidate(self, simple_project: Path) -> None:
+        import os, time
+        from codebrain.indexer import scan_stale
+        with self._indexed(simple_project) as store:
+            target = simple_project / "mypackage" / "core.py"
+            past = time.time() - 3600  # well before indexing
+            os.utime(target, (past, past))
+            changed, _ = scan_stale(simple_project, store)
+            assert target not in changed