php-parser-py 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

php_parser_py/__init__.py

@@ -5,40 +5,22 @@ This package provides a Python interface to PHP-Parser, enabling AST parsing
 and manipulation of PHP code.
 """
 
-from typing import TYPE_CHECKING
+from pathlib import Path
+from typing import Callable
 
-if TYPE_CHECKING:
-    from pathlib import Path
-    from typing import Callable
-
-from php_parser_py._parser import Parser as _Parser
-from php_parser_py._printer import PrettyPrinter as _PrettyPrinter
-from php_parser_py._resources import ensure_php_parser_extracted
+from ._resources import ensure_php_parser_extracted
 
 # Ensure PHP-Parser is extracted on first import
 ensure_php_parser_extracted()
 
 # Import and expose public classes directly
-from php_parser_py._ast import AST
-from php_parser_py._edge import Edge
-from php_parser_py._exceptions import ParseError, RunnerError
-from php_parser_py._node import Node
-
-
-class Parser(_Parser):
-    """Parses PHP source code using PHP-Parser.
-
-    Invokes PHP-Parser to parse PHP code and converts the resulting JSON
-    to cpg2py Storage format for graph-based analysis.
-    """
-
-
-class PrettyPrinter(_PrettyPrinter):
-    """Converts AST to PHP code using PHP-Parser's PrettyPrinter.
-
-    Reconstructs JSON from AST graph and invokes PHP-Parser to generate
-    formatted PHP source code.
-    """
+from ._ast import AST
+from ._edge import Edge
+from ._exceptions import NodeNotInFileError, ParseError, RunnerError
+from ._modifier import Modifier
+from ._node import Node
+from ._parser import Parser
+from ._printer import PrettyPrinter
 
 
 def parse_code(code: str) -> list[Node]:
@@ -79,9 +61,13 @@ def parse_file(path: str) -> AST:
     return parser.parse_file(path)
 
 
+def _default_file_filter(path: Path) -> bool:
+    return path.suffix == ".php"
+
+
 def parse_project(
     project_path: str,
-    file_filter: "Callable[[Path], bool]" = lambda p: p.suffix == ".php",  # type: ignore
+    file_filter: Callable[[Path], bool] | None = None,
 ) -> AST:
     """Parse all PHP files in a project directory into an AST.
 
@@ -91,7 +77,7 @@ def parse_project(
     Args:
         project_path: Project root directory path.
         file_filter: Function to filter files. Takes a Path and returns
-            True if the file should be parsed. Defaults to checking for `.php` suffix.
+            True if the file should be parsed. Defaults to .php suffix.
 
     Returns:
         AST instance with project -> files -> statements hierarchy.
@@ -101,6 +87,8 @@ def parse_project(
         FileNotFoundError: If project directory does not exist.
         ValueError: If project_path is not a directory.
     """
+    if file_filter is None:
+        file_filter = _default_file_filter
     parser = Parser()
     return parser.parse_project(project_path, file_filter=file_filter)
 
@@ -108,12 +96,14 @@ def parse_project(
 __version__ = "0.1.0"
 __all__ = [
     "AST",
-    "Node",
     "Edge",
+    "Modifier",
+    "Node",
     "Parser",
     "PrettyPrinter",
     "ParseError",
     "RunnerError",
+    "NodeNotInFileError",
     "parse_code",
     "parse_file",
     "parse_project",

php_parser_py/_ast.py

@@ -4,11 +4,12 @@ from __future__ import annotations
 
 import json
 import logging
-from typing import Any, Optional
+from typing import Any
 
 from cpg2py import AbcGraphQuerier, Storage
 
 from php_parser_py._edge import Edge
+from php_parser_py._exceptions import NodeNotInFileError
 from php_parser_py._node import Node
 
 logger = logging.getLogger(__name__)
@@ -30,10 +31,11 @@ class AST(AbcGraphQuerier[Node, Edge]):
         Edge: The concrete edge type for parent-child relationships
 
     Provides graph traversal methods, JSON reconstruction for code generation,
-    and AST merging capabilities.
+    and AST merging capabilities. Uses cpg2py graph API (nodes, edges, succ,
+    prev, ancestors, descendants); storage is only used where the graph API
+    does not provide an alternative (node/edge existence and Node/Edge construction).
 
     Attributes:
-        _storage: cpg2py Storage containing AST nodes and edges.
         _root_node_id: ID of the root project node (always "project").
     """
 
@@ -45,23 +47,25 @@ class AST(AbcGraphQuerier[Node, Edge]):
             root_node_id: ID of the root node. Defaults to "project".
         """
         super().__init__(storage)
-        self._storage = storage
         self._root_node_id = root_node_id
 
-    def node(self, whose_id_is: str) -> Optional[Node]:
+    def node(self, whose_id_is: str) -> Node:
         """Return node wrapper by ID.
 
         Args:
             whose_id_is: Node ID string.
 
         Returns:
-            Node instance or None if not found.
+            Node instance for the given ID.
+
+        Raises:
+            KeyError: If the node ID is not in the graph.
         """
-        if not self._storage.contains_node(whose_id_is):
-            return None
-        return Node(self._storage, whose_id_is)
+        if not self.storage.contains_node(whose_id_is):
+            raise KeyError(f"Node not found: {whose_id_is!r}")
+        return Node(self.storage, whose_id_is)
 
-    def edge(self, fid: str, tid: str, eid: str) -> Optional[Edge]:
+    def edge(self, fid: str, tid: str, eid: str) -> Edge:
         """Return edge wrapper by IDs.
 
         Args:
@@ -70,24 +74,31 @@ class AST(AbcGraphQuerier[Node, Edge]):
             eid: Edge type.
 
         Returns:
-            Edge instance or None if not found.
+            Edge instance for the given (from, to, type).
+
+        Raises:
+            KeyError: If the edge is not in the graph.
         """
         edge_id = (fid, tid, eid)
-        if not self._storage.contains_edge(edge_id):
-            return None
-        return Edge(self._storage, fid, tid, eid)
+        if not self.storage.contains_edge(edge_id):
+            raise KeyError(f"Edge not found: {edge_id!r}")
+        return Edge(self.storage, fid, tid, eid)
 
-    def project_node(self) -> Optional[Node]:
-        """Return the project node.
+    def project_node(self) -> Node:
+        """Return the project node (root of the AST).
 
-        The project node is the root of the AST with ID "project".
+        The project node has ID "project" and is always present when the AST
+        was created by parse_file or parse_project.
 
         Returns:
-            Project Node instance or None if not found.
+            Project Node instance.
+
+        Raises:
+            KeyError: If the root node is not in the graph.
         """
-        if not self._storage.contains_node(self._root_node_id):
-            return None
-        return Node(self._storage, self._root_node_id)
+        if not self.storage.contains_node(self._root_node_id):
+            raise KeyError(f"Project node not found: {self._root_node_id!r}")
+        return Node(self.storage, self._root_node_id)
 
     def file_nodes(self) -> list[Node]:
         """Return all file nodes in the project.
@@ -95,86 +106,79 @@ class AST(AbcGraphQuerier[Node, Edge]):
         Returns:
             List of File Node instances.
         """
-        if not self.project_node():
+        try:
+            project = self.project_node()
+        except KeyError:
             return []
 
-        file_nodes = []
-        for edge_id in self._storage.get_edges():
-            from_id, to_id, edge_type = edge_id
-            if from_id == self._root_node_id and edge_type == "PARENT_OF":
-                file_node = self.node(to_id)
-                if file_node and file_node.get_property("nodeType") == "File":
-                    file_nodes.append(file_node)
-
-        # Sort by file path for consistent ordering
-        return sorted(file_nodes, key=lambda n: n.get_property("filePath", ""))
+        file_nodes = [n for n in self.succ(project) if n.node_type == "File"]
+        return sorted(file_nodes, key=lambda n: n.get("absolutePath", ""))
 
-    def get_file(
-        self, node_id: str
-    ) -> Optional[Node]:  # pylint: disable=too-many-return-statements
+    def get_file_node(self, node_id: str) -> Node:
         """Get the file node that contains the given node.
 
-        Traverses upward from the given node via PARENT_OF edges until
-        finding a File node. If the node itself is a File node, returns it.
+        Uses the AST ID convention: file node ID is the file hash (e.g. 8-char hex);
+        nodes inside that file have ID ``file_hash + "_" + increment`` (e.g. ``a1b2c3d4_1``).
+        Resolves by structure first, then falls back to ancestors() traversal.
 
         Args:
             node_id: ID of any node in the AST.
 
         Returns:
-            File Node instance containing the given node, or None if:
-            - Node ID doesn't exist
-            - Node is the project node (project doesn't belong to a file)
-            - Node is not under any file node
-        """
-        if not self._storage.contains_node(node_id):
-            return None
+            File Node instance containing the given node.
 
-        # Check if the node itself is a File node
+        Raises:
+            KeyError: If the node ID is not in the graph.
+            NodeNotInFileError: If the node is not under any file (e.g. project node).
+        """
         node = self.node(node_id)
-        if node and node.get_property("nodeType") == "File":
+        if node.node_type == "File":
             return node
 
-        # Check if it's the project node
         if node_id == self._root_node_id:
-            return None
-
-        # Traverse upward via PARENT_OF edges to find File node
-        current_id = node_id
-        visited = set()
+            raise NodeNotInFileError(node_id, "Project node has no containing file.")
 
-        while current_id and current_id not in visited:
-            visited.add(current_id)
+        result = self._try_file_by_id_prefix(node_id)
+        if result is not None:
+            return result
 
-            # Find parent node via incoming PARENT_OF edge (each node has one parent)
-            parent_id = None
-            for edge_id in self._storage.get_edges():
-                from_id, to_id, edge_type = edge_id
-                if to_id == current_id and edge_type == "PARENT_OF":
-                    parent_id = from_id
-                    break
+        return self._find_file_ancestor(node)
 
-            if not parent_id:
-                # No parent found, can't determine file
-                return None
+    def _try_file_by_id_prefix(self, node_id: str) -> Node | None:
+        """Try to find file node by ID prefix convention.
 
-            # Check parent node
-            parent_node = self.node(parent_id)
-            if not parent_node:
-                return None
+        If node_id is like "hash_123", attempts to get file node with ID "hash".
+        Returns None if ID doesn't match convention or file not found.
+        """
+        if "_" not in node_id:
+            return None
 
-            node_type = parent_node.get_property("nodeType")
-            if node_type == "File":
-                return parent_node
-            elif node_type == "Project":
-                # Reached project, no file found
-                return None
+        prefix, rest = node_id.split("_", 1)
+        if not rest.isdigit():
+            return None
 
-            # Continue traversing upward
-            current_id = parent_id
+        try:
+            candidate = self.node(prefix)
+            if candidate.node_type == "File":
+                return candidate
+        except KeyError:
+            pass
 
         return None
 
-    def to_json(self, file_hash: Optional[str] = None) -> str:
+    def _find_file_ancestor(self, node: Node) -> Node:
+        """Find first File ancestor of a node via traversal.
+
+        Raises NodeNotInFileError if no File ancestor exists.
+        """
+        for ancestor in self.ancestors(node):
+            if ancestor.node_type == "File":
+                result: Node = ancestor
+                return result
+
+        raise NodeNotInFileError(node.id, "No File node among ancestors.")
+
+    def to_json(self, file_hash: str | None = None) -> str:
         """Reconstruct PHP-Parser JSON from Storage for code generation.
 
         If file_hash is provided, exports only that file's statements.
@@ -187,10 +191,8 @@ class AST(AbcGraphQuerier[Node, Edge]):
             JSON string compatible with PHP-Parser's JsonDecoder.
         """
         if file_hash:
-            # Export single file
-            file_node = self.node(file_hash)
-            if not file_node:
-                return json.dumps([])
+            # Export single file (node() raises KeyError if file_hash not in graph)
+            self.node(file_hash)
             top_level_nodes = self._get_file_statements(file_hash)
         else:
             # Try to export from file structure first
@@ -201,53 +203,34 @@ class AST(AbcGraphQuerier[Node, Edge]):
                 for file_node in file_nodes:
                     top_level_nodes.extend(self._get_file_statements(file_node.id))
             else:
-                # No file structure - find root nodes (nodes without incoming PARENT_OF edges)
-                # Exclude project node if it exists
-                all_nodes = set(self._storage.get_nodes())
-                nodes_with_parents = set()
-
-                for edge_id in self._storage.get_edges():
-                    _, to_id, edge_type = edge_id
-                    if edge_type == "PARENT_OF":
-                        nodes_with_parents.add(to_id)
-
+                # No file structure - find root nodes via graph API (no incoming PARENT_OF)
+                all_nodes = {n.id for n in self.nodes()}
+                nodes_with_parents = {
+                    e.to_nid for e in self.edges() if e.type == "PARENT_OF"
+                }
                 root_nodes = all_nodes - nodes_with_parents
-                # Exclude project node if present
                 root_nodes.discard(self._root_node_id)
-                top_level_nodes = sorted(list(root_nodes))
+                top_level_nodes = sorted(root_nodes)
 
         result = [self._reconstruct_node(nid) for nid in top_level_nodes]
         return json.dumps(result)
 
     def _get_file_statements(self, file_hash: str) -> list[str]:
-        """Get top-level statement nodes for a specific file.
-
-        Args:
-            file_hash: File node ID (hash).
+        """Get top-level statement node IDs for a file (direct children with edge field \"stmts\").
 
-        Returns:
-            List of statement node IDs.
+        Uses succ() traversal; statement IDs follow the convention file_hash_1, file_hash_2, ...
         """
-        statement_nodes = []
-        for edge_id in self._storage.get_edges():
-            from_id, to_id, edge_type = edge_id
-            if from_id == file_hash and edge_type == "PARENT_OF":
-                edge_props = self._storage.get_edge_props(edge_id)
-                if edge_props and edge_props.get("field") == "stmts":
-                    statement_nodes.append(to_id)
-
-        # Sort by edge index to preserve order
-        def get_index(nid: str) -> int:
-            edge_props = self._storage.get_edge_props((file_hash, nid, "PARENT_OF"))
-            if edge_props:
-                return edge_props.get("index", 999999)
-            return 999999
-
-        return sorted(statement_nodes, key=get_index)
-
-    def _reconstruct_node(  # pylint: disable=too-many-locals,too-many-branches,too-many-statements
-        self, nid: str
-    ) -> dict[str, Any]:
+        file_node = self.node(file_hash)
+        stmts_with_index = []
+        for child in self.succ(file_node):
+            edge = self.edge(file_hash, child.id, "PARENT_OF")
+            if edge.get("field") == "stmts":
+                idx = edge.get("index")
+                stmts_with_index.append((999999 if idx is None else idx, child.id))
+        stmts_with_index.sort(key=lambda t: t[0])
+        return [nid for _, nid in stmts_with_index]
+
+    def _reconstruct_node(self, nid: str) -> dict[str, Any]:
         """Recursively reconstruct JSON object for a node.
 
         Args:
@@ -256,106 +239,103 @@ class AST(AbcGraphQuerier[Node, Edge]):
         Returns:
             Dictionary representing the node in PHP-Parser JSON format.
         """
-        props = self._storage.get_node_props(nid)
-        if props is None:
-            logger.warning("Node %s not found in storage, returning empty dict", nid)
-            return {}
+        node = self.node(nid)
+        props = node.all_properties
+        result: dict[str, Any] = {"nodeType": node.node_type}
+
+        attributes = self._extract_attributes(props)
+        if attributes:
+            result["attributes"] = attributes
 
-        result: dict[str, Any] = {}
-        node_type = props.get("nodeType")
-        if node_type:
-            result["nodeType"] = node_type
+        self._add_non_attribute_props(result, props)
+        self._reconstruct_child_fields(result, nid)
+        self._add_default_attrs(result, node.node_type)
 
-        # Collect attribute fields
-        attributes = {}
-        child_fields: dict[str, Any] = {}
+        return result
 
+    def _extract_attributes(self, props: dict[str, Any]) -> dict[str, Any]:
+        """Extract metadata attributes from node properties.
+
+        Returns dict with position and comment metadata.
+        """
+        attr_keys = {
+            "startLine",
+            "endLine",
+            "startFilePos",
+            "endFilePos",
+            "startTokenPos",
+            "endTokenPos",
+            "kind",
+            "comments",
+        }
+        return {k: v for k, v in props.items() if k in attr_keys}
+
+    def _add_non_attribute_props(
+        self, result: dict[str, Any], props: dict[str, Any]
+    ) -> None:
+        """Add non-attribute, non-nodeType properties to result."""
+        attr_keys = {
+            "nodeType",
+            "startLine",
+            "endLine",
+            "startFilePos",
+            "endFilePos",
+            "startTokenPos",
+            "endTokenPos",
+            "kind",
+            "comments",
+        }
         for key, value in props.items():
-            if key == "nodeType":
-                continue
-            # Attributes are typically line numbers and metadata
-            if key in (
-                "startLine",
-                "endLine",
-                "startFilePos",
-                "endFilePos",
-                "startTokenPos",
-                "endTokenPos",
-                "kind",
-                "comments",
-            ):
-                attributes[key] = value
-            else:
-                # All other fields go directly in result
-                # Child nodes will be added separately via edges
+            if key not in attr_keys:
                 result[key] = value
 
-        if attributes:
-            result["attributes"] = attributes
+    def _reconstruct_child_fields(self, result: dict[str, Any], nid: str) -> None:
+        """Reconstruct and add child fields to result.
 
-        # Reconstruct child nodes from PARENT_OF edges
-        outgoing_edges = [
-            eid
-            for eid in self._storage.get_edges()
-            if eid[0] == nid and eid[2] == "PARENT_OF"
-        ]
+        Child nodes are fetched via succ() and indexed by edge properties.
+        """
+        node = self.node(nid)
+        child_fields: dict[str, dict[int, Any]] = {}
 
-        for from_id, to_id, edge_type in outgoing_edges:
-            edge_props = self._storage.get_edge_props((from_id, to_id, edge_type))
-            if edge_props is None:
+        for child in self.succ(node):
+            try:
+                edge = self.edge(nid, child.id, "PARENT_OF")
+            except KeyError:
                 continue
 
-            field_name = edge_props.get("field")
+            field_name = edge.get("field")
             if field_name is None:
                 continue
 
-            # Skip project/file structure edges when reconstructing
-            if field_name in ("files", "stmts"):
-                # Only include stmts edges for file nodes
-                if field_name == "stmts":
-                    child_json = self._reconstruct_node(to_id)
-                    index = edge_props.get("index")
-
-                    if index is not None:
-                        # Array field
-                        if field_name not in child_fields:
-                            child_fields[field_name] = {}
-                        child_fields[field_name][index] = child_json
-                    else:
-                        # Single object field
-                        result[field_name] = child_json
+            child_json = self._reconstruct_node(child.id)
+            index = edge.get("index")
+
+            if field_name not in child_fields:
+                child_fields[field_name] = {}
+
+            if index is not None:
+                child_fields[field_name][index] = child_json
             else:
-                # Regular child field
-                child_json = self._reconstruct_node(to_id)
-                index = edge_props.get("index")
-
-                if index is not None:
-                    # Array field
-                    if field_name not in child_fields:
-                        child_fields[field_name] = {}
-                    child_fields[field_name][index] = child_json
-                else:
-                    # Single object field
-                    result[field_name] = child_json
-
-        # Convert indexed dictionaries to arrays
+                result[field_name] = child_json
+
         for field_name, indexed_children in child_fields.items():
-            if isinstance(indexed_children, dict):
-                # Sort by index and create array
+            if indexed_children:
                 max_index = max(indexed_children.keys())
                 array = [None] * (max_index + 1)
                 for idx, child in indexed_children.items():
                     array[idx] = child
                 result[field_name] = array
 
-        # Add default values for common optional fields that PHP-Parser expects
-        if node_type and ("attrGroups" not in result):
-            if (
-                node_type.startswith("Stmt_")
-                or node_type == "Param"
-                or node_type.startswith("Expr_Closure")
-                or node_type.startswith("Expr_ArrowFunction")
-            ):
-                result["attrGroups"] = []
+    def _add_default_attrs(self, result: dict[str, Any], node_type: str) -> None:
+        """Add default attrGroups if not already present.
 
-        return result
+        PHP-Parser expects attrGroups on certain node types.
+        """
+        if "attrGroups" in result:
+            return
+
+        if any(
+            node_type.startswith(prefix)
+            for prefix in ("Stmt_", "Expr_Closure", "Expr_ArrowFunction")
+        ) or node_type == "Param":
+            result["attrGroups"] = []