compass-code 0.1.0__py3-none-any.whl

compass_core/progress.py

@@ -0,0 +1,45 @@
+"""Progress reporting protocol for pipeline phases.
+
+Core modules call ``reporter.update(phase, current, total)`` without any
+dependency on display libraries. The CLI layer provides a concrete
+``IngestReporter`` implementation (a live Rich table); tests can use a null
+or recording stub that satisfies the same protocol.
+
+Adding a new phase
+------------------
+1. Add its name to the ``Phase`` literal.
+2. Call ``reporter.update("<new_phase>", current, total)`` in the relevant
+   core module.
+3. Wire it up in ``compass_cli.progress.IngestReporter``.
+
+Nothing else needs to change.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol
+
+Phase = Literal[
+    "discovery",
+    "parse",
+    "symbol_table",
+    "resolution",
+    "validation",
+    "resolve",
+    "write_nodes",
+    "write_edges",
+]
+
+
+class ProgressReporter(Protocol):
+    """Minimal interface for reporting progress across pipeline phases."""
+
+    def update(self, phase: Phase, current: int, total: int) -> None:
+        """Report progress for a pipeline phase.
+
+        Args:
+            phase: The pipeline phase being reported (e.g. ``"parse"``).
+            current: Number of items completed so far.
+            total: Total number of items for this phase.
+        """
+        ...

compass_core/query/__init__.py

@@ -0,0 +1 @@
+"""Query-layer contract: typed vocabularies and result models."""

compass_core/query/cypher.py

@@ -0,0 +1,92 @@
+"""Typed Cypher queries: each statement lives next to the decoder for its rows.
+
+A ``Query`` is defined once, at module level, with its full Cypher text. Running it
+returns typed values instead of raw rows, so no caller indexes a row by position, and
+the ``$parameters`` a statement uses are checked against the ones supplied.
+
+User text only ever reaches Cypher as a ``$parameter``. Statements may be composed
+from the column lists in ``query/rows.py`` when the module is imported, never per call.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Generic, TypeVar
+
+from compass_core.graph.db import GraphDB, QueryParams, Row, as_rows
+
+T = TypeVar("T")
+
+_PARAMETER = re.compile(r"\$([A-Za-z_][A-Za-z0-9_]*)")
+
+
+@dataclass(frozen=True, slots=True)
+class Query(Generic[T]):
+    """A Cypher statement and the decoder for one of its result rows.
+
+    Attributes:
+        cypher: The full statement. User input appears only as ``$name`` parameters.
+        decode: Turns one result row into a typed value.
+        parameters: Names of the ``$parameters`` the statement uses, derived from
+            ``cypher``.
+
+    Example:
+        ``FILE_PATHS = Query("MATCH (f:File) RETURN f.path", lambda row: text_value(row[0],
+        "path"))`` makes ``FILE_PATHS.run(db)`` return ``["app/auth.py", ...]``.
+    """
+
+    cypher: str
+    decode: Callable[[Row], T]
+    parameters: frozenset[str] = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "parameters", frozenset(_PARAMETER.findall(self.cypher)))
+
+    def run(self, db: GraphDB, params: Mapping[str, object] | None = None) -> list[T]:
+        """Execute the statement and decode every row.
+
+        Args:
+            db: Open graph database.
+            params: A value for every ``$parameter`` of the statement, and nothing else.
+
+        Returns:
+            One decoded value per result row, in result order.
+
+        Raises:
+            ValueError: ``params`` does not name exactly the statement's parameters. This
+                is a bug in the query layer, never caused by user input.
+            IndexIncompatibleError: A row does not have the shape the decoder expects.
+
+        Example:
+            ``ENTRY_POINTS.run(db, {"limit": 5})`` returns up to five file symbols.
+        """
+        supplied: QueryParams = dict(params or {})
+        if supplied.keys() != self.parameters:
+            raise ValueError(
+                f"query expects parameters {sorted(self.parameters)}, got {sorted(supplied)}"
+            )
+        result = db.execute(self.cypher, supplied) if supplied else db.execute(self.cypher)
+        rows = as_rows(result)
+        return [self.decode(row) for row in rows]
+
+    def first(self, db: GraphDB, params: Mapping[str, object] | None = None) -> T | None:
+        """Like ``run`` but return only the first decoded row, or ``None`` when empty.
+
+        Args:
+            db: Open graph database.
+            params: A value for every ``$parameter`` of the statement, and nothing else.
+
+        Returns:
+            The first decoded value, or ``None`` if the statement returned no rows.
+
+        Raises:
+            ValueError: ``params`` does not name exactly the statement's parameters.
+            IndexIncompatibleError: The row does not have the shape the decoder expects.
+
+        Example:
+            ``FUNCTION_COUNT.first(db)`` returns ``412`` on a repo with 412 functions.
+        """
+        found = self.run(db, params)
+        return found[0] if found else None

compass_core/query/detail.py

@@ -0,0 +1,241 @@
+"""Node detail: everything the graph knows about one file, class, function or method.
+
+The reference is resolved with ``references.resolve`` (a public id such as
+``app/auth/permissions.py::Policy`` or ``file::app/auth/permissions.py`` resolves under the
+exact-id rule). The resolved symbol is then enriched with its docstring and source text and
+with the neighbours that make sense for its kind:
+
+* class: base classes, subclasses and methods;
+* function / method: callees and callers;
+* file: the classes and functions it defines, the files it imports and the files that import it,
+  and its text, read from the working tree (the index does not store file contents);
+* external: nothing beyond the symbol.
+
+User text only ever reaches Cypher as a ``$parameter``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+
+from compass_core.contract.models import SymbolRef
+from compass_core.contract.results import Lookup, NodeDetail
+from compass_core.graph.db import GraphDB, QueryParams, Row
+from compass_core.index.locate import IndexLocation
+from compass_core.query.cypher import Query
+from compass_core.query.references import ResolvedReference, resolve
+from compass_core.query.rows import (
+    CLASS_FIELDS,
+    FILE_FIELDS,
+    FUNCTION_FIELDS,
+    class_from_row,
+    columns,
+    file_from_row,
+    function_from_row,
+)
+from compass_core.query.status import index_status
+from compass_core.shared_types import SymbolKind
+
+MAX_FILE_BYTES = 512 * 1024
+"""Largest file whose text is returned; bigger files are described without source."""
+MAX_RELATED = 200
+"""Most neighbours returned per relationship; the result is flagged ``truncated`` past it."""
+
+
+def _is_definition(variable: str) -> str:
+    """``WHERE`` condition selecting the definition ``$id`` (a primary-key match).
+
+    Used only to compose the constants below, at import.
+    """
+    return f"{variable}.id = $id"
+
+
+def _text_pair(row: Row) -> tuple[str | None, str | None]:
+    return _text_or_none(row[0]), _text_or_none(row[1])
+
+
+_CLASS = columns("r", CLASS_FIELDS)
+_FUNCTION = columns("r", FUNCTION_FIELDS)
+
+_BASES: Query[SymbolRef] = Query(
+    f"MATCH (c:Class)-[:INHERITS]->(r:Class) WHERE {_is_definition('c')} RETURN DISTINCT {_CLASS}",
+    class_from_row,
+)
+_SUBCLASSES: Query[SymbolRef] = Query(
+    f"MATCH (r:Class)-[:INHERITS]->(c:Class) WHERE {_is_definition('c')} RETURN DISTINCT {_CLASS}",
+    class_from_row,
+)
+_METHODS: Query[SymbolRef] = Query(
+    f"MATCH (c:Class)-[:CONTAINS]->(r:Function) WHERE {_is_definition('c')} "
+    f"RETURN DISTINCT {_FUNCTION}",
+    function_from_row,
+)
+_CALLEES: Query[SymbolRef] = Query(
+    f"MATCH (f:Function)-[:CALLS]->(r:Function) WHERE {_is_definition('f')} "
+    f"RETURN DISTINCT {_FUNCTION}",
+    function_from_row,
+)
+_CALLERS: Query[SymbolRef] = Query(
+    f"MATCH (r:Function)-[:CALLS]->(f:Function) WHERE {_is_definition('f')} "
+    f"RETURN DISTINCT {_FUNCTION}",
+    function_from_row,
+)
+_FILE_CLASSES: Query[SymbolRef] = Query(
+    f"MATCH (f:File)-[:CONTAINS]->(r:Class) WHERE f.path = $path RETURN DISTINCT {_CLASS}",
+    class_from_row,
+)
+_FILE_FUNCTIONS: Query[SymbolRef] = Query(
+    f"MATCH (f:File)-[:CONTAINS]->(r:Function) WHERE f.path = $path RETURN DISTINCT {_FUNCTION}",
+    function_from_row,
+)
+_IMPORTS: Query[SymbolRef] = Query(
+    f"MATCH (f:File)-[:IMPORTS]->(r:File) WHERE f.path = $path "
+    f"RETURN DISTINCT {columns('r', FILE_FIELDS)}",
+    file_from_row,
+)
+_IMPORTED_BY: Query[SymbolRef] = Query(
+    f"MATCH (r:File)-[:IMPORTS]->(f:File) WHERE f.path = $path "
+    f"RETURN DISTINCT {columns('r', FILE_FIELDS)}",
+    file_from_row,
+)
+_CLASS_TEXT: Query[tuple[str | None, str | None]] = Query(
+    f"MATCH (n:Class) WHERE {_is_definition('n')} RETURN n.docstring, n.source",
+    _text_pair,
+)
+_FUNCTION_TEXT: Query[tuple[str | None, str | None]] = Query(
+    f"MATCH (n:Function) WHERE {_is_definition('n')} RETURN n.docstring, n.source",
+    _text_pair,
+)
+
+
+def _definition_params(symbol: SymbolRef) -> QueryParams:
+    return {"id": symbol.id}
+
+
+def _text_or_none(value: object) -> str | None:
+    """Docstring/source column: ``None`` or empty means absent."""
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _ordered(symbols: list[SymbolRef]) -> list[SymbolRef]:
+    """Stable display order: by file, line, then id."""
+    return sorted(symbols, key=lambda s: (s.file_path or "", s.line_start or 0, s.id))
+
+
+def _class_relations(
+    db: GraphDB, params: QueryParams
+) -> tuple[list[SymbolRef], list[SymbolRef], list[SymbolRef]]:
+    return (
+        _BASES.run(db, params),
+        _SUBCLASSES.run(db, params),
+        _METHODS.run(db, params),
+    )
+
+
+def _function_relations(
+    db: GraphDB, params: QueryParams
+) -> tuple[list[SymbolRef], list[SymbolRef]]:
+    return _CALLEES.run(db, params), _CALLERS.run(db, params)
+
+
+def _file_relations(
+    db: GraphDB, symbol: SymbolRef
+) -> tuple[list[SymbolRef], list[SymbolRef], list[SymbolRef]]:
+    params: QueryParams = {"path": symbol.file_path}
+    members = _FILE_CLASSES.run(db, params) + _FILE_FUNCTIONS.run(db, params)
+    return members, _IMPORTS.run(db, params), _IMPORTED_BY.run(db, params)
+
+
+def _cap(symbols: list[SymbolRef]) -> tuple[tuple[SymbolRef, ...], bool]:
+    ordered = _ordered(symbols)
+    return tuple(ordered[:MAX_RELATED]), len(ordered) > MAX_RELATED
+
+
+def _docstring_and_source(db: GraphDB, symbol: SymbolRef) -> tuple[str | None, str | None]:
+    if symbol.kind not in (SymbolKind.CLASS, SymbolKind.FUNCTION, SymbolKind.METHOD):
+        return None, None
+    query = _CLASS_TEXT if symbol.kind is SymbolKind.CLASS else _FUNCTION_TEXT
+    return query.first(db, _definition_params(symbol)) or (None, None)
+
+
+def _file_source(symbol: SymbolRef, root: Path) -> str | None:
+    """Text of a file under ``root``, or ``None`` if it is gone, unreadable, binary-sized or outside.
+
+    The text is what is on disk now, which can differ from what was indexed; the index status in
+    the result says whether files changed since.
+    """
+    if not symbol.file_path:
+        return None
+    path = (root / symbol.file_path).resolve()
+    try:
+        if (
+            not path.is_relative_to(root)
+            or not path.is_file()
+            or path.stat().st_size > MAX_FILE_BYTES
+        ):
+            return None
+        return _text_or_none(path.read_text(encoding="utf-8", errors="replace"))
+    except OSError:
+        return None
+
+
+def describe(db: GraphDB, location: IndexLocation, ref: str) -> Lookup[NodeDetail]:
+    """Describe one node of the graph.
+
+    Args:
+        db: Open graph database.
+        location: Index location, used to build the result's ``IndexStatus``.
+        ref: Reference to the node; a public id from the graph endpoint always resolves.
+
+    Returns:
+        A ``NodeDetail``; an ``AmbiguousReference`` or ``SymbolNotFound`` when ``ref`` does
+        not resolve to exactly one node.
+
+    Raises:
+        IndexIncompatibleError: A stored row or the index metadata is unreadable.
+
+    Example:
+        ``describe(db, loc, "app/models.py::User")`` returns a ``NodeDetail`` whose ``symbol``
+        has the class source, ``bases`` is empty and ``members`` lists ``User.save``.
+    """
+    status = index_status(location, db)  # first: rejects an incompatible index
+    root = location.repo_root.resolve()
+    resolved = resolve(db, ref, repo_root=root, allow_file=True)
+    if not isinstance(resolved, ResolvedReference):
+        return resolved
+
+    symbol = resolved.symbol
+    docstring, source = _docstring_and_source(db, symbol)
+    if symbol.kind is SymbolKind.FILE:
+        source = _file_source(symbol, root)
+    bases: list[SymbolRef] = []
+    subclasses: list[SymbolRef] = []
+    members: list[SymbolRef] = []
+    callees: list[SymbolRef] = []
+    callers: list[SymbolRef] = []
+    imports: list[SymbolRef] = []
+    imported_by: list[SymbolRef] = []
+
+    if symbol.kind is SymbolKind.CLASS:
+        bases, subclasses, members = _class_relations(db, _definition_params(symbol))
+    elif symbol.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD):
+        callees, callers = _function_relations(db, _definition_params(symbol))
+    elif symbol.kind is SymbolKind.FILE:
+        members, imports, imported_by = _file_relations(db, symbol)
+
+    capped = [_cap(x) for x in (bases, subclasses, members, callees, callers, imports, imported_by)]
+    return NodeDetail(
+        index=status,
+        caveats=(),
+        symbol=replace(symbol, source=source),
+        docstring=docstring,
+        bases=capped[0][0],
+        subclasses=capped[1][0],
+        members=capped[2][0],
+        callees=capped[3][0],
+        callers=capped[4][0],
+        imports=capped[5][0],
+        imported_by=capped[6][0],
+        truncated=any(truncated for _, truncated in capped),
+    )

compass_core/query/graph_map.py

@@ -0,0 +1,127 @@
+"""The whole graph as nodes and edges, for adapters that draw it.
+
+Unlike the other operations this returns no ``ResultHeader``: a map answers no question
+about the index, so it carries neither an ``IndexStatus`` nor caveats.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from compass_core.contract.results import GraphMap, MapEdge, MapNode
+from compass_core.contract.types import SymbolId
+from compass_core.graph.db import GraphDB, Row
+from compass_core.query.cypher import Query
+from compass_core.query.rows import (
+    is_method_flag,
+    public_file_id,
+    text_value,
+)
+from compass_core.shared_types import EdgeType, SymbolKind
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _StoredDefinition:
+    """A class or function as stored: id, name and path.
+
+    Attributes:
+        id: Public id.
+        name: Unqualified name.
+        kind: ``CLASS``, ``FUNCTION`` or ``METHOD``.
+        path: Stored ``file_path``.
+
+    Example:
+        ``class User`` in ``app/models.py`` gives ``_StoredDefinition(id="app/models.py::User",
+        name="User", kind=SymbolKind.CLASS, path="app/models.py")``.
+    """
+
+    id: str
+    name: str
+    kind: SymbolKind
+    path: str
+
+
+def _definition(row: Row, kind: SymbolKind) -> _StoredDefinition:
+    return _StoredDefinition(
+        id=text_value(row[0], "id"),
+        name=text_value(row[1], "name"),
+        kind=kind,
+        path=text_value(row[2], "file_path"),
+    )
+
+
+def _edge_query(cypher: str, edge_type: EdgeType) -> Query[MapEdge]:
+    return Query(
+        cypher,
+        lambda row: MapEdge(
+            source=text_value(row[0], "source"), target=text_value(row[1], "target"), type=edge_type
+        ),
+    )
+
+
+_FILE_PATHS: Query[str] = Query(
+    "MATCH (f:File) RETURN f.path", lambda row: text_value(row[0], "path")
+)
+_CLASSES: Query[_StoredDefinition] = Query(
+    "MATCH (c:Class) RETURN c.id, c.name, c.file_path",
+    lambda row: _definition(row, SymbolKind.CLASS),
+)
+_FUNCTIONS: Query[_StoredDefinition] = Query(
+    "MATCH (fn:Function) RETURN fn.id, fn.name, fn.file_path, fn.is_method",
+    lambda row: _definition(
+        row, SymbolKind.METHOD if is_method_flag(row[3]) else SymbolKind.FUNCTION
+    ),
+)
+_EDGES: tuple[Query[MapEdge], ...] = (
+    _edge_query("MATCH (a:File)-[:CONTAINS]->(b:Class) RETURN a.path, b.id", EdgeType.CONTAINS),
+    _edge_query("MATCH (a:File)-[:CONTAINS]->(b:Function) RETURN a.path, b.id", EdgeType.CONTAINS),
+    _edge_query("MATCH (a:Class)-[:CONTAINS]->(b:Function) RETURN a.id, b.id", EdgeType.CONTAINS),
+    _edge_query("MATCH (a:File)-[:IMPORTS]->(b:File) RETURN a.path, b.path", EdgeType.IMPORTS),
+    _edge_query("MATCH (a:Class)-[:INHERITS]->(b:Class) RETURN a.id, b.id", EdgeType.INHERITS),
+    _edge_query("MATCH (a:Function)-[:CALLS]->(b:Function) RETURN a.id, b.id", EdgeType.CALLS),
+)
+
+
+def _file_nodes(db: GraphDB) -> list[MapNode]:
+    return [
+        MapNode(
+            id=path,
+            label=path.split("/")[-1],
+            kind=SymbolKind.FILE,
+            file_path=path,
+            public_id=public_file_id(path),
+        )
+        for path in _FILE_PATHS.run(db)
+    ]
+
+
+def _definition_nodes(db: GraphDB) -> list[MapNode]:
+    return [
+        MapNode(id=d.id, label=d.name, kind=d.kind, file_path=d.path, public_id=SymbolId(d.id))
+        for d in (*_CLASSES.run(db), *_FUNCTIONS.run(db))
+    ]
+
+
+def _edges(db: GraphDB) -> tuple[MapEdge, ...]:
+    edges = (edge for query in _EDGES for edge in query.run(db))
+    return tuple(dict.fromkeys(edges))
+
+
+def graph_map(db: GraphDB) -> GraphMap:
+    """Read every node and edge of an index.
+
+    Args:
+        db: Open, read-only graph database.
+
+    Returns:
+        The map: files, then classes, then functions and methods, and the distinct
+        edges between them.
+
+    Raises:
+        IndexIncompatibleError: A stored column has an unexpected type.
+
+    Example:
+        ``graph_map(db).nodes[0].public_id`` is ``"file::app/auth.py"`` when
+        ``app/auth.py`` is the first indexed file.
+    """
+    return GraphMap(nodes=(*_file_nodes(db), *_definition_nodes(db)), edges=_edges(db))