compass-code 0.1.0__py3-none-any.whl

compass_core/query/impact.py

@@ -0,0 +1,273 @@
+"""Impact analysis: what may break if a file or symbol changes.
+
+Semantics follow the query-layer design (section 4.2). A symbol target walks reverse
+``CALLS`` (a class also pulls in subclasses and callers of its methods); a file target
+walks importers, files of callers and files of subclasses. The walks live in
+``impact_walk``; this module resolves the reference, orders, groups and truncates the
+items, and adds the ``UNRESOLVED_CALLS`` and ``STALE_INDEX`` caveats.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from itertools import groupby
+
+from compass_core.contract.models import Caveat, EdgeRef, ResultItem, SymbolRef
+from compass_core.contract.params import ImpactParams
+from compass_core.contract.results import ImpactGroup, ImpactResult, Lookup
+from compass_core.contract.types import CaveatCode, RepoPath
+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_walk import Walk, walk_files, walk_key, walk_symbols
+from compass_core.query.references import ResolvedReference, resolve
+from compass_core.query.rows import text_list_value, text_value
+from compass_core.query.status import index_status
+from compass_core.shared_types import SymbolKind
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RawCaller:
+    """A function with raw call sites, and the names its resolved edges reach.
+
+    Attributes:
+        key: Id of the function.
+        path: Its file path.
+        raw_calls: Its raw call strings, in source order.
+        reached: Names of the functions and externals it has a ``CALLS`` or
+            ``CALLS_EXTERN`` edge to.
+
+    Example:
+        ``def run(): parse(x); getattr(o, n)()`` with only ``parse`` resolved gives
+        ``RawCaller(key="app/cli.py::run", path="app/cli.py",
+        raw_calls=("parse", "getattr(o, n)"), reached=frozenset({"parse"}))``.
+    """
+
+    key: str
+    path: str
+    raw_calls: tuple[str, ...]
+    reached: frozenset[str]
+
+
+RAW_CALLERS: Query[RawCaller] = Query(
+    """
+    MATCH (f:Function) WHERE size(f.raw_calls) > 0
+    OPTIONAL MATCH (f)-[:CALLS]->(g:Function) WITH f, collect(g.name) AS internal
+    OPTIONAL MATCH (f)-[:CALLS_EXTERN]->(x:ExternalFunction)
+    RETURN f.id, f.file_path, f.raw_calls, internal, collect(x.name)
+    """,
+    lambda row: RawCaller(
+        key=text_value(row[0], "id"),
+        path=text_value(row[1], "file_path"),
+        raw_calls=text_list_value(row[2], "raw_calls"),
+        reached=frozenset(text_list_value(row[3], "name") + text_list_value(row[4], "name")),
+    ),
+)
+"""Every function with raw calls, with the names its resolved edges reach."""
+
+
+def _name(row: Row) -> str:
+    return text_value(row[0], "name")
+
+
+_METHOD_NAMES: Query[str] = Query(
+    "MATCH (c:Class)-[:CONTAINS]->(m:Function) WHERE c.id IN $ids RETURN m.name", _name
+)
+_FILE_DEFINITION_NAMES: Query[str] = Query(
+    """
+    MATCH (f:Function) WHERE f.file_path = $path RETURN f.name
+    UNION MATCH (c:Class) WHERE c.file_path = $path RETURN c.name
+    """,
+    _name,
+)
+"""Names of every definition in a file: functions, methods and classes."""
+
+
+def bare_call_name(raw_call: str) -> str:
+    """The called name of a raw call string: last dotted segment, arguments removed.
+
+    Args:
+        raw_call: A ``Function.raw_calls`` entry.
+
+    Returns:
+        The bare name, or ``""`` when nothing is left.
+
+    Example:
+        ``bare_call_name("User().save")`` returns ``"save"``;
+        ``bare_call_name("getattr(obj, name)")`` returns ``"getattr"``.
+    """
+    depth = 0
+    kept: list[str] = []
+    for char in raw_call:
+        if char == "(":
+            depth += 1
+        elif char == ")":
+            depth = max(depth - 1, 0)
+        elif depth == 0:
+            kept.append(char)
+    return "".join(kept).rsplit(".", 1)[-1].strip()
+
+
+def _watched_names(db: GraphDB, target: SymbolRef, target_key: str, walk: Walk) -> set[str]:
+    """Bare names whose unresolved calls may hide callers: the target, every affected
+    symbol and the methods of the target and affected classes."""
+    names = {target.name} | {r.item.symbol.name for r in walk.reached}
+    classes = [r.key for r in walk.reached if r.item.symbol.kind is SymbolKind.CLASS]
+    if target.kind is SymbolKind.CLASS:
+        classes.append(target_key)
+    if classes:
+        names |= set(_METHOD_NAMES.run(db, {"ids": sorted(classes)}))
+    return names
+
+
+def _file_watched_names(db: GraphDB, path: str) -> set[str]:
+    """Bare names whose unresolved calls may hide dependents of the file at ``path``:
+    every function, method and class defined in it."""
+    return set(_FILE_DEFINITION_NAMES.run(db, {"path": path}))
+
+
+def _unresolved_callers(
+    db: GraphDB, names: set[str], *, skip_id: str | None = None, skip_file: str | None = None
+) -> set[str]:
+    """Functions with a raw call to one of ``names`` that resolved to no edge to a
+    function (or external) of that name.
+
+    Only such calls can hide further callers of the target; a dependent's other
+    unresolved calls (builtins, methods on locals) cannot, so they are not counted.
+
+    Args:
+        db: Open graph database.
+        names: Watched bare names.
+        skip_id: Id of a function not to count (the symbol target itself).
+        skip_file: Path whose functions are not counted (the file target).
+
+    Returns:
+        The ids of the flagged functions.
+    """
+    found: set[str] = set()
+    for caller in RAW_CALLERS.run(db):
+        if caller.key == skip_id or caller.path == skip_file:
+            continue
+        called = {bare_call_name(c) for c in caller.raw_calls}
+        if (called & names) - caller.reached:
+            found.add(caller.key)
+    return found
+
+
+def _unresolved_caveat(functions: set[str]) -> tuple[Caveat, ...]:
+    count = len(functions)
+    if not count:
+        return ()
+    noun = "function contains" if count == 1 else "functions contain"
+    message = f"{count} {noun} calls that could not be resolved; there may be more callers"
+    return (Caveat(code=CaveatCode.UNRESOLVED_CALLS, message=message, count=count),)
+
+
+def _stale_caveat(stale: int) -> tuple[Caveat, ...]:
+    if not stale:
+        return ()
+    noun = "file has" if stale == 1 else "files have"
+    message = f"{stale} indexed {noun} changed since the last ingest; run `compass ingest`"
+    return (Caveat(code=CaveatCode.STALE_INDEX, message=message, count=stale),)
+
+
+def _file_of(item: ResultItem) -> RepoPath:
+    path = item.symbol.file_path
+    assert path is not None, "impact walks only reach files and definitions"
+    return path
+
+
+def _groups(items: Sequence[ResultItem]) -> tuple[ImpactGroup, ...]:
+    """Group already-sorted items by ``(distance, file_path)``."""
+    return tuple(
+        ImpactGroup(distance=distance, file_path=path, items=tuple(members))
+        for (distance, path), members in groupby(items, key=lambda i: (i.distance, _file_of(i)))
+    )
+
+
+def _edges(walk: Walk, kept: Iterable[ResultItem]) -> tuple[EdgeRef, ...]:
+    """Edges owned by the kept items, deduplicated and in a stable order."""
+    ids = {i.symbol.id for i in kept}
+    unique = {owned.edge for owned in walk.edges if owned.owner in ids}
+    return tuple(sorted(unique, key=lambda e: (e.type, e.source_id, e.target_id, e.line or 0)))
+
+
+def _walk(db: GraphDB, target: SymbolRef, params: ImpactParams) -> tuple[Walk, set[str]]:
+    """Run the walk for ``target`` and collect the functions behind its caveat."""
+    key = walk_key(target)
+    depth, min_confidence = params.depth, params.min_confidence
+    if target.kind is SymbolKind.FILE:
+        walk = walk_files(db, target, depth=depth, min_confidence=min_confidence)
+        return walk, _unresolved_callers(db, _file_watched_names(db, key), skip_file=key)
+    walk = walk_symbols(db, target, depth=depth, min_confidence=min_confidence)
+    return walk, _unresolved_callers(db, _watched_names(db, target, key, walk), skip_id=key)
+
+
+def impact(
+    db: GraphDB, location: IndexLocation, ref: str, params: ImpactParams
+) -> Lookup[ImpactResult]:
+    """List what may be affected by changing a file or symbol.
+
+    Args:
+        db: Open, read-only graph database.
+        location: Index location, used for ``repo_root`` and the ``IndexStatus``.
+        ref: File path or symbol reference (section 4.1 rules; files allowed).
+        params: Depth, minimum ``CALLS`` confidence and item limit.
+
+    Returns:
+        An ``ImpactResult``, or the ``AmbiguousReference`` / ``SymbolNotFound`` from
+        resolution. Groups are ordered by distance then file path, items by name.
+        ``total`` counts items before the limit; ``affected_file_count`` counts the
+        distinct files of all items. A symbol target lists affected functions, methods
+        and classes; a file target lists one ``FILE`` item per affected file. An
+        external target (``ext::json.dumps``) lists its ``CALLS_EXTERN`` callers at
+        distance 1 (``min_confidence`` ``None``) and walks reverse ``CALLS`` from there.
+        Each item's ``min_confidence`` is that of the chosen shortest path (see
+        ``impact_walk`` for tie-breaks), not the best path overall. ``edges`` are the
+        edges traversed from the returned items; their endpoints may not be items
+        (non-tree edges, and function/class-level edges behind a file dependency).
+
+    Raises:
+        IndexIncompatibleError: A stored row or the index metadata is unreadable.
+
+    Note:
+        ``UNRESOLVED_CALLS`` counts functions that have a raw call to a watched bare
+        name with no resolved edge to a function or external of that name. For a
+        symbol target the watched names are the target, every affected symbol and
+        the methods of the target and affected classes (the target itself is not
+        counted); for a file target they are the names of every function, method and
+        class defined in the file (its own functions are not counted). A dependent's
+        other unresolved calls (builtins, methods on locals) are not counted.
+        ``min_confidence`` is compared with a ``1e-6`` tolerance because stored
+        confidences are float32. Overriding methods in subclasses are not walked.
+
+    Example:
+        ``impact(db, loc, "app/auth.py::decode_token", ImpactParams(depth=2))`` returns
+        ``handle``, ``run`` and ``nightly`` at distance 1 (``via`` calls
+        ``decode_token``, ``min_confidence`` 1.0) and ``tick`` at distance 2.
+    """
+    status = index_status(location, db)  # first: rejects an incompatible index
+    repo_root = location.repo_root.resolve()
+    resolved = resolve(db, ref, repo_root=repo_root, allow_file=True)
+    if not isinstance(resolved, ResolvedReference):
+        return resolved
+    target = resolved.symbol
+    walk, unresolved = _walk(db, target, params)
+    items = sorted(
+        (r.item for r in walk.reached),
+        key=lambda i: (i.distance, _file_of(i), i.symbol.name, i.symbol.id),
+    )
+    kept = items[: params.limit]
+    return ImpactResult(
+        index=status,
+        caveats=_unresolved_caveat(unresolved) + _stale_caveat(status.stale_file_count),
+        target=target,
+        matched_by=resolved.rule,
+        depth=params.depth,
+        groups=_groups(kept),
+        affected_file_count=len({_file_of(i) for i in items}),
+        edges=_edges(walk, kept),
+        total=len(items),
+        truncated=len(items) > params.limit,
+    )

compass_core/query/impact_walk.py

@@ -0,0 +1,352 @@
+"""Breadth-first reverse walks behind ``impact``.
+
+Each walk expands one distance level at a time with a fixed set of parameterized,
+single-hop queries (``WHERE x IN $ids``), so the cost is one query per level per edge
+family, never one per node. Nodes are keyed by ``walk_key``: the id of a definition, the
+path of a file; a node is visited once, at its shortest distance, so cycles terminate and
+the target never lists itself. ``CALLS`` edges below ``min_confidence`` are not traversed;
+stored confidences are float32, so the threshold is compared with a ``1e-6`` tolerance
+(a stored ``0.9`` reads back as ``0.8999999761``).
+
+The recorded edges are every edge traversed from an affected node, including non-tree
+edges (a second, equally short or longer route) and, for file targets, the function- and
+class-level edges behind a file dependency, so an edge endpoint may not be an item.
+
+When several edges reach a new node at the same distance, the winner is chosen by via
+kind (``IMPORTS`` before ``CALLS`` before ``INHERITS``), then by the higher path
+confidence, then by the via symbol's id, so results are deterministic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from compass_core.contract.models import EdgeRef, ResultItem, SymbolRef, Via
+from compass_core.contract.types import SymbolId, ViaKind
+from compass_core.errors import IndexIncompatibleError
+from compass_core.graph.db import GraphDB
+from compass_core.query.references import FILES_AT_PATHS
+from compass_core.query.walk_queries import (
+    CALLERS_IN_FILES,
+    CALLERS_OF_EXTERNALS,
+    CALLERS_OF_FUNCTIONS,
+    CALLERS_OF_METHODS,
+    IMPORTERS_OF_FILES,
+    SUBCLASSES_IN_FILES,
+    SUBCLASSES_OF,
+    CallRow,
+    ExternalCallRow,
+)
+from compass_core.shared_types import EdgeType, SymbolKind
+
+_PRIORITY = {ViaKind.IMPORTS: 0, ViaKind.CALLS: 1, ViaKind.INHERITS: 2}
+_CONFIDENCE_TOLERANCE = 1e-6
+
+
+def _threshold(min_confidence: float) -> float:
+    """The ``$minc`` parameter: ``min_confidence`` lowered by the float32 tolerance."""
+    return min_confidence - _CONFIDENCE_TOLERANCE
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Reached:
+    """A node the walk reached, with the item describing how.
+
+    Attributes:
+        key: ``walk_key`` of the node: id of a definition, path of a file.
+        item: Distance, via and path confidence of the node.
+
+    Example:
+        ``Reached(key="app/jobs.py::nightly", item=ResultItem(symbol=<nightly>,
+        distance=1, via=Via(kind=ViaKind.CALLS, symbol=<decode_token>),
+        min_confidence=1.0))``
+    """
+
+    key: str
+    item: ResultItem
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OwnedEdge:
+    """A traversed edge and the affected item it belongs to.
+
+    Attributes:
+        owner: Public id of the affected item that the edge pulled in or leaves from;
+            used to drop edges of items cut by the result limit.
+        edge: The traversed edge.
+
+    Example:
+        ``OwnedEdge(owner=SymbolId("file::app/api.py"), edge=<api.py IMPORTS auth.py>)``
+    """
+
+    owner: SymbolId
+    edge: EdgeRef
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Walk:
+    """Everything a walk reached.
+
+    Attributes:
+        reached: Affected nodes in discovery order (the target is never included).
+        edges: Traversed edges whose owner is an affected node, deduplicated.
+
+    Example:
+        Walking callers of ``decode_token`` at depth 1 yields three ``Reached`` items
+        (``handle``, ``run``, ``nightly``) and their three ``CALLS`` edges.
+    """
+
+    reached: tuple[Reached, ...]
+    edges: tuple[OwnedEdge, ...]
+
+
+class _Walker:
+    """Mutable BFS bookkeeping shared by the symbol and file walks."""
+
+    def __init__(self, target_key: str, target: SymbolRef) -> None:
+        self.symbols: dict[str, SymbolRef] = {target_key: target}
+        self._visited: set[str] = {target_key}
+        self._path_min: dict[str, float | None] = {target_key: None}
+        self._reached: list[Reached] = []
+        self._level: dict[str, tuple[tuple[int, float, str], Reached]] = {}
+        self._edges: list[tuple[str, EdgeRef]] = []
+
+    def offer(
+        self,
+        key: str,
+        symbol: SymbolRef,
+        distance: int,
+        via: Via,
+        parent_key: str,
+        confidence: float | None,
+    ) -> None:
+        """Propose ``symbol`` at ``distance``; the best proposal per level wins."""
+        if key in self._visited:
+            return
+        path = self._path_min.get(parent_key)
+        if confidence is not None:
+            path = confidence if path is None else min(path, confidence)
+        rank = (_PRIORITY[via.kind], -(1.0 if path is None else path), via.symbol.id)
+        current = self._level.get(key)
+        if current is None or rank < current[0]:
+            item = ResultItem(symbol=symbol, distance=distance, via=via, min_confidence=path)
+            self._level[key] = (rank, Reached(key=key, item=item))
+
+    def edge(self, owner_key: str, edge: EdgeRef) -> None:
+        """Record a traversed edge owned by the node ``owner_key``."""
+        self._edges.append((owner_key, edge))
+
+    def close_level(self) -> list[str]:
+        """Commit this level's proposals; return the new frontier keys, sorted."""
+        new = sorted(self._level)
+        for key in new:
+            reached = self._level[key][1]
+            self._visited.add(key)
+            self._path_min[key] = reached.item.min_confidence
+            self.symbols[key] = reached.item.symbol
+            self._reached.append(reached)
+        self._level = {}
+        return new
+
+    def result(self) -> Walk:
+        """The walk so far; edges are kept only when their owner was reached."""
+        owners = {r.key: r.item.symbol.id for r in self._reached}
+        seen: set[tuple[SymbolId, EdgeRef]] = set()
+        edges: list[OwnedEdge] = []
+        for owner_key, edge in self._edges:
+            owner = owners.get(owner_key)
+            if owner is not None and (owner, edge) not in seen:
+                seen.add((owner, edge))
+                edges.append(OwnedEdge(owner=owner, edge=edge))
+        return Walk(reached=tuple(self._reached), edges=tuple(edges))
+
+
+def _structural_edge(source: SymbolRef, target: SymbolRef, kind: EdgeType) -> EdgeRef:
+    """An ``IMPORTS`` or ``INHERITS`` edge (no confidence, call type or line)."""
+    return EdgeRef(
+        source_id=source.id,
+        target_id=target.id,
+        type=kind,
+        confidence=None,
+        call_type=None,
+        line=None,
+    )
+
+
+def walk_key(symbol: SymbolRef) -> str:
+    """The key a walk uses for a node: what the graph matches the node on.
+
+    Args:
+        symbol: A file, class, function, method or external function.
+
+    Returns:
+        The id of a class or function, the path of a file, the full reference of an
+        external function.
+
+    Example:
+        ``<app/auth.py::parse>`` maps to ``"app/auth.py::parse"``, ``<file::app/a.py>`` to
+        ``"app/a.py"`` and ``<ext::json.dumps>`` to ``"json.dumps"``.
+    """
+    if symbol.kind is SymbolKind.FILE:
+        assert symbol.file_path is not None, "a file symbol always has a path"
+        return symbol.file_path
+    if symbol.kind is SymbolKind.EXTERNAL:
+        return symbol.id.removeprefix("ext::")
+    return symbol.id
+
+
+def walk_symbols(db: GraphDB, target: SymbolRef, *, depth: int, min_confidence: float) -> Walk:
+    """Walk reverse ``CALLS`` (and, for classes, reverse ``INHERITS``) from a symbol.
+
+    A function or method in the frontier pulls in its callers (``Via(CALLS, callee)``).
+    A class in the frontier pulls in its subclasses (``Via(INHERITS, class)``) and the
+    callers of its methods (``Via(CALLS, method)``). An external target pulls in its
+    callers over ``CALLS_EXTERN`` (``Via(CALLS, external)``, no confidence); the walk then
+    continues over reverse ``CALLS``. Each item's ``min_confidence`` is that of the chosen
+    shortest path, not the best path overall.
+
+    Args:
+        db: Open graph database.
+        target: The resolved class, function, method or external function.
+        depth: Maximum distance.
+        min_confidence: ``CALLS`` edges below this are not traversed.
+
+    Returns:
+        The affected symbols and every edge traversed from them; an edge endpoint may
+        not be an item (non-tree edges, or the target's class methods).
+
+    Raises:
+        IndexIncompatibleError: A stored row does not have the expected shape.
+
+    Example:
+        From ``decode_token`` at depth 2 the walk reaches ``handle``, ``run`` and
+        ``nightly`` at distance 1 and ``tick`` (which calls ``nightly``) at distance 2.
+    """
+    target_key = walk_key(target)
+    walker = _Walker(target_key, target)
+    frontier = [target_key]
+    for distance in range(1, depth + 1):
+        kinds = {k: walker.symbols[k].kind for k in frontier}
+        functions = [k for k in frontier if kinds[k] in (SymbolKind.FUNCTION, SymbolKind.METHOD)]
+        classes = [k for k in frontier if kinds[k] is SymbolKind.CLASS]
+        externals = [k for k in frontier if kinds[k] is SymbolKind.EXTERNAL]
+        if externals:
+            for ext in CALLERS_OF_EXTERNALS.run(db, {"ids": externals}):
+                _offer_external_caller(walker, ext, distance, target_key)
+        minc = _threshold(min_confidence)
+        if functions:
+            for call in CALLERS_OF_FUNCTIONS.run(db, {"ids": functions, "minc": minc}):
+                _offer_caller(walker, call, distance, call.callee.id)
+        if classes:
+            params = {"ids": classes, "minc": minc}
+            for method_call in CALLERS_OF_METHODS.run(db, params):
+                _offer_caller(walker, method_call.call, distance, method_call.class_key)
+            for pair in SUBCLASSES_OF.run(db, {"ids": classes}):
+                child, parent = pair.source, pair.target
+                via = Via(kind=ViaKind.INHERITS, symbol=parent)
+                walker.offer(child.id, child, distance, via, parent.id, None)
+                walker.edge(child.id, _structural_edge(child, parent, EdgeType.INHERITS))
+        frontier = walker.close_level()
+        if not frontier:
+            break
+    return walker.result()
+
+
+def _offer_caller(walker: _Walker, call: CallRow, distance: int, parent_key: str) -> None:
+    via = Via(kind=ViaKind.CALLS, symbol=call.callee)
+    walker.offer(call.caller.id, call.caller, distance, via, parent_key, call.confidence)
+    walker.edge(call.caller.id, call.edge)
+
+
+def _offer_external_caller(
+    walker: _Walker, ext: ExternalCallRow, distance: int, external_key: str
+) -> None:
+    external = walker.symbols[external_key]
+    via = Via(kind=ViaKind.CALLS, symbol=external)
+    walker.offer(ext.caller.id, ext.caller, distance, via, external_key, None)
+    edge = EdgeRef(
+        source_id=ext.caller.id,
+        target_id=external.id,
+        type=EdgeType.CALLS_EXTERN,
+        confidence=None,
+        call_type=None,
+        line=ext.line,
+    )
+    walker.edge(ext.caller.id, edge)
+
+
+def walk_files(db: GraphDB, target: SymbolRef, *, depth: int, min_confidence: float) -> Walk:
+    """Walk dependent files: importers, files of callers and files of subclasses.
+
+    Each affected file is one ``FILE`` item. Its via is ``IMPORTS`` (symbol: the
+    imported file), ``CALLS`` (symbol: the called function) or ``INHERITS`` (symbol:
+    the base class), whichever reaches it first.
+
+    Args:
+        db: Open graph database.
+        target: The resolved file.
+        depth: Maximum distance.
+        min_confidence: ``CALLS`` edges below this are not traversed.
+
+    Returns:
+        The affected files and the edges traversed (``IMPORTS`` between files,
+        ``CALLS`` and ``INHERITS`` between the definitions involved). Endpoints of the
+        ``CALLS`` and ``INHERITS`` edges are functions and classes, never items here.
+
+    Raises:
+        IndexIncompatibleError: A stored row does not have the expected shape.
+
+    Example:
+        From ``app/auth.py`` at depth 2: ``app/api.py``, ``app/cli.py``,
+        ``app/jobs.py`` and ``app/__init__.py`` at distance 1 (they import it) and
+        ``app/scheduler.py`` at distance 2 (it imports ``app/jobs.py``).
+    """
+    target_key = walk_key(target)
+    walker = _Walker(target_key, target)
+    frontier = [target_key]
+    for distance in range(1, depth + 1):
+        # (owner path, via, parent path, confidence) per proposal; files resolved below.
+        pending: list[tuple[str, Via, str, float | None]] = []
+        for pair in IMPORTERS_OF_FILES.run(db, {"paths": frontier}):
+            importer, imported = pair.source, pair.target
+            importer_key = walk_key(importer)
+            walker.symbols.setdefault(importer_key, importer)
+            via = Via(kind=ViaKind.IMPORTS, symbol=imported)
+            pending.append((importer_key, via, walk_key(imported), None))
+            walker.edge(importer_key, _structural_edge(importer, imported, EdgeType.IMPORTS))
+        params = {"paths": frontier, "minc": _threshold(min_confidence)}
+        for call in CALLERS_IN_FILES.run(db, params):
+            owner = _path(call.caller)
+            via = Via(kind=ViaKind.CALLS, symbol=call.callee)
+            pending.append((owner, via, _path(call.callee), call.confidence))
+            walker.edge(owner, call.edge)
+        for pair in SUBCLASSES_IN_FILES.run(db, {"paths": frontier}):
+            child, parent = pair.source, pair.target
+            via = Via(kind=ViaKind.INHERITS, symbol=parent)
+            pending.append((_path(child), via, _path(parent), None))
+            walker.edge(_path(child), _structural_edge(child, parent, EdgeType.INHERITS))
+        _load_files(db, walker, [p[0] for p in pending])
+        for owner, via, parent_path, path_confidence in pending:
+            walker.offer(owner, walker.symbols[owner], distance, via, parent_path, path_confidence)
+        frontier = walker.close_level()
+        if not frontier:
+            break
+    return walker.result()
+
+
+def _path(symbol: SymbolRef) -> str:
+    """The file path of a class or function, which keys its file in a file walk."""
+    assert symbol.file_path is not None, "definitions always have a file path"
+    return symbol.file_path
+
+
+def _load_files(db: GraphDB, walker: _Walker, paths: list[str]) -> None:
+    """Make sure every stored path in ``paths`` has a ``FILE`` symbol (one query)."""
+    missing = sorted({p for p in paths if p not in walker.symbols})
+    if not missing:
+        return
+    for file in FILES_AT_PATHS.run(db, {"paths": missing}):
+        walker.symbols[walk_key(file)] = file
+    absent = [p for p in missing if p not in walker.symbols]
+    if absent:
+        raise IndexIncompatibleError(f"definitions reference unindexed files: {absent}")