codemap-core 0.1.0__py3-none-any.whl

codemap/__init__.py

@@ -0,0 +1,7 @@
+"""CodeMap — language-neutral code index for AI agents."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

codemap/cli/__init__.py

@@ -0,0 +1,3 @@
+"""Typer CLI surface. Only argument parsing and output rendering live here."""
+
+from __future__ import annotations

codemap/cli/_common.py

@@ -0,0 +1,90 @@
+"""Shared helpers for the query commands (search / get / callers / callees / trace).
+
+These keep error UX consistent: a missing ``.codemap/`` is exit 66, a
+corrupt index is exit 65, and a malformed SymbolID is exit 64. Friendly
+messages go to stderr; the commands themselves only emit data on stdout.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+import typer
+
+from codemap.cli.renderers import text
+from codemap.core.symbol import SymbolID, SymbolParseError
+from codemap.diagnostics.exit_codes import ExitCode
+from codemap.io.json_store import IntegrityError, JsonStore
+from codemap.io.manifest import SchemaVersionError
+
+CODEMAP_DIR = ".codemap"
+_SNIPPET_CONTEXT = 0
+
+
+def open_store_or_exit(project_path: Path) -> JsonStore:
+    """Open ``<project>/.codemap/`` read-only; exit gracefully on failure."""
+    codemap_dir = project_path / CODEMAP_DIR
+    if not codemap_dir.exists():
+        text.console(stderr=True).print(
+            f"[red]No `.codemap/` directory found at {project_path}[/red]. "
+            "Run `codemap index` first."
+        )
+        raise typer.Exit(code=int(ExitCode.NO_INPUT))
+    try:
+        return JsonStore.open(codemap_dir, mode="r")
+    except (SchemaVersionError, IntegrityError) as exc:
+        text.console(stderr=True).print(
+            f"[red]Index corrupted:[/red] {exc}\nTry `codemap index --rebuild`."
+        )
+        raise typer.Exit(code=int(ExitCode.DATA_ERROR)) from exc
+
+
+def parse_symbol_id_or_exit(raw: str) -> SymbolID:
+    """Parse a SCIP SymbolID; exit 64 with a readable message on failure."""
+    try:
+        return SymbolID.parse(raw)
+    except SymbolParseError as exc:
+        text.console(stderr=True).print(
+            f"[red]Invalid SymbolID:[/red] {exc}\n"
+            "Expected format: '<scheme> <manager> <package> <version> <descriptors>'"
+        )
+        raise typer.Exit(code=int(ExitCode.USAGE_ERROR)) from exc
+
+
+def read_snippet(
+    project_root: Path,
+    file: PurePosixPath,
+    line: int,
+    *,
+    context: int = _SNIPPET_CONTEXT,
+) -> str | None:
+    """Read ``project_root/file`` and return the line ``line`` (1-based).
+
+    With ``context > 0`` returns the surrounding ``context`` lines joined with
+    newlines. Returns ``None`` if the file is missing or the line is out of
+    range — callers render symbols without snippets in that case.
+    """
+    src = project_root / str(file)
+    try:
+        lines = src.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return None
+    if line < 1 or line > len(lines):
+        return None
+    start = max(line - 1 - context, 0)
+    end = min(line + context, len(lines))
+    return "\n".join(lines[start:end])
+
+
+def format_location(file: PurePosixPath, line: int) -> str:
+    """Render a ``file:line`` cursor."""
+    return f"{file}:{line}"
+
+
+__all__ = [
+    "CODEMAP_DIR",
+    "format_location",
+    "open_store_or_exit",
+    "parse_symbol_id_or_exit",
+    "read_snippet",
+]

codemap/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command modules. Each command is one file."""
+
+from __future__ import annotations

codemap/cli/commands/callees.py

@@ -0,0 +1,102 @@
+"""``codemap callees <symbol-id>`` — list downstream callees."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from codemap.cli._common import (
+    format_location,
+    open_store_or_exit,
+    parse_symbol_id_or_exit,
+)
+from codemap.cli.renderers import json as json_renderer
+from codemap.cli.renderers import text
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("callees")
+    def callees(
+        ctx: typer.Context,
+        symbol_id: Annotated[str, typer.Argument(help="Source SymbolID.")],
+        depth: Annotated[
+            int,
+            typer.Option("--depth", "-d", min=1, help="How many hops downstream."),
+        ] = 1,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """Print every edge whose ``source`` matches ``symbol_id`` (depth-limited)."""
+        as_json: bool = ctx.obj["json_output"]
+        sid = parse_symbol_id_or_exit(symbol_id)
+        with open_store_or_exit(project) as store:
+            edges = store.callees(sid, depth=depth)
+            results = []
+            for edge in edges:
+                target_sym = store.get(edge.target)
+                results.append((edge, target_sym))
+
+        if as_json:
+            json_renderer.emit(
+                "callees",
+                {
+                    "source": str(sid),
+                    "depth": depth,
+                    "results": [
+                        {
+                            "symbol": str(edge.target),
+                            "kind": (sym.kind if sym else "external"),
+                            "file": (str(sym.file) if sym else None),
+                            "line": (
+                                edge.location.start_line
+                                if edge.location
+                                else (sym.range.start_line if sym else None)
+                            ),
+                            "edge": {
+                                "kind": edge.kind,
+                                "confidence": edge.confidence,
+                            },
+                        }
+                        for edge, sym in results
+                    ],
+                },
+            )
+            return
+
+        cons = text.console()
+        if not results:
+            cons.print(f"[yellow]No callees for[/yellow] {symbol_id!r}")
+            return
+        rows = []
+        for edge, sym in results:
+            line = (
+                edge.location.start_line if edge.location else (sym.range.start_line if sym else 0)
+            )
+            rows.append(
+                [
+                    edge.kind,
+                    edge.confidence,
+                    (format_location(sym.file, line) if sym is not None else "(external)"),
+                    str(edge.target),
+                ]
+            )
+        cons.print(
+            text.table(
+                f"Callees of {symbol_id}",
+                ["edge", "confidence", "location", "target"],
+                rows,
+            )
+        )
+
+
+__all__ = ["register"]

codemap/cli/commands/callers.py

@@ -0,0 +1,107 @@
+"""``codemap callers <symbol-id>`` — list upstream callers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from codemap.cli._common import (
+    format_location,
+    open_store_or_exit,
+    parse_symbol_id_or_exit,
+    read_snippet,
+)
+from codemap.cli.renderers import json as json_renderer
+from codemap.cli.renderers import text
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("callers")
+    def callers(
+        ctx: typer.Context,
+        symbol_id: Annotated[str, typer.Argument(help="Target SymbolID.")],
+        depth: Annotated[
+            int,
+            typer.Option("--depth", "-d", min=1, help="How many hops upstream."),
+        ] = 1,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """Print every edge whose ``target`` matches ``symbol_id`` (depth-limited)."""
+        as_json: bool = ctx.obj["json_output"]
+        sid = parse_symbol_id_or_exit(symbol_id)
+        with open_store_or_exit(project) as store:
+            edges = store.callers(sid, depth=depth)
+            manifest = store.manifest()
+            results = []
+            for edge in edges:
+                source_sym = store.get(edge.source)
+                results.append((edge, source_sym))
+
+        if as_json:
+            json_renderer.emit(
+                "callers",
+                {
+                    "target": str(sid),
+                    "depth": depth,
+                    "results": [
+                        {
+                            "symbol": str(edge.source),
+                            "kind": (sym.kind if sym else "unknown"),
+                            "file": (str(sym.file) if sym else None),
+                            "line": (
+                                edge.location.start_line
+                                if edge.location
+                                else (sym.range.start_line if sym else None)
+                            ),
+                            "edge": {
+                                "kind": edge.kind,
+                                "confidence": edge.confidence,
+                            },
+                        }
+                        for edge, sym in results
+                    ],
+                },
+            )
+            return
+
+        cons = text.console()
+        if not results:
+            cons.print(f"[yellow]No callers for[/yellow] {symbol_id!r}")
+            return
+        rows = []
+        for edge, sym in results:
+            line = (
+                edge.location.start_line if edge.location else (sym.range.start_line if sym else 0)
+            )
+            rows.append(
+                [
+                    edge.kind,
+                    edge.confidence,
+                    (format_location(sym.file, line) if sym is not None else "(external)"),
+                    str(edge.source),
+                ]
+            )
+        cons.print(
+            text.table(
+                f"Callers of {symbol_id}",
+                ["edge", "confidence", "location", "source"],
+                rows,
+            )
+        )
+        # Suppress unused warning by referencing manifest for snippet support
+        _ = manifest
+        _ = read_snippet  # snippets in callers add too much noise — kept for future
+
+
+__all__ = ["register"]

codemap/cli/commands/config.py

@@ -0,0 +1,78 @@
+"""``codemap config show`` — print the merged effective configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from codemap.cli.renderers import json as json_renderer
+from codemap.cli.renderers import text
+from codemap.config import ConfigError, dump_config, load_config
+from codemap.config.loader import project_config_path, user_config_path
+from codemap.diagnostics.exit_codes import ExitCode
+
+
+def register(app: typer.Typer) -> None:
+    config_app = typer.Typer(
+        name="config",
+        help="Inspect and edit configuration files.",
+        no_args_is_help=True,
+    )
+    app.add_typer(config_app, name="config")
+
+    @config_app.command("show")
+    def show(
+        ctx: typer.Context,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """Print the merged configuration that ``index`` would use."""
+        as_json: bool = ctx.obj["json_output"]
+        codemap_dir = project / ".codemap"
+        try:
+            config = load_config(codemap_dir if codemap_dir.exists() else None)
+        except ConfigError as exc:
+            text.console(stderr=True).print(f"[red]Config error:[/red] {exc}")
+            raise typer.Exit(code=int(ExitCode.CONFIG_ERROR)) from exc
+
+        sources = {
+            "defaults": "(built-in)",
+            "user": str(user_config_path()),
+            "project": str(project_config_path(codemap_dir)),
+        }
+
+        if as_json:
+            json_renderer.emit(
+                "config show",
+                {
+                    "config": config.model_dump(mode="json"),
+                    "sources": sources,
+                },
+            )
+            return
+
+        cons = text.console()
+        cons.print("[bold]Config sources (overlaid in order):[/bold]")
+        for label, p in sources.items():
+            mark = ""
+            if (label == "user" and not user_config_path().exists()) or (
+                label == "project" and not project_config_path(codemap_dir).exists()
+            ):
+                mark = " [dim](missing)[/dim]"
+            cons.print(f"  • {label}: {p}{mark}")
+        cons.print()
+        cons.print("[bold]Effective configuration:[/bold]")
+        cons.print(dump_config(config))
+
+
+__all__ = ["register"]

codemap/cli/commands/diagnostics.py

@@ -0,0 +1,142 @@
+"""``codemap diagnostics`` — surface indexer / bridge diagnostics."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from codemap.cli._common import format_location, open_store_or_exit
+from codemap.cli.renderers import json as json_renderer
+from codemap.cli.renderers import text
+
+_SEVERITY_COLORS = {
+    "error": "red",
+    "warning": "yellow",
+    "info": "cyan",
+}
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("diagnostics")
+    def diagnostics(
+        ctx: typer.Context,
+        severity: Annotated[
+            str | None,
+            typer.Option(
+                "--severity",
+                "-s",
+                help="Filter by severity: error / warning / info.",
+            ),
+        ] = None,
+        producer: Annotated[
+            str | None,
+            typer.Option(
+                "--producer",
+                help="Filter by producer (indexer or bridge name).",
+            ),
+        ] = None,
+        code: Annotated[
+            str | None,
+            typer.Option(
+                "--code",
+                help="Filter by diagnostic code (e.g. ROUTE001).",
+            ),
+        ] = None,
+        limit: Annotated[
+            int,
+            typer.Option("--limit", "-n", help="Maximum entries to show.", min=1),
+        ] = 50,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """List diagnostics collected during the last `codemap index`."""
+        as_json: bool = ctx.obj["json_output"]
+        severity_filter = severity.lower() if severity else None
+        with open_store_or_exit(project) as store:
+            all_diag = list(store.iter_diagnostics())
+
+        filtered = [
+            d
+            for d in all_diag
+            if (severity_filter is None or d.severity == severity_filter)
+            and (producer is None or d.producer == producer)
+            and (code is None or d.code == code)
+        ]
+        shown = filtered[:limit]
+
+        if as_json:
+            json_renderer.emit(
+                "diagnostics",
+                {
+                    "total": len(all_diag),
+                    "matched": len(filtered),
+                    "shown": len(shown),
+                    "filters": {
+                        "severity": severity_filter,
+                        "producer": producer,
+                        "code": code,
+                    },
+                    "results": [
+                        {
+                            "severity": d.severity,
+                            "code": d.code,
+                            "producer": d.producer,
+                            "file": str(d.file),
+                            "line": d.range.start_line if d.range else None,
+                            "message": d.message,
+                        }
+                        for d in shown
+                    ],
+                },
+            )
+            return
+
+        cons = text.console()
+        if not all_diag:
+            cons.print("[green]No diagnostics recorded.[/green]")
+            return
+        if not filtered:
+            cons.print(
+                f"[yellow]No diagnostics matched the filter.[/yellow] "
+                f"(total recorded: {len(all_diag)})"
+            )
+            return
+
+        cons.print(
+            f"[bold]Showing {len(shown)} of {len(filtered)} matched ({len(all_diag)} total)[/bold]"
+        )
+        rows = []
+        for d in shown:
+            color = _SEVERITY_COLORS.get(d.severity, "white")
+            location = (
+                format_location(d.file, d.range.start_line) if d.range is not None else str(d.file)
+            )
+            rows.append(
+                [
+                    f"[{color}]{d.severity}[/{color}]",
+                    d.code,
+                    d.producer,
+                    location,
+                    d.message,
+                ]
+            )
+        cons.print(
+            text.table(
+                "Diagnostics",
+                ["severity", "code", "producer", "location", "message"],
+                rows,
+            )
+        )
+
+
+__all__ = ["register"]

codemap/cli/commands/doctor.py

@@ -0,0 +1,158 @@
+"""``codemap doctor`` — health check for the local index and plugin set."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from codemap import __version__
+from codemap.cli.renderers import json as json_renderer
+from codemap.cli.renderers import text
+from codemap.core.bridge.registry import get_registry as get_bridges
+from codemap.diagnostics.exit_codes import ExitCode
+from codemap.indexers.registry import get_registry as get_indexers
+from codemap.io.json_store import IntegrityError, JsonStore
+from codemap.io.manifest import SchemaVersionError
+
+CODEMAP_DIR = ".codemap"
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("doctor")
+    def doctor(
+        ctx: typer.Context,
+        path: Annotated[
+            Path,
+            typer.Argument(
+                exists=False,
+                file_okay=False,
+                dir_okay=True,
+                help="Project root to diagnose (defaults to CWD).",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """Report on registered plugins and the local `.codemap/` state."""
+        as_json: bool = ctx.obj["json_output"]
+        codemap_dir = path / CODEMAP_DIR
+
+        indexer_rows = [
+            [ix.name, ix.version, ", ".join(ix.languages), ", ".join(ix.file_patterns)]
+            for ix in get_indexers().all().values()
+        ]
+        bridge_rows = [
+            [b.name, b.version, ", ".join(b.requires) or "-"] for b in get_bridges().all().values()
+        ]
+
+        index_status, manifest_info, issue = _inspect_index(codemap_dir)
+
+        payload = {
+            "codemap_version": __version__,
+            "project_root": str(path.resolve()),
+            "indexers": [
+                {
+                    "name": r[0],
+                    "version": r[1],
+                    "languages": r[2].split(", ") if r[2] else [],
+                    "file_patterns": r[3].split(", ") if r[3] else [],
+                }
+                for r in indexer_rows
+            ],
+            "bridges": [
+                {"name": r[0], "version": r[1], "requires": r[2].split(", ") if r[2] != "-" else []}
+                for r in bridge_rows
+            ],
+            "index": {
+                "status": index_status,
+                "info": manifest_info,
+                "issue": issue,
+            },
+        }
+
+        if as_json:
+            json_renderer.emit("doctor", payload)
+        else:
+            _render_text(payload, indexer_rows, bridge_rows)
+
+        # Non-zero exit if index is in a recoverable bad state, so CI can act.
+        if index_status == "corrupted":
+            raise typer.Exit(code=int(ExitCode.DATA_ERROR))
+
+
+def _inspect_index(codemap_dir: Path) -> tuple[str, dict[str, object], str | None]:
+    if not codemap_dir.exists():
+        return "absent", {}, None
+    try:
+        with JsonStore.open(codemap_dir, mode="r") as store:
+            m = store.manifest()
+            return (
+                "ok",
+                {
+                    "schema_version": m.schema_version,
+                    "codemap_version": m.codemap_version,
+                    "storage_backend": m.storage_backend,
+                    "symbol_count": m.stats.symbol_count,
+                    "edge_count": m.stats.edge_count,
+                    "indexer_count": len(m.indexers),
+                    "bridge_count": len(m.bridges),
+                    "updated_at": m.updated_at.isoformat(),
+                },
+                None,
+            )
+    except (SchemaVersionError, IntegrityError, OSError, ValueError) as exc:
+        return "corrupted", {}, str(exc)
+
+
+def _render_text(
+    payload: Mapping[str, Any],
+    indexer_rows: list[list[str]],
+    bridge_rows: list[list[str]],
+) -> None:
+    cons = text.console()
+    cons.print(f"[bold]CodeMap[/bold] {payload['codemap_version']}")
+    cons.print(f"project_root: {payload['project_root']}")
+    cons.print()
+    if indexer_rows:
+        cons.print(
+            text.table(
+                "Registered indexers",
+                ["name", "version", "languages", "file_patterns"],
+                indexer_rows,
+            )
+        )
+    else:
+        cons.print("[yellow]No indexers registered[/yellow]")
+    if bridge_rows:
+        cons.print(
+            text.table(
+                "Registered bridges",
+                ["name", "version", "requires"],
+                bridge_rows,
+            )
+        )
+    cons.print()
+    idx = payload["index"]
+    assert isinstance(idx, dict)
+    status = idx["status"]
+    if status == "absent":
+        cons.print(
+            "[yellow]No `.codemap/` directory found.[/yellow] Run `codemap index` to build one."
+        )
+    elif status == "corrupted":
+        cons.print(f"[red]Index corrupted:[/red] {idx['issue']}")
+        cons.print("Run `codemap index --rebuild` to regenerate.")
+    else:
+        info = idx["info"]
+        assert isinstance(info, dict)
+        cons.print(
+            text.table(
+                "Index status",
+                ["field", "value"],
+                [[k, v] for k, v in info.items()],
+            )
+        )
+
+
+__all__ = ["register"]