codebase-index 1.6.0__py3-none-any.whl

codebase_index/scaffold.py

@@ -0,0 +1,399 @@
+"""Materialize the bundled skill template into project CLI trees.
+
+Pure filesystem helpers used by the `init` CLI command. The template is read from
+the wheel via importlib.resources, so it works in editable and zip installs alike.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import stat
+import sys
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Optional
+
+from .config import Config
+
+CLI_TARGETS = ("claude", "codex", "opencode")
+
+# MCP clients that receive a JSON config entry (no skill files needed).
+MCP_TARGETS = ("cursor", "claude-desktop", "zed", "vscode", "windsurf")
+
+ALL_TARGETS = CLI_TARGETS + MCP_TARGETS
+
+CLAUDE_SKILL_REL = Path(".claude") / "skills" / "codebase-index"
+CODEX_SKILL_REL = Path(".codex") / "skills" / "codebase-index"
+OPENCODE_SKILL_REL = Path(".opencode") / "skills" / "codebase-index"
+OPENCODE_COMMAND_REL = Path(".opencode") / "commands" / "codebase-index.md"
+OPENCODE_AGENT_REL = Path(".opencode") / "agents" / "codebase-index.md"
+
+SKILL_REL = CLAUDE_SKILL_REL
+CACHE_REL = Path(".claude") / "cache" / "codebase-index"
+_CACHE_IGNORE_LINE = ".claude/cache/codebase-index/"
+_GITIGNORE_BLOCK = (
+    "\n# codebase-index cache (machine-local; do not commit)\n"
+    f"{_CACHE_IGNORE_LINE}\n"
+)
+_MANAGED_START = "<!-- >>> codebase-index managed >>> -->"
+_MANAGED_END = "<!-- <<< codebase-index managed <<< -->"
+
+
+def _template_root() -> Traversable:
+    return resources.files("codebase_index") / "skill_template"
+
+
+def _iter_template(node: Traversable, prefix: str = "") -> "list[tuple[str, Traversable]]":
+    """Depth-first list of (relative-posix-path, file) under a template dir."""
+    out: list[tuple[str, Traversable]] = []
+    for child in node.iterdir():
+        rel = f"{prefix}{child.name}"
+        if child.is_dir():
+            out.extend(_iter_template(child, prefix=f"{rel}/"))
+        else:
+            out.append((rel, child))
+    return out
+
+
+def skill_rel_for_target(target: str) -> Path:
+    if target == "claude":
+        return CLAUDE_SKILL_REL
+    if target == "codex":
+        return CODEX_SKILL_REL
+    if target == "opencode":
+        return OPENCODE_SKILL_REL
+    raise ValueError(f"unknown CLI target: {target}")
+
+
+def detect_cli_targets(root: Path) -> list[str]:
+    """Detect usable local CLI targets for a project install."""
+    home = Path.home()
+    checks = (
+        ("claude", "claude", root / ".claude", home / ".claude"),
+        ("codex", "codex", root / ".codex", home / ".codex"),
+        ("opencode", "opencode", root / ".opencode", home / ".config" / "opencode"),
+    )
+    return [
+        target
+        for target, command, project_marker, home_marker in checks
+        if project_marker.exists() or shutil.which(command) or home_marker.exists()
+    ]
+
+
+def detect_mcp_targets(root: Path) -> list[str]:
+    """Detect MCP-capable clients present on this machine or in this project."""
+    home = Path.home()
+    found: list[str] = []
+
+    checks: list[tuple[str, list[Optional[Path]]]] = [
+        ("cursor",        [root / ".cursor",      home / ".cursor"]),
+        ("windsurf",      [root / ".windsurf",     home / ".windsurf"]),
+        ("vscode",        [root / ".vscode"]),
+        ("zed",           [root / ".zed",          home / ".config" / "zed"]),
+        ("claude-desktop", [_claude_desktop_config_path()]),
+    ]
+    exe_checks = {
+        "cursor":    ["cursor"],
+        "windsurf":  ["windsurf"],
+        "vscode":    ["code", "code-insiders"],
+        "zed":       ["zed"],
+    }
+    for target, markers in checks:
+        if any(m is not None and m.exists() for m in markers):
+            found.append(target)
+            continue
+        for exe in exe_checks.get(target, []):
+            if shutil.which(exe):
+                found.append(target)
+                break
+    return found
+
+
+def materialize_skill(root: Path, *, force: bool, target: str = "claude") -> list[Path]:
+    """Copy the whole skill template to the target's project resource directory."""
+    dest = root / skill_rel_for_target(target)
+    if dest.exists() and not force:
+        raise FileExistsError(dest)
+
+    written: list[Path] = []
+    for rel, node in _iter_template(_template_root()):
+        dst = dest / Path(rel)
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.write_bytes(node.read_bytes())
+        if rel == "scripts/cbx":
+            dst.chmod(dst.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        written.append(dst)
+
+    # Write version stamp so auto-update can detect when the skill is outdated.
+    try:
+        from importlib.metadata import version as _pkg_version
+        pkg_ver = _pkg_version("codebase-index")
+    except Exception:
+        pkg_ver = "unknown"
+    stamp = dest / ".skill_version"
+    stamp.write_text(pkg_ver + "\n", encoding="utf-8")
+    written.append(stamp)
+
+    return written
+
+
+def _managed_block(content: str) -> str:
+    return f"{_MANAGED_START}\n{content.rstrip()}\n{_MANAGED_END}\n"
+
+
+def _upsert_managed_block(path: Path, content: str) -> Path:
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    block = _managed_block(content)
+    if _MANAGED_START in existing and _MANAGED_END in existing:
+        before, rest = existing.split(_MANAGED_START, 1)
+        _, after = rest.split(_MANAGED_END, 1)
+        new_text = before.rstrip() + "\n\n" + block + after.lstrip()
+    else:
+        sep = "" if existing in ("", "\n") else "\n\n"
+        new_text = existing.rstrip() + sep + block
+    path.write_text(new_text, encoding="utf-8")
+    return path
+
+
+def write_codex_agents(root: Path) -> Path:
+    rel = CODEX_SKILL_REL / "SKILL.md"
+    content = f"""# codebase-index
+
+Use the local codebase index before scanning repository files.
+
+Skill resources: `{rel.as_posix()}`
+
+Run `codebase-index search "<query>" --json` for general questions, or use
+`symbol`, `refs`, `impact`, and `graph` for symbol lookup, references, change
+impact, and HTML graph export. Search/read commands auto-build the index when
+it is missing; run `codebase-index update` when responses report stale data.
+"""
+    return _upsert_managed_block(root / "AGENTS.md", content)
+
+
+def write_opencode_files(root: Path) -> list[Path]:
+    command = root / OPENCODE_COMMAND_REL
+    agent = root / OPENCODE_AGENT_REL
+    command.parent.mkdir(parents=True, exist_ok=True)
+    agent.parent.mkdir(parents=True, exist_ok=True)
+    command.write_text(
+        """---
+description: Search this repository with codebase-index before reading files.
+---
+
+Run:
+
+```bash
+codebase-index search "$ARGUMENTS" --json
+```
+
+Use `symbol <name>`, `refs <name>`, or `impact <file|symbol>` when those match
+the request. If the index is missing, run `codebase-index index` first.
+""",
+        encoding="utf-8",
+    )
+    src = _template_root() / "SKILL.md"
+    agent.write_bytes(src.read_bytes())
+    return [command, agent]
+
+
+def install_target(root: Path, target: str, *, force: bool) -> list[Path]:
+    written = materialize_skill(root, force=force, target=target)
+    if target == "codex":
+        written.append(write_codex_agents(root))
+    elif target == "opencode":
+        written.extend(write_opencode_files(root))
+    return written
+
+
+def write_config(root: Path, *, force: bool) -> Path:
+    """Write resolved defaults to `<root>/.claude/cache/codebase-index/config.json`."""
+    path = root / CACHE_REL / "config.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and not force:
+        return path
+    cfg = Config()
+    path.write_text(cfg.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def merge_gitignore(root: Path) -> bool:
+    """Append the cache-ignore block to `<root>/.gitignore` if absent. Returns True if changed."""
+    path = root / ".gitignore"
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    if _CACHE_IGNORE_LINE in existing:
+        return False
+    sep = "" if existing.endswith("\n") or existing == "" else "\n"
+    path.write_text(existing + sep + _GITIGNORE_BLOCK, encoding="utf-8")
+    return True
+
+
+def write_hooks_example(root: Path) -> Path:
+    """Copy the hooks example next to the installed skill (for manual `--with-hooks` review)."""
+    src = _template_root() / "examples" / "hooks" / "settings.json"
+    path = root / SKILL_REL / "examples" / "hooks" / "settings.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(src.read_bytes())
+    return path
+
+
+SETTINGS_REL = Path(".claude") / "settings.json"
+_HOOK_MARKER = "codebase-index update"
+
+
+def _template_hook_entries() -> "list[dict]":
+    src = _template_root() / "examples" / "hooks" / "settings.json"
+    data = json.loads(src.read_text(encoding="utf-8"))
+    return data["hooks"]["PostToolUse"]
+
+
+def _has_our_hook(settings: dict) -> bool:
+    for entry in settings.get("hooks", {}).get("PostToolUse", []):
+        for hk in entry.get("hooks", []):
+            if _HOOK_MARKER in hk.get("command", ""):
+                return True
+    return False
+
+
+def merge_hook_settings(root: Path) -> bool:
+    path = root / SETTINGS_REL
+    settings: dict = {}
+    if path.exists():
+        settings = json.loads(path.read_text(encoding="utf-8"))
+    if _has_our_hook(settings):
+        return False
+
+    hooks = settings.setdefault("hooks", {})
+    post = hooks.setdefault("PostToolUse", [])
+    post.extend(_template_hook_entries())
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    return True
+
+
+# ── MCP client config helpers ──────────────────────────────────────────────────────────────────
+
+_MCP_SERVER_NAME = "codebase-index"
+_MCP_ENTRY_STDIO = {"command": "codebase-index", "args": ["mcp"]}
+
+
+def _claude_desktop_config_path() -> Optional[Path]:
+    """Platform-specific path to Claude Desktop's config file."""
+    if sys.platform == "win32":
+        appdata = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+        return appdata / "Claude" / "claude_desktop_config.json"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    return Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def _load_json_file(path: Path) -> dict:
+    if path.exists():
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+    return {}
+
+
+def _write_json_file(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _merge_mcp_servers(path: Path, entry: dict, *, force: bool) -> bool:
+    """Merge {"mcpServers": {"codebase-index": entry}} into a JSON config file.
+
+    Returns True if the file was written (new or updated), False if already present.
+    """
+    data = _load_json_file(path)
+    servers: dict = data.setdefault("mcpServers", {})
+    if _MCP_SERVER_NAME in servers and not force:
+        return False
+    servers[_MCP_SERVER_NAME] = entry
+    _write_json_file(path, data)
+    return True
+
+
+def _merge_vscode_mcp(path: Path, *, force: bool) -> bool:
+    """VS Code uses {"servers": {"name": {"type": "stdio", ...}}} in .vscode/mcp.json."""
+    data = _load_json_file(path)
+    servers: dict = data.setdefault("servers", {})
+    if _MCP_SERVER_NAME in servers and not force:
+        return False
+    servers[_MCP_SERVER_NAME] = {"type": "stdio", **_MCP_ENTRY_STDIO}
+    _write_json_file(path, data)
+    return True
+
+
+def _merge_zed_settings(path: Path, *, force: bool) -> bool:
+    """Zed uses context_servers with a nested command object in settings.json."""
+    data = _load_json_file(path)
+    ctx: dict = data.setdefault("context_servers", {})
+    if _MCP_SERVER_NAME in ctx and not force:
+        return False
+    ctx[_MCP_SERVER_NAME] = {
+        "command": {
+            "path": "codebase-index",
+            "args": ["mcp"],
+        }
+    }
+    _write_json_file(path, data)
+    return True
+
+
+def install_mcp_target(root: Path, target: str, *, force: bool = False) -> tuple[Path, bool]:
+    """Write or merge the MCP server entry for `target`.
+
+    Returns (config_path, written) where written=False means it was already present.
+    Raises ValueError for unknown targets.
+    """
+    if target == "cursor":
+        path = root / ".cursor" / "mcp.json"
+        written = _merge_mcp_servers(path, _MCP_ENTRY_STDIO, force=force)
+        return path, written
+
+    if target == "windsurf":
+        path = root / ".windsurf" / "mcp.json"
+        written = _merge_mcp_servers(path, _MCP_ENTRY_STDIO, force=force)
+        return path, written
+
+    if target == "vscode":
+        path = root / ".vscode" / "mcp.json"
+        written = _merge_vscode_mcp(path, force=force)
+        return path, written
+
+    if target == "zed":
+        # prefer project-local; Zed picks it up automatically
+        path = root / ".zed" / "settings.json"
+        written = _merge_zed_settings(path, force=force)
+        return path, written
+
+    if target == "claude-desktop":
+        maybe_path = _claude_desktop_config_path()
+        if maybe_path is None:
+            raise RuntimeError("Cannot determine Claude Desktop config path on this platform.")
+        written = _merge_mcp_servers(maybe_path, _MCP_ENTRY_STDIO, force=force)
+        return maybe_path, written
+
+    raise ValueError(f"unknown MCP target: {target!r}. Valid: {MCP_TARGETS}")
+
+
+def enabled_hooks(root: Path) -> list[str]:
+    path = root / SETTINGS_REL
+    if not path.exists():
+        return []
+    try:
+        settings = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    return [
+        hk.get("command", "")
+        for entry in settings.get("hooks", {}).get("PostToolUse", [])
+        for hk in entry.get("hooks", [])
+        if _HOOK_MARKER in hk.get("command", "")
+    ]

codebase_index/service.py

@@ -0,0 +1,158 @@
+"""Shared service layer for the CLI and the MCP server.
+
+Both surfaces drive the same retrieval/storage code; this module owns the
+pieces that used to be duplicated and drift apart: the cache-path formula,
+db/config resolution, the explain query rewrite, vector-aware search
+sessions, and the stats payload (including the per-language graph tier the
+skill keys on).
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+
+if TYPE_CHECKING:
+    from .config import Config
+
+_EXPLAIN_HINTS = ("how", "architecture", "overview")
+
+
+def cache_dir_for(cfg: "Config") -> Path:
+    """Per-project cache directory (index DB, graph exports, skill backups)."""
+    return Path(cfg.root) / ".claude" / "cache" / "codebase-index"
+
+
+def db_path_for(cfg: "Config") -> Path:
+    """Index location for a resolved config; the CBX_DB_PATH env var overrides."""
+    override = os.environ.get("CBX_DB_PATH")
+    if override:
+        return Path(override)
+    return cache_dir_for(cfg) / "index.sqlite"
+
+
+def resolve_db(root: Optional[Union[Path, str]] = None) -> tuple[Path, "Config"]:
+    """Resolve (db_path, config) the same way on every surface.
+
+    The config loads from *root* (CLI --root, MCP CBX_ROOT, else upward
+    discovery from cwd); CBX_DB_PATH overrides only the index location.
+    """
+    from .config import load
+
+    cfg = load(Path(root) if root is not None else None)
+    return db_path_for(cfg), cfg
+
+
+def search_backend(cfg: "Config", warn: Callable[[str], None]) -> Any:
+    """Embedding backend for query-time vector search.
+
+    Returns a NoopBackend (enabled=False) when embeddings are off, so callers
+    can branch on `backend.enabled`. Network/external gating is enforced by
+    resolve_backend (SECURITY.md §4).
+    """
+    from .embeddings.backend import resolve_backend
+
+    return resolve_backend(cfg, warn=warn)
+
+
+def normalize_explain_query(query: str) -> str:
+    """Rewrite a bare topic into a how-does-X-work question for intent detection."""
+    if any(w in query.lower() for w in _EXPLAIN_HINTS):
+        return query
+    return f"how does {query} work"
+
+
+def search_payload(
+    db_path: Path,
+    cfg: "Config",
+    query: str,
+    *,
+    mode: str = "hybrid",
+    limit: int = 10,
+    offset: int = 0,
+    token_budget: int = 1500,
+    no_fallback: bool = False,
+    backend: Any = None,
+    raw: bool = False,
+) -> dict:
+    """One search session: open the DB (vector-enabled when the backend is
+    live), run retrieval, return the payload dict both surfaces serialize.
+
+    ``raw`` forces full snippets; otherwise snippets are skeletonized when
+    ``cfg.retrieval.compact_snippets`` is on (the default)."""
+    from .retrieval.pipeline import search as run_search
+    from .storage.db import Database
+
+    compact = cfg.retrieval.compact_snippets and not raw
+    with Database(db_path) as db:
+        if backend is not None and getattr(backend, "enabled", False):
+            db.enable_vectors()
+        return run_search(
+            db.conn,
+            query,
+            mode=mode,
+            limit=limit,
+            offset=offset,
+            token_budget=token_budget,
+            no_fallback=no_fallback,
+            backend=backend,
+            root=Path(cfg.root),
+            config=cfg,
+            compact=compact,
+            compact_min_reduction=cfg.retrieval.compact_min_reduction,
+        )
+
+
+def architecture_payload(db_path: Path, cfg: "Config") -> dict[str, Any]:
+    """The cached architecture analytics (communities / god nodes / surprising /
+    questions) plus index freshness — the payload both CLI and MCP serialize.
+
+    Returns ``available: False`` when no analysis is cached (an index built before
+    this feature, or an empty graph); the caller tells the user to reindex.
+    """
+    from .graph import analysis
+    from .indexer.freshness import compute_freshness
+    from .storage.db import Database
+
+    with Database(db_path) as db:
+        fresh = compute_freshness(db.conn, Path(cfg.root), cfg)
+        summary = analysis.load_analysis(db.conn)
+        if summary is None:
+            return {
+                "exists": True,
+                "available": False,
+                "reason": (
+                    "No architecture analysis cached. Rebuild the index "
+                    "(`codebase-index index`) to compute it."
+                ),
+                "index": fresh.model_dump(),
+            }
+        return {"exists": True, "available": True, "index": fresh.model_dump(), **summary}
+
+
+def stats_payload(conn: sqlite3.Connection) -> dict[str, Any]:
+    """Index size, freshness, and per-language coverage with the graph tier."""
+    from .parsers.languages import has_full_graph
+    from .storage import repo
+
+    coverage = [
+        {
+            "lang": r["lang"],
+            "files": r["files"],
+            "symbols": r["symbols"],
+            # Tier-A languages get import/inheritance edges; Tier-B is
+            # symbols-only, so refs/impact are partial for them.
+            "graph": "full" if has_full_graph(r["lang"]) else "partial",
+        }
+        for r in repo.treesitter_coverage(conn)
+    ]
+    return {
+        "files": repo.count_files(conn),
+        "symbols": repo.count_symbols(conn),
+        "built_at": repo.get_meta(conn, "built_at"),
+        "head_commit": repo.get_meta(conn, "head_commit"),
+        "treesitter_coverage": coverage,
+        "exists": True,
+    }