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

php_parser_py/__init__.py

@@ -5,11 +5,8 @@ This package provides a Python interface to PHP-Parser, enabling AST parsing
 and manipulation of PHP code.
 """
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from pathlib import Path
-    from typing import Callable
+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
@@ -21,7 +18,7 @@ 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._exceptions import NodeNotInFileError, ParseError, RunnerError
 from php_parser_py._node import Node
 
 
@@ -79,9 +76,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.
 
@@ -101,6 +102,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)
 
@@ -114,6 +117,7 @@ __all__ = [
     "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"] = []

php_parser_py/_edge.py

@@ -6,14 +6,14 @@ from cpg2py import AbcEdgeQuerier, Storage
 
 
 class Edge(AbcEdgeQuerier):
-    """Represents an edge between AST nodes.
+    """Represents an edge between AST nodes with generic property access.
 
-    Extends cpg2py's AbcEdgeQuerier to represent parent-child relationships
-    in the PHP AST. Edges store the relationship type and optional metadata
-    like field names and array indices for ordered children.
-
-    Note: PHP-Parser doesn't have explicit Edge objects. This is our abstraction
-    for representing the graph structure in cpg2py Storage.
+    Extends cpg2py's AbcEdgeQuerier. Edge type is fixed (e.g. "PARENT_OF");
+    other data is stored as arbitrary properties via Storage. For PARENT_OF
+    edges in our PHP AST mapping, we use properties "field" and "index" to
+    represent the PHP-Parser subnode key and array position—access them via
+    edge.get("field"), edge.get("index") or edge["field"], edge["index"];
+    they are not special-cased on this class.
 
     Attributes:
         _storage: cpg2py Storage instance containing edge data.
@@ -39,45 +39,11 @@ class Edge(AbcEdgeQuerier):
 
     @property
     def type(self) -> str:
-        """Return the edge type.
-
-        Returns:
-            Edge type string (e.g., "PARENT_OF").
-        """
+        """Return the edge type (e.g. "PARENT_OF")."""
         return self._edge_id[2]
 
     @property
-    def field(self) -> str | None:
-        """Return the field name for this edge.
-
-        The field name indicates which subnode property this edge represents
-        (e.g., "name", "params", "stmts").
-
-        Returns:
-            Field name string or None.
-        """
-        props = self._storage.get_edge_props(self._edge_id)
-        if props is None:
-            return None
-        return props.get("field")
-
-    @property
-    def index(self) -> int | None:
-        """Return the array index for ordered child relationships.
-
-        For edges representing array elements in PHP-Parser JSON, this property
-        contains the index position to maintain ordering.
-
-        Returns:
-            Integer index or None if not an array element.
-        """
-        props = self._storage.get_edge_props(self._edge_id)
-        if props is None:
-            return None
-        return props.get("index")
-
-    @property
-    def all_properties(self) -> dict:
+    def all_properties(self) -> dict[str, Any]:
         """Return all edge properties.
 
         Returns:

php_parser_py/_exceptions.py

@@ -21,6 +21,18 @@ class ParseError(Exception):
         self.line = line
 
 
+class NodeNotInFileError(Exception):
+    """Raised when a node has no containing file (e.g. project node or orphan).
+
+    Use when get_file(node_id) is called and the node is not under any file node.
+    """
+
+    def __init__(self, node_id: str, message: str | None = None) -> None:
+        self.node_id = node_id
+        self.message = message or f"Node {node_id!r} is not under any file node."
+        super().__init__(self.message)
+
+
 class RunnerError(Exception):
     """Raised when PHP process execution fails.
 

php_parser_py/_node.py

@@ -49,19 +49,21 @@ class Node(AbcNodeQuerier):
         return self._nid
 
     @property
-    def node_type(self) -> str | None:
+    def node_type(self) -> str:
         """Return the node type from PHP-Parser.
 
-        Returns the `nodeType` field from the stored JSON, which contains
-        the PHP-Parser class name (e.g., "Stmt_Function", "Expr_Variable").
+        Returns the `nodeType` field from the stored JSON (e.g. "Stmt_Function").
 
         Returns:
-            Node type string or None if not set.
+            Node type string.
         """
-        return self.get_property("nodeType")
+        value = self.get_property("nodeType")
+        if isinstance(value, str):
+            return value
+        raise TypeError(f"Invalid nodeType for node {self._nid}: {value!r}")
 
     @property
-    def all_properties(self) -> dict:
+    def all_properties(self) -> dict[str, Any]:
         """Return all stored properties for this node.
 
         Includes both subnodes (structural properties) and attributes (metadata).
@@ -120,69 +122,172 @@ class Node(AbcNodeQuerier):
     # PHP-Parser standard attributes (metadata properties)
 
     @property
-    def start_line(self) -> int | None:
+    def start_line(self) -> int:
         """Get starting line number.
 
         Returns:
-            Starting line number or None.
+            Starting line number.
         """
-        return self.get_property("startLine")
+        value = self.get_property("startLine")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        raise TypeError(f"Invalid startLine for node {self._nid}: {value!r}")
 
     @property
-    def end_line(self) -> int | None:
+    def end_line(self) -> int:
         """Get ending line number.
 
         Returns:
-            Ending line number or None.
+            Ending line number.
         """
-        return self.get_property("endLine")
+        value = self.get_property("endLine")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        raise TypeError(f"Invalid endLine for node {self._nid}: {value!r}")
 
     @property
-    def start_file_pos(self) -> int | None:
+    def start_file_pos(self) -> int:
         """Get starting file position (byte offset).
 
         Returns:
-            Starting byte offset or None.
+            Starting byte offset.
         """
-        return self.get_property("startFilePos")
+        value = self.get_property("startFilePos")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        raise TypeError(f"Invalid startFilePos for node {self._nid}: {value!r}")
 
     @property
-    def end_file_pos(self) -> int | None:
+    def end_file_pos(self) -> int:
         """Get ending file position (byte offset).
 
         Returns:
-            Ending byte offset or None.
+            Ending byte offset.
         """
-        return self.get_property("endFilePos")
+        value = self.get_property("endFilePos")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        raise TypeError(f"Invalid endFilePos for node {self._nid}: {value!r}")
 
     @property
-    def start_token_pos(self) -> int | None:
+    def start_token_pos(self) -> int:
         """Get starting token position.
 
         Returns:
-            Starting token index or None.
+            Starting token index.
         """
-        return self.get_property("startTokenPos")
+        value = self.get_property("startTokenPos")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        raise TypeError(f"Invalid startTokenPos for node {self._nid}: {value!r}")
 
     @property
-    def end_token_pos(self) -> int | None:
+    def end_token_pos(self) -> int:
         """Get ending token position.
 
         Returns:
-            Ending token index or None.
+            Ending token index.
         """
-        return self.get_property("endTokenPos")
+        value = self.get_property("endTokenPos")
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        raise TypeError(f"Invalid endTokenPos for node {self._nid}: {value!r}")
 
     @property
-    def comments(self) -> list | None:
+    def comments(self) -> list[str]:
         """Get comments associated with this node.
 
         Returns:
-            List of Comment objects or None.
+            List of Comment objects (may be empty).
         """
-        return self.get_property("comments")
+        value = self.get_property("comments")
+        if isinstance(value, list):
+            return value
+        raise TypeError(f"Invalid comments for node {self._nid}: {value!r}")
 
-    # Attribute helper methods
+    @property
+    def relative_path(self) -> str | None:
+        """Get the relative path of the file containing this node.
+
+        For File or Project nodes: returns their own relativePath property if set.
+        For other nodes: resolves the containing File node and returns its relativePath.
+
+        Returns:
+            Relative path string, or None if not available.
+        """
+        # If this node is a File or Project, get its own relativePath
+        if self.node_type in ("File", "Project"):
+            value = self.get_property("relativePath")
+            return value if isinstance(value, str) else None
+
+        # For other nodes, try to get from containing file via ID prefix convention
+        return self._get_file_property("relativePath")
+
+    @property
+    def absolute_path(self) -> str | None:
+        """Get the absolute path of the file containing this node.
+
+        For File or Project nodes: returns their own absolutePath property if set.
+        For other nodes: resolves the containing File node and returns its absolutePath.
+
+        Returns:
+            Absolute path string, or None if not available.
+        """
+        # If this node is a File or Project, get its own absolutePath
+        if self.node_type in ("File", "Project"):
+            value = self.get_property("absolutePath")
+            return value if isinstance(value, str) else None
+
+        # For other nodes, try to get from containing file via ID prefix convention
+        return self._get_file_property("absolutePath")
+
+    def _get_file_property(self, prop_name: str) -> str | None:
+        """Get a path property from the containing file node via ID prefix convention.
+
+        Node IDs follow the pattern: file_hash_1, file_hash_2, etc.
+        This method extracts the file_hash prefix and retrieves the property from that file node.
+
+        Args:
+            prop_name: Property name to retrieve ("relativePath" or "absolutePath").
+
+        Returns:
+            Property value from the file node, or None if not found.
+        """
+        if "_" not in self._nid:
+            return None
+
+        # Extract prefix: everything before the last underscore followed by digits
+        last_underscore = self._nid.rfind("_")
+        if last_underscore == -1:
+            return None
+
+        potential_index = self._nid[last_underscore + 1 :]
+        if not potential_index.isdigit():
+            return None
+
+        # Get the file node with ID = prefix
+        file_id = self._nid[:last_underscore]
+        if not self._storage.contains_node(file_id):
+            return None
+
+        file_props = self._storage.get_node_props(file_id)
+        if not file_props or file_props.get("nodeType") != "File":
+            return None
+
+        value = file_props.get(prop_name)
+        return value if isinstance(value, str) else None
 
     def has_attribute(self, name: str) -> bool:
         """Check if attribute exists.

php_parser_py/_parser.py

@@ -60,15 +60,16 @@ class Parser:
             raise
 
         # Normalize to list
-        if not isinstance(json_data, list):
-            json_data = [json_data]
+        node_list: list[dict[str, Any]] = (
+            [json_data] if not isinstance(json_data, list) else json_data
+        )
 
         # Create temporary storage to convert JSON to nodes
         storage = Storage()
-        node_ids = []
+        node_ids: list[str] = []
         node_counter = [1]  # Use list to allow mutation in recursive calls
 
-        for item in json_data:
+        for item in node_list:
             node_id = self._process_node(
                 storage, item, None, None, None, node_counter, ""
             )
@@ -114,12 +115,11 @@ class Parser:
                 raise ParseError("Syntax error in PHP code", line=1) from e
             raise
 
-        # Normalize json_data to list
-        if not isinstance(json_data, list):
-            json_data = [json_data]
-
+        file_list: list[dict[str, Any]] = (
+            [json_data] if not isinstance(json_data, list) else json_data
+        )
         storage = self._create_project_structure(
-            [(file_path, json_data)],
+            [(file_path, file_list)],
             [(file_path, file_hash)],
             project_path=project_path,
         )
@@ -162,18 +162,14 @@ class Parser:
         php_files = [f for f in all_files if f.is_file() and file_filter(f)]
 
         if not php_files:
-            logger.warning(f"No PHP files found in project directory: {project_path}")
+            logger.warning("No PHP files found in project directory: %s", project_path)
             # Create empty project structure
             storage = Storage()
             project_id = "project"
             storage.add_node(project_id)
             storage.set_node_props(
                 project_id,
-                {
-                    "nodeType": "Project",
-                    "label": "Project",
-                    "path": str(project_path_obj),
-                },
+                {"nodeType": "Project", "absolutePath": str(project_path)},
             )
             return AST(storage, root_node_id="project")
 
@@ -189,9 +185,10 @@ class Parser:
             code = file_path.read_text(encoding="utf-8")
             try:
                 json_data = self._runner.parse(code)
-                if not isinstance(json_data, list):
-                    json_data = [json_data]
-                all_json_data.append((file_path, json_data))
+                node_list: list[dict[str, Any]] = (
+                    [json_data] if not isinstance(json_data, list) else json_data
+                )
+                all_json_data.append((file_path, node_list))
             except RunnerError as e:
                 if "Syntax error" in str(e):
                     raise ParseError(f"Syntax error in {file_path}", line=1) from e
@@ -225,7 +222,7 @@ class Parser:
         storage.add_node(project_id)
         storage.set_node_props(
             project_id,
-            {"nodeType": "Project", "label": "Project", "path": str(project_path)},
+            {"nodeType": "Project", "absolutePath": str(project_path)},
         )
 
         # Create file nodes and process their statements
@@ -234,8 +231,26 @@ class Parser:
             try:
                 relative_path = file_path.relative_to(project_path)
             except ValueError:
-                # If file is not under project_path, use filename
-                relative_path = file_path.name
+                relative_path = Path(file_path.name)
+
+            # Normalize and inspect statements to compute file position range
+            stmt_list: list[dict[str, Any]] = (
+                [json_data] if not isinstance(json_data, list) else json_data
+            )
+            file_end_line = 1
+            file_end_file_pos = 0
+            file_end_token_pos = 0
+            for stmt in stmt_list:
+                attributes = stmt.get("attributes", {})
+                end_line = attributes.get("endLine")
+                if isinstance(end_line, int) and end_line > file_end_line:
+                    file_end_line = end_line
+                end_file_pos = attributes.get("endFilePos")
+                if isinstance(end_file_pos, int) and end_file_pos > file_end_file_pos:
+                    file_end_file_pos = end_file_pos
+                end_token_pos = attributes.get("endTokenPos")
+                if isinstance(end_token_pos, int) and end_token_pos > file_end_token_pos:
+                    file_end_token_pos = end_token_pos
 
             # Create file node (ID: hex hash)
             file_id = file_hash
@@ -244,9 +259,14 @@ class Parser:
                 file_id,
                 {
                     "nodeType": "File",
-                    "label": "File",
-                    "filePath": str(file_path),  # Absolute path
-                    "path": str(relative_path),  # Relative path from project root
+                    "absolutePath": str(file_path),
+                    "relativePath": str(relative_path),
+                    "startLine": 1,
+                    "endLine": file_end_line,
+                    "startFilePos": 0,
+                    "endFilePos": file_end_file_pos,
+                    "startTokenPos": 0,
+                    "endTokenPos": file_end_token_pos,
                 },
             )
 
@@ -257,17 +277,30 @@ class Parser:
 
             # Process statements in file (node IDs: {hex}_1, {hex}_2, ...)
             node_counter = [1]
-            if not isinstance(json_data, list):
-                json_data = [json_data]
-
-            for idx, item in enumerate(json_data):
+            for idx, item in enumerate(stmt_list):
                 self._process_node(
                     storage, item, file_id, "stmts", idx, node_counter, file_hash
                 )
 
+        # Project node does not correspond to a concrete source range.
+        # Use sentinel values for all position attributes.
+        storage.set_node_props(
+            project_id,
+            {
+                "nodeType": "Project",
+                "absolutePath": str(project_path),
+                "startLine": -1,
+                "endLine": -1,
+                "startFilePos": -1,
+                "endFilePos": -1,
+                "startTokenPos": -1,
+                "endTokenPos": -1,
+            },
+        )
+
         return storage
 
-    def _process_node(  # pylint: disable=too-many-arguments,too-many-locals,too-many-branches
+    def _process_node(
         self,
         storage: Storage,
         node_data: Any,
@@ -340,7 +373,7 @@ class Parser:
 
         # Create edge from parent if applicable
         if parent_id is not None and field_name is not None:
-            edge_props = {"field": field_name}
+            edge_props: dict[str, str | int] = {"field": field_name}
             if index is not None:
                 edge_props["index"] = index
             edge_id = (parent_id, node_id, "PARENT_OF")
@@ -349,20 +382,18 @@ class Parser:
                 storage.set_edge_props(edge_id, edge_props)
 
         # Process child fields recursively
-        for field_name, field_value in child_fields:
-            if isinstance(field_value, list):
-                # Array of child objects
-                for idx, item in enumerate(field_value):
+        for child_key, child_value in child_fields:
+            if isinstance(child_value, list):
+                for idx, item in enumerate(child_value):
                     self._process_node(
-                        storage, item, node_id, field_name, idx, node_counter, prefix
+                        storage, item, node_id, child_key, idx, node_counter, prefix
                     )
             else:
-                # Single child object
                 self._process_node(
                     storage,
-                    field_value,
+                    child_value,
                     node_id,
-                    field_name,
+                    child_key,
                     None,
                     node_counter,
                     prefix,

php_parser_py/_printer.py

@@ -59,7 +59,7 @@ class PrettyPrinter:
         # Generate code for each file
         result: dict[str, str] = {}
         for file_node in file_nodes:
-            file_path = file_node.get_property("filePath", "")
+            file_path = file_node.get_property("absolutePath", "")
             file_hash = file_node.id
 
             # Get JSON for this file only
@@ -97,7 +97,7 @@ class PrettyPrinter:
         """
         # Find file node by its relative path property
         for file_node in ast.file_nodes():
-            if file_node.get_property("path") == relative_path:
+            if file_node.get_property("relativePath") == relative_path:
                 file_hash = file_node.id
                 json_str = ast.to_json(file_hash=file_hash)
                 return self._runner.print(json_str)

php_parser_py/_resources.py

@@ -12,7 +12,7 @@ from typing import Optional
 
 # Global lock for thread-safe extraction
 _extraction_lock = threading.Lock()
-_extraction_done = False  # pylint: disable=invalid-name
+_extraction_state: dict[str, bool] = {"done": False}
 
 
 def get_vendor_path() -> Path:
@@ -55,7 +55,7 @@ def is_already_extracted(zip_path: Path) -> bool:
         stored_hash = marker_file.read_text().strip()
         current_hash = calculate_zip_hash(zip_path)
         return stored_hash == current_hash
-    except Exception:
+    except OSError:
         # If we can't read the marker or calculate hash, re-extract
         return False
 
@@ -95,10 +95,7 @@ def ensure_php_parser_extracted() -> Path:
         FileNotFoundError: If the php-parser zip file is not found
         RuntimeError: If extraction fails
     """
-    global _extraction_done
-
-    # Fast path: already extracted in this process
-    if _extraction_done:
+    if _extraction_state["done"]:
         return get_vendor_path()
 
     vendor_path = get_vendor_path()
@@ -114,25 +111,21 @@ def ensure_php_parser_extracted() -> Path:
 
     zip_path = zip_files[0]
 
-    # Check if already extracted (with marker file)
     if is_already_extracted(zip_path):
-        _extraction_done = True
+        _extraction_state["done"] = True
         return vendor_path
 
-    # Thread-safe extraction
     with _extraction_lock:
-        # Double-check after acquiring lock (another thread might have extracted)
         if is_already_extracted(zip_path):
-            _extraction_done = True
+            _extraction_state["done"] = True
             return vendor_path
 
         try:
-            # Extract PHP-Parser
             extract_php_parser(zip_path, vendor_path)
-            _extraction_done = True
+            _extraction_state["done"] = True
             return vendor_path
 
-        except Exception as e:
+        except (OSError, zipfile.BadZipFile, ValueError) as e:
             raise RuntimeError(
                 f"Failed to extract PHP-Parser from {zip_path}: {e}"
             ) from e

php_parser_py/_runner.py

@@ -3,7 +3,7 @@
 import json
 import logging
 import subprocess
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from static_php_py import PHP
 from static_php_py.exceptions import BinaryNotFoundError, DownloadError
@@ -39,7 +39,7 @@ class Runner:
         try:
             self._php = php if php is not None else PHP.builtin()
             self._php_binary = self._php.path()
-            
+
         except BinaryNotFoundError as e:
             raise RunnerError(
                 f"PHP binary not found: {e}. "
@@ -84,10 +84,10 @@ class Runner:
                 # Log complete error information
                 error_msg = f"PHP execution failed with exit code {result.returncode}"
                 if result.stderr:
-                    logger.error(f"PHP stderr: {result.stderr}")
+                    logger.error("PHP stderr: %s", result.stderr)
                     error_msg += f"\nStderr: {result.stderr}"
                 if result.stdout:
-                    logger.error(f"PHP stdout: {result.stdout}")
+                    logger.error("PHP stdout: %s", result.stdout)
                     error_msg += f"\nStdout: {result.stdout}"
 
                 raise RunnerError(
@@ -139,7 +139,7 @@ class Runner:
                         first_error.get("line"),
                     )
 
-            return result
+            return cast(dict[str, Any], result)
 
         except json.JSONDecodeError as e:
             raise RunnerError(

{php_parser_py-1.2.0.dist-info → php_parser_py-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: php-parser-py
-Version: 1.2.0
+Version: 1.2.1
 Summary: Python wrapper for PHP-Parser using cpg2py
 Author: samhsu-dev
 Author-email: samhsu-dev <yxu166@jh.edu>
@@ -11,6 +11,8 @@ Description-Content-Type: text/markdown
 
 # php-parser-py
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jhu-seclab-beluga/php-parser-py)
+
 Python wrapper for [nikic/PHP-Parser](https://github.com/nikic/PHP-Parser) built on the [cpg2py](https://github.com/jhu-seclab/cpg2py) graph framework.
 
 - **Automated**: Uses [static-php-cli](https://github.com/static-php-cli/static-php-cli) binaries (no local PHP required).

php_parser_py-1.2.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+php_parser_py/__init__.py,sha256=heraS-IKwTKjDeatzSe2OMPv7zUErOeuKZHMeJMEPUg,3387
+php_parser_py/_ast.py,sha256=hEH5XmhCAD_Qn5QgVBmGlas0mUqKVMY1eMFXeLLZdtc,11744
+php_parser_py/_edge.py,sha256=bHMtb0Bf-bQjBzlTaB01pnntYcE3WL6JRWiMyGlzq0M,2919
+php_parser_py/_exceptions.py,sha256=4jX9WfV--vCnSacEQgEE0Xtm09Ii88GkYj17yBMf7Cc,1788
+php_parser_py/_node.py,sha256=zyp0j4GRBCe2VFt22ajbYM9ZYuxgLs-Awdjwi2FisL4,9918
+php_parser_py/_parser.py,sha256=mwi7idEJZLgzkMPvUThHyt1MjOEEuNEqfyJam9YVRg4,14511
+php_parser_py/_printer.py,sha256=mvJ9o8ql_Yk9-6u69Jx-4azD7aIG9W1NDWaJVkzc2gI,3506
+php_parser_py/_resources.py,sha256=TUYfH58HV1y93kq39gW-aHKkR1MRZQb131VHzfR4LBc,4305
+php_parser_py/_runner.py,sha256=MxTh5Z7tuyOLneX0IggfshmyQf6mL1duJPYozu4899c,6985
+php_parser_py/resources/php-parser-4.19.4.zip,sha256=ND6zsylItt4owMoQnq-3id_ScMAXEfVyHzzRi0wKthQ,144334
+php_parser_py/vendor/.extracted,sha256=35VHVRaR8xmvJSW2J6Z8MXxiFVnsRgeuJJPNS_5yzB8,64
+php_parser_py/vendor/LICENSE.txt,sha256=3YWeEH-sn4ekQTq4w8lvDxYRoX9Zai21YqWk9JBMHpc,1520
+php_parser_py/vendor/php-parser.phar,sha256=xeuVm4n37yt_DX3pNH1Ugc1ihGtoC97b7ao7a-AGjTk,1009441
+php_parser_py-1.2.1.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+php_parser_py-1.2.1.dist-info/METADATA,sha256=1IagDWYT0alURw-YwmgfCnu4nF9m5tpdob2vpr_DFS4,2037
+php_parser_py-1.2.1.dist-info/RECORD,,

php_parser_py-1.2.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-php_parser_py/__init__.py,sha256=Iiea9w5auFtG4yAA8KNECRIwbw6IysYteTWv8HcE16E,3284
-php_parser_py/_ast.py,sha256=QnkdtMsaB3IFDhGRxqr1QIXQif9blIZE8tIGus9qmuo,12728
-php_parser_py/_edge.py,sha256=CFGIakA_-kAeS8PQZ56ukBBohdBN7XpXZmYjuJ7fq1Q,3789
-php_parser_py/_exceptions.py,sha256=cqGfU64-jXzJ9Y0edlMMZUzmMyClco0t-e33p5r90TA,1351
-php_parser_py/_node.py,sha256=8YZfXjKf_4lf1R29UxxByw_iN2pBlTK6HNbx0z-9uWU,5654
-php_parser_py/_parser.py,sha256=rJ8_Oco7sCOwhy512oJJmGr2WijF25rqvLRA4Da6c3Y,13071
-php_parser_py/_printer.py,sha256=wj6poxv_85YvhTHwa0zEJpP3_FXyTWxxzBrxQTvtgSY,3494
-php_parser_py/_resources.py,sha256=1BL6cNiBuGr7kPFw7MKF5F_ZaUvFsvgEPjU2wThNlCE,4519
-php_parser_py/_runner.py,sha256=RVysl2489tBpg0t595nZ1buutz5HdOVjQaPnk36F9Tg,6967
-php_parser_py/resources/php-parser-4.19.4.zip,sha256=ND6zsylItt4owMoQnq-3id_ScMAXEfVyHzzRi0wKthQ,144334
-php_parser_py/vendor/.extracted,sha256=35VHVRaR8xmvJSW2J6Z8MXxiFVnsRgeuJJPNS_5yzB8,64
-php_parser_py/vendor/LICENSE.txt,sha256=3YWeEH-sn4ekQTq4w8lvDxYRoX9Zai21YqWk9JBMHpc,1520
-php_parser_py/vendor/php-parser.phar,sha256=xeuVm4n37yt_DX3pNH1Ugc1ihGtoC97b7ao7a-AGjTk,1009441
-php_parser_py-1.2.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
-php_parser_py-1.2.0.dist-info/METADATA,sha256=ji7zPJ5JqLdjVKyj-5AaArrh9Lc8mc-73yRqkAUdgpQ,1932
-php_parser_py-1.2.0.dist-info/RECORD,,