compass-code 0.1.0__py3-none-any.whl

compass_core/query/rows.py

@@ -0,0 +1,378 @@
+"""Map raw graph rows to public query models.
+
+This is, with ``graph/db.py``, the only module allowed to touch untyped (``Any``)
+driver values. Every column is validated here so the rest of the query layer works
+with typed models, and a schema mismatch surfaces as ``IndexIncompatibleError``.
+
+The graph stores exactly what the public models carry: class and function ids are
+public ids (``app/models.py::User.save``), ``file_path`` values are repo-relative POSIX
+paths, and ``qualified_name`` is stored (``app.models.User.save``). Files and external
+functions get their public ids here: ``file::<path>`` and ``ext::<full_ref>``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import PurePosixPath
+from typing import Any
+
+from compass_core.contract.models import SymbolRef
+from compass_core.contract.types import QualifiedName, RepoPath, SymbolId
+from compass_core.errors import IndexIncompatibleError
+from compass_core.shared_types import CallType, SymbolKind
+
+_SEP = "::"
+_CONFIDENCE_DIGITS = 6
+
+FUNCTION_FIELDS = (
+    "id",
+    "name",
+    "qualified_name",
+    "file_path",
+    "line_start",
+    "line_end",
+    "signature",
+    "is_method",
+)
+"""``Function`` properties read by ``function_from_row``, in column order."""
+CLASS_FIELDS = ("id", "name", "qualified_name", "file_path", "line_start", "line_end")
+"""``Class`` properties read by ``class_from_row``, in column order."""
+FILE_FIELDS = ("path", "module_name")
+"""``File`` properties read by ``file_from_row``, in column order."""
+FUNCTION_WIDTH = len(FUNCTION_FIELDS)
+CLASS_WIDTH = len(CLASS_FIELDS)
+FILE_WIDTH = len(FILE_FIELDS)
+
+
+def columns(variable: str, fields: Sequence[str]) -> str:
+    """Render a ``RETURN`` column list for one node variable.
+
+    Used only to compose module-level ``Query`` constants, so the column order a query
+    returns and the order its decoder reads are the same list.
+
+    Args:
+        variable: Cypher variable bound to the node, e.g. ``"n"``.
+        fields: Property names, e.g. ``FUNCTION_FIELDS``.
+
+    Returns:
+        The comma-separated column list.
+
+    Example:
+        ``columns("a", FILE_FIELDS)`` returns ``"a.path, a.module_name"``.
+    """
+    return ", ".join(f"{variable}.{name}" for name in fields)
+
+
+def _text(value: Any, column: str) -> str:
+    if not isinstance(value, str):
+        raise IndexIncompatibleError(
+            f"unexpected column type for {column}: expected str, got {type(value).__name__}"
+        )
+    return value
+
+
+def _line(value: Any, column: str) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise IndexIncompatibleError(
+            f"unexpected column type for {column}: expected int, got {type(value).__name__}"
+        )
+    return value if value > 0 else None
+
+
+def _expect_width(row: Sequence[Any], width: int, what: str) -> None:
+    if len(row) < width:
+        raise IndexIncompatibleError(
+            f"unexpected column count for {what}: expected {width}, got {len(row)}"
+        )
+
+
+def public_file_id(path: str) -> SymbolId:
+    """Build the public id of a file from its stored path.
+
+    Args:
+        path: Repo-relative POSIX path, as stored.
+
+    Returns:
+        ``file::<path>``.
+
+    Example:
+        ``public_file_id("app/auth.py")`` returns ``"file::app/auth.py"``.
+    """
+    return SymbolId(f"file{_SEP}{path}")
+
+
+def _definition(row: Sequence[Any], kind: SymbolKind, signature: str | None) -> SymbolRef:
+    return SymbolRef(
+        id=SymbolId(_text(row[0], "id")),
+        kind=kind,
+        name=_text(row[1], "name"),
+        qualified_name=QualifiedName(_text(row[2], "qualified_name")),
+        file_path=RepoPath(_text(row[3], "file_path")),
+        line_start=_line(row[4], "line_start"),
+        line_end=_line(row[5], "line_end"),
+        signature=signature,
+    )
+
+
+def symbol_from_row(row: Sequence[Any], kind: SymbolKind) -> SymbolRef:
+    """Build a function, method or class ``SymbolRef`` from a graph row.
+
+    Args:
+        row: Columns ``[id, name, qualified_name, file_path, line_start, line_end,
+            signature]``; extra trailing columns are ignored. A stored line of ``0``
+            means "unknown".
+        kind: Kind to assign (``FUNCTION``, ``METHOD`` or ``CLASS``); a class gets no
+            signature.
+
+    Returns:
+        The symbol.
+
+    Raises:
+        IndexIncompatibleError: A column is missing or has an unexpected type.
+
+    Example:
+        ``["app/auth.py::parse", "parse", "app.auth.parse", "app/auth.py", 6, 7,
+        "def parse(raw):"]`` becomes ``SymbolRef(id="app/auth.py::parse",
+        qualified_name="app.auth.parse", line_start=6, ...)``.
+    """
+    _expect_width(row, 7, "symbol row")
+    signature = _text(row[6], "signature") or None
+    return _definition(row, kind, None if kind is SymbolKind.CLASS else signature)
+
+
+def file_from_row(row: Sequence[Any]) -> SymbolRef:
+    """Build a ``FILE`` ``SymbolRef`` from a row of ``FILE_FIELDS`` columns.
+
+    Args:
+        row: Columns ``[path, module_name]``.
+
+    Returns:
+        The file symbol with id ``file::<path>``.
+
+    Raises:
+        IndexIncompatibleError: A column is missing or has an unexpected type.
+
+    Example:
+        ``["app/auth.py", "app.auth"]`` becomes ``SymbolRef(id="file::app/auth.py",
+        name="auth.py", qualified_name="app.auth", ...)``.
+    """
+    _expect_width(row, FILE_WIDTH, "file row")
+    path = _text(row[0], "path")
+    return SymbolRef(
+        id=public_file_id(path),
+        kind=SymbolKind.FILE,
+        name=PurePosixPath(path).name,
+        qualified_name=QualifiedName(_text(row[1], "module_name")),
+        file_path=RepoPath(path),
+        line_start=None,
+        line_end=None,
+        signature=None,
+    )
+
+
+def external_from_row(row: Sequence[Any]) -> SymbolRef:
+    """Build an ``EXTERNAL`` ``SymbolRef`` from a ``[full_ref, name]`` row.
+
+    Args:
+        row: Columns ``[full_ref, name]``.
+
+    Returns:
+        The external symbol with id ``ext::<full_ref>``.
+
+    Raises:
+        IndexIncompatibleError: A column is missing or has an unexpected type.
+    """
+    _expect_width(row, 2, "external row")
+    full_ref = _text(row[0], "full_ref")
+    return SymbolRef(
+        id=SymbolId(f"ext{_SEP}{full_ref}"),
+        kind=SymbolKind.EXTERNAL,
+        name=_text(row[1], "name"),
+        qualified_name=QualifiedName(full_ref),
+        file_path=None,
+        line_start=None,
+        line_end=None,
+        signature=None,
+    )
+
+
+def is_method_flag(value: Any) -> bool:
+    """Validate a ``Function.is_method`` column.
+
+    Args:
+        value: Raw column value.
+
+    Returns:
+        The flag as a ``bool``.
+
+    Raises:
+        IndexIncompatibleError: The value is not a boolean.
+    """
+    if not isinstance(value, bool):
+        raise IndexIncompatibleError(
+            f"unexpected column type for is_method: expected bool, got {type(value).__name__}"
+        )
+    return value
+
+
+def count_value(value: Any) -> int:
+    """Validate a count column.
+
+    Args:
+        value: Raw column value.
+
+    Returns:
+        The count as an ``int``.
+
+    Raises:
+        IndexIncompatibleError: The value is not an integer.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise IndexIncompatibleError(
+            f"unexpected column type for count: expected int, got {type(value).__name__}"
+        )
+    return value
+
+
+def function_from_row(row: Sequence[Any]) -> SymbolRef:
+    """Build a function or method ``SymbolRef`` from a row of ``FUNCTION_FIELDS`` columns.
+
+    Args:
+        row: Columns in ``FUNCTION_FIELDS`` order.
+
+    Returns:
+        The symbol, with kind ``METHOD`` when ``is_method`` is true, else ``FUNCTION``.
+
+    Raises:
+        IndexIncompatibleError: A column is missing or has an unexpected type.
+
+    Example:
+        ``["app/models.py::User.save", "save", "app.models.User.save", "app/models.py", 6,
+        7, "def save(self):", True]`` becomes a ``METHOD`` with id
+        ``"app/models.py::User.save"``.
+    """
+    _expect_width(row, FUNCTION_WIDTH, "function row")
+    kind = SymbolKind.METHOD if is_method_flag(row[7]) else SymbolKind.FUNCTION
+    return symbol_from_row(row, kind)
+
+
+def class_from_row(row: Sequence[Any]) -> SymbolRef:
+    """Build a ``CLASS`` ``SymbolRef`` from a row of ``CLASS_FIELDS`` columns.
+
+    Args:
+        row: Columns in ``CLASS_FIELDS`` order; extra trailing columns are ignored.
+
+    Returns:
+        The class symbol; classes have no signature.
+
+    Raises:
+        IndexIncompatibleError: A column is missing or has an unexpected type.
+
+    Example:
+        ``["app/models.py::User", "User", "app.models.User", "app/models.py", 4, 9]``
+        becomes ``SymbolRef(id="app/models.py::User", kind=SymbolKind.CLASS, ...)``.
+    """
+    _expect_width(row, CLASS_WIDTH, "class row")
+    return _definition(row, SymbolKind.CLASS, None)
+
+
+def text_value(value: Any, column: str) -> str:
+    """Validate a string column.
+
+    Args:
+        value: Raw column value.
+        column: Column name, for the error message.
+
+    Returns:
+        The value as a ``str``.
+
+    Raises:
+        IndexIncompatibleError: The value is not a string.
+    """
+    return _text(value, column)
+
+
+def text_list_value(value: Any, column: str) -> tuple[str, ...]:
+    """Validate a ``STRING[]`` column such as ``Function.raw_calls``.
+
+    Args:
+        value: Raw column value; a stored ``NULL`` reads as an empty tuple.
+        column: Column name, for the error message.
+
+    Returns:
+        The strings, in stored order.
+
+    Raises:
+        IndexIncompatibleError: The value is not a list of strings.
+
+    Example:
+        ``text_list_value(["parse"], "raw_calls")`` returns ``("parse",)``.
+    """
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise IndexIncompatibleError(
+            f"unexpected column type for {column}: expected list, got {type(value).__name__}"
+        )
+    return tuple(_text(item, column) for item in value)
+
+
+def line_value(value: Any, column: str) -> int | None:
+    """Validate a 1-indexed line column; a stored ``0`` (unknown) becomes ``None``.
+
+    Args:
+        value: Raw column value.
+        column: Column name, for the error message.
+
+    Returns:
+        The 1-indexed line, or ``None`` when unknown.
+
+    Raises:
+        IndexIncompatibleError: The value is not an integer.
+
+    Example:
+        ``line_value(0, "line")`` returns ``None``; ``line_value(4, "line")`` returns ``4``.
+    """
+    return _line(value, column)
+
+
+def confidence_value(value: Any) -> float:
+    """Validate a ``CALLS.confidence`` column.
+
+    Args:
+        value: Raw column value.
+
+    Returns:
+        The confidence as a ``float`` in ``[0, 1]``, rounded to 6 decimals: the column
+        is float32, so a written ``0.9`` reads back as ``0.8999999761581421``.
+
+    Raises:
+        IndexIncompatibleError: The value is not a number in ``[0, 1]``.
+
+    Example:
+        ``confidence_value(0.800000011920929)`` returns ``0.8``.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0 <= value <= 1:
+        raise IndexIncompatibleError(f"unexpected value for confidence: {value!r}")
+    return round(float(value), _CONFIDENCE_DIGITS)
+
+
+def call_type_value(value: Any) -> CallType:
+    """Validate a ``CALLS.call_type`` column.
+
+    Args:
+        value: Raw column value.
+
+    Returns:
+        The call type.
+
+    Raises:
+        IndexIncompatibleError: The value is not one of the ``CallType`` values.
+
+    Example:
+        ``call_type_value("MRO")`` returns ``CallType.MRO``.
+    """
+    try:
+        return CallType(_text(value, "call_type"))
+    except ValueError as exc:
+        raise IndexIncompatibleError(f"unexpected value for call_type: {value!r}") from exc

compass_core/query/search.py

@@ -0,0 +1,183 @@
+"""Symbol search: files, classes, functions and methods by name or path.
+
+Matching is case-insensitive substring matching done in the graph with
+``lower(x) CONTAINS lower($q)``; the user text only ever reaches Cypher as a
+``$parameter``, so ``%``, ``_``, quotes and backslashes are literal. Each candidate is
+then classified (see ``SearchMatch``) and ranked by match class, fan-in, then name.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from compass_core.contract.models import IndexStatus, SymbolRef
+from compass_core.contract.params import SearchParams
+from compass_core.contract.results import SearchHit, SearchResult
+from compass_core.contract.types import SearchMatch
+from compass_core.graph.db import GraphDB, Row
+from compass_core.index.locate import IndexLocation
+from compass_core.query.cypher import Query
+from compass_core.query.rows import (
+    CLASS_FIELDS,
+    FILE_FIELDS,
+    FILE_WIDTH,
+    FUNCTION_FIELDS,
+    FUNCTION_WIDTH,
+    class_from_row,
+    columns,
+    count_value,
+    file_from_row,
+    function_from_row,
+)
+from compass_core.query.status import index_status
+from compass_core.shared_types import SymbolKind
+
+_RANK = {match: i for i, match in enumerate(SearchMatch)}
+
+
+def _with_fan_in(
+    decode: Callable[[Row], SymbolRef], width: int
+) -> Callable[[Row], tuple[SymbolRef, int]]:
+    """Decoder for rows of symbol columns followed by one count column."""
+    return lambda row: (decode(row), count_value(row[width]))
+
+
+# Candidates are fetched by the last dotted segment of the query ("User.save" -> "save"),
+# then classified in Python against the full qualified name.
+_FUNCTIONS_NAMED: Query[tuple[SymbolRef, int]] = Query(
+    f"""
+    MATCH (n:Function) WHERE lower(n.name) CONTAINS lower($last)
+    OPTIONAL MATCH (c:Function)-[:CALLS]->(n)
+    RETURN {columns("n", FUNCTION_FIELDS)}, count(c)
+    """,
+    _with_fan_in(function_from_row, FUNCTION_WIDTH),
+)
+_CLASSES_NAMED: Query[SymbolRef] = Query(
+    f"""
+    MATCH (n:Class) WHERE lower(n.name) CONTAINS lower($last)
+    RETURN {columns("n", CLASS_FIELDS)}
+    """,
+    class_from_row,
+)
+_FILES_WITH_PATH: Query[tuple[SymbolRef, int]] = Query(
+    f"""
+    MATCH (n:File) WHERE lower(n.path) CONTAINS lower($q)
+    OPTIONAL MATCH (i:File)-[:IMPORTS]->(n)
+    RETURN {columns("n", FILE_FIELDS)}, count(i)
+    """,
+    _with_fan_in(file_from_row, FILE_WIDTH),
+)
+
+
+def _classify_definition(symbol: SymbolRef, query: str) -> SearchMatch | None:
+    """Match class of a function/class for a lower-cased ``query``, or ``None``."""
+    name = symbol.name.lower()
+    qualified = symbol.qualified_name.lower()
+    if name == query or qualified == query:
+        return SearchMatch.EXACT
+    if qualified.endswith("." + query):
+        return SearchMatch.QUALIFIED_SUFFIX
+    if name.startswith(query):
+        return SearchMatch.PREFIX
+    if query in name:
+        return SearchMatch.SUBSTRING
+    return None
+
+
+def _classify_file(symbol: SymbolRef, query: str) -> SearchMatch | None:
+    """Match class of a file for a lower-cased ``query``, or ``None``."""
+    path = (symbol.file_path or "").lower()
+    name = symbol.name.lower()
+    if path == query or name == query:
+        return SearchMatch.EXACT
+    if path.endswith("/" + query):
+        return SearchMatch.QUALIFIED_SUFFIX
+    if path.startswith(query) or name.startswith(query):
+        return SearchMatch.PREFIX
+    if query in path:
+        return SearchMatch.SUBSTRING
+    return None
+
+
+def _definition_hits(db: GraphDB, kind: SymbolKind | None, text: str) -> list[SearchHit]:
+    params = {"last": text.rsplit(".", 1)[-1]}
+    lowered = text.lower()
+    hits: list[SearchHit] = []
+
+    def add(symbol: SymbolRef, fan_in: int) -> None:
+        match = _classify_definition(symbol, lowered)
+        if match is not None:
+            hits.append(SearchHit(symbol=symbol, match=match, fan_in=fan_in))
+
+    if kind in (None, SymbolKind.CLASS):
+        for symbol in _CLASSES_NAMED.run(db, params):
+            add(symbol, 0)
+    if kind in (None, SymbolKind.FUNCTION, SymbolKind.METHOD):
+        for symbol, fan_in in _FUNCTIONS_NAMED.run(db, params):
+            if kind in (None, symbol.kind):
+                add(symbol, fan_in)
+    return hits
+
+
+def _file_hits(db: GraphDB, text: str) -> list[SearchHit]:
+    lowered = text.lower()
+    hits: list[SearchHit] = []
+    for symbol, fan_in in _FILES_WITH_PATH.run(db, {"q": text}):
+        match = _classify_file(symbol, lowered)
+        if match is not None:
+            hits.append(SearchHit(symbol=symbol, match=match, fan_in=fan_in))
+    return hits
+
+
+def find_symbols(db: GraphDB, location: IndexLocation, params: SearchParams) -> SearchResult:
+    """Search files, classes, functions and methods.
+
+    Args:
+        db: Open graph database.
+        location: Index location, used to build the result's ``IndexStatus``. (Adds
+            ``location`` to the parent spec's signature; recorded ruling.)
+        params: Query text, optional kind filter and limit.
+
+    Returns:
+        Hits best first: ``EXACT`` > ``QUALIFIED_SUFFIX`` > ``PREFIX`` > ``SUBSTRING``,
+        ties broken by fan-in (incoming ``CALLS`` for functions, incoming ``IMPORTS``
+        for files, 0 for classes) then name. ``total`` counts matches before the limit.
+
+    Raises:
+        IndexIncompatibleError: A stored row or the index metadata is unreadable.
+
+    Note:
+        Cost is O(matches of the last dotted segment of the query) because an exact
+        ``total`` is required. Qualified-prefix queries such as ``auth.decode`` are not
+        supported: dotted queries match only exactly or as a suffix of the qualified
+        name. A query whose last dotted segment is empty (``"."``, ``"a."``) matches
+        nothing. ``index_status`` stats every indexed file per call; callers may cache.
+        Fan-in counts edges (not distinct callers), as in ``references``.
+
+    Example:
+        ``find_symbols(db, loc, SearchParams(query="User.save"))`` returns
+        ``app/models.py::User.save`` first with ``SearchMatch.QUALIFIED_SUFFIX``.
+    """
+    status = index_status(location, db)  # first: rejects an incompatible index
+    text = params.query.strip()
+    hits: list[SearchHit] = []
+    if text.endswith("."):
+        # Empty last segment: a CONTAINS '' scan would match everything.
+        return _result(status, params, hits)
+    if params.kind in (None, SymbolKind.FILE):
+        hits += _file_hits(db, text)
+    hits += _definition_hits(db, params.kind, text)
+    return _result(status, params, hits)
+
+
+def _result(status: IndexStatus, params: SearchParams, hits: list[SearchHit]) -> SearchResult:
+    hits.sort(key=lambda h: (_RANK[h.match], -h.fan_in, h.symbol.name, h.symbol.id))
+    return SearchResult(
+        index=status,
+        caveats=(),
+        query=params.query,
+        kind=params.kind,
+        hits=tuple(hits[: params.limit]),
+        total=len(hits),
+        truncated=len(hits) > params.limit,
+    )

compass_core/query/status.py

@@ -0,0 +1,49 @@
+"""Index status for query results: metadata plus a count of stale files."""
+
+from __future__ import annotations
+
+from compass_core.contract.models import IndexStatus
+from compass_core.contract.types import RepoPath
+from compass_core.graph.db import GraphDB
+from compass_core.index.freshness import count_stale
+from compass_core.index.locate import IndexLocation
+from compass_core.index.metadata import load_metadata
+from compass_core.query.cypher import Query
+from compass_core.query.rows import text_value
+
+_FILE_PATHS: Query[RepoPath] = Query(
+    "MATCH (f:File) RETURN f.path", lambda row: RepoPath(text_value(row[0], "path"))
+)
+
+
+def index_status(location: IndexLocation, db: GraphDB) -> IndexStatus:
+    """Describe the index and count its stale files.
+
+    The indexed paths come from the graph; the stale check itself is
+    ``index.freshness.count_stale`` (missing, or modified after the ingest).
+
+    Args:
+        location: Where the index lives.
+        db: Open graph database of that index.
+
+    Returns:
+        The status, with ``new_file_count`` left ``None`` (only ``status`` computes it).
+
+    Raises:
+        IndexIncompatibleError: The metadata or a stored row is unreadable.
+
+    Example:
+        After ``touch app/auth.py`` post-ingest, ``index_status(loc, db).stale_file_count``
+        is ``1``.
+    """
+    meta = load_metadata(location.metadata_path)
+    repo_root = location.repo_root.resolve()
+    paths = _FILE_PATHS.run(db)
+    return IndexStatus(
+        repo_root=repo_root,
+        indexed_at=meta.indexed_at,
+        indexed_commit=meta.indexed_commit,
+        schema_version=meta.schema_version,
+        stale_file_count=count_stale(repo_root, paths, int(meta.indexed_at.timestamp())),
+        new_file_count=None,
+    )