compass-code 0.1.0__py3-none-any.whl

compass_cli/commands/setup.py

@@ -0,0 +1,171 @@
+"""The ``compass setup`` command: tell coding agents in a repository about Code Compass.
+
+It keeps one managed block, between ``<!-- compass:begin -->`` and ``<!-- compass:end -->``,
+in ``AGENTS.md`` (read by Codex, Cursor and others) and ``CLAUDE.md`` (read by Claude
+Code), creating the files when missing and never touching text outside the markers.
+``CLAUDE.md`` is left alone when it already imports ``@AGENTS.md``. With ``--mcp`` it also
+registers the MCP server in the project's ``.mcp.json``. Running it again refreshes the
+block and changes nothing else.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from pathlib import Path
+
+import typer
+
+from compass_core.index.locate import find_index
+from compass_mcp.guide import AGENT_GUIDE
+from compass_mcp.server import SERVER_NAME
+
+BEGIN = "<!-- compass:begin -->"
+END = "<!-- compass:end -->"
+AGENTS_FILE = "AGENTS.md"
+CLAUDE_FILE = "CLAUDE.md"
+CLAUDE_IMPORTS_AGENTS = "@AGENTS.md"
+MCP_FILE = ".mcp.json"
+MCP_ENTRY: dict[str, object] = {"command": "compass", "args": ["mcp"]}
+CODEX_HINT = f"""\
+For Codex, add this to ~/.codex/config.toml:
+  [mcp_servers.{SERVER_NAME}]
+  command = "compass"
+  args = ["mcp"]"""
+
+
+class Change(StrEnum):
+    """What ``setup`` did to one file.
+
+    Attributes:
+        CREATED: The file did not exist and was written.
+        UPDATED: The file existed and its managed part was added or replaced.
+        UNCHANGED: The file already had exactly this content.
+        SKIPPED: The file was deliberately left alone.
+    """
+
+    CREATED = "created"
+    UPDATED = "updated"
+    UNCHANGED = "unchanged"
+    SKIPPED = "skipped"
+
+
+def managed_block() -> str:
+    """The agent guide between the markers, ending with a newline.
+
+    Returns:
+        The block ``setup`` keeps in agent instruction files.
+
+    Example:
+        ``managed_block().splitlines()[0]`` is ``"<!-- compass:begin -->"``.
+    """
+    return f"{BEGIN}\n{AGENT_GUIDE}{END}\n"
+
+
+def upsert_block(text: str, block: str) -> str:
+    """Replace the managed block in ``text``, or append it; other text is kept as is.
+
+    Args:
+        text: Current file content (may be empty).
+        block: The new managed block, markers included.
+
+    Returns:
+        The new content.
+
+    Example:
+        ``upsert_block("# Rules\\n", block)`` returns ``"# Rules\\n\\n" + block``; calling it
+        again on that result with a newer block replaces only the block.
+    """
+    start = text.find(BEGIN)
+    end = text.find(END, start)
+    if start != -1 and end != -1:
+        tail = text[end + len(END) :].removeprefix("\n")
+        return text[:start] + block + tail
+    if not text.strip():
+        return block
+    return text.rstrip("\n") + "\n\n" + block
+
+
+def write_guide(path: Path, block: str) -> Change:
+    """Put the managed block into one agent instruction file.
+
+    Args:
+        path: ``AGENTS.md`` or ``CLAUDE.md``.
+        block: The managed block.
+
+    Returns:
+        What happened to the file.
+    """
+    existed = path.exists()
+    current = path.read_text(encoding="utf-8") if existed else ""
+    if path.name == CLAUDE_FILE and CLAUDE_IMPORTS_AGENTS in current.replace(block, ""):
+        return Change.SKIPPED
+    updated = upsert_block(current, block)
+    if updated == current:
+        return Change.UNCHANGED
+    path.write_text(updated, encoding="utf-8")
+    return Change.UPDATED if existed else Change.CREATED
+
+
+def register_mcp(path: Path) -> Change:
+    """Add or refresh the Code Compass entry in a project's ``.mcp.json``.
+
+    Other servers and keys are kept. A file that is not a JSON object is not touched.
+
+    Args:
+        path: The ``.mcp.json`` file.
+
+    Returns:
+        What happened to the file.
+
+    Raises:
+        ValueError: The existing file is not a JSON object with an ``mcpServers`` object.
+    """
+    existed = path.exists()
+    data = json.loads(path.read_text(encoding="utf-8")) if existed else {}
+    servers = data.setdefault("mcpServers", {}) if isinstance(data, dict) else None
+    if not isinstance(servers, dict):
+        raise ValueError(f"{path} is not a JSON object with an 'mcpServers' object")
+    if servers.get(SERVER_NAME) == MCP_ENTRY:
+        return Change.UNCHANGED
+    servers[SERVER_NAME] = MCP_ENTRY
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return Change.UPDATED if existed else Change.CREATED
+
+
+REPO = typer.Option(
+    Path("."), "--repo", file_okay=False, help="Repository to set up; default: here."
+)
+
+
+def setup(
+    repo: Path = REPO,
+    mcp: bool = typer.Option(False, "--mcp", help=f"Also register the server in {MCP_FILE}."),
+    print_only: bool = typer.Option(
+        False, "--print", help="Print the agent guide and write nothing."
+    ),
+) -> None:
+    """Tell coding agents in this repository to use Code Compass.
+
+    Writes a managed section to AGENTS.md and CLAUDE.md (and, with --mcp, the MCP server
+    to .mcp.json). Safe to run again; text outside the section is never changed.
+    """
+    block = managed_block()
+    if print_only:
+        typer.echo(block, nl=False)
+        return
+    root = repo.resolve()
+    for name in (AGENTS_FILE, CLAUDE_FILE):
+        change = write_guide(root / name, block)
+        note = f" (it imports {CLAUDE_IMPORTS_AGENTS})" if change is Change.SKIPPED else ""
+        typer.echo(f"{name}: {change.value}{note}")
+    if mcp:
+        try:
+            change = register_mcp(root / MCP_FILE)
+        except (ValueError, json.JSONDecodeError) as exc:
+            typer.echo(f"{MCP_FILE}: not changed: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+        typer.echo(f"{MCP_FILE}: {change.value} ({SERVER_NAME} runs `compass mcp`)")
+        typer.echo(CODEX_HINT)
+    if find_index(root) is None:
+        typer.echo("No index yet: run `compass ingest` here before asking questions.")

compass_cli/display.py

@@ -0,0 +1,231 @@
+"""Rich-based display rendering for the Code Compass CLI.
+
+All terminal output formatting lives here — commands/ handles argument
+parsing and phase orchestration, this module handles how things look.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.table import Table
+from rich.text import Text
+
+from compass_cli.progress import fmt_duration
+from compass_cli.types import IngestSummary
+from compass_core.shared_types import Language
+
+GOLD = "color(214)"
+"""Accent colour of every Code Compass panel, rule and command name."""
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Help
+# ---------------------------------------------------------------------------
+
+
+_COMMANDS: tuple[tuple[str, str], ...] = (
+    ("ingest", "Index a repository (run again after code changes)"),
+    ("status", "Show which index is used and whether it is up to date"),
+    ("search", "Find files, classes, functions and methods by name"),
+    ("describe", "Show one symbol: location, docstring, callers, callees"),
+    ("impact", "List what may break if a symbol or file changes"),
+    ("overview", "Summarise the repository: entry points and hot spots"),
+    ("setup", "Tell coding agents in this repo to use Code Compass"),
+    ("mcp", "Serve the code graph to coding agents over MCP"),
+    ("serve", "Start the API server and the web UI"),
+    ("help", "Show this list"),
+)
+"""Commands listed by ``compass`` with no arguments, in the order a user needs them."""
+
+
+def help_commands() -> None:
+    """Print the available CLI commands with one line each."""
+    width = max(len(name) for name, _ in _COMMANDS)
+    console.print(f"[bold {GOLD}]Code Compass[/bold {GOLD}] — Navigate your codebase with ease\n")
+    console.print("[bold]Usage:[/bold]  compass [OPTIONS] COMMAND [ARGS]...\n")
+    console.print("[bold]Commands:[/bold]")
+    for name, summary in _COMMANDS:
+        console.print(f"  [bold {GOLD}]{name:<{width}}[/bold {GOLD}]  {summary}")
+    console.print()
+    console.print("[dim]Run [bold]compass COMMAND --help[/bold] for a command's options.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# Ingest command display helpers
+# ---------------------------------------------------------------------------
+
+
+def ingest_header(repo_path: Path) -> None:
+    """Print the opening line for an ingest run.
+
+    Args:
+        repo_path: The filesystem path to the repository being ingested.
+    """
+    console.print(f"\n[dim]Ingesting[/dim] [bold]{repo_path}[/bold]\n")
+
+
+def phase_header(num: int, total: int, title: str) -> None:
+    """Print a centered phase separator rule.
+
+    Example output: `Phase 1 of 2 · Ingestion` (centered with a gold rule).
+
+    Args:
+        num: The 1-indexed phase number currently starting.
+        total: The total number of phases in the run.
+        title: A descriptive name for the current phase.
+    """
+    console.print(
+        Rule(
+            f"[bold {GOLD}]Phase {num} of {total}[/bold {GOLD}]"
+            f"[dim]  ·  [/dim]"
+            f"[bold]{title}[/bold]",
+            style=GOLD,
+            align="center",
+        )
+    )
+    console.print()
+
+
+def _language_grid(language_counts: dict[Language, int]) -> Table:
+    """Lay out a "Languages" label followed by a language -> file-count
+    breakdown, three columns wide."""
+    grid = Table.grid(padding=(0, 3))
+    grid.add_column(style="dim", min_width=13)
+    for _ in range(3):
+        grid.add_column(style="bold")
+        grid.add_column(style="dim", min_width=6)
+
+    items = sorted(language_counts.items(), key=lambda kv: kv[1], reverse=True)
+    for i in range(0, len(items), 3):
+        row: list[str] = ["Languages" if i == 0 else ""]
+        for lang, count in items[i : i + 3]:
+            row += [lang, f"{count:,}"]
+        row += [""] * (7 - len(row))
+        grid.add_row(*row)
+    return grid
+
+
+def summary(summary: IngestSummary) -> None:
+    """Print the final summary in a gold-bordered panel.
+
+    Args:
+        summary: Aggregate results of the ingest run to display.
+    """
+    left = Table.grid(padding=(0, 3))
+    left.add_column(style="dim", min_width=13)
+    left.add_column(style="bold")
+    left.add_row("Files indexed", f"{summary.file_count:,}")
+    left.add_row("Classes", f"{summary.class_count:,}")
+    left.add_row("Functions", f"{summary.function_count:,}")
+    left.add_row("Skipped", str(summary.skipped))
+    left.add_row("Elapsed", fmt_duration(summary.elapsed))
+
+    right = Table.grid(padding=(0, 3))
+    right.add_column(style="dim", min_width=9)
+    right.add_column(style="bold")
+    right.add_row("Nodes", f"{summary.node_count:,}")
+    right.add_row("Edges", f"{summary.edge_count:,}")
+    if summary.dropped_edges:
+        right.add_row("Skipped", f"{summary.dropped_edges:,} edges")
+    right.add_row("Resolved", f"{summary.resolved_pct:.0%}")
+    right.add_row("Orphans", f"{summary.orphan_count:,}")
+    right.add_row("DB size", fmt_size(summary.db_size))
+
+    columns = Table.grid(padding=(0, 6))
+    columns.add_column()
+    columns.add_column()
+    columns.add_row(left, right)
+
+    db_line = Text(no_wrap=True, overflow="fold")
+    db_line.append("Database   ", style="dim")
+    db_line.append(str(summary.db_path), style="bold")
+
+    parts: list[Table | Text] = [columns, Text("")]
+    if summary.language_counts:
+        parts.append(_language_grid(summary.language_counts))
+        parts.append(Text(""))
+    parts.append(db_line)
+
+    console.print(
+        Panel(
+            Group(*parts),
+            title=f"[bold {GOLD}]compass ingest complete[/bold {GOLD}]",
+            border_style=GOLD,
+            padding=(1, 2),
+            expand=True,
+        )
+    )
+    if summary.dropped_edges:
+        console.print(f"  [dim]{skipped_edges_note(summary.dropped_edges)}[/dim]", soft_wrap=True)
+    console.print()
+
+
+def skipped_edges_note(count: int) -> str:
+    """Explain why some resolved edges are missing from the database.
+
+    Args:
+        count: Number of edges the writer could not store.
+
+    Returns:
+        A one-line explanation, e.g. ``"3 edges skipped (callee is not a stored
+        function, e.g. class constructor calls)"``.
+    """
+    noun = "edge" if count == 1 else "edges"
+    return (
+        f"{count:,} {noun} skipped (callee is not a stored function, e.g. class constructor calls)"
+    )
+
+
+NEXT_STEPS: tuple[tuple[str, str], ...] = (
+    ("compass overview", "See entry points and hot spots"),
+    ("compass search NAME", "Find where something is defined"),
+    ("compass setup", "Let coding agents (Claude Code, Codex) use this index"),
+    ("compass serve", "Explore the graph in the web UI"),
+    ("compass help", "See every command"),
+)
+"""Commands suggested after an ingest, most useful first."""
+
+
+def next_steps() -> None:
+    """Print the commands worth running after a successful ingest."""
+    width = max(len(command) for command, _ in NEXT_STEPS)
+    console.print("[bold]What's next:[/bold]")
+    for command, summary in NEXT_STEPS:
+        console.print(f"  [bold {GOLD}]{command:<{width}}[/bold {GOLD}]  {summary}")
+    console.print()
+
+
+# ---------------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------------
+
+
+def error(message: str) -> None:
+    """Print a formatted error message.
+
+    Args:
+        message: The error text to display.
+    """
+    console.print(f"[bold red]Error:[/bold red] {message}")
+
+
+def fmt_size(size_bytes: int) -> str:
+    """Format a byte count as a human-readable string.
+
+    Args:
+        size_bytes: The number of bytes to format.
+
+    Returns:
+        A formatted string (e.g., "1.5 KB", "300 B").
+    """
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    if size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    return f"{size_bytes / (1024 * 1024):.1f} MB"

compass_cli/errors.py

@@ -0,0 +1,30 @@
+"""Shared CLI error-boundary decorator."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import TypeVar
+
+import typer
+
+from compass_cli import display
+
+F = TypeVar("F", bound=Callable[..., None])
+
+
+def handle_errors(func: F) -> F:
+    """Catch expected OS-level failures, print a clean message, and exit(1).
+
+    Anything not an OSError still propagates with a full traceback.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: object, **kwargs: object) -> None:
+        try:
+            func(*args, **kwargs)
+        except OSError as exc:
+            display.error(str(exc))
+            raise typer.Exit(code=1) from exc
+
+    return wrapper  # type: ignore[return-value]  # functools.wraps keeps the signature; mypy cannot prove wrapper is F

compass_cli/main.py

@@ -0,0 +1,54 @@
+from importlib.metadata import version
+
+import typer
+
+from compass_cli import display
+from compass_cli.commands.ingest import ingest
+from compass_cli.commands.mcp import mcp
+from compass_cli.commands.query import describe, impact, overview, search, status
+from compass_cli.commands.serve import serve
+from compass_cli.commands.setup import setup
+
+app = typer.Typer(
+    help="Code Compass CLI",
+    no_args_is_help=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+DISTRIBUTION = "compass-code"
+"""The PyPI package that installs the ``compass`` command."""
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"{DISTRIBUTION} {version(DISTRIBUTION)}")
+        raise typer.Exit()
+
+
+VERSION = typer.Option(
+    False, "--version", "-V", callback=_print_version, is_eager=True, help="Print the version."
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context, show_version: bool = VERSION) -> None:
+    """Code Compass — Navigate your codebase with ease."""
+    if ctx.invoked_subcommand is None:
+        display.help_commands()
+
+
+app.command(name="ingest")(ingest)
+app.command(name="status")(status)
+app.command(name="search")(search)
+app.command(name="describe")(describe)
+app.command(name="impact")(impact)
+app.command(name="overview")(overview)
+app.command(name="serve")(serve)
+app.command(name="mcp")(mcp)
+app.command(name="setup")(setup)
+app.command(name="help")(display.help_commands)
+
+
+if __name__ == "__main__":
+    app()

compass_cli/progress.py

@@ -0,0 +1,191 @@
+"""Rich Live table reporter for the CLI ingest pipeline.
+
+``IngestReporter`` owns a single Rich ``Live`` table with one row per
+pipeline stage (STAGE / RESULT / TIME). A row appears the moment its stage
+starts, shows a live current/total counter while running (for stages that
+report granular progress — parse, persistence), and freezes to its final
+summary text once the stage completes via ``complete()``.
+
+Adding a new phase
+-------------------
+1. Add a ``(phase_name, stage_label)`` entry to ``_STAGE_LABELS``.
+2. If the phase reports granular progress, map its ``ProgressReporter``
+   phase name(s) to it in ``_REPORTER_TO_STAGE``.
+3. Call ``reporter.complete(phase_name, primary, secondary, warn=...)`` from
+   the CLI once that phase finishes.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from rich.console import Console, Group, RenderableType
+from rich.live import Live
+from rich.spinner import Spinner
+from rich.table import Table
+from rich.text import Text
+
+from compass_core.progress import Phase
+
+_GOLD = "color(214)"
+_GREEN = "green"
+_WARN = "color(208)"
+_DIM = "dim"
+_BAR_WIDTH = 14
+_DOT_THRESHOLD = 0.12
+
+_STAGE_LABELS: dict[str, str] = {
+    "discovery": "discover",
+    "parse": "parse",
+    "symbol_table": "symbols",
+    "resolution": "resolve",
+    "validation": "validate",
+    "persistence": "write",
+}
+_STAGE_ORDER = list(_STAGE_LABELS)
+
+# ProgressReporter phase names (fine-grained, item-level) mapped onto the
+# pipeline stage whose row they should update while it runs.
+_REPORTER_TO_STAGE: dict[str, str] = {
+    "parse": "parse",
+    "write_nodes": "persistence",
+    "write_edges": "persistence",
+}
+
+
+@dataclass
+class _StageRow:
+    status: str = "pending"  # pending | running | done
+    primary: str = ""
+    secondary: str = ""
+    warn: bool = False
+    start: float | None = None
+    duration: float | None = None
+    current: int = 0
+    total: int = 0
+
+
+def fmt_duration(seconds: float) -> str:
+    if seconds >= 60:
+        minutes, rest = divmod(seconds, 60)
+        return f"{int(minutes)}m {rest:.0f}s"
+    return f"{seconds:.1f}s"
+
+
+def _bar(frac: float, *, style: str) -> Text:
+    frac = max(0.0, min(1.0, frac))
+    if frac < _DOT_THRESHOLD:
+        return Text("●", style=_DIM)
+    filled = max(1, round(frac * _BAR_WIDTH))
+    return Text("━" * filled, style=style)
+
+
+class IngestReporter:
+    """Live Rich table of pipeline stages; also satisfies ``ProgressReporter``."""
+
+    def __init__(self, console: Console | None = None) -> None:
+        self._rows: dict[str, _StageRow] = {name: _StageRow() for name in _STAGE_ORDER}
+        self._show_total = False
+        self._live = Live(self._render(), console=console, refresh_per_second=8, transient=False)
+
+    def __enter__(self) -> IngestReporter:
+        self._live.start()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self._live.stop()
+
+    # -- ProgressReporter protocol -----------------------------------------
+
+    def update(self, phase: Phase, current: int, total: int) -> None:
+        """Update the live current/total counter for the stage *phase* maps to."""
+        stage = _REPORTER_TO_STAGE.get(phase)
+        if stage is None:
+            return
+        row = self._rows[stage]
+        if row.status == "pending":
+            row.status = "running"
+            row.start = time.monotonic()
+        row.current, row.total = current, total
+        self._refresh()
+
+    # -- CLI-facing API -------------------------------------------------------
+
+    def complete(self, phase: str, primary: str, secondary: str, *, warn: bool = False) -> None:
+        """Freeze *phase*'s row with its final summary text and elapsed duration."""
+        row = self._rows[phase]
+        now = time.monotonic()
+        if row.start is None:
+            row.start = now
+        row.duration = now - row.start
+        row.status = "done"
+        row.primary = primary
+        row.secondary = secondary
+        row.warn = warn
+        self._refresh()
+
+    def finalize(self) -> None:
+        """Show the total row and stop the live display."""
+        self._show_total = True
+        self._refresh()
+        self._live.stop()
+
+    @property
+    def total_duration(self) -> float:
+        return sum(r.duration or 0.0 for r in self._rows.values())
+
+    # -- rendering --------------------------------------------------------
+
+    def _refresh(self) -> None:
+        self._live.update(self._render())
+
+    def _render(self) -> RenderableType:
+        table = Table.grid(padding=(0, 3))
+        table.add_column(min_width=9)
+        table.add_column(min_width=26)
+        table.add_column(justify="right", min_width=10)
+
+        table.add_row(
+            Text("STAGE", style=_DIM), Text("RESULT", style=_DIM), Text("TIME", style=_DIM)
+        )
+
+        max_duration = max((r.duration for r in self._rows.values() if r.duration), default=0.0)
+        for name in _STAGE_ORDER:
+            row = self._rows[name]
+            if row.status == "pending":
+                continue
+            label = _STAGE_LABELS[name]
+
+            if row.status == "running":
+                stage_text = Text(label, style=f"bold {_GOLD}")
+                progress_text = Text(
+                    f"{row.current:,} / {row.total:,}" if row.total else "working…"
+                )
+                table.add_row(stage_text, progress_text, Spinner("dots", style=_GOLD))
+                continue
+
+            style = _WARN if row.warn else "bold"
+            stage_text = Text(label, style=style)
+            result: RenderableType = (
+                Group(Text(row.primary, style=style), Text(row.secondary, style=_DIM))
+                if row.secondary
+                else Text(row.primary, style=style)
+            )
+            frac = ((row.duration or 0.0) / max_duration) if max_duration else 0.0
+            bar_style = _WARN if row.warn else (_GREEN if frac >= _DOT_THRESHOLD else _DIM)
+            time_cell = Group(
+                Text(fmt_duration(row.duration or 0.0), justify="right"),
+                _bar(frac, style=bar_style),
+            )
+            table.add_row(stage_text, result, time_cell)
+            table.add_row("", "", "")
+
+        if self._show_total:
+            table.add_row("", "", "")
+            table.add_row(
+                Text("total", style=_DIM),
+                Text(""),
+                Text(fmt_duration(self.total_duration), style="bold", justify="right"),
+            )
+        return table