php-parser-py 1.2.1__tar.gz → 1.2.2__tar.gz

{php_parser_py-1.2.1 → php_parser_py-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: php-parser-py
-Version: 1.2.1
+Version: 1.2.2
 Summary: Python wrapper for PHP-Parser using cpg2py
 Author: samhsu-dev
 Author-email: samhsu-dev <yxu166@jh.edu>
@@ -13,9 +13,9 @@ Description-Content-Type: text/markdown
 
 [![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.
+Python wrapper for [nikic/PHP-Parser](https://github.com/nikic/PHP-Parser) built on the [cpg2py](https://github.com/samhsu-dev/cpg2py) graph framework.
 
-- **Automated**: Uses [static-php-cli](https://github.com/static-php-cli/static-php-cli) binaries (no local PHP required).
+- **Automated**: Uses [static-php-py](https://github.com/jhu-seclab-beluga/static-php-py) binaries (no local PHP required).
 - **Graph-Based**: AST nodes are stored in a queryable graph database.
 - **Accurate**: Full support for PHP-Parser 4.19.4 AST structure.
 
@@ -25,38 +25,37 @@ pip install php-parser-py
 ```
 
 ```python
-from php_parser_py import parse_file, parse_project
+from php_parser_py import parse_file, Modifier
 
 # 1. Parse
 ast = parse_file("src/User.php")
-# ast = parse_project("src/")
 
-# 2. Traverse
-files = ast.file_nodes()
-
-# Find specific nodes
+# 2. Query
 functions = ast.nodes(lambda n: n.node_type == "Stmt_Function")
-
-# Get properties (scalars)
 for func in functions:
     print(f"Function: {func['namespacedName']}")
-
-# Get child nodes (structure)
-for func in functions:
-    # Use helper method or traverse edges
     params = [c for c in ast.succ(func) if c.node_type == "Param"]
+
+# 3. Modify properties
+func.set_property("analyzed", True)
+
+# 4. Modify structure
+modifier = Modifier(ast)
+modifier.add_node("new_1", "Stmt_Break")
+modifier.add_edge("parent_id", "new_1", field="stmts", index=0)
+modifier.remove_node("obsolete_node_id")
 ```
 
 ## Documentation
 
 - **[Architecture & Design](docs/design.md)**
-  Detailed design documentation covering internal architecture, class specifications, and design rationale.
+  Internal architecture, class specifications, and design rationale.
 
 - **[AST Structure Reference](docs/libs/php_parser_ast.md)**  
-  Complete table of all node types, subnodes (children), and properties. Verified against PHP-Parser source.
+  Complete table of all node types, subnodes (children), and properties.
 
-- **[Graph Traversal Guide](docs/libs/cpg2py_traversal.md)**  
-  How to navigate the graph (`succ`, `prev`), access properties, and modify the graph (`set_property`).
+- **[cpg2py Graph API](docs/libs/cpg2py.md)**  
+  Querying (`nodes`, `succ`, `prev`)
 
 ## Requirements
 - Python ≥ 3.11

{php_parser_py-1.2.1 → php_parser_py-1.2.2}/README.md

@@ -2,9 +2,9 @@
 
 [![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.
+Python wrapper for [nikic/PHP-Parser](https://github.com/nikic/PHP-Parser) built on the [cpg2py](https://github.com/samhsu-dev/cpg2py) graph framework.
 
-- **Automated**: Uses [static-php-cli](https://github.com/static-php-cli/static-php-cli) binaries (no local PHP required).
+- **Automated**: Uses [static-php-py](https://github.com/jhu-seclab-beluga/static-php-py) binaries (no local PHP required).
 - **Graph-Based**: AST nodes are stored in a queryable graph database.
 - **Accurate**: Full support for PHP-Parser 4.19.4 AST structure.
 
@@ -14,38 +14,37 @@ pip install php-parser-py
 ```
 
 ```python
-from php_parser_py import parse_file, parse_project
+from php_parser_py import parse_file, Modifier
 
 # 1. Parse
 ast = parse_file("src/User.php")
-# ast = parse_project("src/")
 
-# 2. Traverse
-files = ast.file_nodes()
-
-# Find specific nodes
+# 2. Query
 functions = ast.nodes(lambda n: n.node_type == "Stmt_Function")
-
-# Get properties (scalars)
 for func in functions:
     print(f"Function: {func['namespacedName']}")
-
-# Get child nodes (structure)
-for func in functions:
-    # Use helper method or traverse edges
     params = [c for c in ast.succ(func) if c.node_type == "Param"]
+
+# 3. Modify properties
+func.set_property("analyzed", True)
+
+# 4. Modify structure
+modifier = Modifier(ast)
+modifier.add_node("new_1", "Stmt_Break")
+modifier.add_edge("parent_id", "new_1", field="stmts", index=0)
+modifier.remove_node("obsolete_node_id")
 ```
 
 ## Documentation
 
 - **[Architecture & Design](docs/design.md)**
-  Detailed design documentation covering internal architecture, class specifications, and design rationale.
+  Internal architecture, class specifications, and design rationale.
 
 - **[AST Structure Reference](docs/libs/php_parser_ast.md)**  
-  Complete table of all node types, subnodes (children), and properties. Verified against PHP-Parser source.
+  Complete table of all node types, subnodes (children), and properties.
 
-- **[Graph Traversal Guide](docs/libs/cpg2py_traversal.md)**  
-  How to navigate the graph (`succ`, `prev`), access properties, and modify the graph (`set_property`).
+- **[cpg2py Graph API](docs/libs/cpg2py.md)**  
+  Querying (`nodes`, `succ`, `prev`)
 
 ## Requirements
 - Python ≥ 3.11

{php_parser_py-1.2.1 → php_parser_py-1.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "php-parser-py"
-version = "1.2.1"
+version = "1.2.2"
 description = "Python wrapper for PHP-Parser using cpg2py"
 readme = "README.md"
 authors = [

{php_parser_py-1.2.1 → php_parser_py-1.2.2}/src/php_parser_py/__init__.py

@@ -8,34 +8,19 @@ and manipulation of PHP code.
 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 NodeNotInFileError, 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]:
@@ -92,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.
@@ -111,8 +96,9 @@ def parse_project(
 __version__ = "0.1.0"
 __all__ = [
     "AST",
-    "Node",
     "Edge",
+    "Modifier",
+    "Node",
     "Parser",
     "PrettyPrinter",
     "ParseError",

php_parser_py-1.2.2/src/php_parser_py/_modifier.py

@@ -0,0 +1,140 @@
+"""Modifier class for AST graph mutation operations."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ._edge import Edge
+from ._node import Node
+
+if TYPE_CHECKING:
+    from ._ast import AST
+
+logger = logging.getLogger(__name__)
+
+
+class Modifier:
+    """Encapsulates all graph mutation operations for an AST.
+
+    The only approved way to add, remove, or structurally modify nodes and
+    edges in the AST graph. Callers must never use Storage directly.
+
+    AST (AbcGraphQuerier) is a query interface; graph mutation is a separate
+    concern handled by this class. Mutations are immediately visible through
+    the wrapped AST's query methods.
+
+    Attributes:
+        _ast: The AST instance being modified.
+        _storage: Reference to the AST's internal Storage.
+    """
+
+    def __init__(self, ast: AST) -> None:
+        """Wrap an existing AST instance for mutation.
+
+        Args:
+            ast: AST instance to modify.
+        """
+        self._ast = ast
+        self._storage = ast.storage
+
+    @property
+    def ast(self) -> AST:
+        """Return the underlying AST instance."""
+        return self._ast
+
+    # -- Node Operations --
+
+    def add_node(self, node_id: str, node_type: str, **props: object) -> Node:
+        """Create a new node in the graph with the given type and properties.
+
+        Args:
+            node_id: Unique node ID string.
+            node_type: PHP-Parser node type (e.g. "Stmt_Break").
+            **props: Additional node properties to set.
+
+        Returns:
+            Node instance for the newly created node.
+
+        Raises:
+            ValueError: If node_id already exists in the graph.
+        """
+        if self._storage.contains_node(node_id):
+            raise ValueError(f"Node already exists: {node_id!r}")
+
+        self._storage.add_node(node_id)
+        all_props: dict[str, object] = {"nodeType": node_type, **props}
+        self._storage.set_node_props(node_id, all_props)
+        return Node(self._storage, node_id)
+
+    def remove_node(self, node_id: str) -> None:
+        """Remove a node and all its connected edges from the graph.
+
+        Args:
+            node_id: Node ID to remove.
+
+        Raises:
+            KeyError: If node_id is not in the graph.
+        """
+        if not self._storage.contains_node(node_id):
+            raise KeyError(f"Node not found: {node_id!r}")
+        self._storage.remove_node(node_id)
+
+    # -- Edge Operations --
+
+    def add_edge(
+        self,
+        from_id: str,
+        to_id: str,
+        edge_type: str = "PARENT_OF",
+        **props: object,
+    ) -> Edge:
+        """Create a new edge between two existing nodes.
+
+        Args:
+            from_id: Source node ID.
+            to_id: Target node ID.
+            edge_type: Edge type. Defaults to "PARENT_OF".
+            **props: Edge properties (e.g. field="stmts", index=0).
+
+        Returns:
+            Edge instance for the newly created edge.
+
+        Raises:
+            KeyError: If either node does not exist.
+            ValueError: If edge already exists.
+        """
+        if not self._storage.contains_node(from_id):
+            raise KeyError(f"Source node not found: {from_id!r}")
+        if not self._storage.contains_node(to_id):
+            raise KeyError(f"Target node not found: {to_id!r}")
+
+        edge_id = (from_id, to_id, edge_type)
+        if self._storage.contains_edge(edge_id):
+            raise ValueError(f"Edge already exists: {edge_id!r}")
+
+        self._storage.add_edge(edge_id)
+        if props:
+            self._storage.set_edge_props(edge_id, props)
+        return Edge(self._storage, from_id, to_id, edge_type)
+
+    def remove_edge(
+        self,
+        from_id: str,
+        to_id: str,
+        edge_type: str = "PARENT_OF",
+    ) -> None:
+        """Remove an edge from the graph.
+
+        Args:
+            from_id: Source node ID.
+            to_id: Target node ID.
+            edge_type: Edge type. Defaults to "PARENT_OF".
+
+        Raises:
+            KeyError: If edge is not in the graph.
+        """
+        edge_id = (from_id, to_id, edge_type)
+        if not self._storage.contains_edge(edge_id):
+            raise KeyError(f"Edge not found: {edge_id!r}")
+        self._storage.remove_edge(edge_id)

php_parser_py-1.2.2/src/php_parser_py/_parser.py

@@ -0,0 +1,371 @@
+"""Parser class for PHP code parsing."""
+
+import hashlib
+import logging
+from pathlib import Path
+from typing import Callable, Optional
+
+from cpg2py import Storage
+from static_php_py import PHP
+
+from ._ast import AST
+from ._exceptions import ParseError, RunnerError
+from ._modifier import Modifier
+from ._node import Node
+from ._runner import Runner
+
+logger = logging.getLogger(__name__)
+
+
+class Parser:
+    """Parses PHP source code using PHP-Parser.
+
+    Uses Modifier for all AST construction. Parser never calls Storage
+    directly — all node/edge creation goes through Modifier.
+
+    Attributes:
+        _runner: Runner instance for PHP-Parser invocation.
+    """
+
+    def __init__(self, php: Optional[PHP] = None) -> None:
+        """Initialize Parser with Runner.
+
+        Args:
+            php: Optional PHP instance. If not provided, uses builtin PHP.
+        """
+        self._runner = Runner(php=php)
+
+    def parse_code(self, code: str) -> list[Node]:
+        """Parse PHP code string into a list of top-level statement nodes.
+
+        Does not create project or file nodes. Returns raw statement nodes
+        that can be used for analysis or inserted into other AST structures.
+
+        Args:
+            code: PHP source code to parse.
+
+        Returns:
+            List of Node instances representing top-level statements.
+
+        Raises:
+            ParseError: If code has syntax errors.
+            RunnerError: If PHP execution fails.
+        """
+        json_data = self._parse_php(code)
+        node_list = self._normalize_json(json_data)
+
+        modifier = Modifier(AST(Storage(), root_node_id="__code_root__"))
+        node_counter = [1]
+        node_ids: list[str] = []
+
+        for item in node_list:
+            node_id = self._process_node(
+                modifier, item, None, None, None, node_counter, ""
+            )
+            if node_id:
+                node_ids.append(node_id)
+
+        return [modifier.ast.node(nid) for nid in node_ids]
+
+    def parse_file(self, path: str) -> AST:
+        """Parse a single PHP file into an AST with project and file nodes.
+
+        Creates a project node (ID: "project") and a file node (ID: hex
+        hash of path). File node contains all statements from the file.
+
+        Args:
+            path: File path string.
+
+        Returns:
+            AST instance with project -> file -> statements hierarchy.
+
+        Raises:
+            ParseError: If PHP-Parser reports syntax error.
+            FileNotFoundError: If file does not exist.
+        """
+        file_path = Path(path).resolve()
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        project_path = file_path.parent
+        file_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:8]
+        code = file_path.read_text(encoding="utf-8")
+        json_data = self._parse_php(code)
+        file_list = self._normalize_json(json_data)
+
+        modifier = self._build_project_structure(
+            [(file_path, file_list)],
+            [(file_path, file_hash)],
+            project_path=project_path,
+        )
+        return modifier.ast
+
+    def parse_project(
+        self,
+        project_path: str,
+        file_filter: Callable[[Path], bool] = lambda p: p.suffix == ".php",
+    ) -> AST:
+        """Parse all PHP files in a project directory into an AST.
+
+        Recursively traverses the project directory to find all PHP files,
+        then parses them into a single AST with project and file nodes.
+
+        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 .php suffix.
+
+        Returns:
+            AST instance with project -> files -> statements hierarchy.
+
+        Raises:
+            ParseError: If any file has syntax errors.
+            FileNotFoundError: If project directory does not exist.
+            ValueError: If project_path is not a directory.
+        """
+        project_path_obj = Path(project_path).resolve()
+
+        if not project_path_obj.exists():
+            raise FileNotFoundError(f"Project directory not found: {project_path}")
+        if not project_path_obj.is_dir():
+            raise ValueError(f"Project path is not a directory: {project_path}")
+
+        php_files = [
+            f for f in project_path_obj.rglob("*") if f.is_file() and file_filter(f)
+        ]
+
+        if not php_files:
+            logger.warning("No PHP files found in project directory: %s", project_path)
+            return self._build_empty_project(project_path_obj)
+
+        file_infos = [
+            (fp, hashlib.md5(str(fp).encode()).hexdigest()[:8]) for fp in php_files
+        ]
+
+        all_json_data = []
+        for file_path, _ in file_infos:
+            code = file_path.read_text(encoding="utf-8")
+            json_data = self._parse_php(code, source=str(file_path))
+            all_json_data.append((file_path, self._normalize_json(json_data)))
+
+        modifier = self._build_project_structure(
+            all_json_data, file_infos, project_path=project_path_obj
+        )
+        return modifier.ast
+
+    # -- Internal helpers --
+
+    def _parse_php(self, code: str, source: str = "input") -> object:
+        # Invoke PHP-Parser and translate RunnerError into ParseError.
+        try:
+            return self._runner.parse(code)
+        except RunnerError as e:
+            if "Syntax error" in str(e):
+                raise ParseError(f"Syntax error in {source}", line=1) from e
+            raise
+
+    @staticmethod
+    def _normalize_json(json_data: object) -> list[dict[str, object]]:
+        # Ensure JSON data is always a list of node dicts.
+        if isinstance(json_data, list):
+            return json_data
+        if isinstance(json_data, dict):
+            return [json_data]
+        return []
+
+    def _build_empty_project(self, project_path: Path) -> AST:
+        # Create a project-only AST with no files.
+        modifier = Modifier(AST(Storage()))
+        modifier.add_node(
+            "project",
+            "Project",
+            absolutePath=str(project_path),
+            startLine=-1,
+            endLine=-1,
+            startFilePos=-1,
+            endFilePos=-1,
+            startTokenPos=-1,
+            endTokenPos=-1,
+        )
+        return modifier.ast
+
+    def _build_project_structure(
+        self,
+        files_data: list[tuple[Path, list[dict[str, object]]]],
+        file_infos: list[tuple[Path, str]],
+        project_path: Path,
+    ) -> Modifier:
+        # Build project -> files -> statements hierarchy via Modifier.
+        modifier = Modifier(AST(Storage()))
+
+        modifier.add_node("project", "Project", absolutePath=str(project_path))
+
+        for (file_path, file_hash), (_, json_data) in zip(file_infos, files_data):
+            self._add_file_node(modifier, file_path, file_hash, json_data, project_path)
+
+        # Set sentinel position values on project node.
+        project_node = modifier.ast.node("project")
+        project_node.set_properties(
+            {
+                "startLine": -1,
+                "endLine": -1,
+                "startFilePos": -1,
+                "endFilePos": -1,
+                "startTokenPos": -1,
+                "endTokenPos": -1,
+            }
+        )
+
+        return modifier
+
+    def _add_file_node(
+        self,
+        modifier: Modifier,
+        file_path: Path,
+        file_hash: str,
+        stmt_list: list[dict[str, object]],
+        project_path: Path,
+    ) -> None:
+        # Create file node, link to project, process statements.
+        try:
+            relative_path = file_path.relative_to(project_path)
+        except ValueError:
+            relative_path = Path(file_path.name)
+
+        end_pos = self._compute_file_end_positions(stmt_list)
+
+        modifier.add_node(
+            file_hash,
+            "File",
+            absolutePath=str(file_path),
+            relativePath=str(relative_path),
+            startLine=1,
+            endLine=end_pos["endLine"],
+            startFilePos=0,
+            endFilePos=end_pos["endFilePos"],
+            startTokenPos=0,
+            endTokenPos=end_pos["endTokenPos"],
+        )
+        modifier.add_edge("project", file_hash, field="files")
+
+        node_counter = [1]
+        for idx, item in enumerate(stmt_list):
+            self._process_node(
+                modifier, item, file_hash, "stmts", idx, node_counter, file_hash
+            )
+
+    @staticmethod
+    def _compute_file_end_positions(
+        stmt_list: list[dict[str, object]],
+    ) -> dict[str, int]:
+        # Compute file end positions from statement attributes.
+        end_line = 1
+        end_file_pos = 0
+        end_token_pos = 0
+
+        for stmt in stmt_list:
+            attrs = stmt.get("attributes", {})
+            if not isinstance(attrs, dict):
+                continue
+            val = attrs.get("endLine")
+            if isinstance(val, int) and val > end_line:
+                end_line = val
+            val = attrs.get("endFilePos")
+            if isinstance(val, int) and val > end_file_pos:
+                end_file_pos = val
+            val = attrs.get("endTokenPos")
+            if isinstance(val, int) and val > end_token_pos:
+                end_token_pos = val
+
+        return {
+            "endLine": end_line,
+            "endFilePos": end_file_pos,
+            "endTokenPos": end_token_pos,
+        }
+
+    def _process_node(
+        self,
+        modifier: Modifier,
+        node_data: object,
+        parent_id: str | None,
+        field_name: str | None,
+        index: int | None,
+        node_counter: list[int],
+        prefix: str,
+    ) -> str | None:
+        # Recursively convert a PHP-Parser JSON node into graph nodes/edges.
+        if not isinstance(node_data, dict) or "nodeType" not in node_data:
+            return None
+
+        node_id = self._generate_node_id(node_counter, prefix)
+        properties, child_fields = self._extract_node_data(node_data)
+
+        node_type_val = properties.pop("nodeType")
+        if not isinstance(node_type_val, str):
+            return None
+
+        modifier.add_node(node_id, node_type_val, **properties)
+
+        if parent_id is not None and field_name is not None:
+            if index is not None:
+                modifier.add_edge(parent_id, node_id, field=field_name, index=index)
+            else:
+                modifier.add_edge(parent_id, node_id, field=field_name)
+
+        self._process_children(modifier, child_fields, node_id, node_counter, prefix)
+        return node_id
+
+    @staticmethod
+    def _generate_node_id(node_counter: list[int], prefix: str) -> str:
+        # Generate unique node ID from counter and prefix.
+        current = node_counter[0]
+        node_counter[0] += 1
+        if prefix:
+            return f"{prefix}_{current}"
+        return f"node_{current}"
+
+    @staticmethod
+    def _extract_node_data(
+        node_data: dict[str, object],
+    ) -> tuple[dict[str, object], list[tuple[str, object]]]:
+        # Separate scalar properties from child fields.
+        properties: dict[str, object] = {}
+        child_fields: list[tuple[str, object]] = []
+
+        for key, value in node_data.items():
+            if key == "attributes" and isinstance(value, dict):
+                properties.update(value)
+            elif isinstance(value, dict):
+                child_fields.append((key, value))
+            elif isinstance(value, list) and value and isinstance(value[0], dict):
+                child_fields.append((key, value))
+            else:
+                properties[key] = value
+
+        return properties, child_fields
+
+    def _process_children(
+        self,
+        modifier: Modifier,
+        child_fields: list[tuple[str, object]],
+        parent_id: str,
+        node_counter: list[int],
+        prefix: str,
+    ) -> None:
+        # Process child fields recursively.
+        for child_key, child_value in child_fields:
+            if isinstance(child_value, list):
+                for idx, item in enumerate(child_value):
+                    self._process_node(
+                        modifier, item, parent_id, child_key, idx, node_counter, prefix
+                    )
+            else:
+                self._process_node(
+                    modifier,
+                    child_value,
+                    parent_id,
+                    child_key,
+                    None,
+                    node_counter,
+                    prefix,
+                )

php_parser_py-1.2.1/src/php_parser_py/_parser.py

@@ -1,402 +0,0 @@
-"""Parser class for PHP code parsing."""
-
-import hashlib
-import logging
-from pathlib import Path
-from typing import Any, Callable, Optional
-
-from cpg2py import Storage
-from static_php_py import PHP
-
-from php_parser_py._ast import AST
-from php_parser_py._exceptions import ParseError, RunnerError
-from php_parser_py._node import Node
-from php_parser_py._runner import Runner
-
-logger = logging.getLogger(__name__)
-
-
-class Parser:
-    """Parses PHP source code using PHP-Parser.
-
-    Provides three parsing methods:
-    - parse_code: Parse code string, returns list of top-level statement nodes
-    - parse_file: Parse single file, returns AST with project and file nodes
-    - parse_project: Parse project directory, returns AST with project and all PHP files
-
-    Attributes:
-        _runner: Runner instance for PHP-Parser invocation.
-    """
-
-    def __init__(self, php: Optional[PHP] = None) -> None:
-        """Initialize Parser with Runner.
-
-        Args:
-            php: Optional PHP instance. If not provided, uses builtin PHP.
-        """
-        self._runner = Runner(php=php)
-
-    def parse_code(self, code: str) -> list[Node]:
-        """Parse PHP code string into a list of top-level statement nodes.
-
-        Does not create project or file nodes. Returns raw statement nodes
-        that can be used for analysis or inserted into other AST structures.
-
-        Args:
-            code: PHP source code to parse.
-
-        Returns:
-            List of Node instances representing top-level statements.
-
-        Raises:
-            ParseError: If code has syntax errors.
-            RunnerError: If PHP execution fails.
-        """
-        try:
-            json_data = self._runner.parse(code)
-        except RunnerError as e:
-            if "Syntax error" in str(e):
-                raise ParseError("Syntax error in PHP code", line=1) from e
-            raise
-
-        # Normalize to list
-        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: list[str] = []
-        node_counter = [1]  # Use list to allow mutation in recursive calls
-
-        for item in node_list:
-            node_id = self._process_node(
-                storage, item, None, None, None, node_counter, ""
-            )
-            if node_id:
-                node_ids.append(node_id)
-
-        # Return Node instances
-        return [Node(storage, nid) for nid in node_ids]
-
-    def parse_file(self, path: str) -> AST:
-        """Parse a single PHP file into an AST with project and file nodes.
-
-        Creates a project node (ID: "project") and a file node (ID: hex hash of path).
-        File node contains all statements from the file.
-        Project path is set to the file's directory.
-
-        Args:
-            path: File path string.
-
-        Returns:
-            AST instance with project -> file -> statements hierarchy.
-
-        Raises:
-            ParseError: If PHP-Parser reports syntax error.
-            FileNotFoundError: If file does not exist.
-        """
-        file_path = Path(path).resolve()
-        if not file_path.exists():
-            raise FileNotFoundError(f"File not found: {path}")
-
-        # Project path is the file's directory
-        project_path = file_path.parent
-
-        # Generate file hash (hex)
-        file_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:8]
-
-        code = file_path.read_text(encoding="utf-8")
-
-        try:
-            json_data = self._runner.parse(code)
-        except RunnerError as e:
-            if "Syntax error" in str(e):
-                raise ParseError("Syntax error in PHP code", line=1) from e
-            raise
-
-        file_list: list[dict[str, Any]] = (
-            [json_data] if not isinstance(json_data, list) else json_data
-        )
-        storage = self._create_project_structure(
-            [(file_path, file_list)],
-            [(file_path, file_hash)],
-            project_path=project_path,
-        )
-        return AST(storage, root_node_id="project")
-
-    def parse_project(
-        self,
-        project_path: str,
-        file_filter: Callable[[Path], bool] = lambda p: p.suffix == ".php",
-    ) -> AST:
-        """Parse all PHP files in a project directory into an AST.
-
-        Recursively traverses the project directory to find all PHP files,
-        then parses them into a single AST with project and file nodes.
-        Each file node has ID based on its path hash.
-
-        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.
-
-        Returns:
-            AST instance with project -> files -> statements hierarchy.
-
-        Raises:
-            ParseError: If any file has syntax errors.
-            FileNotFoundError: If project directory does not exist.
-            ValueError: If project_path is not a directory.
-        """
-        project_path_obj = Path(project_path).resolve()
-
-        if not project_path_obj.exists():
-            raise FileNotFoundError(f"Project directory not found: {project_path}")
-
-        if not project_path_obj.is_dir():
-            raise ValueError(f"Project path is not a directory: {project_path}")
-
-        # Find all files recursively and filter
-        all_files = project_path_obj.rglob("*")
-        php_files = [f for f in all_files if f.is_file() and file_filter(f)]
-
-        if not php_files:
-            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", "absolutePath": str(project_path)},
-            )
-            return AST(storage, root_node_id="project")
-
-        # Prepare file information
-        file_infos = []
-        for file_path in php_files:
-            file_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:8]
-            file_infos.append((file_path, file_hash))
-
-        # Parse all files
-        all_json_data = []
-        for file_path, _ in file_infos:
-            code = file_path.read_text(encoding="utf-8")
-            try:
-                json_data = self._runner.parse(code)
-                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
-                raise
-
-        storage = self._create_project_structure(
-            all_json_data, file_infos, project_path=project_path_obj
-        )
-        return AST(storage, root_node_id="project")
-
-    def _create_project_structure(
-        self,
-        files_data: list[tuple[Path, Any]],
-        file_infos: list[tuple[Path, str]],
-        project_path: Path,
-    ) -> Storage:
-        """Create AST structure with project -> files -> statements hierarchy.
-
-        Args:
-            files_data: List of (file_path, json_data) tuples.
-            file_infos: List of (file_path, file_hash) tuples.
-            project_path: Project root directory path.
-
-        Returns:
-            Storage instance with complete project structure.
-        """
-        storage = Storage()
-
-        # Create project node (fixed ID: "project")
-        project_id = "project"
-        storage.add_node(project_id)
-        storage.set_node_props(
-            project_id,
-            {"nodeType": "Project", "absolutePath": str(project_path)},
-        )
-
-        # Create file nodes and process their statements
-        for (file_path, file_hash), (_, json_data) in zip(file_infos, files_data):
-            # Calculate relative path from project root
-            try:
-                relative_path = file_path.relative_to(project_path)
-            except ValueError:
-                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
-            storage.add_node(file_id)
-            storage.set_node_props(
-                file_id,
-                {
-                    "nodeType": "File",
-                    "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,
-                },
-            )
-
-            # Link file to project
-            edge_id = (project_id, file_id, "PARENT_OF")
-            storage.add_edge(edge_id)
-            storage.set_edge_props(edge_id, {"field": "files"})
-
-            # Process statements in file (node IDs: {hex}_1, {hex}_2, ...)
-            node_counter = [1]
-            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(
-        self,
-        storage: Storage,
-        node_data: Any,
-        parent_id: str | None,
-        field_name: str | None,
-        index: int | None,
-        node_counter: list[int],
-        prefix: str,
-    ) -> str | None:
-        """Process a single node and its children recursively.
-
-        Args:
-            storage: Storage to populate.
-            node_data: JSON node data.
-            parent_id: Parent node ID if this is a child.
-            field_name: Field name in parent if this is a child.
-            index: Array index if this is an array element.
-            node_counter: Mutable list with single int counter for generating node IDs.
-            prefix: Prefix for node IDs (file hash for file nodes, empty for code nodes).
-
-        Returns:
-            Node ID if a node was created, None otherwise.
-        """
-        if node_data is None:
-            return None
-
-        if not isinstance(node_data, dict):
-            return None
-
-        # Only create nodes for objects with nodeType
-        if "nodeType" not in node_data:
-            return None
-
-        # Generate unique node ID
-        current_counter = node_counter[0]
-        if prefix:
-            node_id = f"{prefix}_{current_counter}"
-        else:
-            node_id = f"node_{current_counter}"
-        node_counter[0] += 1
-
-        # Collect node properties
-        properties: dict[str, Any] = {}
-        child_fields: list[tuple[str, Any]] = []
-
-        for key, value in node_data.items():
-            if key == "attributes":
-                # Flatten attributes to node properties
-                if isinstance(value, dict):
-                    properties.update(value)
-            elif isinstance(value, dict):
-                # Nested object - will create child node
-                child_fields.append((key, value))
-            elif isinstance(value, list):
-                # Check if it's an array of objects or scalars
-                if value and isinstance(value[0], dict):
-                    # Array of objects - create child nodes
-                    child_fields.append((key, value))
-                else:
-                    # Array of scalars - save as property
-                    properties[key] = value
-            else:
-                # Scalar property
-                properties[key] = value
-
-        # Add node to storage
-        storage.add_node(node_id)
-        if properties:
-            storage.set_node_props(node_id, properties)
-
-        # Create edge from parent if applicable
-        if parent_id is not None and field_name is not None:
-            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")
-            storage.add_edge(edge_id)
-            if edge_props:
-                storage.set_edge_props(edge_id, edge_props)
-
-        # Process child fields recursively
-        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, child_key, idx, node_counter, prefix
-                    )
-            else:
-                self._process_node(
-                    storage,
-                    child_value,
-                    node_id,
-                    child_key,
-                    None,
-                    node_counter,
-                    prefix,
-                )
-
-        return node_id