apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/analysis/call_graph.py

@@ -0,0 +1,1197 @@
+"""
+Call graph construction for inter-procedural analysis.
+
+This module builds a directed graph of function calls across an entire project.
+It uses the PyCG algorithm approach: track variable assignments to resolve
+dynamic dispatch (method calls on objects whose type isn't statically known).
+
+DESIGN PRINCIPLES:
+1. Language-agnostic graph structure (nodes and edges)
+2. Language-specific resolvers handle symbol resolution
+3. Graph stored in NetworkX for rich algorithm support
+4. Full provenance: every edge knows WHY it exists
+
+ALGORITHM OVERVIEW (based on PyCG - ICSE 2021):
+1. Build symbol table: all function/method/class definitions
+2. Collect all call sites from parsed files
+3. Track variable assignments to build type bindings
+4. Use fixed-point iteration for transitive propagation
+5. Resolve each call to zero, one, or multiple targets
+6. Build edges with resolution confidence
+
+HANDLES:
+- Direct function calls: foo()
+- Method calls: obj.method()
+- Qualified calls: module.func()
+- Constructor calls: MyClass()
+- Calls through aliases: from x import y as z; z()
+- Higher-order functions: functions passed as arguments
+- Closures and lambdas with return tracking
+- Dynamic dispatch (multiple possible targets)
+- Decorators as calls
+- self/cls implicit binding
+- Chained attribute access
+- Comprehension and generator calls
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..core.manifest import stable_id
+from .binding_tracker import BindingTracker  # noqa: F401
+
+# Re-export everything so existing importers don't break
+from .call_graph_types import (  # noqa: F401
+    PYTHON_BUILTINS,
+    CallContext,
+    CallGraphEdge,
+    CallGraphNode,
+    EdgeType,
+    NodeType,
+    ResolutionConfidence,
+    TypeBinding,
+)
+from .call_resolver import (  # noqa: F401
+    CallContextAnalyzer,
+    CallResolver,
+    DecoratorAnalyzer,
+    LambdaClosureTracker,
+)
+
+try:
+    import networkx as nx
+except ImportError:
+    nx = None  # type: ignore
+
+if TYPE_CHECKING:
+    from ..parsing.base import (
+        ParsedCallSite,
+        ParsedClass,
+        ParsedFile,
+        ParsedFunction,
+    )
+    from ..parsing.services import AnalysisContext, TypeResolver
+    from .flow_analysis import FlowSensitiveBindings
+
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Call Graph Builder
+# =============================================================================
+
+
+class CallGraphBuilder:
+    """
+    Builds a complete call graph from parsed files.
+
+    Usage:
+        builder = CallGraphBuilder()
+
+        for parsed_file in parsed_files:
+            builder.add_file(parsed_file)
+
+        builder.resolve_calls(type_resolver)
+        graph = builder.build()
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the builder."""
+        if nx is None:
+            raise ImportError(
+                "networkx is required for call graph construction. "
+                "Install it with: pip install networkx"
+            )
+
+        self._project_root = project_root
+
+        # Symbol table
+        self._symbols: dict[str, CallGraphNode] = {}
+
+        # Index: (file_path, simple_name) -> [qualified_names] for O(1) lookup
+        self._file_name_index: dict[tuple[Path, str], list[str]] = {}
+
+        # Raw call sites (before resolution)
+        self._call_sites: list[tuple[ParsedCallSite, str | None, Path]] = []
+
+        # Binding tracker for dynamic dispatch (flow-insensitive)
+        self._bindings = BindingTracker()
+
+        # Flow-sensitive bindings (built during resolve_calls)
+        self._flow_bindings: FlowSensitiveBindings | None = None
+
+        # Import mappings
+        self._imports: dict[tuple[Path, str], str] = {}
+
+        # Star imports: file_path -> {local_name: qualified_name}
+        self._star_imports: dict[Path, dict[str, str]] = {}
+
+        # Class hierarchy
+        self._class_bases: dict[str, list[str]] = {}
+
+        # Context analyzer
+        self._context_analyzer = CallContextAnalyzer()
+
+        # Decorator analyzer
+        self._decorator_analyzer = DecoratorAnalyzer()
+
+        # Lambda/closure tracker
+        self._lambda_tracker = LambdaClosureTracker()
+
+        # Decorator calls (separate from regular calls)
+        self._decorator_calls: list[tuple[str, str, Path, int]] = []
+
+        # Resolved edges
+        self._edges: list[CallGraphEdge] = []
+
+        # The graph
+        self._graph: nx.DiGraph = nx.DiGraph()
+
+        # Parsed files for context analysis
+        self._parsed_files: dict[Path, ParsedFile] = {}
+
+        # Protocol/ABC tracking
+        self._known_protocols: set[str] = {
+            "typing.Protocol",
+            "abc.ABC",
+            "abc.ABCMeta",
+            "collections.abc.Iterable",
+            "collections.abc.Iterator",
+            "collections.abc.Callable",
+            "collections.abc.Mapping",
+            "collections.abc.Sequence",
+            "collections.abc.Set",
+        }
+
+    def add_file(self, parsed_file: ParsedFile) -> None:
+        """
+        Process a parsed file and extract symbols, calls, and bindings.
+        """
+        if not parsed_file.success:
+            return
+
+        file_path = parsed_file.path
+        self._parsed_files[file_path] = parsed_file
+
+        # 1. Extract imports and build import map
+        self._process_imports(parsed_file)
+
+        # 2. Extract function definitions
+        for func in parsed_file.functions:
+            self._add_function(func, file_path, None)
+
+        # 3. Extract class definitions and methods
+        for cls in parsed_file.classes:
+            self._add_class(cls, file_path)
+
+        # 4. Extract call sites
+        for call in parsed_file.call_sites:
+            caller = self._get_caller(call, file_path)
+            self._call_sites.append((call, caller, file_path))
+
+        # 5. Extract assignments for binding tracking
+        self._process_assignments(parsed_file)
+
+    def _process_imports(self, parsed_file: ParsedFile) -> None:
+        """Process imports to build import map."""
+        file_path = parsed_file.path
+
+        for imp in parsed_file.imports:
+            line = imp.location.line if imp.location else 0
+
+            # Handle star imports
+            if imp.is_from_import and "*" in imp.names:
+                # Star import - we need to know what's exported
+                # For now, mark it for later resolution
+                if file_path not in self._star_imports:
+                    self._star_imports[file_path] = {}
+                # We'll try to resolve exported names from the module
+                self._bindings.add_import(
+                    "*",
+                    f"{imp.module}.*",
+                    file_path,
+                    line,
+                    is_star=True,
+                )
+                continue
+
+            if imp.is_from_import:
+                # from module import name [as alias]
+                for name in imp.names:
+                    local_name = imp.alias if len(imp.names) == 1 and imp.alias else name
+                    qualified = f"{imp.module}.{name}"
+                    self._imports[(file_path, local_name)] = qualified
+                    self._bindings.add_import(local_name, qualified, file_path, line)
+            else:
+                # import module [as alias]
+                local_name = imp.alias or imp.module.split(".")[-1]
+                self._imports[(file_path, local_name)] = imp.module
+                self._bindings.add_import(local_name, imp.module, file_path, line)
+
+    def _add_function(
+        self,
+        func: ParsedFunction,
+        file_path: Path,
+        enclosing_class: str | None,
+    ) -> None:
+        """Add a function to the symbol table."""
+        qname = func.qualified_name.full
+
+        # Determine node type
+        if func.binding != "free":
+            if func.binding == "static":
+                is_classmethod = any(d.name == "classmethod" for d in func.decorators)
+                node_type = NodeType.CLASS_METHOD if is_classmethod else NodeType.STATIC_METHOD
+            elif any(d.name == "property" for d in func.decorators):
+                node_type = NodeType.PROPERTY
+            elif func.name == "__init__":
+                node_type = NodeType.CONSTRUCTOR
+            else:
+                node_type = NodeType.METHOD
+        else:
+            # Check if it's a nested function (closure)
+            if "." in qname and func.binding == "free":
+                parts = qname.split(".")
+                # If parent is a function, this is a closure
+                parent = ".".join(parts[:-1])
+                if parent in self._symbols:
+                    parent_node = self._symbols[parent]
+                    if parent_node.node_type in (
+                        NodeType.FUNCTION,
+                        NodeType.METHOD,
+                        NodeType.CLOSURE,
+                    ):
+                        node_type = NodeType.CLOSURE
+                    else:
+                        node_type = NodeType.FUNCTION
+                else:
+                    node_type = NodeType.FUNCTION
+            else:
+                node_type = NodeType.FUNCTION
+
+        node = CallGraphNode(
+            qualified_name=qname,
+            name=func.name,
+            node_type=node_type,
+            file_path=file_path,
+            line=func.location.line,
+            end_line=func.location.end_line or func.location.line,
+            class_name=func.owner_type,
+            class_qualified_name=func.class_qualified_name.full
+            if func.class_qualified_name
+            else None,
+            is_async=func.is_async,
+            is_generator=func.has_yield,
+            is_abstract=func.is_abstract,
+            parameters=[p.name for p in func.parameters],
+            return_type=func.return_type,
+            docstring=func.docstring,
+            decorators=[d.name for d in func.decorators],
+        )
+
+        self._symbols[qname] = node
+
+        if file_path:
+            idx_key = (file_path, func.name)
+            if idx_key not in self._file_name_index:
+                self._file_name_index[idx_key] = []
+            self._file_name_index[idx_key].append(qname)
+
+        # Handle self/cls binding for methods
+        if func.binding != "free" and func.parameters and enclosing_class:
+            first_param = func.parameters[0]
+            if first_param.name in ("self", "cls"):
+                self._bindings.add_self_binding(qname, enclosing_class, first_param.name)
+
+        # Add other parameters to binding tracker
+        for param in func.parameters:
+            # Skip self/cls which was already handled
+            if func.binding != "free" and param.name in ("self", "cls"):
+                continue
+            self._bindings.add_parameter(
+                param.name,
+                qname,
+                param.type_annotation,
+            )
+
+        # Track return type for return value propagation
+        if func.return_type:
+            self._bindings.add_return_binding(qname, return_type=func.return_type)
+
+        # Extract decorator calls
+        if func.decorators:
+            dec_calls = self._decorator_analyzer.extract_decorator_calls(
+                qname, func.decorators, file_path
+            )
+            for dec_name, line, _call_type in dec_calls:
+                self._decorator_calls.append((qname, dec_name, file_path, line))
+
+    def _add_class(
+        self,
+        cls: ParsedClass,
+        file_path: Path,
+    ) -> None:
+        """Add a class and its methods to the symbol table."""
+        qname = cls.qualified_name.full
+
+        # Track class hierarchy
+        self._class_bases[qname] = cls.base_classes
+
+        # Check if this class implements a protocol/ABC
+        for base in cls.base_classes:
+            if base in self._known_protocols or base.endswith("Protocol"):
+                self._bindings.add_protocol_implementation(base, qname)
+
+        # Add constructor node for the class itself (for Class() calls)
+        class_node = CallGraphNode(
+            qualified_name=qname,
+            name=cls.name,
+            node_type=NodeType.CONSTRUCTOR,
+            file_path=file_path,
+            line=cls.location.line,
+            end_line=cls.location.end_line or cls.location.line,
+            docstring=cls.docstring,
+            decorators=[d.name for d in cls.decorators],
+        )
+        self._symbols[qname] = class_node
+
+        idx_key = (file_path, cls.name)
+        if idx_key not in self._file_name_index:
+            self._file_name_index[idx_key] = []
+        self._file_name_index[idx_key].append(qname)
+
+        # Extract decorator calls for class
+        if cls.decorators:
+            dec_calls = self._decorator_analyzer.extract_decorator_calls(
+                qname, cls.decorators, file_path
+            )
+            for dec_name, line, _call_type in dec_calls:
+                self._decorator_calls.append((qname, dec_name, file_path, line))
+
+        # Add methods with class context for self/cls binding
+        for method in cls.methods:
+            self._add_function(method, file_path, qname)
+
+        # Track class attributes
+        for attr_name, attr_info in getattr(cls, "attributes", {}).items():
+            if hasattr(attr_info, "type_annotation") and attr_info.type_annotation:
+                self._bindings.add_assignment(
+                    attr_name,
+                    attr_info.type_annotation,
+                    file_path,
+                    cls.location.line,
+                    scope_class=qname,
+                )
+
+    def _process_assignments(self, parsed_file: ParsedFile) -> None:
+        """Process assignments to build type bindings."""
+        file_path = parsed_file.path
+
+        for assign in parsed_file.assignments:
+            scope_function = None
+            if assign.target_qualified_name:
+                # Determine scope
+                parts = assign.target_qualified_name.full.split(".")
+                if len(parts) > 1:
+                    scope_function = ".".join(parts[:-1])
+
+            if assign.source_type == "call" and assign.source_call:
+                # x = SomeClass() -> x is bound to SomeClass
+                called = assign.source_call
+
+                # Try to resolve the called class
+                import_key = (file_path, called)
+                if import_key in self._imports:
+                    called = self._imports[import_key]
+                elif called in self._symbols:
+                    pass  # Already qualified
+
+                self._bindings.add_assignment(
+                    assign.target,
+                    called,
+                    file_path,
+                    assign.location.line,
+                    scope_function=scope_function,
+                )
+
+                # Also track that the variable holds the return value
+                self._bindings.add_assignment(
+                    assign.target,
+                    None,
+                    file_path,
+                    assign.location.line,
+                    scope_function=scope_function,
+                    source_variable=called,  # For return type propagation
+                )
+
+            elif assign.source_type == "variable" and assign.source_value:
+                # x = y -> x has same types as y (transitive)
+                self._bindings.add_assignment(
+                    assign.target,
+                    None,
+                    file_path,
+                    assign.location.line,
+                    scope_function=scope_function,
+                    source_variable=assign.source_value,
+                )
+
+            elif assign.source_type == "literal":
+                # x = "string" or x = 123
+                if assign.inferred_type:
+                    self._bindings.add_assignment(
+                        assign.target,
+                        assign.inferred_type,
+                        file_path,
+                        assign.location.line,
+                        scope_function=scope_function,
+                    )
+
+            # Check if assigning a callable (function reference)
+            if assign.source_type == "variable":
+                source = assign.source_value
+                if source and source in self._symbols:
+                    # Assigning a function to a variable
+                    self._bindings.add_assignment(
+                        assign.target,
+                        None,
+                        file_path,
+                        assign.location.line,
+                        scope_function=scope_function,
+                        is_callable=True,
+                        callable_target=source,
+                    )
+
+    def _get_caller(self, call: ParsedCallSite, file_path: Path | str) -> str:
+        """Get the qualified name of the calling function."""
+        if call.caller_function:
+            return call.caller_function.full
+        # Module-level call - use file-qualified module name
+        p = file_path if isinstance(file_path, Path) else Path(str(file_path))
+        return f"<module:{p.stem}>"
+
+    def resolve_calls(
+        self,
+        type_resolver: TypeResolver | None = None,
+        flow_bindings: FlowSensitiveBindings | None = None,
+    ) -> None:
+        """
+        Resolve all collected call sites to their targets.
+
+        This should be called after all files have been added.
+        """
+        # First, propagate flow-insensitive bindings transitively
+        iterations = self._bindings.propagate()
+        logger.debug("Binding propagation completed in %d iterations", iterations)
+
+        # Use pre-built flow bindings if provided, otherwise build them
+        if flow_bindings is not None:
+            self._flow_bindings = flow_bindings
+        else:
+            try:
+                from .flow_analysis import build_flow_sensitive_bindings
+
+                parsed_files_list = list(self._parsed_files.values())
+                self._flow_bindings = build_flow_sensitive_bindings(parsed_files_list)
+                logger.debug("Built flow-sensitive bindings for %d files", len(parsed_files_list))
+            except Exception as e:
+                logger.warning("Could not build flow-sensitive bindings: %s", e)
+                self._flow_bindings = None
+
+        # Extract control flow info for context analysis
+        for _file_path, parsed_file in self._parsed_files.items():
+            self._context_analyzer.extract_control_flow_from_file(parsed_file)
+
+        resolver = CallResolver(
+            self._symbols,
+            self._bindings,
+            type_resolver,
+            self._flow_bindings,
+            file_name_index=self._file_name_index,
+        )
+
+        # Add import mappings to resolver
+        for key, value in self._imports.items():
+            resolver.add_import_mapping(key[0], key[1], value)
+
+        # Add star imports
+        for file_path, names in self._star_imports.items():
+            for local, qualified in names.items():
+                resolver.add_star_import(file_path, qualified.rsplit(".", 1)[0], {local: qualified})
+
+        # Add class hierarchy
+        for cls, bases in self._class_bases.items():
+            resolver.add_class_hierarchy(cls, bases)
+
+        # Resolve regular call sites
+        for call_site, caller, file_path in self._call_sites:
+            targets, confidence, reason = resolver.resolve(call_site, caller, file_path)
+
+            # Get context information with flow bindings
+            parsed_file = self._parsed_files.get(file_path)
+            if parsed_file:
+                context_info = self._context_analyzer.analyze_call_context(
+                    call_site, parsed_file, self._flow_bindings
+                )
+            else:
+                context_info = {"context": CallContext.NORMAL}
+
+            # Create edge for each target
+            for target in targets:
+                edge = self._create_edge(
+                    caller=caller,
+                    callee=target,
+                    edge_type=self._determine_edge_type(call_site),
+                    file_path=file_path,
+                    line=call_site.location.line,
+                    column=call_site.location.column,
+                    confidence=confidence,
+                    targets=targets,
+                    call_site=call_site,
+                    context_info=context_info,
+                    reason=reason,
+                )
+                self._edges.append(edge)
+
+        # Resolve decorator calls
+        for decorated, decorator_name, file_path, line in self._decorator_calls:
+            # Resolve the decorator
+            import_key = (file_path, decorator_name.split(".")[0])
+            resolved_decorator = decorator_name
+            if import_key in self._imports:
+                prefix = self._imports[import_key]
+                rest = ".".join(decorator_name.split(".")[1:])
+                resolved_decorator = f"{prefix}.{rest}" if rest else prefix
+
+            edge = CallGraphEdge(
+                caller=decorated,
+                callee=resolved_decorator,
+                edge_type=EdgeType.DECORATOR,
+                file_path=file_path,
+                line=line,
+                confidence=ResolutionConfidence.HIGH
+                if resolved_decorator in self._symbols
+                else ResolutionConfidence.MEDIUM,
+                resolution_reason="decorator application",
+            )
+            self._edges.append(edge)
+
+        # Post-resolution: propagate call edges through decorators so taint
+        # analysis can follow data across decorator boundaries.
+        self._propagate_through_decorators()
+
+        # Post-resolution: emit synthetic __enter__/__exit__ edges for
+        # context manager with-statements.
+        self._emit_context_manager_edges()
+
+    def _create_edge(
+        self,
+        caller: str,
+        callee: str,
+        edge_type: EdgeType,
+        file_path: Path,
+        line: int,
+        column: int,
+        confidence: ResolutionConfidence,
+        targets: list[str],
+        call_site: ParsedCallSite,
+        context_info: dict[str, Any],
+        reason: str,
+    ) -> CallGraphEdge:
+        """Create a call graph edge with full context."""
+        return CallGraphEdge(
+            caller=caller,
+            callee=callee,
+            edge_type=edge_type,
+            file_path=file_path,
+            line=line,
+            column=column,
+            confidence=confidence,
+            possible_callees=targets if len(targets) > 1 else [],
+            argument_count=len(call_site.arguments),
+            keyword_arguments=[a.name for a in call_site.arguments if a.name is not None],
+            has_spread=any(a.is_spread for a in call_site.arguments),
+            has_keyword_spread=any(a.is_keyword_spread for a in call_site.arguments),
+            context=context_info.get("context", CallContext.NORMAL),
+            in_loop=context_info.get("in_loop", False),
+            in_conditional=context_info.get("in_conditional", False),
+            in_try_block=context_info.get("in_try_block", False),
+            in_except_handler=context_info.get("in_except_handler", False),
+            in_comprehension=context_info.get("in_comprehension", False),
+            resolution_reason=reason,
+        )
+
+    def _determine_edge_type(self, call_site: ParsedCallSite) -> EdgeType:
+        """Determine the type of call edge."""
+        if call_site.is_method_call:
+            receiver = call_site.receiver_expression or ""
+            if receiver == "super()":
+                return EdgeType.SUPER_CALL
+            return EdgeType.METHOD_CALL
+
+        callee = call_site.callee_name
+
+        # Check if it's a class instantiation (starts with uppercase)
+        if callee and callee[0].isupper():
+            return EdgeType.CONSTRUCTOR_CALL
+
+        # Check for static call (Class.method)
+        if "." in callee:
+            parts = callee.split(".")
+            if parts[0] and parts[0][0].isupper():
+                return EdgeType.STATIC_CALL
+
+        return EdgeType.DIRECT_CALL
+
+    # -----------------------------------------------------------------
+    # Decorator flow-through
+    # -----------------------------------------------------------------
+
+    _NON_PASSTHROUGH_DECORATORS: set[str] = {
+        "property",
+        "staticmethod",
+        "classmethod",
+        "builtins.property",
+        "builtins.staticmethod",
+        "builtins.classmethod",
+        "abc.abstractmethod",
+        "functools.cached_property",
+        "typing.overload",
+    }
+
+    def _propagate_through_decorators(self) -> None:
+        """Emit synthetic CALLS edges so callers of a decorated name reach
+        the original function body.
+
+        For every function F decorated by D (DECORATOR edge F→D), any
+        external caller that calls the *decorated name* should also be
+        considered as calling F's body.  We materialise this as a
+        synthetic DIRECT_CALL edge from D (the wrapper) to F.
+
+        Skips decorators known NOT to be pass-through (property,
+        staticmethod, classmethod, etc.).
+        """
+        decorator_edges = [e for e in self._edges if e.edge_type == EdgeType.DECORATOR]
+        if not decorator_edges:
+            return
+
+        existing_pairs: set[tuple[str, str]] = {(e.caller, e.callee) for e in self._edges}
+
+        for dec_edge in decorator_edges:
+            decorated_func = dec_edge.caller  # the function being decorated
+            decorator_name = dec_edge.callee  # the decorator
+
+            # Skip non-pass-through decorators
+            simple_name = decorator_name.rsplit(".", 1)[-1]
+            if (
+                decorator_name in self._NON_PASSTHROUGH_DECORATORS
+                or simple_name in self._NON_PASSTHROUGH_DECORATORS
+            ):
+                continue
+
+            # Emit: decorator_wrapper → decorated_function body
+            pair = (decorator_name, decorated_func)
+            if pair in existing_pairs:
+                continue
+            existing_pairs.add(pair)
+
+            synthetic = CallGraphEdge(
+                caller=decorator_name,
+                callee=decorated_func,
+                edge_type=EdgeType.DIRECT_CALL,
+                file_path=dec_edge.file_path,
+                line=dec_edge.line,
+                confidence=ResolutionConfidence.MEDIUM,
+                resolution_reason="decorator flow-through (synthetic)",
+            )
+            self._edges.append(synthetic)
+
+        logger.debug(
+            "Decorator flow-through: emitted %d synthetic edges",
+            len(self._edges) - len(existing_pairs),
+        )
+
+    # -----------------------------------------------------------------
+    # Context manager __enter__ / __exit__ modeling
+    # -----------------------------------------------------------------
+
+    def _emit_context_manager_edges(self) -> None:
+        """Emit synthetic call edges for ``with`` statements.
+
+        For each ``with expr as x:`` inside a function, if we can resolve
+        *expr*'s type T (via bindings or imports), we emit two synthetic
+        CALLS edges: caller → T.__enter__ and caller → T.__exit__.
+        """
+        for file_path, parsed_file in self._parsed_files.items():
+            for func in parsed_file.functions:
+                self._emit_cm_edges_for_function(func, file_path)
+            for cls in parsed_file.classes:
+                for method in cls.methods:
+                    self._emit_cm_edges_for_function(method, file_path)
+
+    def _emit_cm_edges_for_function(
+        self,
+        func: ParsedFunction,
+        file_path: Path,
+    ) -> None:
+        cf = getattr(func, "control_flow_info", None)
+        if not cf:
+            return
+
+        caller = func.qualified_name.full
+        with_blocks = cf.get("with_blocks", [])
+        if not with_blocks:
+            return
+
+        existing_pairs: set[tuple[str, str]] = {(e.caller, e.callee) for e in self._edges}
+
+        for wb in with_blocks:
+            line: int = wb.get("start_line", 0)
+            # Use all with_items if available, fall back to single context_expr
+            items: list[str] = wb.get("with_items", [])
+            if not items:
+                ctx_expr = wb.get("context_expr")
+                items = [ctx_expr] if ctx_expr else []
+
+            for ctx_expr in items:
+                possible_types = self._resolve_context_expr_type(ctx_expr, file_path, caller)
+                if not possible_types:
+                    continue
+
+                for type_name in sorted(possible_types):
+                    for dunder in ("__enter__", "__exit__"):
+                        target = f"{type_name}.{dunder}"
+                        pair = (caller, target)
+                        if pair in existing_pairs:
+                            continue
+                        existing_pairs.add(pair)
+
+                        confidence = (
+                            ResolutionConfidence.HIGH
+                            if target in self._symbols
+                            else ResolutionConfidence.MEDIUM
+                        )
+
+                        edge = CallGraphEdge(
+                            caller=caller,
+                            callee=target,
+                            edge_type=EdgeType.METHOD_CALL,
+                            file_path=file_path,
+                            line=line,
+                            confidence=confidence,
+                            resolution_reason=f"context manager {dunder} (synthetic)",
+                        )
+                        self._edges.append(edge)
+
+    def _resolve_context_expr_type(
+        self,
+        ctx_expr: str,
+        file_path: Path,
+        caller: str,
+    ) -> set[str]:
+        """Best-effort type resolution for a context-manager expression."""
+        types: set[str] = set()
+
+        # Direct symbol or import lookup (e.g. ``open(...)`` → skip,
+        # but ``SomeClass()`` or ``some_var`` may resolve).
+        base = ctx_expr.split("(")[0].split(".")[0].strip()
+
+        # Check imports
+        import_key = (file_path, base)
+        if import_key in self._imports:
+            types.add(self._imports[import_key])
+
+        # Check symbols table
+        if base in self._symbols:
+            types.add(base)
+
+        # Check bindings
+        bound = self._bindings.get_possible_types(base, file_path, caller)
+        types.update(bound)
+
+        return types
+
+    def build(self) -> CallGraph:
+        """
+        Build and return the final call graph.
+
+        Should be called after resolve_calls().
+        """
+        # Add nodes to graph
+        for qname, node in self._symbols.items():
+            self._graph.add_node(
+                qname,
+                name=node.name,
+                node_type=node.node_type.name,
+                file_path=str(node.file_path) if node.file_path else None,
+                line=node.line,
+                is_async=node.is_async,
+                is_generator=node.is_generator,
+                is_external=node.is_external,
+                class_name=node.class_name,
+                parameters=node.parameters,
+                return_type=node.return_type,
+            )
+
+        # Add edges to graph
+        for edge in self._edges:
+            # Ensure both nodes exist (add placeholder for unresolved)
+            if edge.caller not in self._graph:
+                self._graph.add_node(
+                    edge.caller,
+                    name=edge.caller.split(".")[-1],
+                    node_type=NodeType.UNKNOWN.name,
+                    is_external="<module:" in edge.caller,
+                )
+            if edge.callee not in self._graph:
+                self._graph.add_node(
+                    edge.callee,
+                    name=edge.callee.split(".")[-1],
+                    node_type=NodeType.EXTERNAL.name
+                    if "<unresolved>" not in edge.callee
+                    else NodeType.UNKNOWN.name,
+                    is_external=True,
+                )
+
+            self._graph.add_edge(
+                edge.caller,
+                edge.callee,
+                edge_type=edge.edge_type.name,
+                file_path=str(edge.file_path),
+                line=edge.line,
+                confidence=edge.confidence.name,
+                resolution_reason=edge.resolution_reason,
+                argument_count=edge.argument_count,
+                context=edge.context.name,
+                in_loop=edge.in_loop,
+                in_conditional=edge.in_conditional,
+            )
+
+        return CallGraph(
+            graph=self._graph,
+            symbols=self._symbols,
+            edges=self._edges,
+            project_root=self._project_root,
+            bindings=self._bindings,
+        )
+
+
+# =============================================================================
+# Call Graph
+# =============================================================================
+
+
+class CallGraph:
+    """
+    A complete call graph for a project.
+
+    Provides query methods for analysis and conversion to manifest format.
+    """
+
+    def __init__(
+        self,
+        graph: nx.DiGraph,
+        symbols: dict[str, CallGraphNode],
+        edges: list[CallGraphEdge],
+        project_root: Path | None = None,
+        bindings: BindingTracker | None = None,
+    ):
+        self._graph = graph
+        self._symbols = symbols
+        self._edges = edges
+        self._project_root = project_root
+        self._bindings = bindings
+
+        # Pre-built indexes for O(1) edge lookups
+        self._edges_by_caller: dict[str, list[CallGraphEdge]] = {}
+        self._edges_by_callee: dict[str, list[CallGraphEdge]] = {}
+        for edge in self._edges:
+            self._edges_by_caller.setdefault(edge.caller, []).append(edge)
+            self._edges_by_callee.setdefault(edge.callee, []).append(edge)
+
+    @property
+    def graph(self) -> nx.DiGraph:
+        """The underlying NetworkX graph."""
+        return self._graph
+
+    @property
+    def node_count(self) -> int:
+        """Number of nodes (functions/methods)."""
+        return self._graph.number_of_nodes()
+
+    @property
+    def edge_count(self) -> int:
+        """Number of edges (calls)."""
+        return self._graph.number_of_edges()
+
+    def get_node(self, qualified_name: str) -> CallGraphNode | None:
+        """Get a node by qualified name."""
+        return self._symbols.get(qualified_name)
+
+    def get_edges_from(self, qualified_name: str) -> list[CallGraphEdge]:
+        """Get all edges (calls) originating from a function."""
+        return self._edges_by_caller.get(qualified_name, [])
+
+    def get_edges_to(self, qualified_name: str) -> list[CallGraphEdge]:
+        """Get all edges (calls) targeting a function."""
+        return self._edges_by_callee.get(qualified_name, [])
+
+    def get_callers(self, qualified_name: str) -> list[str]:
+        """Get functions that call the given function."""
+        if qualified_name not in self._graph:
+            return []
+        return list(self._graph.predecessors(qualified_name))
+
+    def get_callees(self, qualified_name: str) -> list[str]:
+        """Get functions called by the given function."""
+        if qualified_name not in self._graph:
+            return []
+        return list(self._graph.successors(qualified_name))
+
+    def get_all_callers(
+        self,
+        qualified_name: str,
+        max_depth: int = 10,
+    ) -> set[str]:
+        """Get all functions that transitively call the given function."""
+        from collections import deque
+
+        if qualified_name not in self._graph:
+            return set()
+
+        callers: set[str] = set()
+        to_visit: deque[tuple[str, int]] = deque([(qualified_name, 0)])
+        visited = {qualified_name}
+
+        while to_visit:
+            current, depth = to_visit.popleft()
+            if depth >= max_depth:
+                continue
+            for pred in self._graph.predecessors(current):
+                if pred not in visited:
+                    visited.add(pred)
+                    callers.add(pred)
+                    to_visit.append((pred, depth + 1))
+
+        return callers
+
+    def get_all_callees(
+        self,
+        qualified_name: str,
+        max_depth: int = 10,
+    ) -> set[str]:
+        """Get all functions transitively called by the given function."""
+        from collections import deque
+
+        if qualified_name not in self._graph:
+            return set()
+
+        callees: set[str] = set()
+        to_visit: deque[tuple[str, int]] = deque([(qualified_name, 0)])
+        visited = {qualified_name}
+
+        while to_visit:
+            current, depth = to_visit.popleft()
+            if depth >= max_depth:
+                continue
+            for succ in self._graph.successors(current):
+                if succ not in visited:
+                    visited.add(succ)
+                    callees.add(succ)
+                    to_visit.append((succ, depth + 1))
+
+        return callees
+
+    def get_path(
+        self,
+        source: str,
+        target: str,
+    ) -> list[str] | None:
+        """Get a call path from source to target, if one exists."""
+        if source not in self._graph or target not in self._graph:
+            return None
+
+        try:
+            return nx.shortest_path(self._graph, source, target)
+        except nx.NetworkXNoPath:
+            return None
+
+    def get_all_paths(
+        self,
+        source: str,
+        target: str,
+        max_depth: int = 10,
+    ) -> Iterator[list[str]]:
+        """Get all paths from source to target up to max depth."""
+        if source not in self._graph or target not in self._graph:
+            return iter([])
+
+        return nx.all_simple_paths(self._graph, source, target, cutoff=max_depth)
+
+    def get_strongly_connected_components(self) -> list[set[str]]:
+        """Get strongly connected components (recursive call cycles)."""
+        return [set(c) for c in nx.strongly_connected_components(self._graph)]
+
+    def get_entry_points(self) -> list[str]:
+        """Get functions with no callers (potential entry points)."""
+        return [
+            node
+            for node in self._graph.nodes()
+            if self._graph.in_degree(node) == 0
+            and not self._symbols.get(node, CallGraphNode("", "", NodeType.UNKNOWN)).is_external
+            and not node.startswith("<module:")
+        ]
+
+    def get_leaf_functions(self) -> list[str]:
+        """Get functions that don't call anything."""
+        return [node for node in self._graph.nodes() if self._graph.out_degree(node) == 0]
+
+    def get_edges_by_type(self, edge_type: EdgeType) -> list[CallGraphEdge]:
+        """Get all edges of a specific type."""
+        return [e for e in self._edges if e.edge_type == edge_type]
+
+    def get_edges_by_confidence(
+        self,
+        min_confidence: ResolutionConfidence,
+    ) -> list[CallGraphEdge]:
+        """Get edges with at least the given confidence."""
+        confidence_order = [
+            ResolutionConfidence.EXACT,
+            ResolutionConfidence.HIGH,
+            ResolutionConfidence.MEDIUM,
+            ResolutionConfidence.LOW,
+            ResolutionConfidence.UNRESOLVED,
+        ]
+        min_idx = confidence_order.index(min_confidence)
+
+        return [e for e in self._edges if confidence_order.index(e.confidence) <= min_idx]
+
+    def get_unresolved_calls(self) -> list[CallGraphEdge]:
+        """Get all unresolved call edges."""
+        return [e for e in self._edges if e.confidence == ResolutionConfidence.UNRESOLVED]
+
+    def get_statistics(self) -> dict[str, Any]:
+        """Get statistics about the call graph."""
+        internal_nodes = [
+            n for n, data in self._graph.nodes(data=True) if not data.get("is_external", False)
+        ]
+        external_nodes = [
+            n for n, data in self._graph.nodes(data=True) if data.get("is_external", False)
+        ]
+
+        confidence_counts: dict[str, int] = {}
+        edge_type_counts: dict[str, int] = {}
+        context_counts: dict[str, int] = {}
+
+        for edge in self._edges:
+            conf_key = edge.confidence.name
+            confidence_counts[conf_key] = confidence_counts.get(conf_key, 0) + 1
+
+            type_key = edge.edge_type.name
+            edge_type_counts[type_key] = edge_type_counts.get(type_key, 0) + 1
+
+            ctx_key = edge.context.name
+            context_counts[ctx_key] = context_counts.get(ctx_key, 0) + 1
+
+        return {
+            "total_nodes": self.node_count,
+            "internal_nodes": len(internal_nodes),
+            "external_nodes": len(external_nodes),
+            "total_edges": self.edge_count,
+            "entry_points": len(self.get_entry_points()),
+            "leaf_functions": len(self.get_leaf_functions()),
+            "resolution_confidence": confidence_counts,
+            "edge_types": edge_type_counts,
+            "call_contexts": context_counts,
+            "strongly_connected_components": len(self.get_strongly_connected_components()),
+            "decorator_calls": len([e for e in self._edges if e.edge_type == EdgeType.DECORATOR]),
+        }
+
+    def to_manifest_calls(self) -> list[dict[str, Any]]:
+        """
+        Convert to manifest FunctionCallModel format.
+
+        Returns a list of call dictionaries suitable for the manifest.
+        """
+        calls = []
+
+        for edge in self._edges:
+            call_dict = {
+                "id": stable_id(
+                    "call", edge.caller, str(edge.file_path), str(edge.line), str(edge.column)
+                ),
+                "caller": edge.caller,
+                "callee": edge.callee,
+                "callee_resolved": edge.confidence != ResolutionConfidence.UNRESOLVED,
+                "location": {
+                    "file": str(edge.file_path),
+                    "line": edge.line,
+                    "column": edge.column,
+                },
+                "arguments": [],  # Would need argument details
+                "context": {
+                    "in_try_block": edge.in_try_block,
+                    "in_conditional": edge.in_conditional,
+                    "in_loop": edge.in_loop,
+                },
+                "possible_callees": edge.possible_callees,
+                "resolution_reason": edge.resolution_reason,
+            }
+            calls.append(call_dict)
+
+        return calls
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+def build_call_graph(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+    type_resolver: TypeResolver | None = None,
+    flow_bindings: FlowSensitiveBindings | None = None,
+) -> CallGraph:
+    """
+    Build a call graph from parsed files.
+
+    Args:
+        parsed_files: List of successfully parsed files
+        project_root: Project root directory
+        type_resolver: Optional type resolver for better resolution
+        flow_bindings: Pre-built flow-sensitive bindings (avoids duplicate work)
+
+    Returns:
+        Complete CallGraph instance
+    """
+    builder = CallGraphBuilder(project_root)
+
+    for parsed in parsed_files:
+        builder.add_file(parsed)
+
+    builder.resolve_calls(type_resolver, flow_bindings=flow_bindings)
+    return builder.build()
+
+
+def build_call_graph_with_context(
+    parsed_files: list[ParsedFile],
+    context: AnalysisContext,
+    flow_bindings: FlowSensitiveBindings | None = None,
+) -> CallGraph:
+    """
+    Build a call graph using an analysis context.
+
+    This is the preferred method when using the new abstractions.
+    """
+    type_resolver = context.type_resolver if context else None
+    return build_call_graph(
+        parsed_files,
+        project_root=context.project_root if context else None,
+        type_resolver=type_resolver,
+        flow_bindings=flow_bindings,
+    )