compass-code 0.1.0__py3-none-any.whl

compass_core/contract/results.py

@@ -0,0 +1,370 @@
+"""Result types returned by query operations.
+
+Every successful result inherits ``ResultHeader`` so adapters read ``index`` and
+``caveats`` flat. ``operation`` plus ``outcome`` form a discriminated union.
+Reference outcomes (ambiguous / not found) are values, not exceptions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal, TypeAlias, TypeVar
+
+from compass_core.contract.models import Caveat, EdgeRef, IndexStatus, ResultItem, SymbolRef
+from compass_core.contract.types import (
+    MatchRule,
+    Operation,
+    Outcome,
+    RepoPath,
+    SearchMatch,
+    SymbolId,
+)
+from compass_core.shared_types import EdgeType, SymbolKind
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResultHeader:
+    """Fields common to every successful result.
+
+    Attributes:
+        outcome: Always ``Outcome.OK`` for a successful result.
+        index: Status of the index that produced the answer.
+        caveats: Reasons the answer may be incomplete.
+
+    Example:
+        Subclasses are built as ``SearchResult(index=status, caveats=(), ...)``.
+    """
+
+    outcome: Literal[Outcome.OK] = Outcome.OK
+    index: IndexStatus
+    caveats: tuple[Caveat, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SearchHit:
+    """One search match.
+
+    Attributes:
+        symbol: The matching symbol.
+        match: How it matched the query.
+        fan_in: Number of incoming edges, used for ranking.
+
+    Example:
+        ``SearchHit(symbol=<f>, match=SearchMatch.EXACT, fan_in=2)``
+    """
+
+    symbol: SymbolRef
+    match: SearchMatch
+    fan_in: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SearchResult(ResultHeader):
+    """Result of a symbol search.
+
+    Attributes:
+        operation: Always ``Operation.FIND``.
+        query: The search text.
+        kind: Kind filter that was applied, if any.
+        hits: Matching symbols, best first.
+        total: Number of matches before truncation.
+        truncated: Whether ``hits`` was cut at the limit.
+
+    Example:
+        ``find "write"`` yields ``SearchResult(query="write", hits=(...), total=3,
+        truncated=False, ...)``.
+    """
+
+    operation: Literal[Operation.FIND] = Operation.FIND
+    query: str
+    kind: SymbolKind | None
+    hits: tuple[SearchHit, ...]
+    total: int
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ImpactGroup:
+    """Affected symbols at one distance within one file.
+
+    Attributes:
+        distance: Hops from the target.
+        file_path: Repo-relative path of the file holding the items.
+        items: Affected symbols in that file at that distance.
+
+    Example:
+        ``ImpactGroup(distance=1, file_path=RepoPath("a.py"), items=(<item>,))``
+    """
+
+    distance: int
+    file_path: RepoPath
+    items: tuple[ResultItem, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ImpactResult(ResultHeader):
+    """Result of an impact analysis.
+
+    Attributes:
+        operation: Always ``Operation.IMPACT``.
+        target: The analysed file or symbol.
+        matched_by: Resolution rule that matched the reference.
+        depth: Depth that was traversed.
+        groups: Affected symbols grouped by distance and file.
+        affected_file_count: Number of distinct affected files.
+        edges: Edges connecting the affected symbols.
+        total: Number of affected symbols before truncation.
+        truncated: Whether the output was cut at the limit.
+
+    Example:
+        ``impact write`` yields ``ImpactResult(target=<write>, depth=3,
+        groups=(ImpactGroup(...),), affected_file_count=6, total=14, ...)``.
+    """
+
+    operation: Literal[Operation.IMPACT] = Operation.IMPACT
+    target: SymbolRef
+    matched_by: MatchRule
+    depth: int
+    groups: tuple[ImpactGroup, ...]
+    affected_file_count: int
+    edges: tuple[EdgeRef, ...]
+    total: int
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RankedSymbol:
+    """A symbol with a count used for ranking.
+
+    Attributes:
+        symbol: The symbol.
+        count: Ranking count (callers, importers, or affected symbols).
+
+    Example:
+        ``RankedSymbol(symbol=<write>, count=14)``
+    """
+
+    symbol: SymbolRef
+    count: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LibraryUsage:
+    """How heavily an external library is called.
+
+    Attributes:
+        library: Library name, e.g. ``"pydantic"``.
+        call_count: Number of call sites into the library.
+
+    Example:
+        ``LibraryUsage(library="pydantic", call_count=12)``
+    """
+
+    library: str
+    call_count: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class IndexCounts:
+    """Node and edge totals of the index.
+
+    Attributes:
+        files: Number of file nodes.
+        classes: Number of class nodes.
+        functions: Number of function and method nodes.
+        edges_by_type: Edge count per edge type.
+
+    Example:
+        ``IndexCounts(files=10, classes=2, functions=40,
+        edges_by_type={EdgeType.CALLS: 55})``
+    """
+
+    files: int
+    classes: int
+    functions: int
+    edges_by_type: Mapping[EdgeType, int]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallResolution:
+    """How many call sites in the index were tied to a definition.
+
+    Attributes:
+        total: Call sites recorded in function and method bodies.
+        resolved: Call sites whose called name matches a function the caller has a
+            ``CALLS`` or ``CALLS_EXTERN`` edge to.
+
+    Example:
+        ``CallResolution(total=193, resolved=171)`` means 22 calls are unresolved.
+    """
+
+    total: int
+    resolved: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OverviewResult(ResultHeader):
+    """Repository overview.
+
+    Attributes:
+        operation: Always ``Operation.OVERVIEW``.
+        counts: Node and edge totals.
+        call_resolution: Share of call sites the indexer resolved.
+        entry_points: Symbols that are entry points.
+        most_imported_files: Files ranked by number of importers.
+        most_called_functions: Functions ranked by number of callers.
+        riskiest_to_change: Symbols ranked by number of affected symbols.
+        top_external_libraries: External libraries ranked by call count.
+
+    Example:
+        ``OverviewResult(counts=IndexCounts(...), entry_points=(), ...,
+        riskiest_to_change=(RankedSymbol(symbol=<write>, count=14),), ...)``
+    """
+
+    operation: Literal[Operation.OVERVIEW] = Operation.OVERVIEW
+    counts: IndexCounts
+    call_resolution: CallResolution
+    entry_points: tuple[SymbolRef, ...]
+    most_imported_files: tuple[RankedSymbol, ...]
+    most_called_functions: tuple[RankedSymbol, ...]
+    riskiest_to_change: tuple[RankedSymbol, ...]
+    top_external_libraries: tuple[LibraryUsage, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class NodeDetail(ResultHeader):
+    """Everything known about one node, for a details panel.
+
+    Only the relationships that apply to the node's kind are filled; the rest are empty.
+
+    Attributes:
+        operation: Always ``Operation.DESCRIBE``.
+        symbol: The node; ``symbol.source`` holds its source text for classes and functions.
+        docstring: Extracted docstring, or ``None`` when there is none.
+        bases: Classes this class inherits from, within the repository.
+        subclasses: Classes that inherit from this class.
+        members: Methods of a class, or the classes and functions a file defines.
+        callees: Functions this function calls.
+        callers: Functions that call this function.
+        imports: Files this file imports.
+        imported_by: Files that import this file.
+        truncated: Whether any relationship was cut at the per-relationship limit.
+
+    Example:
+        ``describe(db, loc, "app/auth.py::Policy")`` yields ``NodeDetail(symbol=<Policy>,
+        docstring="Declarative mapping...", bases=(), subclasses=(), members=(<Policy.allows>,),
+        ...)``.
+    """
+
+    operation: Literal[Operation.DESCRIBE] = Operation.DESCRIBE
+    symbol: SymbolRef
+    docstring: str | None
+    bases: tuple[SymbolRef, ...]
+    subclasses: tuple[SymbolRef, ...]
+    members: tuple[SymbolRef, ...]
+    callees: tuple[SymbolRef, ...]
+    callers: tuple[SymbolRef, ...]
+    imports: tuple[SymbolRef, ...]
+    imported_by: tuple[SymbolRef, ...]
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AmbiguousReference:
+    """A reference that matched several symbols.
+
+    Attributes:
+        outcome: Always ``Outcome.AMBIGUOUS``.
+        reference: What the user typed.
+        candidates: At least two matches, ordered by rule then fan-in.
+
+    Example:
+        ``AmbiguousReference(reference="run", candidates=(<a.run>, <b.run>))``
+    """
+
+    outcome: Literal[Outcome.AMBIGUOUS] = Outcome.AMBIGUOUS
+    reference: str
+    candidates: tuple[SymbolRef, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SymbolNotFound:
+    """A reference that matched nothing.
+
+    Attributes:
+        outcome: Always ``Outcome.NOT_FOUND``.
+        reference: What the user typed.
+        suggestions: Up to five case-insensitive substring matches.
+
+    Example:
+        ``SymbolNotFound(reference="wrte", suggestions=(<write>,))``
+    """
+
+    outcome: Literal[Outcome.NOT_FOUND] = Outcome.NOT_FOUND
+    reference: str
+    suggestions: tuple[SymbolRef, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MapNode:
+    """One file, class, function or method in the map.
+
+    Attributes:
+        id: What ``MapEdge.source`` and ``MapEdge.target`` refer to: the public id of a
+            class or function, the path of a file.
+        label: Short display name.
+        kind: Kind of node; never ``EXTERNAL``.
+        file_path: Repo-relative path.
+        public_id: Public id, accepted wherever a query takes a reference.
+
+    Example:
+        ``def f(): ...`` in ``a.py`` becomes ``MapNode(id="a.py::f", label="f",
+        kind=SymbolKind.FUNCTION, file_path="a.py", public_id=SymbolId("a.py::f"))``.
+    """
+
+    id: str
+    label: str
+    kind: SymbolKind
+    file_path: str
+    public_id: SymbolId
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MapEdge:
+    """One relationship between two ``MapNode`` values.
+
+    Attributes:
+        source: ``MapNode.id`` the edge leaves.
+        target: ``MapNode.id`` the edge enters.
+        type: Kind of edge; never ``CALLS_EXTERN``, whose targets are not in the map.
+
+    Example:
+        ``a.py`` importing ``b.py`` becomes ``MapEdge(source="a.py", target="b.py",
+        type=EdgeType.IMPORTS)``.
+    """
+
+    source: str
+    target: str
+    type: EdgeType
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GraphMap:
+    """Every indexed node and the deduplicated edges between them.
+
+    Attributes:
+        nodes: Files, then classes, then functions and methods.
+        edges: Distinct ``(source, target, type)`` edges, grouped by type.
+
+    Example:
+        A repo with one file holding one function has two nodes and one ``CONTAINS``
+        edge.
+    """
+
+    nodes: tuple[MapNode, ...]
+    edges: tuple[MapEdge, ...]
+
+
+R = TypeVar("R")
+Lookup: TypeAlias = R | AmbiguousReference | SymbolNotFound

compass_core/contract/serialize.py

@@ -0,0 +1,59 @@
+"""JSON serialization of query results via cached Pydantic ``TypeAdapter``s.
+
+Models stay plain dataclasses; Pydantic is used only here, at the adapter edge.
+Enums serialize as their value, ``datetime`` as ISO-8601, ``Path`` as a string and
+tuples / frozensets as arrays.
+"""
+
+from __future__ import annotations
+
+from pydantic import TypeAdapter
+
+from compass_core.contract.errors import ErrorResponse
+from compass_core.contract.models import IndexStatus
+from compass_core.contract.results import (
+    AmbiguousReference,
+    ImpactResult,
+    NodeDetail,
+    OverviewResult,
+    SearchResult,
+    SymbolNotFound,
+)
+
+Serializable = (
+    SearchResult
+    | ImpactResult
+    | OverviewResult
+    | NodeDetail
+    | AmbiguousReference
+    | SymbolNotFound
+    | IndexStatus
+    | ErrorResponse
+)
+
+
+_ADAPTERS: dict[type[object], TypeAdapter[object]] = {}
+
+
+def _adapter_for(obj: Serializable) -> TypeAdapter[object]:
+    tp: type[object] = type(obj)
+    adapter = _ADAPTERS.get(tp)
+    if adapter is None:
+        adapter = _ADAPTERS[tp] = TypeAdapter(tp)
+    return adapter
+
+
+def to_json(obj: Serializable) -> str:
+    """Serialize a query result, reference outcome or error envelope to JSON.
+
+    Args:
+        obj: The value to serialize.
+
+    Returns:
+        A compact JSON string.
+
+    Example:
+        ``to_json(SymbolNotFound(reference="x", suggestions=()))`` returns
+        ``'{"outcome":"not_found","reference":"x","suggestions":[]}'``.
+    """
+    return _adapter_for(obj).dump_json(obj).decode()

compass_core/contract/types.py

@@ -0,0 +1,76 @@
+"""Closed vocabularies and identifier types of the query contract.
+
+Enums are ``StrEnum`` so they serialize as their string value. Identifiers are
+``NewType`` over ``str`` so a file path cannot be passed where a symbol id is expected.
+Vocabulary shared with parsing and persistence lives in ``compass_core/shared_types.py``.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import NewType
+
+SymbolId = NewType("SymbolId", str)
+"""Public node id, e.g. ``"packages/core/src/compass_core/graph/writer.py::write"``."""
+
+RepoPath = NewType("RepoPath", str)
+"""Repo-relative POSIX path, e.g. ``"packages/core/src/compass_core/graph/writer.py"``."""
+
+QualifiedName = NewType("QualifiedName", str)
+"""Dotted qualified name, e.g. ``"compass_core.graph.writer.write"``."""
+
+
+class ViaKind(StrEnum):
+    """Relationship through which an impact item was reached from the item before it.
+
+    Only values the query layer produces are listed; add one with the operation that
+    produces it.
+    """
+
+    CALLS = "CALLS"
+    IMPORTS = "IMPORTS"
+    INHERITS = "INHERITS"
+
+
+class MatchRule(StrEnum):
+    """Symbol resolution rules, in the order they are tried."""
+
+    EXACT_ID = "EXACT_ID"
+    FILE_PATH = "FILE_PATH"
+    QUALIFIED_NAME = "QUALIFIED_NAME"
+    PATH_AND_NAME = "PATH_AND_NAME"
+    CLASS_MEMBER = "CLASS_MEMBER"
+    BARE_NAME = "BARE_NAME"
+
+
+class SearchMatch(StrEnum):
+    """How a search hit matched the query."""
+
+    EXACT = "EXACT"
+    QUALIFIED_SUFFIX = "QUALIFIED_SUFFIX"
+    PREFIX = "PREFIX"
+    SUBSTRING = "SUBSTRING"
+
+
+class Operation(StrEnum):
+    """Query operations that return a ``ResultHeader`` result (the JSON discriminator)."""
+
+    FIND = "FIND"
+    DESCRIBE = "DESCRIBE"
+    IMPACT = "IMPACT"
+    OVERVIEW = "OVERVIEW"
+
+
+class Outcome(StrEnum):
+    """JSON discriminator for a query result."""
+
+    OK = "ok"
+    AMBIGUOUS = "ambiguous"
+    NOT_FOUND = "not_found"
+
+
+class CaveatCode(StrEnum):
+    """Reasons an answer may be incomplete; only codes the query layer emits."""
+
+    STALE_INDEX = "STALE_INDEX"
+    UNRESOLVED_CALLS = "UNRESOLVED_CALLS"

compass_core/errors.py

@@ -0,0 +1,148 @@
+"""Exception hierarchy for compass_core.
+
+Reserved for genuinely unexpected/unrecoverable failures (DB connection
+lost, malformed grammar binary, config missing) that propagate up to
+phases/pipeline.py and are caught once at the top level. Expected failures
+(an unresolved call site, a degraded parse) are modeled as typed result
+objects elsewhere, never raised as one of these.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+from typing import ClassVar
+
+
+class CompassError(Exception):
+    """Base exception for compass_core. Carries enough context to debug without re-running."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        file_path: str | None = None,
+        language: str | None = None,
+        phase_name: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.file_path = file_path
+        self.language = language
+        self.phase_name = phase_name
+
+
+class DiscoveryError(CompassError):
+    """Phase 0 failure — repo walk or manifest construction failed unrecoverably."""
+
+
+class ParseError(CompassError):
+    """Phase 1 failure. Only raised for unrecoverable extractor setup failures
+    (e.g. grammar binary missing) — per-file parse failures are captured as a
+    `degraded` flag on ParsedFile, not raised."""
+
+
+class UnsupportedLanguageError(ParseError):
+    """Raised by languages/registry.py when no extractor is registered for a file's language."""
+
+
+class ResolutionError(CompassError):
+    """Phase 3 failure — unrecoverable failure building the symbol table or resolving edges."""
+
+
+class ValidationError(CompassError):
+    """Phase 4 failure — the ingest run failed a regression gate check."""
+
+
+class PersistenceError(CompassError):
+    """Phase 5 failure — DB connection lost or write failed unrecoverably mid-batch."""
+
+
+class ErrorCode(StrEnum):
+    """Machine-readable failure codes shared by the API, CLI and MCP adapters."""
+
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    NOT_FOUND = "NOT_FOUND"
+    AMBIGUOUS = "AMBIGUOUS"
+    INDEX_NOT_FOUND = "INDEX_NOT_FOUND"
+    INDEX_BUSY = "INDEX_BUSY"
+    INDEX_INCOMPATIBLE = "INDEX_INCOMPATIBLE"
+    QUERY_TIMEOUT = "QUERY_TIMEOUT"
+    INTERNAL = "INTERNAL"
+
+
+class QueryError(CompassError):
+    """Base class for failures raised by the query layer.
+
+    Attributes:
+        code: Machine-readable failure code; every direct subclass declares a
+            distinct value.
+    """
+
+    code: ClassVar[ErrorCode] = ErrorCode.INTERNAL
+
+
+class InvalidArgumentError(QueryError):
+    """A caller-supplied argument was missing, malformed or out of range.
+
+    Attributes:
+        argument: Name of the offending argument.
+        reason: Human-readable explanation of why it was rejected.
+
+    Example:
+        >>> InvalidArgumentError(argument="depth", reason="must be between 1 and 10")
+    """
+
+    code: ClassVar[ErrorCode] = ErrorCode.INVALID_ARGUMENT
+
+    def __init__(self, *, argument: str, reason: str) -> None:
+        super().__init__(f"Invalid {argument}: {reason}")
+        self.argument = argument
+        self.reason = reason
+
+
+class IndexNotFoundError(QueryError):
+    """No ``.compass/graph.ladybug`` was found walking up from ``searched_from``.
+
+    Attributes:
+        searched_from: Directory the upward search started from.
+    """
+
+    code: ClassVar[ErrorCode] = ErrorCode.INDEX_NOT_FOUND
+
+    def __init__(self, *, searched_from: Path) -> None:
+        super().__init__(f"No Compass index found from {searched_from}. Run `compass ingest`.")
+        self.searched_from = searched_from
+
+
+class IndexBusyError(QueryError):
+    """The index is locked by another process (typically an ingest rebuild).
+
+    Attributes:
+        retry_after_s: Suggested number of seconds to wait before retrying.
+    """
+
+    code: ClassVar[ErrorCode] = ErrorCode.INDEX_BUSY
+
+    def __init__(self, *, retry_after_s: int) -> None:
+        super().__init__(f"The index is being rebuilt; retry in {retry_after_s}s.")
+        self.retry_after_s = retry_after_s
+
+
+class IndexIncompatibleError(QueryError):
+    """The index or its metadata is unreadable or from an unsupported version."""
+
+    code: ClassVar[ErrorCode] = ErrorCode.INDEX_INCOMPATIBLE
+
+
+class QueryTimeoutError(QueryError):
+    """A query ran longer than the configured timeout and was interrupted.
+
+    Attributes:
+        timeout_ms: The timeout, in milliseconds, that was exceeded.
+    """
+
+    code: ClassVar[ErrorCode] = ErrorCode.QUERY_TIMEOUT
+
+    def __init__(self, *, timeout_ms: int) -> None:
+        super().__init__(f"Query exceeded {timeout_ms} ms.")
+        self.timeout_ms = timeout_ms