codemap-core 0.1.0__py3-none-any.whl

codemap/config/schema.py

@@ -0,0 +1,122 @@
+"""Configuration schema for `.codemap/config.yaml`.
+
+Pydantic models double as the single source of truth: the YAML loader
+validates against them, the CLI renders them, the in-memory ``Config``
+object is what callers ever touch. ``extra="forbid"`` ensures typos and
+deprecated keys surface as errors rather than silently being ignored.
+
+Layered loading (cf. ``codemap.config.loader.load_config``):
+
+1. Built-in defaults — every field has a sensible value.
+2. User-level file at ``~/.config/codemap/config.yaml`` (overrides defaults).
+3. Project-level file at ``<project>/.codemap/config.yaml`` (overrides user).
+4. CLI flags (overrides everything; not handled here).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# 10 MB. Matches the previous hard-coded value in `codemap.cli.commands.index`.
+DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024
+
+# Directories ignored even when not explicitly listed in the config — they
+# are universally noise and would otherwise dominate the index.
+DEFAULT_PRUNE_DIRS: tuple[str, ...] = (
+    ".git",
+    ".hg",
+    ".svn",
+    ".codemap",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "dist",
+    "build",
+)
+
+
+class _Base(BaseModel):
+    """Common pydantic config for every config section."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=False,
+        validate_assignment=True,
+    )
+
+
+class StorageConfig(_Base):
+    """Persistence backend configuration."""
+
+    backend: Literal["json", "sqlite"] = "json"
+
+
+class IndexConfig(_Base):
+    """File-discovery and parsing limits."""
+
+    ignore: list[str] = Field(default_factory=list)
+    """Extra glob patterns to exclude during indexing.
+
+    Patterns are matched with ``fnmatch.fnmatch`` against the project-
+    relative POSIX path of each candidate file *and* against each directory
+    name during ``os.walk``. Use ``**/dist/**`` for path-anchored
+    exclusions and ``*.bak`` for filename matching.
+    """
+
+    max_file_bytes: int = Field(default=DEFAULT_MAX_FILE_BYTES, ge=1)
+    """Files larger than this byte count are skipped with a diagnostic."""
+
+    follow_symlinks: bool = False
+    """If ``True``, ``os.walk`` follows symlinks. Use cautiously — cycles
+    are guarded by inode tracking but can still slow indexing significantly."""
+
+
+class IndexersConfig(_Base):
+    """Which indexer plugins to actually run."""
+
+    enabled: list[str] | Literal["all"] = "all"
+    """Either ``"all"`` (default) or an explicit list of indexer names.
+
+    A name in this list that does not match any registered indexer is
+    silently ignored — third-party plugins may come and go between
+    workstations and we don't want to break indexing on a stale config.
+    """
+
+    disabled: list[str] = Field(default_factory=list)
+    """Indexer names to skip even when ``enabled = "all"``.
+
+    The ``_example_lang`` reference indexer is a typical entry here once
+    real indexers are in play."""
+
+
+class BridgesConfig(_Base):
+    """Which bridge plugins to actually run."""
+
+    enabled: list[str] | Literal["all"] = "all"
+    disabled: list[str] = Field(default_factory=list)
+
+
+class Config(_Base):
+    """Top-level CodeMap configuration."""
+
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    index: IndexConfig = Field(default_factory=IndexConfig)
+    indexers: IndexersConfig = Field(default_factory=IndexersConfig)
+    bridges: BridgesConfig = Field(default_factory=BridgesConfig)
+
+
+__all__ = [
+    "DEFAULT_MAX_FILE_BYTES",
+    "DEFAULT_PRUNE_DIRS",
+    "BridgesConfig",
+    "Config",
+    "IndexConfig",
+    "IndexersConfig",
+    "StorageConfig",
+]

codemap/core/__init__.py

@@ -0,0 +1,7 @@
+"""Pure-business core: data models, SymbolID, graph algorithms, query semantics.
+
+Strict dependency rule (ADR-003): `core` MUST NOT import from `cli`, `io`,
+`indexers`, or `mcp`. Protocols defined here are implemented in outer layers.
+"""
+
+from __future__ import annotations

codemap/core/bridge/__init__.py

@@ -0,0 +1,8 @@
+"""Cross-scheme bridge abstractions.
+
+Bridges resolve relationships between symbols of different schemes after all
+indexers have finished. They are language-neutral by construction (ADR-L001):
+bridges operate on Symbol/Edge data, not on language-specific AST.
+"""
+
+from __future__ import annotations

codemap/core/bridge/base.py

@@ -0,0 +1,38 @@
+"""Bridge Protocol — cross-scheme resolvers (HTTP routes, asset-interface
+aliases, dependency injection wiring, etc.).
+
+A bridge runs after every indexer has finished. It inspects the populated
+:class:`codemap.io.base.ReadOnlyStore`, derives new edges/aliases/routes, and
+returns them in a :class:`BridgeResult`. Bridges are pure: the orchestrator,
+not the bridge, decides when and how to persist the output.
+
+All bridges — built-in or external — register via the ``codemap.bridges``
+entry-point group on equal footing (ADR-004, ADR-L001).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Protocol, runtime_checkable
+
+from codemap.core.models import BridgeResult
+from codemap.core.store import ReadOnlyStore
+
+__all__ = ["Bridge", "BridgeResult"]
+
+
+@runtime_checkable
+class Bridge(Protocol):
+    """The required interface for any bridge implementation."""
+
+    name: ClassVar[str]
+    """Unique short identifier (lowercase, ASCII, no spaces)."""
+
+    version: ClassVar[str]
+    """Semantic version of the bridge itself."""
+
+    requires: ClassVar[list[str]]
+    """Names of bridges that must run before this one (topological order)."""
+
+    def resolve(self, store: ReadOnlyStore) -> BridgeResult:
+        """Inspect ``store``; emit derived edges, aliases, routes, diagnostics."""
+        ...

codemap/core/bridge/http_route.py

@@ -0,0 +1,374 @@
+"""HTTP route bridge — language-neutral client ↔ server linker.
+
+The bridge knows nothing about specific server frameworks or HTTP client
+libraries. Instead, it relies on a small **metadata convention** that any
+indexer can populate. Whether the source language is Python, TypeScript,
+Go, Rust, or anything else does not matter; the contract is the same.
+
+## Metadata convention
+
+A server-side handler advertises itself by setting two keys on its
+``Symbol.extra`` dict::
+
+    "http_route": {
+        "method": "GET",                # required, case-insensitive
+        "path":   "/api/user/{id}",     # required, with optional {var}s
+        "context_path": "/api/v1",      # optional, prepended to ``path``
+    }
+
+A client-side caller advertises every HTTP call it issues::
+
+    "http_calls": [
+        {
+            "method":     "GET",
+            "url":        "/api/v1/user/42",
+            "confidence": "high",       # optional; defaults to "medium"
+        },
+        ...
+    ]
+
+## Resolution output
+
+For each unique ``(method, full_path)`` advertised by the server side, the
+bridge mints a synthetic intermediate symbol with the ``scip-route`` scheme
+(e.g. ``scip-route . . . api/GET#`/api/user/{id}`.``). Server handlers and
+client calls both relate to this intermediate via :class:`Alias` and
+:class:`Edge` entries — that way the symbol-store doesn't have to carry
+a direct ``client → server`` edge for every (method, path) combination.
+
+The bridge produces three kinds of outputs:
+
+* :class:`Route` entries (one per server-advertised route) for
+  ``routes.json``.
+* :class:`Alias` entries linking the intermediate to its server handlers
+  (and, when an exact client URL matches, the client callers).
+* :class:`Edge` entries with ``kind="routes_to"`` (``server_handler →
+  route_intermediate``) and ``kind="calls"`` (``client_caller →
+  route_intermediate``) so the existing call-graph queries keep working.
+
+## Path matching
+
+A client ``url`` matches a server ``path`` if they have the same number of
+``/``-separated segments and every static server segment equals the
+corresponding client segment; ``{placeholder}`` segments in the server
+path match any non-empty client segment. Trailing slashes and query
+strings are ignored on the client side.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from pathlib import PurePosixPath
+from typing import ClassVar
+
+from codemap.core.models import (
+    Alias,
+    BridgeResult,
+    Confidence,
+    Diagnostic,
+    Edge,
+    Route,
+)
+from codemap.core.store import ReadOnlyStore
+from codemap.core.symbol import Descriptor, DescriptorKind, SymbolID
+
+SCHEME = "scip-route"
+
+
+class HttpRouteBridge:
+    name: ClassVar[str] = "http_route"
+    version: ClassVar[str] = "0.1.0"
+    requires: ClassVar[list[str]] = []
+
+    def resolve(self, store: ReadOnlyStore) -> BridgeResult:
+        server_routes: list[_ServerRoute] = []
+        client_calls: list[_ClientCall] = []
+
+        for sym in store.iter_symbols():
+            extra = sym.extra
+            server_meta = _read_server_route(extra)
+            if server_meta is not None:
+                method, path, context = server_meta
+                full_path = _join_path(context, path)
+                server_routes.append(
+                    _ServerRoute(
+                        method=method,
+                        full_path=full_path,
+                        symbol_id=sym.id,
+                        file=sym.file,
+                    )
+                )
+            for call in _read_client_calls(extra):
+                client_method, url, conf = call
+                client_calls.append(
+                    _ClientCall(
+                        method=client_method,
+                        url=url,
+                        symbol_id=sym.id,
+                        confidence=conf,
+                        file=sym.file,
+                    )
+                )
+
+        # Mint one intermediate symbol per unique (method, full_path)
+        intermediates: dict[tuple[str, str], SymbolID] = {}
+        for route in server_routes:
+            key = (route.method, route.full_path)
+            if key not in intermediates:
+                intermediates[key] = _route_symbol_id(route.method, route.full_path)
+
+        routes: list[Route] = []
+        aliases: list[Alias] = []
+        edges: list[Edge] = []
+        diagnostics: list[Diagnostic] = []
+
+        # Group server handlers per route so we can warn on duplicates.
+        handlers: defaultdict[tuple[str, str], list[_ServerRoute]] = defaultdict(list)
+        for route in server_routes:
+            handlers[(route.method, route.full_path)].append(route)
+
+        for (method, full_path), group in handlers.items():
+            route_sid = intermediates[(method, full_path)]
+            routes.append(
+                Route(
+                    method=method,
+                    path=full_path,
+                    symbol_id=route_sid,
+                    context_path=None,
+                )
+            )
+            aliases.append(
+                Alias(
+                    source=route_sid,
+                    targets=[handler.symbol_id for handler in group],
+                    producer=self.name,
+                    confidence="high",
+                )
+            )
+            edges.extend(
+                Edge(
+                    source=handler.symbol_id,
+                    target=route_sid,
+                    kind="routes_to",
+                    confidence="high",
+                )
+                for handler in group
+            )
+            if len(group) > 1:
+                diagnostics.append(
+                    Diagnostic(
+                        severity="warning",
+                        file=group[0].file,
+                        code="ROUTE001",
+                        message=(
+                            f"multiple handlers registered for {method} {full_path}: "
+                            f"{len(group)} symbols"
+                        ),
+                        producer=self.name,
+                    )
+                )
+
+        # Match each client call against the known server routes.
+        server_keys = list(intermediates.keys())
+        for cc in client_calls:
+            matched = _match_route(cc.method, cc.url, server_keys)
+            if matched is None:
+                if cc.confidence == "high":
+                    diagnostics.append(
+                        Diagnostic(
+                            severity="warning",
+                            file=cc.file,
+                            code="ROUTE002",
+                            message=(
+                                f"client {cc.method} {cc.url} has no matching "
+                                f"server route in this index"
+                            ),
+                            producer=self.name,
+                        )
+                    )
+                continue
+            route_sid = intermediates[matched]
+            edges.append(
+                Edge(
+                    source=cc.symbol_id,
+                    target=route_sid,
+                    kind="calls",
+                    confidence=cc.confidence,
+                )
+            )
+
+        return BridgeResult(
+            edges=edges,
+            aliases=aliases,
+            routes=routes,
+            diagnostics=diagnostics,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Metadata adapters
+# ---------------------------------------------------------------------------
+
+
+class _ServerRoute:
+    __slots__ = ("file", "full_path", "method", "symbol_id")
+
+    def __init__(
+        self,
+        *,
+        method: str,
+        full_path: str,
+        symbol_id: SymbolID,
+        file: PurePosixPath,
+    ) -> None:
+        self.method = method
+        self.full_path = full_path
+        self.symbol_id = symbol_id
+        self.file = file
+
+
+class _ClientCall:
+    __slots__ = ("confidence", "file", "method", "symbol_id", "url")
+
+    def __init__(
+        self,
+        *,
+        method: str,
+        url: str,
+        symbol_id: SymbolID,
+        confidence: Confidence,
+        file: PurePosixPath,
+    ) -> None:
+        self.method = method
+        self.url = url
+        self.symbol_id = symbol_id
+        self.confidence: Confidence = confidence
+        self.file = file
+
+
+def _read_server_route(extra: dict[str, object]) -> tuple[str, str, str] | None:
+    raw = extra.get("http_route")
+    if not isinstance(raw, dict):
+        return None
+    method_raw = raw.get("method")
+    path_raw = raw.get("path")
+    if not isinstance(method_raw, str) or not isinstance(path_raw, str):
+        return None
+    method = method_raw.strip().upper()
+    path = path_raw.strip()
+    if not method or not path:
+        return None
+    ctx_raw = raw.get("context_path")
+    context = ctx_raw.strip() if isinstance(ctx_raw, str) else ""
+    return method, path, context
+
+
+_VALID_CONFIDENCE = frozenset({"high", "medium", "low"})
+
+
+def _read_client_calls(
+    extra: dict[str, object],
+) -> Iterable[tuple[str, str, Confidence]]:
+    raw = extra.get("http_calls")
+    if not isinstance(raw, list):
+        return
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        method_raw = item.get("method")
+        url_raw = item.get("url")
+        if not isinstance(method_raw, str) or not isinstance(url_raw, str):
+            continue
+        method = method_raw.strip().upper()
+        url = url_raw.strip()
+        if not method or not url:
+            continue
+        conf_raw = item.get("confidence")
+        if isinstance(conf_raw, str) and conf_raw in _VALID_CONFIDENCE:
+            confidence: Confidence = conf_raw  # type: ignore[assignment]
+        else:
+            confidence = "medium"
+        yield method, url, confidence
+
+
+# ---------------------------------------------------------------------------
+# Path manipulation
+# ---------------------------------------------------------------------------
+
+
+def _join_path(context: str, path: str) -> str:
+    """Concatenate ``context_path`` (optional) with ``path``.
+
+    Both arguments may or may not include leading / trailing slashes; the
+    result is normalised to a single leading ``/`` and no trailing ``/``
+    unless the entire result is ``/``.
+    """
+    parts: list[str] = []
+    for piece in (context, path):
+        stripped = piece.strip()
+        if not stripped:
+            continue
+        parts.extend(seg for seg in stripped.split("/") if seg)
+    if not parts:
+        return "/"
+    return "/" + "/".join(parts)
+
+
+def _match_route(
+    method: str,
+    url: str,
+    server_routes: list[tuple[str, str]],
+) -> tuple[str, str] | None:
+    """Return the first ``(method, path)`` from ``server_routes`` that matches.
+
+    Path-variable segments (``{name}``) on the server side match any
+    single non-empty client segment. Query strings on the client URL are
+    stripped before comparison. Trailing slashes are normalised.
+    """
+    client_path = url.split("?", 1)[0].split("#", 1)[0]
+    c_segments = [s for s in client_path.split("/") if s]
+    for s_method, s_path in server_routes:
+        if s_method != method:
+            continue
+        s_segments = [s for s in s_path.split("/") if s]
+        if len(s_segments) != len(c_segments):
+            continue
+        ok = True
+        for s, c in zip(s_segments, c_segments, strict=True):
+            if s.startswith("{") and s.endswith("}") and len(s) >= 2:
+                if not c:
+                    ok = False
+                    break
+                continue
+            if s != c:
+                ok = False
+                break
+        if ok:
+            return (s_method, s_path)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Intermediate symbol minting
+# ---------------------------------------------------------------------------
+
+
+def _route_symbol_id(method: str, path: str) -> SymbolID:
+    """Build the ``scip-route`` intermediate symbol.
+
+    Shape: ``scip-route . . . api/<METHOD>#`<path>`.``. The path is held
+    in a TERM descriptor so it can contain slashes; the parser auto-
+    escapes via backticks.
+    """
+    return SymbolID(
+        scheme=SCHEME,
+        descriptors=(
+            Descriptor(name="api", kind=DescriptorKind.NAMESPACE),
+            Descriptor(name=method, kind=DescriptorKind.TYPE),
+            Descriptor(name=path, kind=DescriptorKind.TERM),
+        ),
+    )
+
+
+__all__ = ["SCHEME", "HttpRouteBridge"]

codemap/core/bridge/python_cross_module.py

@@ -0,0 +1,120 @@
+"""Cross-module Python call resolver.
+
+The Python indexer emits ``calls`` edges whose target is a synthetic
+``scip-python . . . <module-dotted-ns>/<leaf>.`` symbol whenever a name
+came in through an ``import`` statement. That synthetic target rarely
+matches a real on-disk symbol — the same function defined in
+``foo/bar.py`` lives at ``scip-python . . . foo/bar.py/<leaf>().`` (note
+the ``.py`` extension and the method/term suffix).
+
+This bridge bridges the two. After all indexers have run it scans the
+edge table, finds calls pointing at unresolved scip-python targets, and
+maps each one to a concrete local symbol whose **leaf name matches** and
+whose **file stem matches the last namespace segment of the synthetic
+target**. Matches are emitted as :class:`Alias` entries so query code
+(``callers`` / ``callees`` / ``trace``) can transparently expand them.
+
+The matcher is intentionally simple: it ships as a single-language
+heuristic, not a type system. It accepts only one of three confidence
+levels:
+
+* ``high`` — exactly one candidate whose file stem equals the last
+  namespace segment of the synthetic target.
+* ``medium`` — exactly one candidate by leaf name alone, when the
+  synthetic target has no namespace segments to disambiguate.
+* otherwise — drop the edge (no alias produced).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import PurePosixPath
+from typing import ClassVar
+
+from codemap.core.models import Alias, BridgeResult, Confidence, Symbol
+from codemap.core.store import ReadOnlyStore
+from codemap.core.symbol import DescriptorKind, SymbolID
+
+_PYTHON_SCHEME = "scip-python"
+_INDEXABLE_KINDS = frozenset({"function", "method", "class", "field", "variable"})
+
+
+class PythonCrossModuleBridge:
+    name: ClassVar[str] = "python_cross_module"
+    version: ClassVar[str] = "0.1.0"
+    requires: ClassVar[list[str]] = []
+
+    def resolve(self, store: ReadOnlyStore) -> BridgeResult:
+        leaf_to_symbols: dict[str, list[Symbol]] = defaultdict(list)
+        for sym in store.iter_symbols():
+            if sym.language != "python":
+                continue
+            if sym.kind not in _INDEXABLE_KINDS:
+                continue
+            if not sym.id.descriptors:
+                continue
+            leaf = sym.id.descriptors[-1].name
+            leaf_to_symbols[leaf].append(sym)
+
+        aliases: list[Alias] = []
+        seen_sources: set[str] = set()
+        for edge in store.iter_edges():
+            if edge.kind != "calls":
+                continue
+            target = edge.target
+            if target.scheme != _PYTHON_SCHEME:
+                continue
+            if store.get(target) is not None:
+                continue  # already a real local symbol
+            target_key = str(target)
+            if target_key in seen_sources:
+                continue
+            resolved = _resolve_one(target, leaf_to_symbols)
+            if resolved is None:
+                continue
+            local, confidence = resolved
+            aliases.append(
+                Alias(
+                    source=target,
+                    targets=[local.id],
+                    producer=self.name,
+                    confidence=confidence,
+                )
+            )
+            seen_sources.add(target_key)
+        return BridgeResult(aliases=aliases)
+
+
+def _resolve_one(
+    target: SymbolID,
+    leaf_to_symbols: dict[str, list[Symbol]],
+) -> tuple[Symbol, Confidence] | None:
+    """Return ``(local Symbol, confidence)`` or ``None``."""
+    if not target.descriptors:
+        return None
+    last = target.descriptors[-1]
+    # Terms / methods are the shapes the indexer's _module_symbol_id and
+    # _external_symbol_id helpers actually produce; only those are worth
+    # trying to resolve here.
+    if last.kind not in (DescriptorKind.TERM, DescriptorKind.METHOD, DescriptorKind.META):
+        return None
+    leaf = last.name
+    candidates = leaf_to_symbols.get(leaf, [])
+    if not candidates:
+        return None
+
+    ns_parts = [d.name for d in target.descriptors[:-1] if d.kind is DescriptorKind.NAMESPACE]
+    if ns_parts:
+        last_ns = ns_parts[-1]
+        matching = [c for c in candidates if PurePosixPath(c.file).stem == last_ns]
+        if len(matching) == 1:
+            return matching[0], "high"
+        # If the namespace chain matches but multiple candidates share the
+        # file stem, we don't pick one — the index would lie.
+        return None
+    if len(candidates) == 1:
+        return candidates[0], "medium"
+    return None
+
+
+__all__ = ["PythonCrossModuleBridge"]