compass-code 0.1.0__py3-none-any.whl

compass_core/index/metadata.py

@@ -0,0 +1,107 @@
+"""Typed read/write of ``.compass/metadata.json``."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from compass_core.errors import IndexIncompatibleError
+from compass_core.shared_types import Language
+
+SCHEMA_VERSION = 2
+"""Graph schema written by this version of compass; indexes in any other version are
+rejected and must be rebuilt with ``compass ingest``.
+
+History: 1 stored internal ids (``py::app.models::User``); 2 stores public ids
+(``app/models.py::User``) and a ``qualified_name`` on classes and functions.
+"""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class IndexMetadata:
+    """Facts recorded about an index at ingest time.
+
+    Attributes:
+        indexed_commit: Git HEAD commit at ingest, or ``None`` if unknown.
+        indexed_at: Ingest time (timezone-aware).
+        schema_version: Metadata/index schema version; pre-v1 files count as 1.
+        grammar_versions: Installed grammar package version per language.
+
+    Example:
+        ``{"indexed_commit": "abc", "indexed_at": 1788431823, "grammar_versions":
+        {"python": "0.25.0"}}`` loads as ``IndexMetadata(indexed_commit="abc",
+        indexed_at=datetime(..., tzinfo=UTC), schema_version=2,
+        grammar_versions={Language.PYTHON: "0.25.0"})``.
+    """
+
+    indexed_commit: str | None
+    indexed_at: datetime
+    schema_version: int
+    grammar_versions: Mapping[Language, str]
+
+
+def save_metadata(path: Path, meta: IndexMetadata) -> None:
+    """Atomically write ``meta`` to ``path`` as JSON.
+
+    Args:
+        path: Destination ``metadata.json``; parent directories are created.
+        meta: Metadata to store. ``indexed_at`` is stored as epoch seconds.
+    """
+    payload = {
+        "schema_version": meta.schema_version,
+        "indexed_commit": meta.indexed_commit,
+        "indexed_at": int(meta.indexed_at.timestamp()),
+        "grammar_versions": {lang.value: v for lang, v in meta.grammar_versions.items()},
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def load_metadata(path: Path) -> IndexMetadata:
+    """Read metadata from ``path``.
+
+    Args:
+        path: Path to ``metadata.json``.
+
+    Returns:
+        The parsed metadata. A missing ``schema_version`` counts as 1.
+
+    Raises:
+        IndexIncompatibleError: If the file is unreadable, malformed, has an unknown
+            language, or its ``schema_version`` is not ``SCHEMA_VERSION``.
+    """
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        schema_version = raw.get("schema_version", 1)
+        if isinstance(schema_version, bool) or not isinstance(schema_version, int):
+            raise ValueError(f"invalid schema_version {schema_version!r}")
+        if schema_version != SCHEMA_VERSION:
+            raise IndexIncompatibleError(
+                f"The index at {path.parent} uses schema version {schema_version}; this "
+                f"compass reads version {SCHEMA_VERSION}. Run `compass ingest` to rebuild it."
+            )
+        indexed_at = raw["indexed_at"]
+        if isinstance(indexed_at, bool) or not isinstance(indexed_at, int | float):
+            raise ValueError(f"invalid indexed_at {indexed_at!r}")
+        commit = raw.get("indexed_commit")
+        return IndexMetadata(
+            indexed_commit=None if commit is None else str(commit),
+            indexed_at=datetime.fromtimestamp(indexed_at, UTC),
+            schema_version=schema_version,
+            grammar_versions={
+                Language(lang): str(v) for lang, v in raw.get("grammar_versions", {}).items()
+            },
+        )
+    except (OSError, KeyError, ValueError, TypeError, AttributeError, OverflowError) as exc:
+        # JSONDecodeError is a ValueError subclass.
+        raise IndexIncompatibleError(f"Unreadable index metadata at {path}: {exc}") from exc

compass_core/ir/graph.py

@@ -0,0 +1,65 @@
+"""Resolved call/import/inheritance graph — Phase 3 output, Phase 5 input.
+
+Edge shapes are kept as four distinct dataclasses (not collapsed into one
+generic Edge type) because call_resolver's 10 prioritized resolution rules
+carry different fields per edge kind (external edges have no callee_id,
+only a full_ref + library) and collapsing would lose that without gaining
+anything — this mirrors resolver/models.py exactly, just relocated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from compass_core.ir.models import ParsedFile
+from compass_core.shared_types import CallType, UnlinkedCall
+
+CONFIDENCE: dict[CallType | UnlinkedCall, float] = {
+    CallType.DIRECT_IMPORT: 1.0,
+    CallType.MODULE_ATTR: 0.9,
+    CallType.RE_EXPORT: 0.8,
+    CallType.MRO: 0.8,
+    UnlinkedCall.WILDCARD: 0.6,
+    UnlinkedCall.DYNAMIC: 0.0,
+    UnlinkedCall.CIRCULAR: 0.0,
+    UnlinkedCall.EXTERNAL: 0.0,
+    UnlinkedCall.UNRESOLVED: 0.0,
+}
+
+
+@dataclass(slots=True)
+class CallEdge:
+    caller_id: str
+    callee_id: str
+    call_type: CallType
+    confidence: float
+    line: int = 0
+
+
+@dataclass(slots=True)
+class ExternalCallEdge:
+    caller_id: str
+    full_ref: str
+    library: str
+    line: int = 0
+
+
+@dataclass(slots=True)
+class ImportEdge:
+    from_path: str
+    to_path: str
+
+
+@dataclass(slots=True)
+class InheritEdge:
+    child_id: str
+    parent_id: str
+
+
+@dataclass
+class ResolvedGraph:
+    files: list[ParsedFile] = field(default_factory=list)
+    call_edges: list[CallEdge] = field(default_factory=list)
+    external_call_edges: list[ExternalCallEdge] = field(default_factory=list)
+    import_edges: list[ImportEdge] = field(default_factory=list)
+    inherit_edges: list[InheritEdge] = field(default_factory=list)

compass_core/ir/models.py

@@ -0,0 +1,75 @@
+"""Language-agnostic IR — the seam below which no phase may know a specific language.
+
+Definition covers class/function/method (var/interface/struct are future
+kinds, added when a language that needs them is registered — do not add
+unused kinds speculatively).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from compass_core.shared_types import CallType, DefinitionKind, Language, UnlinkedCall
+
+
+@dataclass(slots=True)
+class Definition:
+    id: str  # namespaced, e.g. "py::pkg.mod::Foo" or "py::pkg.mod::Foo.bar"
+    kind: DefinitionKind
+    name: str
+    file_path: str
+    line_start: int
+    line_end: int
+    source: str
+    docstring: str | None
+    bases: list[str]  # populated for CLASS only
+    parent_id: str | None  # populated for METHOD only (id of owning CLASS Definition)
+    signature: str | None  # populated for FUNCTION/METHOD only
+    decorators: list[str]
+    raw_calls: list[str]  # populated for FUNCTION/METHOD only
+
+
+@dataclass(slots=True)
+class ImportStatement:
+    module: str
+    names: list[str]
+    alias: str | None
+    is_relative: bool
+    is_from: bool
+    line: int
+
+
+@dataclass(slots=True)
+class CallSite:
+    callee_name: str
+    receiver_expr: str | None
+    line: int
+    enclosing_definition_id: str | None
+
+
+@dataclass
+class ParsedFile:
+    path: str
+    language: Language
+    module_name: str
+    content_hash: str
+    definitions: list[Definition]
+    imports: list[ImportStatement]
+    call_sites: list[CallSite]
+    degraded: bool = False
+    error: str | None = None  # human-readable reason when degraded=True
+
+
+@dataclass(slots=True)
+class CallResult:
+    """Outcome of resolving one raw call string (Phase 3 / resolution.py).
+
+    Relocated from resolver/call_resolver.py::CallResult, same shape, since
+    it's a shared IR-adjacent type this phase produces internally.
+    """
+
+    raw: str
+    target_id: str | None  # Definition.id if resolved internally
+    call_type: CallType | UnlinkedCall
+    confidence: float
+    external_library: str | None = None  # set only for EXTERNAL calls

compass_core/languages/__init__.py

@@ -0,0 +1 @@
+from compass_core.languages import python as _python  # noqa: F401

compass_core/languages/base.py

@@ -0,0 +1,26 @@
+"""Plugin contracts. Every language extractor/import resolver must satisfy
+these Protocols — enforced by mypy --strict in CI (Task 16), not just at
+review time."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from compass_core.ir.models import ParsedFile
+from compass_core.shared_types import Language
+
+
+@runtime_checkable
+class LanguageExtractor(Protocol):
+    language_id: Language
+    file_extensions: set[str]
+
+    def parse(self, source: bytes, file_path: Path) -> ParsedFile: ...
+
+
+@runtime_checkable
+class ImportResolver(Protocol):
+    language_id: Language
+
+    def resolve(self, files: list[ParsedFile]) -> dict[str, dict[str, str | None]]: ...

compass_core/languages/python/__init__.py

@@ -0,0 +1,6 @@
+from compass_core.languages import registry
+from compass_core.languages.python.extractor import PythonExtractor
+from compass_core.languages.python.import_resolver import PythonImportResolver
+
+registry.register_extractor(PythonExtractor())
+registry.register_import_resolver(PythonImportResolver())