cobraphp 0.1.0.dev1__py3-none-any.whl

cobraphp/analysis/_call_graph_nodes.py

@@ -0,0 +1,195 @@
+"""Call graph node and edge data types."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from cpg2py import AbcEdgeQuerier, AbcNodeQuerier, Storage
+
+from ._errors import StaticAnalysisError
+
+
+class CallNode(AbcNodeQuerier):  # type: ignore[misc]
+    """Abstract base for call graph node metadata.
+
+    Extends AbcNodeQuerier to access call graph node properties
+    from Storage. Do NOT instantiate directly — use FuncNode or
+    SiteNode subclasses.
+
+    Attributes:
+        node_id: AST node ID (readonly, inherited).
+        node_type: "function_declaration" or "call_site" (readonly).
+
+    """
+
+    def __init__(self, storage: Storage, node_id: str, node_type: str) -> None:
+        """Initialize CallNode via AbcNodeQuerier.
+
+        Args:
+            storage: Storage instance containing node data.
+            node_id: AST node ID.
+            node_type: "function_declaration" or "call_site".
+
+        Raises:
+            NodeNotFoundError: If node doesn't exist in storage.
+
+        """
+        super().__init__(storage, node_id)
+        self._storage_ref = storage
+        storage.set_node_prop(node_id, "node_type", node_type)
+
+    @property
+    def node_type(self) -> str:
+        """Node type: 'function_declaration' or 'call_site'."""
+        return self.get_property("node_type") or ""
+
+
+class FuncNode(CallNode):
+    """Storage wrapper for function declaration or file-level container.
+
+    Represents function declarations or file-level containers in
+    call graph. When is_file=True, represents a file-level container
+    for top-level code.
+
+    Attributes:
+        name: Function name or file path (mutable).
+        parameter_ids: AST node IDs of parameter declarations (mutable).
+        return_type_hint: Return type annotation if present (mutable).
+        is_file: Whether this is a file-level container (readonly).
+
+    """
+
+    def __init__(self, storage: Storage, node_id: str) -> None:
+        """Initialize FuncNode.
+
+        Args:
+            storage: Storage instance containing node data.
+            node_id: AST node ID of function declaration or file ID.
+
+        Raises:
+            NodeNotFoundError: If node doesn't exist in storage.
+
+        """
+        super().__init__(storage, node_id, "function_declaration")
+
+    @property
+    def is_file(self) -> bool:
+        """Whether this node represents a file-level container."""
+        value = self.get_property("is_file")
+        return bool(value) if value is not None else False
+
+    @property
+    def name(self) -> str:
+        """Function name."""
+        return self.get_property("name") or ""
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """Set function name."""
+        self._storage_ref.set_node_prop(self.node_id, "name", value)
+
+    @property
+    def parameter_ids(self) -> list[str]:
+        """AST node IDs of parameter declarations."""
+        return self.get_property("parameter_ids") or []
+
+    @parameter_ids.setter
+    def parameter_ids(self, value: list[str]) -> None:
+        """Set parameter IDs."""
+        self._storage_ref.set_node_prop(self.node_id, "parameter_ids", value)
+
+    @property
+    def return_type_hint(self) -> str | None:
+        """Type hint for return value, or None if not specified."""
+        value = self.get_property("return_type_hint")
+        return cast(str, value) if value else None
+
+    @return_type_hint.setter
+    def return_type_hint(self, value: str) -> None:
+        """Set return type hint."""
+        self._storage_ref.set_node_prop(self.node_id, "return_type_hint", value)
+
+
+class SiteNode(CallNode):
+    """Storage wrapper for call site node metadata.
+
+    Attributes:
+        argument_ids: AST node IDs of argument expressions (mutable).
+        caller_id: AST node ID of containing function or file (mutable).
+
+    """
+
+    def __init__(self, storage: Storage, node_id: str) -> None:
+        """Initialize SiteNode.
+
+        Args:
+            storage: Storage instance containing node data.
+            node_id: AST node ID of call expression.
+
+        Raises:
+            NodeNotFoundError: If node doesn't exist in storage.
+
+        """
+        super().__init__(storage, node_id, "call_site")
+
+    @property
+    def argument_ids(self) -> list[str]:
+        """AST node IDs of argument expressions."""
+        return self.get_property("argument_ids") or []
+
+    @argument_ids.setter
+    def argument_ids(self, value: list[str]) -> None:
+        """Set argument IDs."""
+        self._storage_ref.set_node_prop(self.node_id, "argument_ids", value)
+
+    @property
+    def caller_id(self) -> str:
+        """AST node ID of the function or file containing this call site.
+
+        Raises:
+            StaticAnalysisError: If caller_id has not been set.
+
+        """
+        value = self.get_property("caller_id")
+        if value is None:
+            raise StaticAnalysisError(f"Property 'caller_id' not found for node {self.node_id}")
+        return cast(str, value)
+
+    @caller_id.setter
+    def caller_id(self, value: str) -> None:
+        """Set caller function ID."""
+        self._storage_ref.set_node_prop(self.node_id, "caller_id", value)
+
+
+class CallEdge(AbcEdgeQuerier):  # type: ignore[misc]
+    """Storage wrapper for call graph edge (call site to callee).
+
+    Attributes:
+        edge_id: Edge ID tuple (from, to, type) (readonly, inherited).
+        callsite_node_id: Alias for from_nid (readonly).
+        callee_node_id: Alias for to_nid (readonly).
+
+    """
+
+    def __init__(self, storage: Storage, f_nid: str, t_nid: str, e_type: str) -> None:
+        """Initialize CallEdge.
+
+        Args:
+            storage: Storage instance containing edge data.
+            f_nid: Source node ID (callsite).
+            t_nid: Target node ID (callee).
+            e_type: Edge type.
+
+        """
+        super().__init__(storage, f_nid, t_nid, e_type)
+        self._storage_ref = storage
+
+    @property
+    def callsite_node_id(self) -> str:
+        """AST node ID of call expression (alias for from_nid)."""
+        return cast(str, self.from_nid)
+
+    @property
+    def callee_node_id(self) -> str:
+        """AST node ID of function declaration (alias for to_nid)."""
+        return cast(str, self.to_nid)

cobraphp/analysis/_callee_index.py

@@ -0,0 +1,112 @@
+"""Resolve PHP call sites to named callable declarations using the receiver class."""
+
+from __future__ import annotations
+
+from php_parser_py import AST, Node
+
+# PHP AST node types of the declarations and calls callee resolution relates.
+FUNCTION_DECL_TYPE = "Stmt_Function"
+METHOD_DECL_TYPE = "Stmt_ClassMethod"
+NAMED_CALLABLE_TYPES = (FUNCTION_DECL_TYPE, METHOD_DECL_TYPE)
+FUNCTION_CALL_TYPE = "Expr_FuncCall"
+METHOD_CALL_TYPES = ("Expr_MethodCall", "Expr_StaticCall")
+CALL_SITE_TYPES = (FUNCTION_CALL_TYPE, *METHOD_CALL_TYPES)
+# Node types php-parser emits for a name written literally in source.
+_NAME_TYPES = frozenset({"Name", "Name_FullyQualified", "Name_Relative"})
+_IDENTIFIER_TYPES = frozenset({"Identifier"})
+_VARIABLE_TYPE = "Expr_Variable"
+# Declarations that own methods; $this, self, and static refer to the nearest one.
+_CLASS_LIKE_TYPES = frozenset({"Stmt_Class", "Stmt_Trait", "Stmt_Interface", "Stmt_Enum"})
+# PHP's receiver variable and class keywords bound to the enclosing class (keywords are case-insensitive).
+_THIS_VARIABLE = "this"
+_ENCLOSING_CLASS_KEYWORDS = frozenset({"self", "static"})
+NAMESPACE_SEPARATOR = "\\"
+
+
+class CalleeIndex:
+    """Named function and method declarations indexed for callee resolution.
+
+    A function call resolves to a free function only: its exact name, else
+    the short name after the last namespace separator. A method call
+    resolves to its receiver class's method of that name, where $this,
+    self, and static denote the enclosing class and a literal class name
+    denotes that class by short name. With no receiver class (parent, a
+    variable, an expression) or no such method in it, the call resolves to
+    the first method of that name in AST order. A call whose name is an
+    expression has no callee. For every key, the first declaration wins.
+    """
+
+    def __init__(self, ast: AST) -> None:
+        self._ast = ast
+        self._functions: dict[str, Node] = {}
+        self._class_methods: dict[tuple[str, str], Node] = {}
+        self._methods: dict[str, Node] = {}
+
+    def add(self, decl: Node, name: str) -> None:
+        """Index a Stmt_Function or Stmt_ClassMethod declaration under its name."""
+        if decl.node_type == FUNCTION_DECL_TYPE:
+            self._functions.setdefault(name, decl)
+            return
+        class_name = _enclosing_class_name(self._ast, decl)
+        if class_name is not None:
+            self._class_methods.setdefault((class_name, name), decl)
+        self._methods.setdefault(name, decl)
+
+    def resolve(self, call_site: Node) -> Node | None:
+        """Return the declaration a call site targets, or None when unresolved."""
+        if call_site.node_type == FUNCTION_CALL_TYPE:
+            return self._resolve_function(call_site)
+        return self._resolve_method(call_site)
+
+    # Free function by exact name, else by namespace short name.
+    def _resolve_function(self, call_site: Node) -> Node | None:
+        name = _child_name(self._ast, call_site, _NAME_TYPES)
+        if name is None:
+            return None
+        exact = self._functions.get(name)
+        if exact is not None or NAMESPACE_SEPARATOR not in name:
+            return exact
+        return self._functions.get(_short_name(name))
+
+    # Receiver class's method, else the first method of that name.
+    def _resolve_method(self, call_site: Node) -> Node | None:
+        name = _child_name(self._ast, call_site, _IDENTIFIER_TYPES)
+        if name is None:
+            return None
+        class_name = self._receiver_class_name(call_site)
+        own = None if class_name is None else self._class_methods.get((class_name, name))
+        return own if own is not None else self._methods.get(name)
+
+    # Class a method call's receiver (its first child) statically denotes, or None.
+    def _receiver_class_name(self, call_site: Node) -> str | None:
+        receiver = next(iter(self._ast.succ(call_site)))
+        name = str(receiver.all_properties.get("name", ""))
+        if receiver.node_type == _VARIABLE_TYPE:
+            return _enclosing_class_name(self._ast, call_site) if name == _THIS_VARIABLE else None
+        if receiver.node_type not in _NAME_TYPES or name.lower() == "parent":
+            return None
+        if name.lower() in _ENCLOSING_CLASS_KEYWORDS:
+            return _enclosing_class_name(self._ast, call_site)
+        return _short_name(name)
+
+
+# Name of the nearest enclosing class-like declaration; None when absent or anonymous.
+def _enclosing_class_name(ast: AST, node: Node) -> str | None:
+    enclosing = next((a for a in ast.ancestors(node) if a.node_type in _CLASS_LIKE_TYPES), None)
+    if enclosing is None:
+        return None
+    return _child_name(ast, enclosing, _IDENTIFIER_TYPES)
+
+
+# Non-empty name property of the first direct child of the given types, else None.
+def _child_name(ast: AST, node: Node, child_types: frozenset[str]) -> str | None:
+    child = next((c for c in ast.succ(node) if c.node_type in child_types), None)
+    if child is None:
+        return None
+    name = child.all_properties.get("name", "")
+    return str(name) if name else None
+
+
+# Segment after the last namespace separator.
+def _short_name(name: str) -> str:
+    return name.rsplit(NAMESPACE_SEPARATOR, 1)[-1]