compass-code 0.1.0__py3-none-any.whl

compass_core/query/overview.py

@@ -0,0 +1,221 @@
+"""Repository overview: totals, entry points and the hot spots of the graph.
+
+Every list comes from one aggregate query. The riskiest-to-change list additionally
+runs the reverse ``CALLS`` walk of ``impact_walk`` for a bounded set of candidates.
+"""
+
+from __future__ import annotations
+
+from compass_core.contract.models import Caveat, SymbolRef
+from compass_core.contract.results import (
+    CallResolution,
+    IndexCounts,
+    LibraryUsage,
+    OverviewResult,
+    RankedSymbol,
+)
+from compass_core.contract.types import CaveatCode
+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.impact import RAW_CALLERS, bare_call_name
+from compass_core.query.impact_walk import walk_symbols
+from compass_core.query.rows import (
+    FILE_FIELDS,
+    FILE_WIDTH,
+    FUNCTION_FIELDS,
+    FUNCTION_WIDTH,
+    columns,
+    count_value,
+    file_from_row,
+    function_from_row,
+    text_value,
+)
+from compass_core.query.status import index_status
+from compass_core.shared_types import EdgeType
+
+TOP_N = 5
+"""Length of every ranked list."""
+
+RISK_CANDIDATES = 30
+"""How many most-called functions are walked to rank ``riskiest_to_change``."""
+
+RISK_DEPTH = 3
+"""Traversal depth used to count the symbols affected by a change."""
+
+
+def _count(row: Row) -> int:
+    return count_value(row[0])
+
+
+_FILE_COUNT: Query[int] = Query("MATCH (n:File) RETURN count(n)", _count)
+_CLASS_COUNT: Query[int] = Query("MATCH (n:Class) RETURN count(n)", _count)
+_FUNCTION_COUNT: Query[int] = Query("MATCH (n:Function) RETURN count(n)", _count)
+_EDGE_COUNTS: dict[EdgeType, Query[int]] = {
+    edge: Query(f"MATCH ()-[r:{edge.value}]->() RETURN count(r)", _count) for edge in EdgeType
+}
+"""One count query per relationship table; ``EdgeType`` values are the table names."""
+_ENTRY_POINTS: Query[SymbolRef] = Query(
+    f"""
+    MATCH (f:File) WHERE NOT EXISTS {{ MATCH (:File)-[:IMPORTS]->(f) }}
+    RETURN {columns("f", FILE_FIELDS)} ORDER BY f.path LIMIT $limit
+    """,
+    file_from_row,
+)
+_MOST_IMPORTED: Query[RankedSymbol] = Query(
+    f"""
+    MATCH (i:File)-[:IMPORTS]->(f:File)
+    RETURN {columns("f", FILE_FIELDS)}, count(DISTINCT i) AS n
+    ORDER BY n DESC, f.path LIMIT $limit
+    """,
+    lambda row: RankedSymbol(symbol=file_from_row(row), count=count_value(row[FILE_WIDTH])),
+)
+_MOST_CALLED: Query[tuple[SymbolRef, int]] = Query(
+    f"""
+    MATCH (c:Function)-[:CALLS]->(n:Function)
+    RETURN {columns("n", FUNCTION_FIELDS)}, count(DISTINCT c) AS k
+    ORDER BY k DESC, n.name, n.id LIMIT $limit
+    """,
+    lambda row: (function_from_row(row), count_value(row[FUNCTION_WIDTH])),
+)
+_LIBRARIES: Query[LibraryUsage] = Query(
+    """
+    MATCH (:Function)-[e:CALLS_EXTERN]->(x:ExternalFunction)
+    RETURN x.library, count(e) AS n ORDER BY n DESC, x.library LIMIT $limit
+    """,
+    lambda row: LibraryUsage(library=text_value(row[0], "library"), call_count=count_value(row[1])),
+)
+
+
+def index_counts(db: GraphDB) -> IndexCounts:
+    """Count the nodes of an index and its edges of every type.
+
+    Args:
+        db: Open, read-only graph database.
+
+    Returns:
+        The totals. ``edges_by_type`` has every ``EdgeType``, zeros included, and
+        ``functions`` counts functions and methods.
+
+    Raises:
+        IndexIncompatibleError: A stored count is not an integer.
+
+    Example:
+        A repo with one file holding one function has ``files=1``, ``functions=1`` and
+        ``edges_by_type[EdgeType.CONTAINS] == 1``.
+    """
+    return IndexCounts(
+        files=_FILE_COUNT.first(db) or 0,
+        classes=_CLASS_COUNT.first(db) or 0,
+        functions=_FUNCTION_COUNT.first(db) or 0,
+        edges_by_type={edge: query.first(db) or 0 for edge, query in _EDGE_COUNTS.items()},
+    )
+
+
+def entry_points(db: GraphDB) -> tuple[SymbolRef, ...]:
+    """List the files nobody imports, by path.
+
+    Args:
+        db: Open, read-only graph database.
+
+    Returns:
+        At most ``TOP_N`` ``FILE`` symbols.
+
+    Raises:
+        IndexIncompatibleError: A stored row is unreadable.
+
+    Example:
+        If ``app/main.py`` imports ``app/auth.py``, only ``app/main.py`` is returned.
+    """
+    return tuple(_ENTRY_POINTS.run(db, {"limit": TOP_N}))
+
+
+def _call_resolution(db: GraphDB) -> CallResolution:
+    """Count call sites, and those whose called name matches a resolved callee of the caller."""
+    total = resolved = 0
+    for caller in RAW_CALLERS.run(db):
+        for raw in caller.raw_calls:
+            total += 1
+            resolved += bare_call_name(raw) in caller.reached
+    return CallResolution(total=total, resolved=resolved)
+
+
+def _riskiest(db: GraphDB, called: list[tuple[SymbolRef, int]]) -> tuple[RankedSymbol, ...]:
+    """Rank candidates (results of ``_MOST_CALLED``) by symbols affected at ``RISK_DEPTH``."""
+    ranked = [
+        RankedSymbol(
+            symbol=symbol,
+            count=len(walk_symbols(db, symbol, depth=RISK_DEPTH, min_confidence=0.0).reached),
+        )
+        for symbol, _ in called
+    ]
+    ranked.sort(key=lambda r: (-r.count, r.symbol.name, r.symbol.id))
+    return tuple(ranked[:TOP_N])
+
+
+def _caveats(counts: IndexCounts, stale: int) -> tuple[Caveat, ...]:
+    caveats: list[Caveat] = []
+    if stale:
+        noun = "file has" if stale == 1 else "files have"
+        message = f"{stale} indexed {noun} changed since the last ingest; run `compass ingest`"
+        caveats.append(Caveat(code=CaveatCode.STALE_INDEX, message=message, count=stale))
+    if counts.functions and not counts.edges_by_type[EdgeType.CALLS]:
+        message = (
+            "no function-to-function calls were resolved among the "
+            f"{counts.functions} indexed functions; symbol-level lists may be empty"
+        )
+        caveats.append(
+            Caveat(code=CaveatCode.UNRESOLVED_CALLS, message=message, count=counts.functions)
+        )
+    return tuple(caveats)
+
+
+def overview(db: GraphDB, location: IndexLocation) -> OverviewResult:
+    """Summarise an index: totals, entry points and ranked hot spots.
+
+    Args:
+        db: Open, read-only graph database.
+        location: Index location, used for the ``IndexStatus``.
+
+    Returns:
+        An ``OverviewResult``. ``counts.edges_by_type`` has every ``EdgeType`` (zeros
+        included) and ``counts.functions`` counts functions and methods.
+        ``call_resolution`` counts every call site and those matching a callee the caller
+        has an edge to (a constructor call such as ``User()`` has no edge, so it counts as
+        unresolved). Each list holds
+        at most 5 entries: ``entry_points`` are files nobody imports, by path;
+        ``most_imported_files`` ranks files by importing files; ``most_called_functions``
+        ranks functions and methods by distinct callers; ``top_external_libraries`` ranks
+        libraries by ``CALLS_EXTERN`` edges; ``riskiest_to_change`` ranks functions and
+        methods by the number of symbols a change affects within 3 hops of reverse
+        ``CALLS``. To bound the cost only the 30 most-called functions (fan-in at least
+        1) are walked, so a rarely called function with a deep caller chain can be
+        missed. Ties break by name. Caveats: ``STALE_INDEX`` when indexed files changed,
+        and ``UNRESOLVED_CALLS`` (count = functions) when functions exist but no call
+        was resolved, which is why the symbol-level lists may be empty.
+
+    Raises:
+        IndexIncompatibleError: A stored row or the index metadata is unreadable.
+
+    Example:
+        On a repo where ``handle``, ``run`` and ``nightly`` call ``decode_token`` and
+        ``tick`` calls ``nightly``, ``riskiest_to_change[0]`` is ``decode_token`` with
+        ``count=4``.
+    """
+    status = index_status(location, db)  # first: rejects an incompatible index
+    limit = {"limit": TOP_N}
+    counts = index_counts(db)
+    called = _MOST_CALLED.run(db, {"limit": RISK_CANDIDATES})
+    return OverviewResult(
+        index=status,
+        caveats=_caveats(counts, status.stale_file_count),
+        counts=counts,
+        call_resolution=_call_resolution(db),
+        entry_points=entry_points(db),
+        most_imported_files=tuple(_MOST_IMPORTED.run(db, limit)),
+        most_called_functions=tuple(
+            RankedSymbol(symbol=symbol, count=count) for symbol, count in called[:TOP_N]
+        ),
+        riskiest_to_change=_riskiest(db, called),
+        top_external_libraries=tuple(_LIBRARIES.run(db, limit)),
+    )

compass_core/query/references.py

@@ -0,0 +1,235 @@
+"""Resolve a user-typed symbol reference to exactly one graph node.
+
+Rules are tried in the order of the query-layer design (section 4.1): exact id, file
+path (only when ``allow_file``), fully qualified dotted name, ``path::Name``,
+``Class.member`` and bare name. The first rule with any hit decides the outcome: one
+hit resolves, several hits are an ``AmbiguousReference``, and no hit at all is a
+``SymbolNotFound`` with substring suggestions. A reference is never guessed.
+
+The graph stores public ids, repo-relative paths and qualified names, so an exact id,
+a file path and a qualified name are equality matches; only the partial rules
+(``path::Name`` with a partial path, ``Class.member``) match on a suffix. User input
+only ever reaches Cypher as a ``$parameter``; the only text composed into a query is
+the constant ``WHERE`` conditions below, at import.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from compass_core.contract.models import SymbolRef
+from compass_core.contract.results import AmbiguousReference, Lookup, SymbolNotFound
+from compass_core.contract.types import MatchRule
+from compass_core.graph.db import GraphDB, QueryParams
+from compass_core.query.cypher import Query
+from compass_core.query.rows import (
+    CLASS_FIELDS,
+    FILE_FIELDS,
+    FUNCTION_FIELDS,
+    class_from_row,
+    columns,
+    count_value,
+    external_from_row,
+    file_from_row,
+    function_from_row,
+    text_value,
+)
+from compass_core.shared_types import SymbolKind
+
+_SEP = "::"
+_MAX_SUGGESTIONS = 5
+
+
+@dataclass(frozen=True, slots=True)
+class DefinitionQueries:
+    """The class and the function query for one definition filter over node ``n``.
+
+    Attributes:
+        classes: Matching classes.
+        functions: Matching functions and methods.
+
+    Example:
+        ``_BY_NAME.functions.run(db, {"q": "save"})`` returns both ``save`` methods.
+    """
+
+    classes: Query[SymbolRef]
+    functions: Query[SymbolRef]
+
+
+def _definitions_where(condition: str) -> DefinitionQueries:
+    """Build the query pair for a constant ``WHERE`` condition (module load time only)."""
+    return DefinitionQueries(
+        classes=Query(
+            f"MATCH (n:Class) WHERE {condition} RETURN {columns('n', CLASS_FIELDS)}",
+            class_from_row,
+        ),
+        functions=Query(
+            f"MATCH (n:Function) WHERE {condition} RETURN {columns('n', FUNCTION_FIELDS)}",
+            function_from_row,
+        ),
+    )
+
+
+_BY_ID = _definitions_where("n.id = $id")
+_BY_ID_OR_ID_SUFFIX = _definitions_where("n.id = $id OR n.id ENDS WITH $suffix")
+_BY_QUALIFIED_NAME = _definitions_where("n.qualified_name = $q")
+_BY_TAIL = _definitions_where("n.id ENDS WITH $tail")
+_BY_NAME = _definitions_where("n.name = $q")
+_NAME_CONTAINS = _definitions_where("lower(n.name) CONTAINS lower($q)")
+
+FILES_AT_PATHS: Query[SymbolRef] = Query(
+    f"MATCH (f:File) WHERE f.path IN $paths RETURN {columns('f', FILE_FIELDS)}",
+    file_from_row,
+)
+"""Files whose repo-relative path is one of ``$paths``."""
+_EXTERNAL: Query[SymbolRef] = Query(
+    "MATCH (e:ExternalFunction) WHERE e.full_ref = $q RETURN e.full_ref, e.name",
+    external_from_row,
+)
+_FAN_IN: Query[tuple[str, int]] = Query(
+    """
+    MATCH (c:Function)-[:CALLS]->(f:Function) WHERE f.id IN $ids
+    RETURN f.id, count(c)
+    """,
+    lambda row: (text_value(row[0], "id"), count_value(row[1])),
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResolvedReference:
+    """A reference that resolved to exactly one symbol.
+
+    Attributes:
+        symbol: The resolved symbol.
+        rule: The resolution rule that matched.
+
+    Example:
+        ``resolve(db, "User.save", repo_root=root)`` returns
+        ``ResolvedReference(symbol=<app/models.py::User.save>, rule=MatchRule.CLASS_MEMBER)``.
+    """
+
+    symbol: SymbolRef
+    rule: MatchRule
+
+
+def _definitions(db: GraphDB, queries: DefinitionQueries, params: QueryParams) -> list[SymbolRef]:
+    """Classes, then functions and methods, matching one definition filter."""
+    return queries.classes.run(db, params) + queries.functions.run(db, params)
+
+
+def _normalize_path(text: str, repo_root: Path) -> str:
+    """Make an absolute path under ``repo_root`` relative; leave anything else alone."""
+    path = Path(text)
+    if path.is_absolute():
+        try:
+            return path.relative_to(repo_root).as_posix()
+        except ValueError:
+            return text
+    return text.removeprefix("./")
+
+
+def _file(db: GraphDB, path: str) -> list[SymbolRef]:
+    return FILES_AT_PATHS.run(db, {"paths": [path]})
+
+
+def _exact_id(db: GraphDB, ref: str, repo_root: Path, allow_file: bool) -> list[SymbolRef]:
+    if ref.startswith("ext" + _SEP):
+        return _EXTERNAL.run(db, {"q": ref.removeprefix("ext" + _SEP)})
+    if ref.startswith("file" + _SEP):
+        return _file(db, ref.removeprefix("file" + _SEP)) if allow_file else []
+    if _SEP not in ref:
+        return []
+    path, tail = ref.rsplit(_SEP, 1)
+    return _definitions(db, _BY_ID, {"id": f"{_normalize_path(path, repo_root)}{_SEP}{tail}"})
+
+
+def _qualified(db: GraphDB, ref: str) -> list[SymbolRef]:
+    """Match a stored qualified name, ``module.[Class.]name``, exactly."""
+    return _definitions(db, _BY_QUALIFIED_NAME, {"q": ref})
+
+
+def _path_and_name(db: GraphDB, ref: str, repo_root: Path) -> list[SymbolRef]:
+    """``path::Name`` where ``path`` is the file's path or a trailing part of it."""
+    path, tail = ref.rsplit(_SEP, 1)
+    exact = f"{_normalize_path(path, repo_root)}{_SEP}{tail}"
+    return _definitions(db, _BY_ID_OR_ID_SUFFIX, {"id": exact, "suffix": "/" + exact})
+
+
+def _class_member(db: GraphDB, ref: str) -> list[SymbolRef]:
+    return _definitions(db, _BY_TAIL, {"tail": _SEP + ref})
+
+
+def _bare_name(db: GraphDB, ref: str) -> list[SymbolRef]:
+    return _definitions(db, _BY_NAME, {"q": ref})
+
+
+def _hits(
+    db: GraphDB, rule: MatchRule, text: str, repo_root: Path, allow_file: bool
+) -> list[SymbolRef]:
+    """Symbols matching ``text`` under one rule; empty when the rule does not apply."""
+    plain = _SEP not in text
+    if rule is MatchRule.EXACT_ID:
+        return _exact_id(db, text, repo_root, allow_file)
+    if rule is MatchRule.FILE_PATH:
+        return _file(db, _normalize_path(text, repo_root)) if allow_file else []
+    if rule is MatchRule.QUALIFIED_NAME:
+        return _qualified(db, text) if plain and "." in text else []
+    if rule is MatchRule.PATH_AND_NAME:
+        return _path_and_name(db, text, repo_root) if not plain else []
+    if rule is MatchRule.CLASS_MEMBER:
+        return _class_member(db, text) if plain and "." in text else []
+    return _bare_name(db, text) if plain else []
+
+
+def _fan_in(db: GraphDB, symbols: Sequence[SymbolRef]) -> dict[str, int]:
+    """Incoming ``CALLS`` count per function or method (one query); others count zero."""
+    ids = [s.id for s in symbols if s.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD)]
+    return dict(_FAN_IN.run(db, {"ids": ids})) if ids else {}
+
+
+def _suggestions(db: GraphDB, text: str) -> tuple[SymbolRef, ...]:
+    if not text:
+        return ()
+    found = _definitions(db, _NAME_CONTAINS, {"q": text})
+    found.sort(key=lambda s: (s.name.lower() != text.lower(), len(s.name), s.id))
+    return tuple(found[:_MAX_SUGGESTIONS])
+
+
+def resolve(
+    db: GraphDB, ref: str, *, repo_root: Path, allow_file: bool = False
+) -> Lookup[ResolvedReference]:
+    """Resolve a symbol reference using the first rule that has any hit.
+
+    Args:
+        db: Open graph database.
+        ref: User-typed reference: public id, file path, dotted name, ``path::Name``,
+            ``Class.member`` or bare name.
+        repo_root: Absolute repository root; an absolute path in ``ref`` is made
+            relative to it.
+        allow_file: Whether a file path (rule 2) is acceptable for this operation.
+
+    Returns:
+        A ``ResolvedReference`` for a single match, an ``AmbiguousReference`` listing
+        the candidates (most incoming calls first) when several symbols matched the
+        same rule, or a ``SymbolNotFound`` with up to five suggestions.
+
+    Raises:
+        IndexIncompatibleError: A stored row does not have the expected shape.
+
+    Example:
+        ``resolve(db, "app/auth.py::decode_token", repo_root=root)`` returns
+        ``ResolvedReference(symbol=<decode_token>, rule=MatchRule.EXACT_ID)``.
+    """
+    text = ref.strip()
+    if text:
+        for rule in MatchRule:
+            found = _hits(db, rule, text, repo_root, allow_file)
+            if len(found) == 1:
+                return ResolvedReference(symbol=found[0], rule=rule)
+            if found:
+                fan_in = _fan_in(db, found)
+                ordered = sorted(found, key=lambda s: (-fan_in.get(s.id, 0), s.id))
+                return AmbiguousReference(reference=ref, candidates=tuple(ordered))
+    return SymbolNotFound(reference=ref, suggestions=_suggestions(db, text))