compass-code 0.1.0__py3-none-any.whl

compass_core/graph/writer.py

@@ -0,0 +1,482 @@
+"""Persist a ResolvedGraph into LadybugDB.
+
+This module acts as a pure sink for the graph resolution process. It is
+responsible for taking a fully resolved graph and persisting its nodes
+and edges into the underlying graph database.
+
+The writing process follows a strict order, ensuring nodes are created
+before the edges that connect them:
+  1. File nodes
+  2. Class nodes
+  3. Function nodes
+  4. ExternalFunction nodes (derived from call edges to external libraries)
+  5. CONTAINS edges (File -> Class, File -> Function, Class -> Function)
+  6. IMPORTS edges
+  7. INHERITS edges
+  8. CALLS edges (Internal)
+  9. CALLS_EXTERN edges (External)
+
+Every edge is written with ``MATCH (a ...), (b ...) CREATE ... RETURN
+count(*)``. When an endpoint was never stored as a node the MATCH yields no
+row and the CREATE silently does nothing, so the writer checks the returned
+count and reports such edges as dropped instead of written.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from compass_core.graph.db import GraphDB, as_row
+from compass_core.graph.stored_ids import with_stored_ids
+from compass_core.ir.graph import CallEdge, ExternalCallEdge, ImportEdge, InheritEdge, ResolvedGraph
+from compass_core.ir.models import Definition, ParsedFile
+from compass_core.progress import ProgressReporter
+from compass_core.shared_types import SymbolKind
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WriteResult:
+    """Statistics returned after persisting a graph to the database.
+
+    Attributes:
+        node_count: Number of nodes successfully written to the DB.
+        edge_count: Number of edges actually stored in the DB (verified per
+            statement, so it equals ``MATCH ()-[r]->() RETURN count(r)`` on
+            a fresh database).
+        dropped_edges: Number of edges in the resolved graph that could not be
+            stored, because an endpoint is not a stored node of the required
+            label (e.g. a resolved call whose callee is a class constructor:
+            CALLS only connects ``Function`` nodes) or the write failed.
+
+    Example:
+        A graph with ``run() -> helper()`` and ``build() -> Widget()``
+        (``Widget`` a class) plus four CONTAINS edges yields
+        ``WriteResult(node_count=..., edge_count=5, dropped_edges=1)``.
+    """
+
+    node_count: int
+    edge_count: int
+    dropped_edges: int = 0
+
+
+def _calculate_expected_nodes(graph: ResolvedGraph) -> int:
+    """Calculate the exact number of nodes the writer will attempt to persist.
+
+    Counts one File node per file, one Class/Function/Method node per
+    definition, and one ExternalFunction node per unique ``full_ref`` across
+    all external call edges.
+    """
+    unique_ext = {e.full_ref for e in graph.external_call_edges}
+    return sum(1 + len(f.definitions) for f in graph.files) + len(unique_ext)
+
+
+def _calculate_expected_edges(graph: ResolvedGraph) -> int:
+    """Calculate the exact number of edges the writer will attempt to persist.
+
+    Counts one CONTAINS edge per class, top-level function, and method,
+    plus one edge each for every import, inheritance, internal call, and
+    external call relationship.
+    """
+    return (
+        sum(len(f.definitions) for f in graph.files)
+        + len(graph.import_edges)
+        + len(graph.inherit_edges)
+        + len(graph.call_edges)
+        + len(graph.external_call_edges)
+    )
+
+
+def write(
+    db: GraphDB,
+    graph: ResolvedGraph,
+    reporter: ProgressReporter | None = None,
+) -> WriteResult:
+    """Write all nodes and edges from a resolved graph into the database.
+
+    Args:
+        db: An active ``GraphDB`` connection with an initialized schema.
+        graph: A ``ResolvedGraph`` with all extracted nodes and edges.
+        reporter: Optional progress reporter. Receives ``"write_nodes"``
+            updates during node insertion and ``"write_edges"`` updates
+            during edge insertion.
+
+    Returns:
+        WriteResult with final node and edge counts. Counts reflect rows
+        actually written — failed DB writes and edges whose endpoints do not
+        exist are not included; they are counted in ``dropped_edges``.
+    """
+    stored = with_stored_ids(graph)
+    graph = stored.graph
+    node_total = _calculate_expected_nodes(graph)
+    edge_total = _calculate_expected_edges(graph)
+    node_count = 0
+    edge_count = 0
+
+    def _node() -> None:
+        nonlocal node_count
+        node_count += 1
+        if reporter:
+            reporter.update("write_nodes", node_count, node_total)
+
+    def _edge() -> None:
+        nonlocal edge_count
+        edge_count += 1
+        if reporter:
+            reporter.update("write_edges", edge_count, edge_total)
+
+    id_to_name: dict[str, str] = {d.id: d.name for f in graph.files for d in f.definitions}
+
+    # --- Nodes first ---
+    for pf in graph.files:
+        _write_file(db, pf)
+        _node()
+        for d in pf.definitions:
+            qualified = stored.qualified_names[d.id]
+            if d.kind is SymbolKind.CLASS:
+                _write_class(db, d, qualified)
+            else:
+                _write_function(db, d, qualified, id_to_name)
+            _node()
+
+    seen_ext: set[str] = set()
+    for ext_edge in graph.external_call_edges:
+        if ext_edge.full_ref not in seen_ext:
+            _write_external_function(db, ext_edge.full_ref, ext_edge.library)
+            seen_ext.add(ext_edge.full_ref)
+            _node()
+
+    # --- Edges second ---
+    for pf in graph.files:
+        _write_contains(db, pf, _edge)
+
+    for import_edge in graph.import_edges:
+        if _write_import_edge(db, import_edge):
+            _edge()
+
+    for inherit_edge in graph.inherit_edges:
+        if _write_inherit_edge(db, inherit_edge):
+            _edge()
+
+    for call_edge in graph.call_edges:
+        if _write_call_edge(db, call_edge):
+            _edge()
+
+    for extern_call_edge in graph.external_call_edges:
+        if _write_external_call_edge(db, extern_call_edge):
+            _edge()
+
+    dropped = edge_total - edge_count
+    if dropped:
+        logger.info(
+            "%d of %d edges were not stored (endpoint not a stored node)", dropped, edge_total
+        )
+    return WriteResult(node_count=node_count, edge_count=edge_count, dropped_edges=dropped)
+
+
+# ---------------------------------------------------------------------------
+# Node writers
+# ---------------------------------------------------------------------------
+
+
+def _write_file(db: GraphDB, f: ParsedFile) -> None:
+    """Persist a file node to the database.
+
+    Args:
+        db: Active database connection.
+        f: The `ParsedFile` metadata containing the path and module info.
+    """
+    db.execute(
+        """
+        MERGE (n:File {path: $path})
+        ON CREATE SET n.module_name = $module_name, n.content_hash = $content_hash
+        ON MATCH  SET n.module_name = $module_name, n.content_hash = $content_hash
+        """,
+        {"path": f.path, "module_name": f.module_name, "content_hash": f.content_hash},
+    )
+
+
+def _write_class(db: GraphDB, cls: Definition, qualified_name: str) -> None:
+    """Persist a class node to the database.
+
+    Args:
+        db: Active database connection.
+        cls: The `Definition` (kind=CLASS) metadata, keyed by its public id, including
+            1-indexed line numbers and source content.
+        qualified_name: Dotted qualified name, e.g. ``app.models.User``.
+    """
+    db.execute(
+        """
+        MERGE (n:Class {id: $id})
+        ON CREATE SET n.name = $name, n.qualified_name = $qualified_name,
+                      n.file_path = $file_path,
+                      n.line_start = $line_start, n.line_end = $line_end,
+                      n.source = $source, n.docstring = $docstring,
+                      n.bases = $bases
+        ON MATCH  SET n.name = $name, n.qualified_name = $qualified_name,
+                      n.file_path = $file_path,
+                      n.line_start = $line_start, n.line_end = $line_end,
+                      n.source = $source, n.docstring = $docstring,
+                      n.bases = $bases
+        """,
+        {
+            "id": cls.id,
+            "name": cls.name,
+            "qualified_name": qualified_name,
+            "file_path": cls.file_path,
+            "line_start": cls.line_start,
+            "line_end": cls.line_end,
+            "source": cls.source,
+            "docstring": cls.docstring or "",
+            "bases": cls.bases,
+        },
+    )
+
+
+def _write_function(
+    db: GraphDB, func: Definition, qualified_name: str, id_to_name: dict[str, str]
+) -> None:
+    """Persist a function or method node to the database.
+
+    Args:
+        db: Active database connection.
+        func: The `Definition` (kind=FUNCTION or METHOD) metadata, keyed by its public
+            id, including 1-indexed line numbers, signature details, and decorators.
+        qualified_name: Dotted qualified name, e.g. ``app.models.User.save``.
+        id_to_name: Maps every `Definition.id` in the graph to its short name,
+            used to recover the parent class's short name from `func.parent_id`.
+    """
+    is_method = func.kind is SymbolKind.METHOD
+    parent_class = id_to_name.get(func.parent_id, "") if func.parent_id else ""
+    db.execute(
+        """
+        MERGE (n:Function {id: $id})
+        ON CREATE SET n.name = $name, n.qualified_name = $qualified_name,
+                      n.signature = $signature,
+                      n.file_path = $file_path, n.line_start = $line_start,
+                      n.line_end = $line_end, n.source = $source,
+                      n.docstring = $docstring, n.is_method = $is_method,
+                      n.parent_class = $parent_class,
+                      n.decorators = $decorators, n.raw_calls = $raw_calls
+        ON MATCH  SET n.name = $name, n.qualified_name = $qualified_name,
+                      n.signature = $signature,
+                      n.file_path = $file_path, n.line_start = $line_start,
+                      n.line_end = $line_end, n.source = $source,
+                      n.docstring = $docstring, n.is_method = $is_method,
+                      n.parent_class = $parent_class,
+                      n.decorators = $decorators, n.raw_calls = $raw_calls
+        """,
+        {
+            "id": func.id,
+            "name": func.name,
+            "qualified_name": qualified_name,
+            "signature": func.signature or "",
+            "file_path": func.file_path,
+            "line_start": func.line_start,
+            "line_end": func.line_end,
+            "source": func.source,
+            "docstring": func.docstring or "",
+            "is_method": is_method,
+            "parent_class": parent_class,
+            "decorators": func.decorators,
+            "raw_calls": func.raw_calls,
+        },
+    )
+
+
+def _write_external_function(db: GraphDB, full_ref: str, library: str) -> None:
+    """Persist an external function node to the database.
+
+    External functions are identified during the call resolution phase
+    when a call target is found to reside in an external library.
+
+    Args:
+        db: Active database connection.
+        full_ref: The fully qualified reference to the function (e.g., 'os.path.join').
+        library: The name of the external library containing the function.
+    """
+    db.execute(
+        """
+        MERGE (n:ExternalFunction {full_ref: $full_ref})
+        ON CREATE SET n.name = $name, n.library = $library
+        ON MATCH  SET n.name = $name, n.library = $library
+        """,
+        {"full_ref": full_ref, "name": full_ref.split(".")[-1], "library": library},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Edge writers
+# ---------------------------------------------------------------------------
+
+
+def _write_contains(db: GraphDB, f: ParsedFile, on_edge: Callable[[], None]) -> None:
+    """Write structural containment edges (CONTAINS) for a file.
+
+    Establishes relationships between a file and its defined classes/functions,
+    as well as between classes and their methods. Calls ``on_edge`` once per
+    edge successfully written, enabling granular progress reporting.
+
+    Args:
+        db: Active database connection.
+        f: The `ParsedFile` whose internal structure is being persisted.
+        on_edge: Callback invoked once for each edge successfully written.
+    """
+    for d in f.definitions:
+        if d.kind is SymbolKind.CLASS:
+            if _exec(
+                db,
+                "MATCH (a:File {path: $src}), (b:Class {id: $dst}) CREATE (a)-[:CONTAINS]->(b) "
+                "RETURN count(*)",
+                {"src": f.path, "dst": d.id},
+            ):
+                on_edge()
+        elif d.kind is SymbolKind.METHOD:
+            if d.parent_id is not None and _exec(
+                db,
+                "MATCH (a:Class {id: $src}), (b:Function {id: $dst}) CREATE (a)-[:CONTAINS]->(b) "
+                "RETURN count(*)",
+                {"src": d.parent_id, "dst": d.id},
+            ):
+                on_edge()
+        else:
+            if _exec(
+                db,
+                "MATCH (a:File {path: $src}), (b:Function {id: $dst}) CREATE (a)-[:CONTAINS]->(b) "
+                "RETURN count(*)",
+                {"src": f.path, "dst": d.id},
+            ):
+                on_edge()
+
+
+def _write_import_edge(db: GraphDB, edge: ImportEdge) -> bool:
+    """Write an IMPORTS edge (File -> File).
+
+    Args:
+        db: Active database connection.
+        edge: The `ImportEdge` describing the importing and imported files.
+
+    Returns:
+        ``True`` if the edge was stored, ``False`` if either endpoint was
+        not found or the write failed.
+    """
+    return _exec(
+        db,
+        "MATCH (a:File {path: $src}), (b:File {path: $dst}) CREATE (a)-[:IMPORTS]->(b) "
+        "RETURN count(*)",
+        {"src": edge.from_path, "dst": edge.to_path},
+    )
+
+
+def _write_inherit_edge(db: GraphDB, edge: InheritEdge) -> bool:
+    """Write an INHERITS edge (Class -> Class).
+
+    Args:
+        db: Active database connection.
+        edge: The `InheritEdge` describing the child and parent classes.
+
+    Returns:
+        ``True`` if the edge was stored, ``False`` if either endpoint was
+        not found or the write failed.
+    """
+    return _exec(
+        db,
+        "MATCH (a:Class {id: $src}), (b:Class {id: $dst}) CREATE (a)-[:INHERITS]->(b) "
+        "RETURN count(*)",
+        {"src": edge.child_id, "dst": edge.parent_id},
+    )
+
+
+def _write_call_edge(db: GraphDB, edge: CallEdge) -> bool:
+    """Write a CALLS edge (Function -> Function) for an internal call.
+
+    A resolved call whose callee is a class (constructor or exception call)
+    has no ``Function`` node to match, so it is not stored and is reported
+    as dropped. OPEN DESIGN DECISION: storing calls to classes (a CALLS
+    Function -> Class relation, or mapping the call to ``__init__``) needs a
+    schema and impact-walker change and is deliberately out of scope here.
+
+    Args:
+        db: Active database connection.
+        edge: The `CallEdge` describing the caller, callee, and call metadata.
+
+    Returns:
+        ``True`` if the edge was stored, ``False`` if either endpoint was
+        not found or the write failed.
+    """
+    return _exec(
+        db,
+        """
+        MATCH (a:Function {id: $src}), (b:Function {id: $dst})
+        CREATE (a)-[:CALLS {confidence: $conf, call_type: $ctype, line: $line}]->(b)
+        RETURN count(*)
+        """,
+        {
+            "src": edge.caller_id,
+            "dst": edge.callee_id,
+            "conf": edge.confidence,
+            "ctype": str(edge.call_type),
+            "line": edge.line,
+        },
+    )
+
+
+def _write_external_call_edge(db: GraphDB, edge: ExternalCallEdge) -> bool:
+    """Write a CALLS_EXTERN edge (Function -> ExternalFunction).
+
+    Args:
+        db: Active database connection.
+        edge: The `ExternalCallEdge` describing the caller and external target.
+
+    Returns:
+        ``True`` if the edge was stored, ``False`` if either endpoint was
+        not found or the write failed.
+    """
+    return _exec(
+        db,
+        "MATCH (a:Function {id: $src}), (b:ExternalFunction {full_ref: $dst}) "
+        "CREATE (a)-[:CALLS_EXTERN {line: $line}]->(b) RETURN count(*)",
+        {
+            "src": edge.caller_id,
+            "dst": edge.full_ref,
+            "line": edge.line,
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+
+def _exec(db: GraphDB, query: str, params: dict[str, object]) -> bool:
+    """Execute an edge ``MATCH ... CREATE ... RETURN count(*)``; report if it stored one.
+
+    A MATCH that finds no endpoint yields no row, so the CREATE silently
+    does nothing and ``count(*)`` is 0 (verified against LadybugDB: a
+    matching statement returns ``[[1]]``, a non-matching one ``[[0]]``).
+    Neither a missing endpoint nor a DB error aborts the batch; both are
+    logged at DEBUG level.
+
+    Args:
+        db: Active database connection.
+        query: The Cypher edge statement, ending in ``RETURN count(*)``.
+        params: Key-value pairs for query parameterization.
+
+    Returns:
+        ``True`` if exactly one edge was created, ``False`` otherwise.
+    """
+    try:
+        row = as_row(db.execute(query, params))
+    except Exception:
+        logger.debug(
+            "DB write failed — query: %s | params: %s", query.strip(), params, exc_info=True
+        )
+        return False
+    stored = int(row[0]) == 1
+    if not stored:
+        logger.debug("Edge not stored (endpoint missing) — params: %s", params)
+    return stored

compass_core/index/__init__.py

@@ -0,0 +1 @@
+"""Locating and describing the on-disk Compass index."""

compass_core/index/freshness.py

@@ -0,0 +1,55 @@
+"""Whether indexed files changed on disk since the last ingest.
+
+Pure file-system checks with no database access: the caller supplies the indexed
+paths (the query layer reads them from the graph) and the ingest time from
+``metadata.json``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def is_stale(path: Path, indexed_at: int) -> bool:
+    """Whether a file is missing or was modified after the ingest.
+
+    Metadata stores whole seconds, so mtimes are compared at second resolution to keep
+    a just-ingested file from looking stale. Consequently an edit made within the same
+    second as the ingest is invisible (a false negative).
+
+    Args:
+        path: Absolute path of an indexed file.
+        indexed_at: Ingest time in epoch seconds.
+
+    Returns:
+        ``True`` if the file no longer exists or its mtime is later than ``indexed_at``.
+
+    Example:
+        After ``touch app/auth.py`` post-ingest,
+        ``is_stale(Path("/repo/app/auth.py"), meta_indexed_at)`` returns ``True``.
+    """
+    try:
+        return int(path.stat().st_mtime) > indexed_at
+    except OSError:
+        return True
+
+
+def count_stale(repo_root: Path, paths: Iterable[str], indexed_at: int) -> int:
+    """Count the indexed files that are missing or changed since the ingest.
+
+    Every path is stat'ed on each call, so callers may want to cache the result.
+
+    Args:
+        repo_root: Absolute repository root.
+        paths: Repo-relative POSIX paths of the indexed files.
+        indexed_at: Ingest time in epoch seconds.
+
+    Returns:
+        How many of ``paths`` are stale.
+
+    Example:
+        With ``app/auth.py`` deleted after ingest,
+        ``count_stale(Path("/repo"), ["app/auth.py", "app/db.py"], t)`` returns ``1``.
+    """
+    return sum(1 for path in paths if is_stale(repo_root / path, indexed_at))

compass_core/index/locate.py

@@ -0,0 +1,155 @@
+"""Locate the on-disk Compass index."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from compass_core.errors import IndexNotFoundError
+from compass_core.index.metadata import load_metadata
+from compass_core.settings import settings
+
+_INDEX_DIR = ".compass"
+_DB_NAME = "graph.ladybug"
+_META_NAME = "metadata.json"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class IndexLocation:
+    """Where an index lives on disk.
+
+    Attributes:
+        repo_root: Directory that contains ``.compass/``.
+        db_path: Path to ``graph.ladybug``.
+        metadata_path: Path to ``metadata.json``.
+
+    Example:
+        ``find_index(Path("/repo/pkg"))`` with ``/repo/.compass/graph.ladybug`` present
+        returns ``IndexLocation(repo_root=Path("/repo"), ...)``.
+    """
+
+    repo_root: Path
+    db_path: Path
+    metadata_path: Path
+
+
+def metadata_path_for(db_path: Path) -> Path:
+    """Where the metadata of the database at ``db_path`` lives: beside it.
+
+    Args:
+        db_path: Path to a ``graph.ladybug`` database.
+
+    Returns:
+        ``db_path.parent / "metadata.json"``.
+
+    Example:
+        ``metadata_path_for(Path("/repo/.compass/graph.ladybug"))`` returns
+        ``Path("/repo/.compass/metadata.json")``.
+    """
+    return db_path.parent / _META_NAME
+
+
+def _location(repo_root: Path) -> IndexLocation:
+    base = repo_root / _INDEX_DIR
+    return IndexLocation(
+        repo_root=repo_root, db_path=base / _DB_NAME, metadata_path=base / _META_NAME
+    )
+
+
+def find_index(start: Path) -> IndexLocation | None:
+    """Walk up from ``start`` to the first directory holding ``.compass/graph.ladybug``.
+
+    Args:
+        start: Directory to begin searching from.
+
+    Returns:
+        The location, or ``None`` if none exists up to the filesystem root.
+    """
+    for candidate in (start, *start.parents):
+        if (candidate / _INDEX_DIR / _DB_NAME).exists():
+            return _location(candidate)
+    return None
+
+
+def require_index(start: Path, override: Path | None = None) -> IndexLocation:
+    """Like ``find_index`` but an explicit ``override`` db path wins, and a miss raises.
+
+    Args:
+        start: Directory to begin searching from.
+        override: Explicit path to a ``graph.ladybug`` file.
+
+    Returns:
+        The index location.
+
+    Raises:
+        IndexNotFoundError: If nothing is found.
+    """
+    if override is not None:
+        return IndexLocation(
+            repo_root=override.parent.parent,
+            db_path=override,
+            metadata_path=metadata_path_for(override),
+        )
+    location = find_index(start)
+    if location is None:
+        raise IndexNotFoundError(searched_from=start)
+    return location
+
+
+def locate_index(start: Path | None = None) -> IndexLocation:
+    """Find and check the index every adapter should use: ``LADYBUG_DB_PATH``, else walk up.
+
+    When the configured ``LADYBUG_DB_PATH`` exists it wins, resolved so ``repo_root``
+    is absolute whatever the working directory. Otherwise the index is found by
+    walking up from ``start``, as git does with ``.git/``. Its metadata is then read, so
+    an index built by an incompatible version of compass is rejected before any query.
+
+    Args:
+        start: Directory to search from; defaults to the working directory.
+
+    Returns:
+        The index location.
+
+    Raises:
+        IndexNotFoundError: If no configured index exists and none is found above
+            ``start``.
+        IndexIncompatibleError: If the index's metadata is unreadable or its schema
+            version is not the one this compass reads; the message says to re-ingest.
+
+    Example:
+        Run from ``/repo/pkg`` with ``/repo/.compass/graph.ladybug`` present and the
+        default ``LADYBUG_DB_PATH``, ``locate_index()`` returns
+        ``IndexLocation(repo_root=Path("/repo"), ...)``.
+    """
+    origin = start if start is not None else Path.cwd()
+    configured = Path(settings.LADYBUG_DB_PATH).resolve()
+    location = (
+        require_index(origin, override=configured) if configured.exists() else require_index(origin)
+    )
+    load_metadata(location.metadata_path)
+    return location
+
+
+def locate_repo_index(repo: Path) -> IndexLocation:
+    """Find and check the index of an explicitly named repository.
+
+    Unlike ``locate_index`` this ignores ``LADYBUG_DB_PATH``: the caller named the
+    repository, so a configured path elsewhere must not win.
+
+    Args:
+        repo: The repository, or any directory inside it.
+
+    Returns:
+        The index location.
+
+    Raises:
+        IndexNotFoundError: If no index is found at or above ``repo``.
+        IndexIncompatibleError: If the index must be rebuilt with ``compass ingest``.
+
+    Example:
+        ``locate_repo_index(Path("~/src/app").expanduser())`` returns the index in
+        ``~/src/app/.compass/``.
+    """
+    location = require_index(repo.resolve())
+    load_metadata(location.metadata_path)
+    return location