code-context-mcp 1.0.0__py3-none-any.whl

code_context/__init__.py

@@ -0,0 +1,3 @@
+"""code-context: MCP server with local RAG for Claude Code repo context."""
+
+__version__ = "1.0.0"

code_context/_background.py

@@ -0,0 +1,93 @@
+"""BackgroundIndexer — runs reindex on a worker thread, posts to the bus.
+
+Single-threaded coordinator. External code calls `.trigger()` to ask
+for a reindex; the thread coalesces multiple triggers into one job
+(an `Event` is set/cleared, not a queue), so a 5-event burst from a
+file watcher saving in rapid succession produces ONE reindex, not
+five. On completion, the configured `swap` callback runs first
+(typically `_atomic_swap_current` from the composition root) and
+then `bus.publish_swap(new_dir)` notifies any subscriber.
+
+Errors in the indexer are caught and logged at ERROR level; the
+worker keeps running so the next trigger has a chance. This matches
+the philosophy of "background reindex must never crash the MCP
+server."
+
+The thread is daemonic so it doesn't block process exit if `.stop()`
+is missed (e.g., a hard SIGINT before the main loop's finally
+block). `.stop()` itself sets a flag and joins with a 5 s timeout
+by default; longer for the ~1 s default `idle_seconds`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from code_context.domain.index_bus import IndexUpdateBus
+
+log = logging.getLogger(__name__)
+
+
+class BackgroundIndexer(threading.Thread):
+    def __init__(
+        self,
+        *,
+        indexer: Any,  # IndexerUseCase, untyped to avoid circular import
+        swap: Callable[[Path], None],
+        bus: IndexUpdateBus,
+        idle_seconds: float = 1.0,
+    ) -> None:
+        super().__init__(name="code-context-bg-indexer", daemon=True)
+        self._indexer = indexer
+        self._swap = swap
+        self._bus = bus
+        self._idle = idle_seconds
+        self._wake = threading.Event()
+        self._stop_event = threading.Event()
+
+    def trigger(self) -> None:
+        """Ask the worker thread to run a reindex.
+
+        Idempotent within an idle window: 5 rapid triggers coalesce
+        into one job because the Event is sticky until consumed.
+        """
+        self._wake.set()
+
+    def stop(self, timeout: float = 5.0) -> None:
+        """Signal the worker to exit and join up to `timeout` seconds."""
+        self._stop_event.set()
+        self._wake.set()  # break out of `wait()`
+        self.join(timeout=timeout)
+
+    def run(self) -> None:
+        while not self._stop_event.is_set():
+            self._wake.wait()
+            self._wake.clear()
+            if self._stop_event.is_set():
+                return
+            try:
+                self._reindex_once()
+            except Exception:  # noqa: BLE001 - bg failure must not kill the thread
+                log.exception("background reindex failed; will retry on next trigger")
+            # Idle so rapid triggers coalesce; stop_event lets `.stop()`
+            # break out without waiting the full window.
+            self._stop_event.wait(self._idle)
+
+    def _reindex_once(self) -> None:
+        stale = self._indexer.dirty_set()
+        no_work = (
+            not stale.full_reindex_required and not stale.dirty_files and not stale.deleted_files
+        )
+        if no_work:
+            return
+        if stale.full_reindex_required:
+            new_dir = self._indexer.run()
+        else:
+            new_dir = self._indexer.run_incremental(stale)
+        self._swap(new_dir)
+        self._bus.publish_swap(str(new_dir))
+        log.info("background reindex complete (%s) -> %s", stale.reason, new_dir)

code_context/_composition.py

@@ -0,0 +1,425 @@
+"""Composition helpers shared by server.py and cli.py."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from code_context.adapters.driven.chunker_dispatcher import ChunkerDispatcher
+from code_context.adapters.driven.chunker_line import LineChunker
+from code_context.adapters.driven.chunker_treesitter import TreeSitterChunker
+from code_context.adapters.driven.code_source_fs import FilesystemSource
+from code_context.adapters.driven.embeddings_local import LocalST
+from code_context.adapters.driven.git_source_cli import GitCliSource
+from code_context.adapters.driven.introspector_fs import FilesystemIntrospector
+from code_context.adapters.driven.keyword_index_sqlite import SqliteFTS5Index
+from code_context.adapters.driven.reranker_crossencoder import CrossEncoderReranker
+from code_context.adapters.driven.symbol_index_sqlite import SymbolIndexSqlite
+from code_context.adapters.driven.vector_store_numpy import NumPyParquetStore
+from code_context.config import Config
+from code_context.domain.index_bus import IndexUpdateBus
+from code_context.domain.models import StaleSet
+from code_context.domain.ports import (
+    Chunker,
+    EmbeddingsProvider,
+    KeywordIndex,
+    Reranker,
+    SymbolIndex,
+)
+from code_context.domain.use_cases.explain_diff import ExplainDiffUseCase
+from code_context.domain.use_cases.find_definition import FindDefinitionUseCase
+from code_context.domain.use_cases.find_references import FindReferencesUseCase
+from code_context.domain.use_cases.get_file_tree import GetFileTreeUseCase
+from code_context.domain.use_cases.get_summary import GetSummaryUseCase
+from code_context.domain.use_cases.indexer import IndexerUseCase
+from code_context.domain.use_cases.recent_changes import RecentChangesUseCase
+from code_context.domain.use_cases.search_repo import SearchRepoUseCase
+
+log = logging.getLogger("code_context")
+
+
+class _NullKeywordIndex:
+    """No-op keyword index for users who set CC_KEYWORD_INDEX=none.
+
+    Implements the KeywordIndex Protocol with search returning []. Lets the
+    hybrid pipeline degrade gracefully to vector-only without special-casing
+    in SearchRepoUseCase.
+    """
+
+    @property
+    def version(self) -> str:
+        return "null-v1"
+
+    def add(self, entries) -> None:
+        pass
+
+    def search(self, query: str, k: int):
+        return []
+
+    def delete_by_path(self, path: str) -> int:
+        return 0
+
+    def persist(self, path) -> None:
+        pass
+
+    def load(self, path) -> None:
+        pass
+
+
+class _NullSymbolIndex:
+    """No-op symbol index for users who set CC_SYMBOL_INDEX=none.
+
+    Implements the SymbolIndex Protocol; find_definition/find_references
+    return []. Lets users disable the symbol pipeline without breaking
+    composition (e.g., on platforms where SQLite FTS5 misbehaves).
+    """
+
+    @property
+    def version(self) -> str:
+        return "null-symbol-v1"
+
+    def add_definitions(self, defs) -> None:
+        pass
+
+    def add_references(self, refs) -> None:
+        pass
+
+    def find_definition(self, name, language=None, max_count=5):
+        return []
+
+    def find_references(self, name, max_count=50):
+        return []
+
+    def delete_by_path(self, path: str) -> int:
+        return 0
+
+    def persist(self, path) -> None:
+        pass
+
+    def load(self, path) -> None:
+        pass
+
+
+def build_embeddings(cfg: Config) -> EmbeddingsProvider:
+    if cfg.embeddings_provider == "openai":
+        if not cfg.openai_api_key:
+            log.error("CC_EMBEDDINGS=openai but OPENAI_API_KEY is unset")
+            sys.exit(1)
+        from code_context.adapters.driven.embeddings_openai import OpenAIProvider
+
+        return OpenAIProvider(
+            model=cfg.embeddings_model or "text-embedding-3-small",
+            api_key=cfg.openai_api_key,
+        )
+    return LocalST(
+        model_name=cfg.embeddings_model or "all-MiniLM-L6-v2",
+        trust_remote_code=cfg.trust_remote_code,
+    )
+
+
+def build_chunker(cfg: Config) -> Chunker:
+    """Build the chunker according to cfg.chunker_strategy.
+
+    "treesitter" (default in v0.2.0+): TreeSitterChunker for Py/JS/TS/Go/Rust,
+    LineChunker for everything else AND for parse errors. "line": legacy
+    behavior — LineChunker only. Anything else logs an error and falls back
+    to LineChunker so composition root never crashes on bad config.
+    """
+    line = LineChunker(chunk_lines=cfg.chunk_lines, overlap=cfg.chunk_overlap)
+    if cfg.chunker_strategy == "line":
+        return line
+    if cfg.chunker_strategy == "treesitter":
+        return ChunkerDispatcher(treesitter=TreeSitterChunker(), line=line)
+    log.error("unknown CC_CHUNKER=%r; falling back to line", cfg.chunker_strategy)
+    return line
+
+
+def build_keyword_index(cfg: Config) -> KeywordIndex:
+    if cfg.keyword_strategy == "none":
+        return _NullKeywordIndex()
+    if cfg.keyword_strategy == "sqlite":
+        return SqliteFTS5Index()
+    log.error(
+        "unknown CC_KEYWORD_INDEX=%r; falling back to sqlite",
+        cfg.keyword_strategy,
+    )
+    return SqliteFTS5Index()
+
+
+def build_symbol_index(cfg: Config) -> SymbolIndex:
+    if cfg.symbol_index_strategy == "none":
+        return _NullSymbolIndex()
+    if cfg.symbol_index_strategy == "sqlite":
+        return SymbolIndexSqlite()
+    log.error(
+        "unknown CC_SYMBOL_INDEX=%r; falling back to sqlite",
+        cfg.symbol_index_strategy,
+    )
+    return SymbolIndexSqlite()
+
+
+def build_reranker(cfg: Config) -> Reranker | None:
+    if not cfg.rerank:
+        return None
+    return CrossEncoderReranker(
+        model_name=cfg.rerank_model or "cross-encoder/ms-marco-MiniLM-L-6-v2",
+    )
+
+
+def build_indexer_and_store(
+    cfg: Config,
+) -> tuple[
+    IndexerUseCase,
+    NumPyParquetStore,
+    EmbeddingsProvider,
+    KeywordIndex,
+    SymbolIndex,
+]:
+    cfg.repo_cache_subdir().mkdir(parents=True, exist_ok=True)
+
+    embeddings = build_embeddings(cfg)
+    chunker = build_chunker(cfg)
+    code_source = FilesystemSource()
+    git_source = GitCliSource()
+    store = NumPyParquetStore()
+    keyword_index = build_keyword_index(cfg)
+    symbol_index = build_symbol_index(cfg)
+    indexer = IndexerUseCase(
+        cache_dir=cfg.repo_cache_subdir(),
+        repo_root=cfg.repo_root,
+        embeddings=embeddings,
+        vector_store=store,
+        keyword_index=keyword_index,
+        symbol_index=symbol_index,
+        chunker=chunker,
+        code_source=code_source,
+        git_source=git_source,
+        include_extensions=cfg.include_extensions,
+        max_file_bytes=cfg.max_file_bytes,
+    )
+    return indexer, store, embeddings, keyword_index, symbol_index
+
+
+def build_use_cases(
+    cfg: Config,
+    indexer: IndexerUseCase,
+    store: NumPyParquetStore,
+    embeddings: EmbeddingsProvider,
+    keyword_index: KeywordIndex,
+    symbol_index: SymbolIndex,
+    bus: IndexUpdateBus | None = None,
+    reload_callback: Callable[[], None] | None = None,
+) -> tuple[
+    SearchRepoUseCase,
+    RecentChangesUseCase,
+    GetSummaryUseCase,
+    FindDefinitionUseCase,
+    FindReferencesUseCase,
+    GetFileTreeUseCase,
+    ExplainDiffUseCase,
+]:
+    git_source = GitCliSource()
+    introspector = FilesystemIntrospector()
+    code_source = FilesystemSource()
+    chunker = build_chunker(cfg)
+    reranker = build_reranker(cfg)
+    return (
+        SearchRepoUseCase(
+            embeddings=embeddings,
+            vector_store=store,
+            keyword_index=keyword_index,
+            reranker=reranker,
+            bus=bus,
+            reload_callback=reload_callback,
+        ),
+        RecentChangesUseCase(git_source=git_source, repo_root=cfg.repo_root),
+        GetSummaryUseCase(introspector=introspector, repo_root=cfg.repo_root),
+        FindDefinitionUseCase(symbol_index=symbol_index),
+        FindReferencesUseCase(symbol_index=symbol_index),
+        GetFileTreeUseCase(code_source=code_source, repo_root=cfg.repo_root),
+        ExplainDiffUseCase(
+            chunker=chunker,
+            code_source=code_source,
+            git_source=git_source,
+            repo_root=cfg.repo_root,
+        ),
+    )
+
+
+def make_reload_callback(
+    indexer: IndexerUseCase,
+    store: NumPyParquetStore,
+    keyword_index: KeywordIndex,
+    symbol_index: SymbolIndex,
+) -> Callable[[], None]:
+    """Build the closure that SearchRepoUseCase fires on bus drift.
+
+    Reloads all 3 stores from whatever current.json says is active.
+    No-op if there's no current index yet (cold-start case where
+    the bg indexer hasn't published its first swap). Returns None
+    so the use case's reload-on-tick path remains side-effects-only.
+    """
+
+    def _reload() -> None:
+        active = indexer.current_index_dir()
+        if active is None or not active.exists():
+            return
+        store.load(active)
+        try:
+            keyword_index.load(active)
+            symbol_index.load(active)
+        except FileNotFoundError:
+            # Reindex was published but one of the stores' files isn't
+            # there yet (race between persist + swap); next bus tick
+            # will reload again.
+            log.warning(
+                "reload: keyword/symbol index missing in %s; will retry next swap",
+                active,
+            )
+
+    return _reload
+
+
+def fast_load_existing_index(
+    indexer: IndexerUseCase,
+    store: NumPyParquetStore,
+    keyword_index: KeywordIndex,
+    symbol_index: SymbolIndex,
+) -> bool:
+    """Sprint 7: load whatever's already on disk WITHOUT triggering a
+    reindex. Returns True if all 3 stores loaded successfully, False
+    if the cache is empty / partial — caller should fall back to
+    `ensure_index` (synchronous reindex) or rely on the bg indexer to
+    populate fresh.
+    """
+    active = indexer.current_index_dir()
+    if active is None or not active.exists():
+        return False
+    try:
+        store.load(active)
+        keyword_index.load(active)
+        symbol_index.load(active)
+    except FileNotFoundError:
+        return False
+    return True
+
+
+def atomic_swap_current(cfg: Config, new_dir: Path) -> None:
+    """Update current.json to point at `new_dir.name`, atomically.
+
+    The bg indexer's swap callback. Mirrors the inline swap in
+    safe_reindex(); split out so the BackgroundIndexer can use it
+    directly without re-acquiring the file lock (the bg thread already
+    holds the lock during its run_incremental call when invoked via
+    safe_reindex; but when we wire it directly to the bg thread we
+    need a thinner helper that just updates current.json).
+    """
+    current_path = cfg.repo_cache_subdir() / "current.json"
+    tmp = current_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps({"active": new_dir.name, "version": 1}))
+    os.replace(tmp, current_path)
+
+
+def _lock_path(cfg: Config) -> Path:
+    cfg.repo_cache_subdir().mkdir(parents=True, exist_ok=True)
+    return cfg.repo_cache_subdir() / ".lock"
+
+
+def safe_reindex(
+    cfg: Config,
+    indexer: IndexerUseCase,
+    stale: StaleSet | None = None,
+) -> Path:
+    """Run reindex (full or incremental) protected by a cross-platform file lock.
+
+    Acquires the lock or blocks for up to 5 min. Returns the path of the
+    new index dir AND atomically swaps current.json to point at it.
+
+    If `stale` is omitted or has `full_reindex_required=True`, runs the
+    legacy full `indexer.run()`. Otherwise dispatches to
+    `indexer.run_incremental(stale)` so only `stale.dirty_files` get
+    re-embedded — the Sprint 6 win that turns a 1-2 minute edit-cycle
+    reindex into <10s on a typical repo.
+    """
+    from filelock import FileLock, Timeout
+
+    lock = FileLock(str(_lock_path(cfg)), timeout=300)
+    try:
+        with lock:
+            log.info("acquired reindex lock at %s", _lock_path(cfg))
+            if stale is not None and not stale.full_reindex_required:
+                new_dir = indexer.run_incremental(stale)
+            else:
+                new_dir = indexer.run()
+            current_path = cfg.repo_cache_subdir() / "current.json"
+            tmp = current_path.with_suffix(".json.tmp")
+            tmp.write_text(json.dumps({"active": new_dir.name, "version": 1}))
+            os.replace(tmp, current_path)
+            return new_dir
+    except Timeout as exc:
+        raise RuntimeError(
+            f"could not acquire reindex lock at {_lock_path(cfg)} after 5 min; "
+            "is another reindex running? if not, delete the .lock file and retry."
+        ) from exc
+
+
+def ensure_index(
+    cfg: Config,
+    indexer: IndexerUseCase,
+    store: NumPyParquetStore,
+    keyword_index: KeywordIndex,
+    symbol_index: SymbolIndex,
+) -> None:
+    """Ensure the on-disk index is fresh, reusing it if possible.
+
+    Sprint 6 routing: ask the indexer for a `dirty_set()` once, then:
+      - StaleSet says no work → load the active index, return.
+      - StaleSet says full reindex required → full `indexer.run()`.
+      - Otherwise → `indexer.run_incremental(stale)`; only the
+        `dirty_files` pay the embedding cost.
+
+    Pre-Sprint-3 caches without keyword.sqlite and pre-Sprint-4 ones
+    without symbols.sqlite still self-heal: load() raises FileNotFound,
+    which forces a full reindex via the `_force_full` short-circuit.
+    """
+    stale = indexer.dirty_set()
+    no_work = not stale.full_reindex_required and not stale.dirty_files and not stale.deleted_files
+    if no_work:
+        current = indexer.current_index_dir()
+        if current is not None:
+            log.info("loading existing index from %s", current)
+            store.load(current)
+            try:
+                keyword_index.load(current)
+                symbol_index.load(current)
+            except FileNotFoundError:
+                log.info(
+                    "keyword or symbol index missing in %s; reindexing to backfill",
+                    current,
+                )
+                new_dir = safe_reindex(cfg, indexer)  # full
+                store.load(new_dir)
+                keyword_index.load(new_dir)
+                symbol_index.load(new_dir)
+            return
+    log.info(
+        "ensure_index: %s — running %s reindex",
+        stale.reason,
+        "full" if stale.full_reindex_required else "incremental",
+    )
+    new_dir = safe_reindex(cfg, indexer, stale=stale)
+    store.load(new_dir)
+    keyword_index.load(new_dir)
+    symbol_index.load(new_dir)
+
+
+def setup_logging(cfg: Config) -> None:
+    logging.basicConfig(
+        level=cfg.log_level,
+        stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )

code_context/_watcher.py

@@ -0,0 +1,89 @@
+"""RepoWatcher — debounced file-system watcher that triggers reindex.
+
+Lazily imports `watchdog` (it's an optional `[watch]` extra). Listens
+for created/modified/deleted/moved events under `cfg.repo_root`,
+debounces them with a configurable delay, and calls `on_change()`
+once per quiet window.
+
+If `watchdog` isn't installed, `start()` logs a warning and becomes a
+no-op so users who set `CC_WATCH=on` without the extra get a clear
+signal instead of a hard crash.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+class RepoWatcher:
+    def __init__(
+        self,
+        root: Path,
+        on_change: Callable[[], None],
+        debounce_ms: int = 1000,
+    ) -> None:
+        self._root = root
+        self._on_change = on_change
+        self._debounce_s = max(debounce_ms, 1) / 1000.0
+        self._timer_lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._observer = None  # watchdog Observer, lazy-imported in start()
+        self._stopped = False
+
+    def start(self) -> None:
+        try:
+            from watchdog.events import FileSystemEventHandler
+            from watchdog.observers import Observer
+        except ImportError as exc:
+            log.warning(
+                "watchdog not installed; CC_WATCH=on is a no-op (%s). "
+                "Install code-context[watch] to enable live reindex on save.",
+                exc,
+            )
+            return
+
+        watcher = self  # closure ref for the inner handler
+
+        class _Handler(FileSystemEventHandler):
+            def on_any_event(self, _event) -> None:
+                watcher._on_event()
+
+        self._observer = Observer()
+        self._observer.schedule(_Handler(), str(self._root), recursive=True)
+        self._observer.start()
+        log.info("repo watcher started for %s (debounce=%.2fs)", self._root, self._debounce_s)
+
+    def stop(self) -> None:
+        self._stopped = True
+        if self._observer is not None:
+            self._observer.stop()
+            self._observer.join(timeout=2.0)
+            self._observer = None
+        with self._timer_lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+
+    def _on_event(self) -> None:
+        """Reset the debounce timer on every event."""
+        if self._stopped:
+            return
+        with self._timer_lock:
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(self._debounce_s, self._fire)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _fire(self) -> None:
+        if self._stopped:
+            return
+        try:
+            self._on_change()
+        except Exception:  # noqa: BLE001 - watcher must survive callback bugs
+            log.exception("RepoWatcher on_change callback failed; will keep watching")

code_context/adapters/driven/chunker_dispatcher.py

@@ -0,0 +1,43 @@
+"""ChunkerDispatcher — routes chunking by file extension.
+
+Tree-sitter languages → TreeSitterChunker. Everything else → LineChunker.
+If TreeSitterChunker returns [] (unsupported or parse error), LineChunker
+takes over so we don't lose the file from the index.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from code_context.domain.models import Chunk, SymbolDef
+from code_context.domain.ports import Chunker
+
+_TREESITTER_EXTS = {".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs", ".cs"}
+
+
+@dataclass
+class ChunkerDispatcher:
+    """Composite chunker: tree-sitter for known languages, line fallback."""
+
+    treesitter: Chunker
+    line: Chunker
+
+    @property
+    def version(self) -> str:
+        # Both sub-versions in the identifier so any change invalidates the cache.
+        return f"dispatcher({self.treesitter.version}|{self.line.version})-v1"
+
+    def chunk(self, content: str, path: str) -> list[Chunk]:
+        if Path(path).suffix.lower() in _TREESITTER_EXTS:
+            chunks = self.treesitter.chunk(content, path)
+            if chunks:
+                return chunks
+        return self.line.chunk(content, path)
+
+    def extract_definitions(self, content: str, path: str) -> list[SymbolDef]:
+        """Delegate symbol extraction to the tree-sitter sub-chunker if it has it."""
+        extractor = getattr(self.treesitter, "extract_definitions", None)
+        if extractor is None:
+            return []
+        return extractor(content, path)