compass-code 0.1.0__py3-none-any.whl

compass_core/query/walk_queries.py

@@ -0,0 +1,202 @@
+"""The single-hop queries behind the impact walks, and the typed rows they return.
+
+Each query expands one distance level for a whole frontier at once (``WHERE x IN $ids``
+or ``$paths``). Rows carry the stored keys the walks match on next to the public
+symbols they return.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from compass_core.contract.models import EdgeRef, SymbolRef
+from compass_core.graph.db import Row
+from compass_core.query.cypher import Query
+from compass_core.query.rows import (
+    CLASS_FIELDS,
+    CLASS_WIDTH,
+    FILE_FIELDS,
+    FILE_WIDTH,
+    FUNCTION_FIELDS,
+    FUNCTION_WIDTH,
+    call_type_value,
+    class_from_row,
+    columns,
+    confidence_value,
+    file_from_row,
+    function_from_row,
+    line_value,
+    text_value,
+)
+from compass_core.shared_types import EdgeType
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallRow:
+    """A ``CALLS`` edge between two stored functions.
+
+    Attributes:
+        caller: The calling function.
+        callee: The called function.
+        confidence: Resolver confidence of the edge.
+        edge: The edge as returned in results.
+
+    Example:
+        ``def handle(): decode_token(t)`` gives ``CallRow(caller=<handle>,
+        callee=<decode_token>, confidence=1.0, edge=EdgeRef(type=EdgeType.CALLS, ...))``.
+    """
+
+    caller: SymbolRef
+    callee: SymbolRef
+    confidence: float
+    edge: EdgeRef
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MethodCallRow:
+    """A call to a method of a frontier class.
+
+    Attributes:
+        call: The ``CALLS`` edge to the method.
+        class_key: Id of the class that owns the method.
+
+    Example:
+        ``User().save()`` resolved to ``User.save`` gives
+        ``MethodCallRow(call=<caller CALLS User.save>, class_key="app/models.py::User")``.
+    """
+
+    call: CallRow
+    class_key: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ExternalCallRow:
+    """A ``CALLS_EXTERN`` edge from a stored function.
+
+    Attributes:
+        caller: The calling function.
+        line: 1-indexed call line, or ``None`` when unknown.
+
+    Example:
+        ``def encode(raw): return json.dumps(raw)`` gives
+        ``ExternalCallRow(caller=<encode>, line=None)`` (call lines are not stored yet).
+    """
+
+    caller: SymbolRef
+    line: int | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PairRow:
+    """Two nodes joined by a structural edge (``IMPORTS`` or ``INHERITS``).
+
+    Attributes:
+        source: The importing file or the subclass.
+        target: The imported file or the base class.
+
+    Example:
+        ``class Admin(User)`` gives ``PairRow(source=<Admin>, target=<User>)``;
+        ``from app.auth import decode_token`` in ``app/api.py`` gives
+        ``PairRow(source=<app/api.py>, target=<app/auth.py>)``.
+    """
+
+    source: SymbolRef
+    target: SymbolRef
+
+
+_CALL_END = 2 * FUNCTION_WIDTH
+_CALL_COLUMNS = "r.confidence, r.call_type, r.line"
+
+
+def _call_row(row: Row) -> CallRow:
+    caller = function_from_row(row[:FUNCTION_WIDTH])
+    callee = function_from_row(row[FUNCTION_WIDTH:_CALL_END])
+    confidence = confidence_value(row[_CALL_END])
+    edge = EdgeRef(
+        source_id=caller.id,
+        target_id=callee.id,
+        type=EdgeType.CALLS,
+        confidence=confidence,
+        call_type=call_type_value(row[_CALL_END + 1]),
+        line=line_value(row[_CALL_END + 2], "line"),
+    )
+    return CallRow(caller=caller, callee=callee, confidence=confidence, edge=edge)
+
+
+def _method_call_row(row: Row) -> MethodCallRow:
+    return MethodCallRow(call=_call_row(row), class_key=text_value(row[_CALL_END + 3], "id"))
+
+
+def _external_call_row(row: Row) -> ExternalCallRow:
+    return ExternalCallRow(
+        caller=function_from_row(row[:FUNCTION_WIDTH]),
+        line=line_value(row[FUNCTION_WIDTH], "line"),
+    )
+
+
+def _class_pair(row: Row) -> PairRow:
+    return PairRow(
+        source=class_from_row(row[:CLASS_WIDTH]), target=class_from_row(row[CLASS_WIDTH:])
+    )
+
+
+def _file_pair(row: Row) -> PairRow:
+    return PairRow(source=file_from_row(row[:FILE_WIDTH]), target=file_from_row(row[FILE_WIDTH:]))
+
+
+_A_FUNCTION = columns("a", FUNCTION_FIELDS)
+_B_FUNCTION = columns("b", FUNCTION_FIELDS)
+
+CALLERS_OF_FUNCTIONS: Query[CallRow] = Query(
+    f"""
+    MATCH (a:Function)-[r:CALLS]->(b:Function)
+    WHERE b.id IN $ids AND r.confidence >= $minc
+    RETURN {_A_FUNCTION}, {_B_FUNCTION}, {_CALL_COLUMNS}
+    """,
+    _call_row,
+)
+CALLERS_OF_METHODS: Query[MethodCallRow] = Query(
+    f"""
+    MATCH (c:Class)-[:CONTAINS]->(b:Function)<-[r:CALLS]-(a:Function)
+    WHERE c.id IN $ids AND r.confidence >= $minc
+    RETURN {_A_FUNCTION}, {_B_FUNCTION}, {_CALL_COLUMNS}, c.id
+    """,
+    _method_call_row,
+)
+CALLERS_OF_EXTERNALS: Query[ExternalCallRow] = Query(
+    f"""
+    MATCH (a:Function)-[r:CALLS_EXTERN]->(e:ExternalFunction) WHERE e.full_ref IN $ids
+    RETURN {_A_FUNCTION}, r.line
+    """,
+    _external_call_row,
+)
+SUBCLASSES_OF: Query[PairRow] = Query(
+    f"""
+    MATCH (a:Class)-[:INHERITS]->(b:Class) WHERE b.id IN $ids
+    RETURN {columns("a", CLASS_FIELDS)}, {columns("b", CLASS_FIELDS)}
+    """,
+    _class_pair,
+)
+# File-target variants, keyed by the stored file paths of the frontier.
+IMPORTERS_OF_FILES: Query[PairRow] = Query(
+    f"""
+    MATCH (a:File)-[:IMPORTS]->(b:File) WHERE b.path IN $paths
+    RETURN {columns("a", FILE_FIELDS)}, {columns("b", FILE_FIELDS)}
+    """,
+    _file_pair,
+)
+CALLERS_IN_FILES: Query[CallRow] = Query(
+    f"""
+    MATCH (a:Function)-[r:CALLS]->(b:Function)
+    WHERE b.file_path IN $paths AND r.confidence >= $minc
+    RETURN {_A_FUNCTION}, {_B_FUNCTION}, {_CALL_COLUMNS}
+    """,
+    _call_row,
+)
+SUBCLASSES_IN_FILES: Query[PairRow] = Query(
+    f"""
+    MATCH (a:Class)-[:INHERITS]->(b:Class) WHERE b.file_path IN $paths
+    RETURN {columns("a", CLASS_FIELDS)}, {columns("b", CLASS_FIELDS)}
+    """,
+    _class_pair,
+)

compass_core/render.py

@@ -0,0 +1,408 @@
+"""Compact text for every query result, shared by the CLI and the MCP server.
+
+One line per item, ``file:line`` first, so the text is cheap for an agent to read and
+easy to grep. Every answer that describes the index starts with a header saying when it
+was built and whether files changed since. Caveats are prefixed with ``!``. JSON output
+does not go through here; it is ``contract.serialize.to_json``.
+
+This module imports only the contract and the shared vocabulary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import assert_never
+
+from compass_core.contract.errors import ErrorResponse
+from compass_core.contract.models import Caveat, IndexStatus, ResultItem, SymbolRef, Via
+from compass_core.contract.results import (
+    AmbiguousReference,
+    ImpactResult,
+    NodeDetail,
+    OverviewResult,
+    RankedSymbol,
+    SearchHit,
+    SearchResult,
+    SymbolNotFound,
+)
+from compass_core.contract.types import SearchMatch, ViaKind
+from compass_core.shared_types import SymbolKind
+
+_INDENT = "  "
+_ID_SEPARATOR = "::"
+"""Splits a public id into its file part and its ``[Class.]name`` part."""
+
+
+def location(symbol: SymbolRef) -> str:
+    """Where a symbol is: ``path:line`` for a definition, ``path`` for a file.
+
+    Args:
+        symbol: Any symbol.
+
+    Returns:
+        The 1-indexed location, or the external reference for an external function.
+
+    Example:
+        ``location(<User.save at app/models.py line 6>)`` returns ``"app/models.py:6"``.
+    """
+    if symbol.file_path is None:
+        return symbol.qualified_name
+    if symbol.line_start is None:
+        return symbol.file_path
+    return f"{symbol.file_path}:{symbol.line_start}"
+
+
+def local_name(symbol: SymbolRef) -> str:
+    """A symbol's name within its file: ``Class.method``, ``function`` or the file path.
+
+    Shorter than the qualified name; shown next to ``location``, which names the file.
+
+    Args:
+        symbol: Any symbol.
+
+    Returns:
+        The part of the public id after ``::`` for a class or function, the path for a
+        file, and the qualified name for an external function.
+
+    Example:
+        ``local_name(<User.save in app/models.py>)`` returns ``"User.save"``.
+    """
+    if symbol.kind is SymbolKind.FILE and symbol.file_path is not None:
+        return symbol.file_path
+    if symbol.kind in (SymbolKind.FILE, SymbolKind.EXTERNAL):
+        return symbol.qualified_name
+    _, separator, name = symbol.id.partition(_ID_SEPARATOR)
+    return name if separator else symbol.name
+
+
+def _span(symbol: SymbolRef) -> str:
+    start, end = symbol.line_start, symbol.line_end
+    if symbol.file_path and start and end and end != start:
+        return f"{symbol.file_path}:{start}-{end}"
+    return location(symbol)
+
+
+def _symbol(symbol: SymbolRef, *extra: str) -> str:
+    """``location  kind  qualified_name  [extra ...]`` on one line."""
+    parts = [location(symbol), symbol.kind.value, symbol.qualified_name, *extra]
+    return _INDENT.join(part for part in parts if part)
+
+
+def plural(count: int, noun: str) -> str:
+    """``count`` and ``noun``, pluralised.
+
+    Args:
+        count: How many.
+        noun: The singular noun.
+
+    Returns:
+        The phrase.
+
+    Example:
+        ``plural(3, "class")`` returns ``"3 classes"``.
+    """
+    if count == 1:
+        return f"{count} {noun}"
+    return f"{count} {noun}es" if noun.endswith("s") else f"{count} {noun}s"
+
+
+def render_status(status: IndexStatus) -> str:
+    """One header line describing the index.
+
+    Args:
+        status: The index status every result carries.
+
+    Returns:
+        The commit, build time and freshness of the index.
+
+    Example:
+        ``index: a1b2c3d · built 2026-11-10 09:14 UTC · 2 files changed since; run
+        `compass ingest```
+    """
+    commit = status.indexed_commit[:7] if status.indexed_commit else "no git commit"
+    built = status.indexed_at.strftime("%Y-%m-%d %H:%M UTC")
+    stale = status.stale_file_count
+    fresh = (
+        f"{plural(stale, 'file')} changed since; run `compass ingest`" if stale else "up to date"
+    )
+    return f"index: {commit} · built {built} · {fresh}"
+
+
+def _caveats(caveats: Iterable[Caveat]) -> list[str]:
+    return [f"! {caveat.message}" for caveat in caveats]
+
+
+def _more(shown: int, total: int) -> list[str]:
+    hidden = total - shown
+    return [f"… {hidden} more; raise the limit to see them"] if hidden > 0 else []
+
+
+def match_reason(hit: SearchHit) -> str:
+    """Why a search hit matched, with its fan-in for files and functions.
+
+    Args:
+        hit: A search hit.
+
+    Returns:
+        The reason.
+
+    Example:
+        ``"exact name · 1 caller"``.
+    """
+    match hit.match:
+        case SearchMatch.EXACT:
+            reason = "exact name"
+        case SearchMatch.QUALIFIED_SUFFIX:
+            reason = "qualified name"
+        case SearchMatch.PREFIX:
+            reason = "name prefix"
+        case SearchMatch.SUBSTRING:
+            reason = "name contains"
+        case _:
+            assert_never(hit.match)
+    if hit.symbol.kind is SymbolKind.FILE:
+        return f"{reason} · {plural(hit.fan_in, 'importer')}"
+    if hit.symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
+        return f"{reason} · {plural(hit.fan_in, 'caller')}"
+    return reason
+
+
+def render_search(result: SearchResult) -> str:
+    """Search hits, best first, each with why it matched.
+
+    Args:
+        result: A search result.
+
+    Returns:
+        The text.
+
+    Example:
+        A search for ``save`` renders ``app/models.py:2  method  app.models.Base.save  exact
+        name · 1 caller``.
+    """
+    lines = [
+        render_status(result.index),
+        f'search "{result.query}" · {plural(result.total, "hit")}',
+        *(_symbol(hit.symbol, match_reason(hit)) for hit in result.hits),
+        *_more(len(result.hits), result.total),
+        *_caveats(result.caveats),
+    ]
+    return "\n".join(lines)
+
+
+def _section(title: str, symbols: tuple[SymbolRef, ...]) -> list[str]:
+    if not symbols:
+        return []
+    return ["", f"{title} ({len(symbols)}):", *(_INDENT + _symbol(s) for s in symbols)]
+
+
+def render_describe(detail: NodeDetail, *, include_source: bool = False) -> str:
+    """One symbol: where it is, its signature and docstring, and its neighbours.
+
+    Args:
+        detail: A describe result.
+        include_source: Also print the symbol's source text (off by default to keep the
+            answer short; the location says where to read it).
+
+    Returns:
+        The text.
+
+    Example:
+        Describing ``User.save`` renders ``method app.models.User.save  app/models.py:6-7``,
+        its id, signature and docstring, then ``callees (1):`` and its callee.
+    """
+    symbol = detail.symbol
+    lines = [
+        render_status(detail.index),
+        f"{symbol.kind.value} {symbol.qualified_name}  {_span(symbol)}",
+        f"id: {symbol.id}",
+    ]
+    if symbol.signature:
+        lines.append(symbol.signature)
+    if detail.docstring:
+        lines += ["", detail.docstring.strip()]
+    lines += _section("bases", detail.bases)
+    lines += _section("subclasses", detail.subclasses)
+    lines += _section("members", detail.members)
+    lines += _section("callers", detail.callers)
+    lines += _section("callees", detail.callees)
+    lines += _section("imports", detail.imports)
+    lines += _section("imported by", detail.imported_by)
+    if detail.truncated:
+        lines += ["", "! some lists were cut short; describe the related symbols directly"]
+    if include_source and symbol.source:
+        lines += ["", "source:", symbol.source.rstrip()]
+    lines += _caveats(detail.caveats)
+    return "\n".join(lines)
+
+
+def via_text(via: Via) -> str:
+    """How an affected symbol depends on the one before it.
+
+    Args:
+        via: The link.
+
+    Returns:
+        A verb and a name.
+
+    Example:
+        ``"calls decode_token"``.
+    """
+    match via.kind:
+        case ViaKind.CALLS:
+            verb = "calls"
+        case ViaKind.IMPORTS:
+            verb = "imports"
+        case ViaKind.INHERITS:
+            verb = "inherits"
+        case _:
+            assert_never(via.kind)
+    return f"{verb} {via.symbol.name}"
+
+
+def _impact_item(item: ResultItem) -> str:
+    via = via_text(item.via) if item.via else ""
+    confidence = "" if item.min_confidence is None else f"{item.min_confidence:.2f}"
+    return _INDENT + _symbol(item.symbol, via, confidence)
+
+
+def render_impact(result: ImpactResult) -> str:
+    """What may break if the target changes, nearest first.
+
+    Args:
+        result: An impact result.
+
+    Returns:
+        The text: the target, a summary, the affected items grouped by distance, and
+        caveats (an empty answer is never shown as certain).
+
+    Example:
+        ``impact of function app.auth.decode_token (app/auth.py:3) · depth 3`` then
+        ``distance 1`` and ``app/api.py:4  function  app.api.handle  calls decode_token
+        1.00``.
+    """
+    target = result.target
+    shown = sum(len(group.items) for group in result.groups)
+    lines = [
+        render_status(result.index),
+        f"impact of {target.kind.value} {target.qualified_name} ({location(target)})"
+        f" · depth {result.depth}",
+        f"{plural(result.total, 'affected symbol')} in "
+        f"{plural(result.affected_file_count, 'file')}",
+    ]
+    distance = None
+    for group in result.groups:
+        if group.distance != distance:
+            distance = group.distance
+            lines.append(f"distance {distance}")
+        lines += [_impact_item(item) for item in group.items]
+    lines += _more(shown, result.total)
+    lines += _caveats(result.caveats)
+    return "\n".join(lines)
+
+
+def _ranked(title: str, ranked: tuple[RankedSymbol, ...], unit: str) -> list[str]:
+    if not ranked:
+        return []
+    return [
+        "",
+        f"{title}:",
+        *(_INDENT + _symbol(r.symbol, plural(r.count, unit)) for r in ranked),
+    ]
+
+
+def render_overview(result: OverviewResult) -> str:
+    """The shape of the repository: totals, entry points and hot spots.
+
+    Args:
+        result: An overview result.
+
+    Returns:
+        The text.
+
+    Example:
+        ``8 files · 3 classes · 15 functions`` then ``calls resolved: 12 of 40 (30%)`` and
+        the ranked lists.
+    """
+    counts = result.counts
+    edges = " · ".join(f"{edge.value} {n}" for edge, n in counts.edges_by_type.items())
+    resolution = result.call_resolution
+    percent = round(100 * resolution.resolved / resolution.total) if resolution.total else 0
+    lines = [
+        render_status(result.index),
+        f"{plural(counts.files, 'file')} · {plural(counts.classes, 'class')} · "
+        f"{plural(counts.functions, 'function')}",
+        f"edges: {edges}",
+        f"calls resolved: {resolution.resolved} of {resolution.total} ({percent}%)",
+    ]
+    lines += _section("entry points", result.entry_points)
+    lines += _ranked("most imported files", result.most_imported_files, "importer")
+    lines += _ranked("most called functions", result.most_called_functions, "caller")
+    lines += _ranked("riskiest to change", result.riskiest_to_change, "affected symbol")
+    if result.top_external_libraries:
+        lines += ["", "top external libraries:"]
+        lines += [
+            f"{_INDENT}{lib.library}  {plural(lib.call_count, 'call')}"
+            for lib in result.top_external_libraries
+        ]
+    lines += _caveats(result.caveats)
+    return "\n".join(lines)
+
+
+def render_ambiguous(result: AmbiguousReference) -> str:
+    """The candidates of an ambiguous reference, with how to pick one.
+
+    Args:
+        result: An ambiguous outcome.
+
+    Returns:
+        The text; each candidate's id resolves exactly when passed back.
+
+    Example:
+        ``"save" matches 2 symbols; pass one of these ids or a qualified name:`` then
+        ``app/models.py::Base.save  method  app/models.py:2``.
+    """
+    lines = [
+        f'"{result.reference}" matches {len(result.candidates)} symbols; '
+        "pass one of these ids or a qualified name:",
+        *(_INDENT + _INDENT.join((c.id, c.kind.value, location(c))) for c in result.candidates),
+    ]
+    return "\n".join(lines)
+
+
+def render_not_found(result: SymbolNotFound) -> str:
+    """A reference that matched nothing, with close suggestions.
+
+    Args:
+        result: A not-found outcome.
+
+    Returns:
+        The text.
+
+    Example:
+        ``no symbol matches "sav"; similar names:`` then ``app/models.py::User.save
+        method  app/models.py:6``.
+    """
+    if not result.suggestions:
+        return f'no symbol matches "{result.reference}"; try `compass search`'
+    lines = [
+        f'no symbol matches "{result.reference}"; similar names:',
+        *(_INDENT + _INDENT.join((s.id, s.kind.value, location(s))) for s in result.suggestions),
+    ]
+    return "\n".join(lines)
+
+
+def render_error(error: ErrorResponse) -> str:
+    """A failure: its code and the sentence that says how to fix it.
+
+    Args:
+        error: The error envelope.
+
+    Returns:
+        ``error [CODE]: message``.
+
+    Example:
+        ``error [INDEX_NOT_FOUND]: No Compass index found from /repo. Run `compass
+        ingest`.``
+    """
+    return f"error [{error.code.value}]: {error.message}"

compass_core/settings.py

@@ -0,0 +1,61 @@
+import os
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+
+STAGE = os.environ.get("STAGE", None)
+
+
+class Settings(BaseSettings):
+    """Engine settings, read from the environment and ``.env``.
+
+    Adapters that need more settings (e.g. ``compass_server.settings.ServerSettings``)
+    subclass this so they share the same sources and ``STAGE`` handling.
+
+    Attributes:
+        LADYBUG_DB_PATH: Explicit path to the graph database; when it does not exist,
+            the index is found by walking up from the working directory.
+        REPO_ROOT: Root path of the repository being analysed.
+        QUERY_TIMEOUT_MS: Per-query timeout for graph queries, in milliseconds.
+
+    Example:
+        ``QUERY_TIMEOUT_MS=5000 compass ingest .`` gives
+        ``Settings().QUERY_TIMEOUT_MS == 5000``.
+    """
+
+    LADYBUG_DB_PATH: str = Field(
+        default=".compass/graph.ladybug", description="Path to the LadybugDB graph database file"
+    )
+    REPO_ROOT: Path = Field(
+        default=Path("."), description="Root path of the repository being analysed"
+    )
+
+    QUERY_TIMEOUT_MS: int = Field(
+        default=10_000, description="Per-query timeout in milliseconds for graph queries"
+    )
+
+    model_config = SettingsConfigDict(
+        validate_assignment=True,
+        case_sensitive=True,
+        env_file=f".env.{STAGE}" if STAGE else ".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        _settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        if os.environ.get("STAGE", "").lower() == "production":
+            return env_settings, init_settings, file_secret_settings
+
+        return env_settings, dotenv_settings, init_settings, file_secret_settings
+
+
+settings = Settings()