codemap-core 0.1.0__py3-none-any.whl

codemap/cli/commands/routes.py

@@ -0,0 +1,104 @@
+"""``codemap routes`` — list HTTP routes produced by the http_route bridge."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+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
+from codemap.core.models import Symbol
+from codemap.core.symbol import SymbolID
+from codemap.io.json_store import JsonStore
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("routes")
+    def routes(
+        ctx: typer.Context,
+        method_filter: Annotated[
+            str | None,
+            typer.Option("--method", "-m", help="Filter by HTTP method (case-insensitive)."),
+        ] = None,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """List all HTTP routes (method, path → server handler)."""
+        as_json: bool = ctx.obj["json_output"]
+        wanted = method_filter.upper() if method_filter else None
+        with open_store_or_exit(project) as store:
+            all_routes = [r for r in store.iter_routes() if wanted is None or r.method == wanted]
+            entries = [(r, list(_resolve_aliases(r.symbol_id, store))) for r in all_routes]
+
+        if as_json:
+            json_renderer.emit(
+                "routes",
+                {
+                    "method_filter": wanted,
+                    "results": [
+                        {
+                            "method": r.method,
+                            "path": r.path,
+                            "route_id": str(r.symbol_id),
+                            "handlers": [
+                                {
+                                    "id": str(s.id),
+                                    "kind": s.kind,
+                                    "language": s.language,
+                                    "file": str(s.file),
+                                    "line": s.range.start_line,
+                                }
+                                for s in handlers
+                            ],
+                        }
+                        for r, handlers in entries
+                    ],
+                },
+            )
+            return
+
+        cons = text.console()
+        if not entries:
+            cons.print(
+                "[yellow]No routes recorded.[/yellow] "
+                "If your indexer doesn't emit `http_route` metadata, "
+                "the bridge has nothing to link."
+            )
+            return
+        rows: list[list[str]] = []
+        for route, handlers in entries:
+            handler_str = (
+                "\n".join(format_location(s.file, s.range.start_line) for s in handlers)
+                if handlers
+                else "(unresolved)"
+            )
+            rows.append([route.method, route.path, handler_str])
+        cons.print(text.table("HTTP routes", ["method", "path", "handler"], rows))
+
+
+def _resolve_aliases(route_id: SymbolID, store: JsonStore) -> Iterator[Symbol]:
+    """Return the Symbol objects each alias.targets points at, for routes."""
+    for alias in store.iter_aliases():
+        if str(alias.source) != str(route_id):
+            continue
+        if alias.producer != "http_route":
+            continue
+        for target_id in alias.targets:
+            sym = store.get(target_id)
+            if sym is not None:
+                yield sym
+
+
+__all__ = ["register"]

codemap/cli/commands/search.py

@@ -0,0 +1,78 @@
+"""``codemap search`` — keyword search across the local index."""
+
+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
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("search")
+    def search(
+        ctx: typer.Context,
+        query: Annotated[str, typer.Argument(help="Substring to look for.")],
+        limit: Annotated[
+            int,
+            typer.Option("--limit", "-n", help="Maximum number of hits."),
+        ] = 10,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """Keyword search across symbol IDs, signatures, and docstrings."""
+        as_json: bool = ctx.obj["json_output"]
+        with open_store_or_exit(project) as store:
+            hits = store.search(query, limit=limit)
+
+        if as_json:
+            json_renderer.emit(
+                "search",
+                {
+                    "query": query,
+                    "limit": limit,
+                    "results": [
+                        {
+                            "id": str(h.symbol.id),
+                            "kind": h.symbol.kind,
+                            "language": h.symbol.language,
+                            "file": str(h.symbol.file),
+                            "line": h.symbol.range.start_line,
+                            "signature": h.symbol.signature,
+                            "score": h.score,
+                            "source": h.source,
+                        }
+                        for h in hits
+                    ],
+                },
+            )
+            return
+
+        cons = text.console()
+        if not hits:
+            cons.print(f"[yellow]No matches for[/yellow] {query!r}")
+            return
+        rows = [
+            [
+                h.symbol.kind,
+                format_location(h.symbol.file, h.symbol.range.start_line),
+                h.symbol.signature or str(h.symbol.id),
+            ]
+            for h in hits
+        ]
+        cons.print(text.table(f"Search: {query}", ["kind", "location", "symbol"], rows))
+
+
+__all__ = ["register"]

codemap/cli/commands/trace.py

@@ -0,0 +1,179 @@
+"""``codemap trace --from <id> [--to <id>]`` — walk or path-find through edges."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.tree import Tree
+
+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
+from codemap.core.graph import ChainNode, shortest_path, walk_chain
+from codemap.diagnostics.exit_codes import ExitCode
+from codemap.io.json_store import JsonStore
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("trace")
+    def trace(
+        ctx: typer.Context,
+        from_: Annotated[
+            str,
+            typer.Option("--from", "-f", help="Starting SymbolID."),
+        ],
+        to: Annotated[
+            str | None,
+            typer.Option(
+                "--to",
+                "-t",
+                help="Optional destination SymbolID — switches to shortest-path mode.",
+            ),
+        ] = None,
+        depth: Annotated[
+            int,
+            typer.Option("--depth", "-d", min=1, help="Maximum hops."),
+        ] = 5,
+        project: Annotated[
+            Path,
+            typer.Option(
+                "--project",
+                "-p",
+                file_okay=False,
+                dir_okay=True,
+                help="Project root containing `.codemap/`.",
+            ),
+        ] = Path("."),
+    ) -> None:
+        """Walk the call chain downstream from ``--from`` (or find the path to ``--to``)."""
+        as_json: bool = ctx.obj["json_output"]
+        start = parse_symbol_id_or_exit(from_)
+        with open_store_or_exit(project) as store:
+            if to is None:
+                root = walk_chain(start, store, max_depth=depth)
+                if as_json:
+                    json_renderer.emit("trace", _chain_to_json(root, store))
+                else:
+                    _render_chain_text(root, store)
+                return
+
+            end = parse_symbol_id_or_exit(to)
+            path = shortest_path(start, end, store, max_depth=depth)
+            if path is None:
+                if as_json:
+                    json_renderer.emit(
+                        "trace",
+                        {"from": str(start), "to": str(end), "found": False, "path": []},
+                    )
+                else:
+                    text.console(stderr=True).print(
+                        f"[yellow]No path found within depth {depth}[/yellow]"
+                    )
+                raise typer.Exit(code=int(ExitCode.GENERIC_ERROR))
+
+            if as_json:
+                json_renderer.emit(
+                    "trace",
+                    {
+                        "from": str(start),
+                        "to": str(end),
+                        "found": True,
+                        "path": _path_to_json(path, store, start),
+                    },
+                )
+            else:
+                _render_path_text(start, path, store)
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+
+def _chain_to_json(node: ChainNode, store: JsonStore) -> dict[str, Any]:
+    sym = store.get(node.symbol_id)
+    return {
+        "id": str(node.symbol_id),
+        "kind": sym.kind if sym else "external",
+        "file": str(sym.file) if sym else None,
+        "line": sym.range.start_line if sym else None,
+        "incoming_edge": (
+            {
+                "kind": node.incoming_edge.kind,
+                "confidence": node.incoming_edge.confidence,
+            }
+            if node.incoming_edge is not None
+            else None
+        ),
+        "depth": node.depth,
+        "children": [_chain_to_json(c, store) for c in node.children],
+    }
+
+
+def _path_to_json(
+    path: list[Any],
+    store: JsonStore,
+    start: Any,
+) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    current = start
+    out.append(_node_payload(current, store, edge=None))
+    for edge in path:
+        out.append(_node_payload(edge.target, store, edge=edge))
+        current = edge.target
+    return out
+
+
+def _node_payload(sid: Any, store: JsonStore, edge: Any) -> dict[str, Any]:
+    sym = store.get(sid)
+    return {
+        "id": str(sid),
+        "kind": sym.kind if sym else "external",
+        "file": str(sym.file) if sym else None,
+        "line": sym.range.start_line if sym else None,
+        "incoming_edge": (
+            {"kind": edge.kind, "confidence": edge.confidence} if edge is not None else None
+        ),
+    }
+
+
+def _render_chain_text(node: ChainNode, store: JsonStore) -> None:
+    tree = Tree(_label_for(node.symbol_id, store, edge=None))
+    for child in node.children:
+        _attach(tree, child, store)
+    text.console().print(tree)
+
+
+def _attach(parent: Tree, node: ChainNode, store: JsonStore) -> None:
+    branch = parent.add(_label_for(node.symbol_id, store, edge=node.incoming_edge))
+    for child in node.children:
+        _attach(branch, child, store)
+
+
+def _render_path_text(start: Any, path: list[Any], store: JsonStore) -> None:
+    cons = text.console()
+    cons.print(_label_for(start, store, edge=None))
+    for edge in path:
+        cons.print("  " + _label_for(edge.target, store, edge=edge))
+
+
+def _label_for(sid: Any, store: JsonStore, edge: Any) -> str:
+    sym = store.get(sid)
+    if sym is not None:
+        head = f"[bold]{format_location(sym.file, sym.range.start_line)}[/bold]"
+        signature = sym.signature or str(sid)
+    else:
+        head = "[dim](external)[/dim]"
+        signature = str(sid)
+    if edge is None:
+        return f"{head}  {signature}"
+    return f"{head}  {signature}  [{edge.kind}/{edge.confidence}]"
+
+
+__all__ = ["register"]

codemap/cli/main.py

@@ -0,0 +1,140 @@
+"""Typer entry point: ``codemap``.
+
+Reads global options, sets up logging, dispatches to per-command modules.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import traceback
+from typing import Annotated
+
+import typer
+
+from codemap import __version__
+from codemap.cli.commands import callees as callees_cmd
+from codemap.cli.commands import callers as callers_cmd
+from codemap.cli.commands import config as config_cmd
+from codemap.cli.commands import diagnostics as diagnostics_cmd
+from codemap.cli.commands import doctor as doctor_cmd
+from codemap.cli.commands import get as get_cmd
+from codemap.cli.commands import index as index_cmd
+from codemap.cli.commands import routes as routes_cmd
+from codemap.cli.commands import search as search_cmd
+from codemap.cli.commands import trace as trace_cmd
+from codemap.cli.renderers import text
+from codemap.diagnostics.exit_codes import ExitCode
+from codemap.diagnostics.logging import LogFormat, configure_logging
+
+app = typer.Typer(
+    name="codemap",
+    help="Language-neutral code index for AI agents.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "-v",
+            "--verbose",
+            count=True,
+            help="Increase verbosity (-v: INFO, -vv: DEBUG).",
+        ),
+    ] = 0,
+    log_format: Annotated[
+        str,
+        typer.Option(
+            "--log-format",
+            help="Log format: text or json.",
+            case_sensitive=False,
+        ),
+    ] = "text",
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Emit machine-readable JSON instead of human-readable text.",
+        ),
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Print version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Global flags and per-invocation state."""
+    fmt: LogFormat = "json" if log_format.lower() == "json" else "text"
+    configure_logging(verbose, log_format=fmt)
+    ctx.obj = {
+        "verbose": verbose,
+        "json_output": json_output,
+        "log_format": fmt,
+    }
+
+
+# Register subcommands
+doctor_cmd.register(app)
+index_cmd.register(app)
+search_cmd.register(app)
+get_cmd.register(app)
+callers_cmd.register(app)
+callees_cmd.register(app)
+trace_cmd.register(app)
+routes_cmd.register(app)
+config_cmd.register(app)
+diagnostics_cmd.register(app)
+
+
+_ISSUE_TRACKER = "https://github.com/qxbyte/codemap/issues"
+_TRACEBACK_ENV_VAR = "CODEMAP_FULL_TRACEBACK"
+
+
+def main() -> None:
+    """Entry point. Catches anything Typer doesn't and prints a friendly hint.
+
+    Set ``CODEMAP_FULL_TRACEBACK=1`` to see the original traceback (useful
+    when filing a bug).
+    """
+    try:
+        app()
+    except (typer.Exit, SystemExit, KeyboardInterrupt):
+        raise
+    except Exception as exc:  # pragma: no cover - exercised manually
+        cons = text.console(stderr=True)
+        cons.print(
+            f"[bold red]Internal error:[/bold red] "
+            f"{type(exc).__name__}: {exc}\n"
+            f"This is a bug in CodeMap. Please file an issue at\n"
+            f"  [cyan]{_ISSUE_TRACKER}[/cyan]\n"
+            f"and include the output of `codemap --version` and the command "
+            f"you ran."
+        )
+        if os.environ.get(_TRACEBACK_ENV_VAR):
+            cons.print("[dim]" + traceback.format_exc() + "[/dim]")
+        else:
+            cons.print(
+                f"[dim]Set {_TRACEBACK_ENV_VAR}=1 to see the full "
+                f"traceback when filing the issue.[/dim]"
+            )
+        sys.exit(int(ExitCode.INTERNAL_BUG))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

codemap/cli/renderers/__init__.py

@@ -0,0 +1,3 @@
+"""Output renderers (JSON / rich text)."""
+
+from __future__ import annotations

codemap/cli/renderers/json.py

@@ -0,0 +1,32 @@
+"""JSON renderer for CLI output (the canonical machine-readable format).
+
+Every CLI command that supports ``--json`` ends here. The envelope is
+versioned (``schema_version``) so changes are observable.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from codemap.core.models import SCHEMA_VERSION
+
+
+def emit(command: str, payload: Any, *, stream: TextIO | None = None) -> None:
+    """Print a single JSON envelope and a trailing newline.
+
+    ``stream`` is resolved at call time so the renderer respects any
+    ``sys.stdout`` redirection done by test runners (``CliRunner`` etc.).
+    """
+    envelope = {
+        "schema_version": SCHEMA_VERSION,
+        "command": command,
+        "result": payload,
+    }
+    s = stream if stream is not None else sys.stdout
+    s.write(json.dumps(envelope, ensure_ascii=False, indent=2))
+    s.write("\n")
+
+
+__all__ = ["emit"]

codemap/cli/renderers/text.py

@@ -0,0 +1,24 @@
+"""Human-readable renderers built on rich."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+
+def console(*, stderr: bool = False) -> Console:
+    return Console(stderr=stderr)
+
+
+def table(title: str, columns: list[str], rows: list[list[Any]]) -> Table:
+    t = Table(title=title, show_lines=False, header_style="bold")
+    for c in columns:
+        t.add_column(c)
+    for row in rows:
+        t.add_row(*[str(x) for x in row])
+    return t
+
+
+__all__ = ["console", "table"]

codemap/config/__init__.py

@@ -0,0 +1,31 @@
+"""Configuration schema and loader for `.codemap/config.yaml`."""
+
+from __future__ import annotations
+
+from codemap.config.loader import (
+    ConfigError,
+    dump_config,
+    load_config,
+    project_config_path,
+    user_config_path,
+)
+from codemap.config.schema import (
+    BridgesConfig,
+    Config,
+    IndexConfig,
+    IndexersConfig,
+    StorageConfig,
+)
+
+__all__ = [
+    "BridgesConfig",
+    "Config",
+    "ConfigError",
+    "IndexConfig",
+    "IndexersConfig",
+    "StorageConfig",
+    "dump_config",
+    "load_config",
+    "project_config_path",
+    "user_config_path",
+]

codemap/config/loader.py

@@ -0,0 +1,96 @@
+"""Load and merge `.codemap/config.yaml` from defaults / user / project."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+from pydantic import ValidationError
+
+from codemap.config.schema import Config
+
+PROJECT_CONFIG_FILENAME = "config.yaml"
+
+
+class ConfigError(ValueError):
+    """Raised when a config file is malformed or fails schema validation."""
+
+
+def user_config_path() -> Path:
+    """Return ``~/.config/codemap/config.yaml`` regardless of whether it exists."""
+    return Path.home() / ".config" / "codemap" / PROJECT_CONFIG_FILENAME
+
+
+def project_config_path(codemap_dir: Path) -> Path:
+    return codemap_dir / PROJECT_CONFIG_FILENAME
+
+
+def load_config(codemap_dir: Path | None = None) -> Config:
+    """Load defaults → user-level → project-level config, merged in that order.
+
+    ``codemap_dir`` is the ``.codemap/`` directory; the project-level file
+    lives there. Pass ``None`` to skip the project layer (useful for CLI
+    invocations against an unindexed directory).
+
+    Raises :class:`ConfigError` on parse or validation failure. Missing
+    files are not errors — they leave the layer at defaults.
+    """
+    merged: dict[str, Any] = {}
+    _merge_into(merged, _read_yaml(user_config_path()))
+    if codemap_dir is not None:
+        _merge_into(merged, _read_yaml(project_config_path(codemap_dir)))
+    try:
+        return Config.model_validate(merged)
+    except ValidationError as exc:
+        raise ConfigError(
+            "config validation failed:\n"
+            + "\n".join(
+                f"  - {'.'.join(str(p) for p in err['loc'])}: {err['msg']}" for err in exc.errors()
+            )
+        ) from exc
+
+
+def _read_yaml(path: Path) -> Mapping[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"failed to parse {path}: {exc}") from exc
+    if raw is None:  # empty file
+        return {}
+    if not isinstance(raw, Mapping):
+        raise ConfigError(f"{path} must contain a YAML mapping at the root")
+    return cast("Mapping[str, Any]", raw)
+
+
+def _merge_into(dst: dict[str, Any], src: Mapping[str, Any]) -> None:
+    """Recursive dict merge: nested mappings are merged key-by-key, scalars
+    and lists in ``src`` replace whatever ``dst`` holds.
+    """
+    for key, value in src.items():
+        existing = dst.get(key)
+        if isinstance(existing, dict) and isinstance(value, Mapping):
+            _merge_into(existing, value)
+        else:
+            dst[key] = value
+
+
+def dump_config(config: Config) -> str:
+    """Render a Config back into YAML for ``codemap config show``."""
+    return yaml.safe_dump(
+        config.model_dump(mode="json"),
+        sort_keys=False,
+        default_flow_style=False,
+    )
+
+
+__all__ = [
+    "ConfigError",
+    "dump_config",
+    "load_config",
+    "project_config_path",
+    "user_config_path",
+]