codrspot-processor-mcp 0.1.0__py3-none-any.whl

codepreproc_client/layer1_business/project_registry.py

@@ -0,0 +1,99 @@
+"""Project registry resolution: match a session's working directory to a
+registered project (by explicit id, active project, root path, or git
+remote). Operates entirely on the local registry mirror
+(local_registry.load_local_projects) - has no server dependency.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from git import Repo
+
+from codepreproc_client.layer1_business.git_utils import get_remote_url, get_repo_root
+from contracts.dtos import ProjectConfig, Registry
+
+
+class ProjectRegistry:
+    """Resolve configured projects for a client session."""
+
+    def __init__(self, registry: Registry) -> None:
+        self.registry = registry
+
+    def list_projects(self) -> list[ProjectConfig]:
+        """Return projects in stable order."""
+
+        return [self.registry.projects[key] for key in sorted(self.registry.projects)]
+
+    def get(self, project_id: str) -> ProjectConfig:
+        """Return a project by id."""
+
+        return self.registry.projects[project_id]
+
+    def resolve_project(
+        self,
+        explicit_project: str | None = None,
+        active_project: str | None = None,
+        roots: list[Path] | None = None,
+        fallback_path: Path | None = None,
+    ) -> ProjectConfig:
+        """Resolve a project using the configured precedence."""
+
+        if explicit_project:
+            return self.get(explicit_project)
+        if active_project and active_project in self.registry.projects:
+            return self.get(active_project)
+
+        root_match = self.resolve_from_roots(roots or [])
+        if root_match:
+            return root_match
+
+        remote_match = self.resolve_from_remote(fallback_path)
+        if remote_match:
+            return remote_match
+
+        if len(self.registry.projects) == 1:
+            return next(iter(self.registry.projects.values()))
+
+        raise KeyError("project_not_resolved")
+
+    def resolve_from_roots(self, roots: list[Path]) -> ProjectConfig | None:
+        """Match a configured project by client root paths."""
+
+        resolved_roots = [root.resolve() for root in roots]
+        best_match: ProjectConfig | None = None
+        best_depth = -1
+        for project in self.registry.projects.values():
+            project_root = project.root.resolve()
+            for root in resolved_roots:
+                try:
+                    root.relative_to(project_root)
+                    depth = len(project_root.parts)
+                    if depth > best_depth:
+                        best_match = project
+                        best_depth = depth
+                except ValueError:
+                    continue
+        return best_match
+
+    def resolve_from_remote(self, path: Path | None) -> ProjectConfig | None:
+        """Match a project by git remote URL."""
+
+        if path is None:
+            return None
+        repo_root = get_repo_root(path)
+        if repo_root is None:
+            return None
+        remote = get_remote_url(Repo(repo_root))
+        if remote is None:
+            return None
+        for project in self.registry.projects.values():
+            project_root = get_repo_root(project.root)
+            if project_root is None:
+                continue
+            try:
+                if get_remote_url(Repo(project_root)) == remote:
+                    return project
+            except Exception:
+                continue
+        return None

codepreproc_client/layer2_tooling/condensation/ast_graph.py

@@ -0,0 +1,426 @@
+"""SQLite-backed AST graph metadata."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import sqlite3
+from pathlib import Path
+
+from contracts.dtos import CodeChunk
+
+
+def _compute_export_surface_hash(symbol_names: list[str]) -> str:
+    """Stable hash over sorted bare symbol names — the foreign lookup key.
+
+    Bumps only when the exported symbol surface changes, not on body edits.
+    """
+    return hashlib.sha256(json.dumps(sorted(symbol_names)).encode()).hexdigest()
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS symbols (
+  chunk_id TEXT PRIMARY KEY,
+  symbol TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  signature TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_symbol ON symbols(symbol);
+CREATE INDEX IF NOT EXISTS idx_file ON symbols(file_path);
+CREATE TABLE IF NOT EXISTS refs (
+  src_chunk_id TEXT NOT NULL,
+  dst_symbol TEXT NOT NULL,
+  PRIMARY KEY (src_chunk_id, dst_symbol)
+);
+CREATE INDEX IF NOT EXISTS idx_dst ON refs(dst_symbol);
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT
+);
+CREATE TABLE IF NOT EXISTS md_knowledge (
+  chunk_id TEXT PRIMARY KEY,
+  file_path TEXT NOT NULL,
+  dir_path TEXT NOT NULL,
+  depth INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_md_dir ON md_knowledge(dir_path);
+"""
+
+
+class AstGraph:
+    """Project-local symbol graph."""
+
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._walk_cache: tuple[dict[str, str], dict[str, list[str]], dict[str, list[str]]] | None = None
+        self._walk_sha: str | None = None
+        self._initialize()
+
+    @contextlib.contextmanager
+    def _connect(self):
+        """Open a connection scoped to the `with` block; always closed on exit.
+
+        A bare `with sqlite3.connect(...) as conn:` only manages the
+        transaction, not the connection's lifetime — every call site here
+        used that pattern, leaking a file handle to ast.sqlite per call. On
+        Windows those leaked handles hold a mandatory lock, so a stuck
+        reader (e.g. a hung MCP call) could permanently block the writer
+        (reindex swap). `timeout` makes SQLite retry instead of failing
+        immediately when a lock is briefly held by another connection.
+        """
+        conn = sqlite3.connect(self.db_path, timeout=30)
+        try:
+            yield conn
+            conn.commit()
+        except BaseException:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def _initialize(self) -> None:
+        with self._connect() as conn:
+            conn.executescript(SCHEMA)
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.execute("PRAGMA busy_timeout=30000")
+
+    def clear_all(self) -> None:
+        """Delete all rows."""
+        self._walk_cache = None
+        self._walk_sha = None
+        with self._connect() as conn:
+            conn.execute("DELETE FROM refs")
+            conn.execute("DELETE FROM symbols")
+            conn.execute("DELETE FROM meta")
+            conn.execute("DELETE FROM md_knowledge")
+
+    def upsert_symbols(self, chunks: list[CodeChunk]) -> None:
+        """Insert or update symbol metadata."""
+
+        with self._connect() as conn:
+            conn.executemany(
+                """
+                INSERT INTO symbols (chunk_id, symbol, file_path, kind, signature)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(chunk_id) DO UPDATE SET
+                  symbol=excluded.symbol,
+                  file_path=excluded.file_path,
+                  kind=excluded.kind,
+                  signature=excluded.signature
+                """,
+                [(chunk.chunk_id, chunk.symbol, chunk.file_path, chunk.kind, chunk.signature) for chunk in chunks],
+            )
+
+    def delete_by_file(self, file_path: str) -> None:
+        """Remove all metadata for a file."""
+
+        with self._connect() as conn:
+            chunk_rows = conn.execute("SELECT chunk_id FROM symbols WHERE file_path = ?", (file_path,)).fetchall()
+            chunk_ids = [row[0] for row in chunk_rows]
+            conn.execute("DELETE FROM symbols WHERE file_path = ?", (file_path,))
+            for chunk_id in chunk_ids:
+                conn.execute("DELETE FROM refs WHERE src_chunk_id = ?", (chunk_id,))
+            conn.execute("DELETE FROM md_knowledge WHERE file_path = ?", (file_path,))
+
+    def add_references(self, chunk_id: str, referenced_symbols: list[str]) -> None:
+        """Upsert lightweight references for a chunk."""
+
+        with self._connect() as conn:
+            conn.execute("DELETE FROM refs WHERE src_chunk_id = ?", (chunk_id,))
+            conn.executemany(
+                "INSERT OR IGNORE INTO refs (src_chunk_id, dst_symbol) VALUES (?, ?)",
+                [(chunk_id, symbol) for symbol in referenced_symbols],
+            )
+
+    def add_references_bulk(self, chunks_deps: list[tuple[str, list[str]]]) -> None:
+        """Upsert references for all chunks in a single transaction."""
+
+        if not chunks_deps:
+            return
+        with self._connect() as conn:
+            conn.executemany(
+                "DELETE FROM refs WHERE src_chunk_id = ?",
+                [(cid,) for cid, _ in chunks_deps],
+            )
+            rows = [(cid, sym) for cid, deps in chunks_deps for sym in deps]
+            if rows:
+                conn.executemany(
+                    "INSERT OR IGNORE INTO refs (src_chunk_id, dst_symbol) VALUES (?, ?)",
+                    rows,
+                )
+
+    def upsert_md_knowledge(self, chunks: list[CodeChunk]) -> None:
+        """Register markdown knowledge chunks by directory scope."""
+        if not chunks:
+            return
+        rows = []
+        for chunk in chunks:
+            dir_path = Path(chunk.file_path).parent.as_posix()
+            depth = len(Path(chunk.file_path).parent.parts)
+            rows.append((chunk.chunk_id, chunk.file_path, dir_path, depth))
+        with self._connect() as conn:
+            conn.executemany(
+                """INSERT INTO md_knowledge (chunk_id, file_path, dir_path, depth)
+                   VALUES (?, ?, ?, ?)
+                   ON CONFLICT(chunk_id) DO UPDATE SET
+                     file_path=excluded.file_path,
+                     dir_path=excluded.dir_path,
+                     depth=excluded.depth""",
+                rows,
+            )
+
+    def get_md_chunk_ids_for_dirs(self, dir_paths: list[str]) -> list[str]:
+        """Return MD chunk IDs for the given directory paths, ordered deepest first."""
+        if not dir_paths:
+            return []
+        placeholders = ','.join('?' * len(dir_paths))
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"SELECT chunk_id FROM md_knowledge WHERE dir_path IN ({placeholders}) ORDER BY depth DESC",
+                dir_paths,
+            ).fetchall()
+        return [row[0] for row in rows]
+
+    def find_callers(self, symbol: str) -> list[str]:
+        """Return chunk ids that reference a symbol."""
+
+        with self._connect() as conn:
+            rows = conn.execute("SELECT src_chunk_id FROM refs WHERE dst_symbol = ?", (symbol,)).fetchall()
+        return [row[0] for row in rows]
+
+    def find_callees(self, chunk_id: str) -> list[str]:
+        """Resolve referenced symbols to chunk ids."""
+
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT DISTINCT symbols.chunk_id
+                FROM refs
+                JOIN symbols ON symbols.symbol = refs.dst_symbol
+                WHERE refs.src_chunk_id = ?
+                """,
+                (chunk_id,),
+            ).fetchall()
+        return [row[0] for row in rows]
+
+    def find_callers_batch(self, symbols: list[str]) -> dict[str, list[str]]:
+        """Return {symbol: [caller_chunk_ids]} for all given symbols in a single query."""
+
+        if not symbols:
+            return {}
+        placeholders = ",".join("?" * len(symbols))
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"SELECT dst_symbol, src_chunk_id FROM refs WHERE dst_symbol IN ({placeholders})",
+                symbols,
+            ).fetchall()
+        result: dict[str, list[str]] = {s: [] for s in symbols}
+        for dst_symbol, src_chunk_id in rows:
+            result[dst_symbol].append(src_chunk_id)
+        return result
+
+    def find_callees_batch(self, chunk_ids: list[str]) -> dict[str, list[str]]:
+        """Return {chunk_id: [callee_chunk_ids]} for all given chunk_ids in a single query."""
+
+        if not chunk_ids:
+            return {}
+        placeholders = ",".join("?" * len(chunk_ids))
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"""
+                SELECT DISTINCT refs.src_chunk_id, symbols.chunk_id
+                FROM refs
+                JOIN symbols ON symbols.symbol = refs.dst_symbol
+                WHERE refs.src_chunk_id IN ({placeholders})
+                """,
+                chunk_ids,
+            ).fetchall()
+        result: dict[str, list[str]] = {cid: [] for cid in chunk_ids}
+        for src_chunk_id, callee_chunk_id in rows:
+            result[src_chunk_id].append(callee_chunk_id)
+        return result
+
+    def get_symbol(self, chunk_id: str) -> str | None:
+        """Return a symbol name for a chunk id."""
+
+        with self._connect() as conn:
+            row = conn.execute("SELECT symbol FROM symbols WHERE chunk_id = ?", (chunk_id,)).fetchone()
+        return row[0] if row else None
+
+    def load_for_walk(self) -> tuple[dict[str, str], dict[str, list[str]], dict[str, list[str]]]:
+        """Load the full graph into memory for BFS traversal.
+
+        Returns (symbol_map, callees_map, callers_map) where:
+          symbol_map[chunk_id]     -> symbol name
+          callees_map[chunk_id]    -> [chunk_ids that chunk_id references]
+          callers_map[symbol_name] -> [chunk_ids that reference that symbol]
+        """
+        with self._connect() as conn:
+            sym_rows = conn.execute("SELECT chunk_id, symbol FROM symbols").fetchall()
+            ref_rows = conn.execute("SELECT src_chunk_id, dst_symbol FROM refs").fetchall()
+
+        symbol_map: dict[str, str] = {r[0]: r[1] for r in sym_rows}
+        sym_to_chunk: dict[str, str] = {v: k for k, v in symbol_map.items()}
+
+        callees_map: dict[str, list[str]] = {}
+        callers_map: dict[str, list[str]] = {}
+        for src_chunk_id, dst_symbol in ref_rows:
+            dst_chunk = sym_to_chunk.get(dst_symbol)
+            if dst_chunk:
+                callees_map.setdefault(src_chunk_id, []).append(dst_chunk)
+            callers_map.setdefault(dst_symbol, []).append(src_chunk_id)
+
+        return symbol_map, callees_map, callers_map
+
+    def load_for_walk_cached(self) -> tuple[dict[str, str], dict[str, list[str]], dict[str, list[str]]]:
+        """Return cached graph; reloads only when SHA has changed since last load."""
+        current_sha = self.get_last_indexed_sha()
+        if self._walk_cache is not None and self._walk_sha == current_sha:
+            return self._walk_cache
+        result = self.load_for_walk()
+        self._walk_cache = result
+        self._walk_sha = current_sha
+        return result
+
+    def flush_all(self, chunks: list[CodeChunk], sha: str) -> None:
+        """Build entire graph in :memory: then backup to disk in one write."""
+        mem = sqlite3.connect(":memory:")
+        mem.executescript(SCHEMA)
+        if chunks:
+            mem.executemany(
+                "INSERT OR IGNORE INTO symbols (chunk_id, symbol, file_path, kind, signature) VALUES (?,?,?,?,?)",
+                [(c.chunk_id, c.symbol, c.file_path, c.kind, c.signature) for c in chunks],
+            )
+            ref_rows = [(c.chunk_id, sym) for c in chunks for sym in c.deps]
+            if ref_rows:
+                mem.executemany(
+                    "INSERT OR IGNORE INTO refs (src_chunk_id, dst_symbol) VALUES (?,?)",
+                    ref_rows,
+                )
+            md_rows = [
+                (c.chunk_id, c.file_path, Path(c.file_path).parent.as_posix(), len(Path(c.file_path).parent.parts))
+                for c in chunks if c.language == 'markdown'
+            ]
+            if md_rows:
+                mem.executemany(
+                    "INSERT OR IGNORE INTO md_knowledge (chunk_id, file_path, dir_path, depth) VALUES (?,?,?,?)",
+                    md_rows,
+                )
+        # Compute export_surface_hash over the frozen symbols table BEFORE commit.
+        sym_names = [row[0] for row in mem.execute("SELECT symbol FROM symbols").fetchall()]
+        export_hash = _compute_export_surface_hash(sym_names)
+        mem.execute(
+            "INSERT INTO meta (key, value) VALUES ('export_surface_hash', ?)",
+            (export_hash,),
+        )
+        mem.execute(
+            "INSERT INTO meta (key, value) VALUES ('last_indexed_sha', ?)",
+            (sha,),
+        )
+        mem.commit()
+        dest = sqlite3.connect(self.db_path)
+        mem.backup(dest)
+        dest.close()
+        mem.close()
+        self._walk_cache = None
+        self._walk_sha = None
+
+    def get_last_indexed_sha(self) -> str | None:
+        """Return last indexed SHA."""
+
+        with self._connect() as conn:
+            row = conn.execute("SELECT value FROM meta WHERE key = 'last_indexed_sha'").fetchone()
+        return row[0] if row else None
+
+    def set_last_indexed_sha(self, sha: str) -> None:
+        """Persist last indexed SHA."""
+
+        self.set_meta("last_indexed_sha", sha)
+
+    def get_export_surface_hash(self) -> str | None:
+        """Return the current export_surface_hash, or None if not yet computed."""
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT value FROM meta WHERE key = 'export_surface_hash'"
+            ).fetchone()
+        return row[0] if row else None
+
+    def recompute_export_surface_hash(self) -> str:
+        """Recompute and persist export_surface_hash after an incremental symbol update."""
+        with self._connect() as conn:
+            names = [row[0] for row in conn.execute("SELECT symbol FROM symbols").fetchall()]
+            h = _compute_export_surface_hash(names)
+            conn.execute(
+                "INSERT INTO meta (key, value) VALUES ('export_surface_hash', ?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (h,),
+            )
+        return h
+
+    def set_meta(self, key: str, value: str) -> None:
+        """Set arbitrary meta value."""
+
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (key, value),
+            )
+
+    def get_chunk_count(self) -> int:
+        """Return number of indexed symbols."""
+
+        with self._connect() as conn:
+            row = conn.execute("SELECT COUNT(*) FROM symbols").fetchone()
+        return int(row[0] if row else 0)
+
+    def get_all_symbols(self) -> list[tuple[str, str, str, str, str | None]]:
+        """Return all (chunk_id, symbol, file_path, kind, signature) sorted by file_path."""
+
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT chunk_id, symbol, file_path, kind, signature FROM symbols ORDER BY file_path, symbol"
+            ).fetchall()
+        return [(r[0], r[1], r[2], r[3], r[4]) for r in rows]
+
+    def lookup_symbol(self, symbol: str, file_path: str) -> str | None:
+        """Return chunk_id for the given (symbol, file_path), or None if not found."""
+
+        normalized = file_path.replace("\\", "/")
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT chunk_id FROM symbols WHERE symbol = ? AND replace(file_path, '\\', '/') = ? LIMIT 1",
+                (symbol, normalized),
+            ).fetchone()
+        return row[0] if row else None
+
+    def export_artifact(self, artifact_path: Path) -> None:
+        """Compress the live SQLite db to a .graph.zst file via VACUUM INTO + zstd."""
+        import zstandard
+        tmp = artifact_path.with_suffix(".vacuumed.db")
+        try:
+            with self._connect() as conn:
+                conn.execute(f"VACUUM INTO '{tmp.as_posix()}'")
+            artifact_path.write_bytes(zstandard.ZstdCompressor(level=3).compress(tmp.read_bytes()))
+        finally:
+            if tmp.exists():
+                tmp.unlink()
+
+    def import_artifact(self, artifact_path: Path) -> None:
+        """Decompress .graph.zst artifact and replace the current db via SQLite backup API."""
+        import zstandard
+        data = zstandard.ZstdDecompressor().decompress(artifact_path.read_bytes())
+        tmp = artifact_path.with_suffix(".restore.db")
+        try:
+            tmp.write_bytes(data)
+            src = sqlite3.connect(tmp)
+            dst = sqlite3.connect(self.db_path)
+            src.backup(dst)
+            dst.close()
+            src.close()
+        finally:
+            if tmp.exists():
+                tmp.unlink()
+        self._walk_cache = None
+        self._walk_sha = None

codepreproc_client/layer2_tooling/condensation/bm25_store.py

@@ -0,0 +1,132 @@
+"""BM25 storage wrapper."""
+
+from __future__ import annotations
+
+import pickle
+import re
+from pathlib import Path
+
+import bm25s
+
+from contracts.dtos import CodeChunk, ScoredChunk
+
+_TOKEN_BOUNDARY_RE = re.compile(r"[^A-Za-z0-9_]+")
+_CAMEL_RE = re.compile(r"([a-z0-9])([A-Z])")
+
+
+class BM25Store:
+    """Per-project BM25 index with simple pickle persistence."""
+
+    def __init__(self, store_path: Path) -> None:
+        self.store_path = store_path
+        self._loaded = False
+        self._bm25: bm25s.BM25 | None = None
+        self._corpus_tokens: list[list[str]] = []
+        self._corpus_docs: list[str] = []
+        self._chunk_map: dict[str, CodeChunk] = {}
+        self._file_map: dict[str, set[str]] = {}
+
+    def load(self) -> None:
+        """Load persisted state lazily."""
+
+        if self._loaded:
+            return
+        if self.store_path.exists():
+            data = pickle.loads(self.store_path.read_bytes())
+            self._corpus_tokens = data["corpus_tokens"]
+            self._corpus_docs = data["corpus_docs"]
+            self._chunk_map = {key: CodeChunk.model_validate(value) for key, value in data["chunk_map"].items()}
+            self._file_map = {key: set(value) for key, value in data["file_map"].items()}
+            self._rebuild_index()
+        self._loaded = True
+
+    def reset(self) -> None:
+        """Clear all in-memory state."""
+
+        self._bm25 = None
+        self._corpus_tokens = []
+        self._corpus_docs = []
+        self._chunk_map = {}
+        self._file_map = {}
+        self._loaded = True
+
+    def persist(self) -> None:
+        """Persist the current state."""
+
+        self.store_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "corpus_tokens": self._corpus_tokens,
+            "corpus_docs": self._corpus_docs,
+            "chunk_map": {key: value.model_dump(mode="json") for key, value in self._chunk_map.items()},
+            "file_map": {key: sorted(value) for key, value in self._file_map.items()},
+        }
+        self.store_path.write_bytes(pickle.dumps(payload))
+
+    def add_chunks(self, chunks: list[CodeChunk]) -> None:
+        """Add chunks and rebuild index."""
+
+        self.load()
+        for chunk in chunks:
+            self._chunk_map[chunk.chunk_id] = chunk
+            self._file_map.setdefault(chunk.file_path, set()).add(chunk.chunk_id)
+        self._rebuild_documents()
+
+    def remove_by_file(self, file_path: str) -> None:
+        """Remove all chunks belonging to a file."""
+
+        self.load()
+        for chunk_id in self._file_map.pop(file_path, set()):
+            self._chunk_map.pop(chunk_id, None)
+        self._rebuild_documents()
+
+    def search(self, query: str, top_k: int) -> list[ScoredChunk]:
+        """Search lexically."""
+
+        self.load()
+        if not self._bm25 or not self._corpus_tokens:
+            return []
+        capped_k = min(top_k, len(self._corpus_docs))
+        if capped_k <= 0:
+            return []
+        results = self._bm25.retrieve([self.tokenize(query)], corpus=self._corpus_docs, k=capped_k, show_progress=False)
+        documents = results.documents[0].tolist() if len(results.documents) else []
+        scores = results.scores[0].tolist() if len(results.scores) else []
+        found: list[ScoredChunk] = []
+        for document, score in zip(documents, scores, strict=False):
+            chunk = self._chunk_map.get(document)
+            if chunk:
+                found.append(ScoredChunk(chunk=chunk, score=float(score), source="bm25"))
+        return found
+
+    def get_by_ids(self, chunk_ids: list[str]) -> list[CodeChunk]:
+        """Return chunks for the given IDs, preserving order and skipping missing."""
+        self.load()
+        return [self._chunk_map[cid] for cid in chunk_ids if cid in self._chunk_map]
+
+    def chunk_count(self) -> int:
+        """Return indexed chunk count."""
+
+        self.load()
+        return len(self._chunk_map)
+
+    @staticmethod
+    def tokenize(text: str) -> list[str]:
+        """Split code-aware tokens."""
+
+        normalized = _CAMEL_RE.sub(r"\1 \2", text.replace(".", " ").replace("/", " ").replace("\\", " "))
+        return [token.lower() for token in _TOKEN_BOUNDARY_RE.split(normalized) if token]
+
+    def _rebuild_documents(self) -> None:
+        self._corpus_docs = list(self._chunk_map.keys())
+        self._corpus_tokens = [
+            self.tokenize(f"{chunk.file_path} {chunk.symbol} {chunk.signature or ''} {chunk.body}")
+            for chunk in self._chunk_map.values()
+        ]
+        self._rebuild_index()
+
+    def _rebuild_index(self) -> None:
+        if not self._corpus_tokens:
+            self._bm25 = None
+            return
+        self._bm25 = bm25s.BM25()
+        self._bm25.index(self._corpus_tokens, show_progress=False)