codegraph-brain 0.6.0__py3-none-any.whl

cgis/resolver/engine.py

@@ -0,0 +1,145 @@
+"""Implements ResolverEngine class."""
+
+from cgis.core.models import (
+    RAW_CLASS_PREFIX,
+    SELF_PREFIX,
+    VIRTUAL_FILE_PATH,
+    Edge,
+    Node,
+    NodeNamespace,
+    NodeType,
+)
+from cgis.resolver.symbols import SymbolResolver
+
+RAW_DEP_PREFIX = "raw_dep:"
+RAW_IMPORT_PREFIX = "raw_import:"
+
+
+class ResolverEngine:
+    """
+    The 'Brain' of the CGIS.
+    Transforms 'raw' semantic edges into resolved, high-confidence edges.
+
+    Thin facade: SymbolResolver builds the SymbolIndex internally (via
+    IndexBuilder), maps raw names to FQNs, and this class keeps edge
+    finalization — confidence policy, edge rewrites, and virtual-node
+    creation (spec §2.5).
+    """
+
+    def __init__(self, nodes: list[Node], edges: list[Edge]) -> None:
+        """Build the symbol resolver (which builds the index) from the extracted graph."""
+        self.edges = edges
+        self._resolver = SymbolResolver(nodes, edges)
+        self._index = self._resolver.index
+
+    def resolve(self) -> tuple[list[Edge], list[Node]]:
+        """
+        Phase 3: The Linking Pass.
+        Resolves raw_call targets to FQNs in a single pass. Virtual nodes for
+        boundary symbols (STDLIB/EXTERNAL/UNKNOWN) are created on the fly as
+        each edge target is finalized.
+
+        Returns (resolved_edges, virtual_nodes).
+        """
+        resolved_edges: list[Edge] = []
+        virtual_nodes: dict[str, Node] = {}
+
+        for edge in self.edges:
+            if edge.target.startswith(RAW_CLASS_PREFIX):
+                class_edge = self._resolved_class_edge(edge)
+                resolved_edges.append(class_edge)
+                self._ensure_virtual_node(class_edge.target, virtual_nodes)
+            elif edge.target.startswith(RAW_DEP_PREFIX):
+                dep_edge = self._resolved_dep_edge(edge)
+                if dep_edge is not None:
+                    resolved_edges.append(dep_edge)
+            elif edge.target.startswith(RAW_IMPORT_PREFIX):
+                import_edge = self._resolved_import_edge(edge)
+                if import_edge is not None:
+                    resolved_edges.append(import_edge)
+                # no _ensure_virtual_node: target exists on hit, edge dies on miss
+            elif not edge.target.startswith("raw_call:"):
+                resolved_edges.append(edge)
+                self._ensure_virtual_node(edge.target, virtual_nodes)
+            else:
+                call_edge = self._resolved_call_edge(edge)
+                resolved_edges.append(call_edge)
+                self._ensure_virtual_node(call_edge.target, virtual_nodes)
+
+        return resolved_edges, list(virtual_nodes.values())
+
+    def _resolved_class_edge(self, edge: Edge) -> Edge:
+        """Resolve a raw_class: edge to its final class FQN.
+
+        Strips the raw_class: prefix, resolves via SymbolResolver, then
+        returns a copy of the edge with the resolved target (confidence 1.0) or
+        the bare name as fallback (confidence 0.5).
+        """
+        raw = edge.target.removeprefix(RAW_CLASS_PREFIX)
+        resolved = self._resolver.resolve_class_ref(raw, edge.source, edge.file_path)
+        final_target = resolved or raw
+        confidence = 1.0 if resolved else 0.5
+        return edge.model_copy(update={"target": final_target, "confidence": confidence})
+
+    def _resolved_call_edge(self, edge: Edge) -> Edge:
+        """Resolve a raw_call: edge to its final call target FQN.
+
+        Strips the raw_call: prefix, dispatches to resolve_self_call for
+        self.* calls or resolve_global_call otherwise, then returns a copy of
+        the edge with the resolved target and adjusted confidence:
+        min(edge.confidence + 0.5, 1.0) on success, 0.8 on failure.
+        """
+        raw_name = edge.target.removeprefix("raw_call:")
+        if raw_name.startswith(SELF_PREFIX):
+            new_target = self._resolver.resolve_self_call(
+                edge.source, raw_name.removeprefix(SELF_PREFIX)
+            )
+        else:
+            new_target = self._resolver.resolve_global_call(raw_name, edge.source, edge.file_path)
+        final_target = new_target or raw_name
+        confidence = min(edge.confidence + 0.5, 1.0) if new_target else 0.8
+        return edge.model_copy(update={"target": final_target, "confidence": confidence})
+
+    def _resolved_dep_edge(self, edge: Edge) -> Edge | None:
+        """Resolve a raw_dep: candidate edge, or None when it must be dropped (spec §3.3)."""
+        dep_name = edge.target.removeprefix(RAW_DEP_PREFIX)
+        dep_target = self._resolver.resolve_dep_candidate(dep_name, edge.source, edge.file_path)
+        if dep_target is None:
+            # Speculative candidate that is not a DI alias: drop the edge
+            # entirely — raw_dep: must never leak into output (spec §3.3).
+            return None
+        return edge.model_copy(update={"target": dep_target, "confidence": 1.0})
+
+    def _resolved_import_edge(self, edge: Edge) -> Edge | None:
+        """Resolve a raw_import: symbol edge, or None when it must be dropped.
+
+        Reuses SymbolIndex.map_to_node_fqn (exact / suffix / strip-prefix). An
+        external or unknown symbol drops the edge: the module-level IMPORTS
+        edge already captures the coupling — raw_import: never leaks into
+        output and never mints a virtual node (spec §2.2/§2.4).
+        """
+        imported_fqn = edge.target.removeprefix(RAW_IMPORT_PREFIX)
+        node_fqn = self._index.map_to_node_fqn(imported_fqn)
+        if node_fqn is None:
+            return None
+        return edge.model_copy(update={"target": node_fqn, "confidence": 1.0})
+
+    def _ensure_virtual_node(self, target: str, virtual_nodes: dict[str, Node]) -> None:
+        """Create a virtual boundary node for target if it is not already in the graph."""
+        if target not in self._index.nodes and target not in virtual_nodes:
+            virtual_nodes[target] = self._make_virtual_node(
+                target, self._index.classify_fqn(target)
+            )
+
+    def _make_virtual_node(self, fqn: str, namespace: NodeNamespace) -> Node:
+        """Create a placeholder node for an external/stdlib symbol."""
+        return Node(
+            id=fqn,
+            type=NodeType.FUNCTION,
+            name=fqn.rsplit(".", maxsplit=1)[-1],
+            file_path=VIRTUAL_FILE_PATH,
+            start_line=0,
+            end_line=0,
+            namespace=namespace,
+            confidence_score=0.8,
+        )

cgis/resolver/indices.py

@@ -0,0 +1,184 @@
+"""Symbol indices for FQN resolution: built once by IndexBuilder, read-only after."""
+
+import builtins
+import os
+import sys
+from dataclasses import dataclass
+
+from cgis.core.models import SELF_PREFIX, Node, NodeNamespace, NodeType
+
+_BUILTINS: frozenset[str] = frozenset(dir(builtins))
+
+
+@dataclass(frozen=True)
+class SymbolIndex:
+    """Immutable lookup indices over the extracted node set.
+
+    Built by IndexBuilder, consumed by SymbolResolver and ResolverEngine.
+    Frozen by convention (field rebinding prevented); the contained dicts
+    are never mutated after construction.
+    """
+
+    # node id (FQN) -> Node
+    nodes: dict[str, Node]
+    # name -> list of FQNs
+    global_symbols: dict[str, list[str]]
+    # (file_path, name) -> list of FQNs (list handles conditional redefinitions)
+    file_global_symbols: dict[tuple[str, str], list[str]]
+    # class_fqn -> {method_name -> method_fqn}
+    class_methods: dict[str, dict[str, str]]
+    # DI-alias (VARIABLE) indices for raw_dep: resolution; kept separate
+    # from global_symbols so call resolution behavior does not change.
+    variable_symbols: dict[str, list[str]]
+    file_variable_symbols: dict[tuple[str, str], list[str]]
+    # normalized file_path -> {local_alias: target_fqn}  (from FILE node import_map)
+    file_imports: dict[str, dict[str, str]]
+    # suffix_fqn -> [full_node_ids]  (handles src/ layout prefix mismatch)
+    suffix_map: dict[str, list[str]]
+    # top-level root segments of all internal nodes (for classify)
+    internal_roots: set[str]
+    # root segments of absolute imports (anything else is UNKNOWN)
+    external_roots: set[str]
+
+    def map_to_node_fqn(self, imported_fqn: str) -> str | None:
+        """Resolve an imported FQN to an actual node in the graph.
+
+        Handles two common prefix-mismatch patterns:
+        - Import has extra package prefix: `cgis.resolver.engine.X` → node `resolver.engine.X`
+          (strip leading segments from the imported FQN)
+        - Node has extra layout prefix: `cgis.pipeline.X` → node `src.cgis.pipeline.X`
+          (look up in suffix_map built from node IDs)
+
+        Returns None when the target is ambiguous or not in the graph.
+        """
+        if imported_fqn in self.nodes:
+            return imported_fqn
+        # Node has extra layout prefix (e.g. src/) — most precise match first
+        candidates = self.suffix_map.get(imported_fqn, [])
+        if len(candidates) == 1:
+            return candidates[0]
+        # Strip leading segments from the imported FQN (import has extra prefix)
+        parts = imported_fqn.split(".")
+        for i in range(1, len(parts)):
+            candidate = ".".join(parts[i:])
+            if candidate in self.nodes:
+                return candidate
+        return None
+
+    def classify_fqn(self, fqn: str) -> NodeNamespace:
+        """Classify an FQN as STDLIB, INTERNAL, EXTERNAL, or UNKNOWN.
+
+        UNKNOWN means the root segment was not found in internal roots,
+        stdlib/builtins, or any known import-map external root.
+        """
+        if fqn.startswith((".", SELF_PREFIX)):
+            return NodeNamespace.INTERNAL
+        root = fqn.split(".", maxsplit=1)[0]
+        if root in self.internal_roots:
+            return NodeNamespace.INTERNAL
+        if root in sys.stdlib_module_names or root in _BUILTINS:
+            return NodeNamespace.STDLIB
+        if root in self.external_roots:
+            return NodeNamespace.EXTERNAL
+        return NodeNamespace.UNKNOWN
+
+    def is_variable_node(self, fqn: str) -> bool:
+        """Return True when fqn names an existing VARIABLE node in the graph."""
+        node = self.nodes.get(fqn)
+        return node is not None and node.type == NodeType.VARIABLE
+
+    def normalized_file_path(self, source_fqn: str, edge_file_path: str | None) -> str | None:
+        """Return the normalized file path for a source FQN, falling back to edge_file_path."""
+        source_node = self.nodes.get(source_fqn)
+        if source_node:
+            return os.path.normpath(source_node.file_path)
+        return os.path.normpath(edge_file_path) if edge_file_path else None
+
+
+class IndexBuilder:
+    """Builds a SymbolIndex from extracted nodes (Phase 1: indexing).
+
+    Takes only nodes — never edges. The inheritance tree is deliberately
+    NOT built here: resolving EXTENDS targets requires symbol resolution,
+    so it belongs to SymbolResolver (spec §2.4).
+    """
+
+    def build(self, nodes: list[Node]) -> SymbolIndex:
+        """Index all nodes for fast resolution and return the frozen index."""
+        nodes_by_id = {n.id: n for n in nodes}
+        global_symbols: dict[str, list[str]] = {}
+        file_global_symbols: dict[tuple[str, str], list[str]] = {}
+        class_methods: dict[str, dict[str, str]] = {}
+        variable_symbols: dict[str, list[str]] = {}
+        file_variable_symbols: dict[tuple[str, str], list[str]] = {}
+        file_imports: dict[str, dict[str, str]] = {}
+        suffix_map: dict[str, list[str]] = {}
+        internal_roots: set[str] = set()
+
+        for node in nodes_by_id.values():
+            # Index FILE-level import maps
+            if node.type == NodeType.FILE:
+                normalized = os.path.normpath(node.file_path)
+                file_imports[normalized] = node.metadata.get("import_map") or {}
+
+            # Index global functions/symbols
+            if node.type in (NodeType.FUNCTION, NodeType.CLASS):
+                global_symbols.setdefault(node.name, []).append(node.id)
+                file_global_symbols.setdefault(
+                    (os.path.normpath(node.file_path), node.name), []
+                ).append(node.id)
+
+            # Index methods within classes
+            if node.type == NodeType.METHOD:
+                class_fqn, sep, _ = node.id.rpartition(".")
+                if sep:
+                    class_methods.setdefault(class_fqn, {})[node.name] = node.id
+
+            # Index DI aliases for raw_dep: candidate resolution
+            if node.type == NodeType.VARIABLE:
+                variable_symbols.setdefault(node.name, []).append(node.id)
+                file_variable_symbols.setdefault(
+                    (os.path.normpath(node.file_path), node.name), []
+                ).append(node.id)
+
+            # Build suffix map for src/-layout prefix normalization:
+            # "src.cgis.pipeline.X" → suffix "cgis.pipeline.X" also points to the node
+            self._add_node_to_suffix_map(node.id, suffix_map, internal_roots)
+
+        return SymbolIndex(
+            nodes=nodes_by_id,
+            global_symbols=global_symbols,
+            file_global_symbols=file_global_symbols,
+            class_methods=class_methods,
+            variable_symbols=variable_symbols,
+            file_variable_symbols=file_variable_symbols,
+            file_imports=file_imports,
+            suffix_map=suffix_map,
+            internal_roots=internal_roots,
+            external_roots=self._build_external_roots(file_imports),
+        )
+
+    def _add_node_to_suffix_map(
+        self, node_id: str, suffix_map: dict[str, list[str]], internal_roots: set[str]
+    ) -> None:
+        """Add node to suffix map and internal roots based on its ID."""
+        parts = node_id.split(".")
+        internal_roots.add(parts[0])
+        if len(parts) > 1 and parts[0] in {"src", "lib"}:
+            internal_roots.add(parts[1])
+        for i in range(1, len(parts)):
+            suffix = ".".join(parts[i:])
+            suffix_map.setdefault(suffix, []).append(node_id)
+
+    def _build_external_roots(self, file_imports: dict[str, dict[str, str]]) -> set[str]:
+        """Build set of known external root modules from file import maps.
+
+        Any root not in internal_roots, stdlib, or external_roots
+        is classified as UNKNOWN by classify_fqn.
+        """
+        return {
+            val.split(".", maxsplit=1)[0]
+            for import_map in file_imports.values()
+            for val in import_map.values()
+            if val and not val.startswith(".")
+        }

cgis/resolver/symbols.py

@@ -0,0 +1,179 @@
+"""Symbol resolution strategies over a SymbolIndex."""
+
+from cgis.core.models import RAW_CLASS_PREFIX, Edge, EdgeType, Node, NodeNamespace
+from cgis.resolver.indices import IndexBuilder, SymbolIndex
+
+
+class SymbolResolver:
+    """Maps raw symbol names to graph FQNs.
+
+    Strategy chain per call site: local variable types, the consuming file's
+    import map, then the global symbol index with same-file preference.
+    Holds the inheritance tree (a resolution product built from EXTENDS
+    edges — not an index, see spec §2.4).
+
+    The constructor accepts nodes and edges directly; it builds the
+    SymbolIndex internally via IndexBuilder and exposes it as the public
+    ``index`` attribute so callers (e.g. ResolverEngine) can read the index
+    without building it themselves.
+    """
+
+    def __init__(self, nodes: list[Node], edges: list[Edge]) -> None:
+        """Build the symbol index from nodes, then the inheritance tree from EXTENDS edges."""
+        self.index: SymbolIndex = IndexBuilder().build(nodes)
+        # class_fqn -> [resolved parent FQNs] built from EXTENDS edges
+        self._inheritance_tree: dict[str, list[str]] = {}
+        for edge in edges:
+            if edge.type == EdgeType.EXTENDS:
+                raw = edge.target.removeprefix(RAW_CLASS_PREFIX)
+                resolved = self.resolve_class_ref(raw, edge.source, edge.file_path)
+                # Only resolved (FQN) parents are useful for method-hierarchy lookup.
+                # Storing the bare `raw` name would false-match an unrelated class
+                # that happens to share that bare name (#183).
+                if resolved:
+                    self._inheritance_tree.setdefault(edge.source, []).append(resolved)
+
+    def resolve_class_ref(
+        self, name: str, source_fqn: str, edge_file_path: str | None
+    ) -> str | None:
+        """Resolve a class name from an EXTENDS edge target to a graph FQN."""
+        file_path = self.index.normalized_file_path(source_fqn, edge_file_path)
+        if file_path:
+            result = self._resolve_via_import_map(name, file_path)
+            if result:
+                return result
+        # Global symbol index is keyed by short name; for dotted refs like `models.BaseModel`
+        # strip the module prefix and verify the resolved FQN ends with the full dotted name.
+        query_name = name.rsplit(".", maxsplit=1)[-1]
+        resolved = self._resolve_via_global_symbols(query_name, file_path)
+        if resolved and ("." not in name or resolved == name or resolved.endswith(f".{name}")):
+            return resolved
+        return None
+
+    def resolve_self_call(self, source_fqn: str, method_name: str) -> str | None:
+        """Attempts to find a method on the class that owns source, traversing inheritance.
+
+        Walks up the FQN segments to handle nested functions (e.g. mod.Cls.method.inner).
+        """
+        parts = source_fqn.split(".")
+        for i in range(len(parts) - 1, 0, -1):
+            candidate = ".".join(parts[:i])
+            if candidate in self.index.class_methods:
+                return self._resolve_method_on_class_hierarchy(candidate, method_name, set())
+        return None
+
+    def resolve_global_call(
+        self, name: str, source_fqn: str, edge_file_path: str | None = None
+    ) -> str | None:
+        """Resolve a global call using local types, import map, then global symbol index."""
+        source_node = self.index.nodes.get(source_fqn)
+        file_path = self.index.normalized_file_path(source_fqn, edge_file_path)
+
+        if source_node:
+            result = self._resolve_local_type_call(name, source_node)
+            if result:
+                return result
+
+        if file_path:
+            result = self._resolve_via_import_map(name, file_path)
+            if result:
+                return result
+
+        return self._resolve_via_global_symbols(name, file_path)
+
+    def resolve_dep_candidate(
+        self, name: str, source_fqn: str, edge_file_path: str | None
+    ) -> str | None:
+        """Resolve a raw_dep: candidate to a VARIABLE (DI alias) node, or None.
+
+        Order: the consuming file's import map first, then the VARIABLE-only
+        symbol index with same-file preference. Returns None for anything that
+        is not an existing VARIABLE node — the caller drops the edge.
+        A globally-unique match is accepted even when the name is not importable
+        in the consuming file — matching resolve_global_call's behavior.
+
+        When ``name`` is present in the file's import map, the import is
+        authoritative: return the hit only if it is a VARIABLE node, otherwise
+        return ``None`` immediately — never fall through to the global
+        ``variable_symbols`` index.  This prevents an explicitly imported
+        class from being shadowed by a same-named DI alias in another module.
+        """
+        file_path = self.index.normalized_file_path(source_fqn, edge_file_path)
+        if file_path:
+            via_import = self._resolve_via_import_map(name, file_path)
+            if via_import:
+                return via_import if self.index.is_variable_node(via_import) else None
+        candidates = self.index.variable_symbols.get(name, [])
+        if len(candidates) == 1:
+            return candidates[0]
+        if candidates and file_path:
+            same_file = self.index.file_variable_symbols.get((file_path, name), [])
+            if len(same_file) == 1:
+                return same_file[0]
+        return None
+
+    def _resolve_method_on_class_hierarchy(
+        self, class_fqn: str, method_name: str, visited: set[str]
+    ) -> str | None:
+        """DFS over EXTENDS edges to find method_name defined in class_fqn or any ancestor."""
+        if class_fqn in visited:
+            return None
+        visited.add(class_fqn)
+        direct = self.index.class_methods.get(class_fqn, {}).get(method_name)
+        if direct:
+            return direct
+        for parent_fqn in self._inheritance_tree.get(class_fqn, []):
+            result = self._resolve_method_on_class_hierarchy(parent_fqn, method_name, visited)
+            if result:
+                return result
+        return None
+
+    def _resolve_via_import_map(self, name: str, file_path: str) -> str | None:
+        """Look up name in the file's import map (direct and module-prefixed calls)."""
+        file_import_map = self.index.file_imports.get(file_path, {})
+
+        if name in file_import_map:
+            target_fqn = file_import_map[name]
+            return self.index.map_to_node_fqn(target_fqn) or target_fqn
+
+        first_part = name.split(".", maxsplit=1)[0]
+        if first_part in file_import_map and "." in name:
+            rest = name[len(first_part) + 1 :]
+            target_fqn = f"{file_import_map[first_part]}.{rest}"
+            return self.index.map_to_node_fqn(target_fqn) or target_fqn
+
+        return None
+
+    def _resolve_local_type_call(self, name: str, source_node: Node) -> str | None:
+        """Resolve `var.method` using local_types metadata on the source node."""
+        if "." not in name:
+            return None
+        var_name, method_name = name.split(".", maxsplit=1)
+        local_types: dict[str, str] = source_node.metadata.get("local_types") or {}
+        class_fqn = local_types.get(var_name)
+        if not class_fqn:
+            return None
+        candidate = f"{class_fqn}.{method_name}"
+        resolved = self.index.map_to_node_fqn(candidate)
+        if resolved:
+            return resolved
+        # No node for `Class.method`. Keep it only when the type is external/stdlib
+        # — that is a real call into a library (it becomes an EXTERNAL/STDLIB virtual
+        # node). For an internal/unknown type it is a phantom method: drop it rather
+        # than fabricate a node that does not exist (#183).
+        if self.index.classify_fqn(candidate) in (NodeNamespace.EXTERNAL, NodeNamespace.STDLIB):
+            return candidate
+        return None
+
+    def _resolve_via_global_symbols(self, name: str, file_path: str | None) -> str | None:
+        """Look up name in the global symbol index, preferring same-file candidates."""
+        candidates = self.index.global_symbols.get(name, [])
+        if not candidates:
+            return None
+        if len(candidates) == 1:
+            return candidates[0]
+        if file_path:
+            same_file = self.index.file_global_symbols.get((file_path, name), [])
+            if len(same_file) == 1:
+                return same_file[0]
+        return None