php-parser-py 1.2.4__py3-none-win_amd64.whl

php_parser_py/_graph/_node.py

@@ -0,0 +1,256 @@
+"""Node class for PHP AST nodes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cpg2py import AbcNodeQuerier, Storage
+
+from ._node_id import NodeId
+
+
+class Node(AbcNodeQuerier):
+    """Wraps a single AST node with dynamic property access to PHP-Parser JSON fields.
+
+    Extends cpg2py's AbcNodeQuerier to provide access to PHP-Parser node data
+    stored in cpg2py Storage. All node properties come from PHP-Parser's JSON
+    output and are accessed dynamically without hardcoded field definitions.
+
+    PHP-Parser nodes have two types of data:
+    - **Subnodes**: Structural properties like name, params, stmts, byRef, etc.
+    - **Attributes**: Metadata like startLine, endLine, comments, etc.
+
+    Both are accessible through this class using dict-like syntax or properties.
+
+    Attributes:
+        _storage: cpg2py Storage instance containing node data.
+        _nid: Unique identifier for this node.
+    """
+
+    def __init__(self, storage: Storage, nid: str) -> None:
+        """Initialize Node with storage reference and node ID.
+
+        Args:
+            storage: cpg2py Storage instance containing node data.
+            nid: Unique identifier for this node.
+
+        Raises:
+            Exception: If node ID is not found in storage.
+        """
+        super().__init__(storage, nid)
+        self._storage = storage
+        self._nid = nid
+
+    # Core properties
+
+    @property
+    def id(self) -> str:
+        """Return the node identifier.
+
+        Returns:
+            Node ID string.
+        """
+        return self._nid
+
+    @property
+    def node_type(self) -> str:
+        """Return the node type from PHP-Parser.
+
+        Returns the `nodeType` field from the stored JSON (e.g. "Stmt_Function").
+
+        Returns:
+            Node type string.
+        """
+        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[str, Any]:
+        """Return all stored properties for this node.
+
+        Includes both subnodes (structural properties) and attributes (metadata).
+
+        Returns:
+            Dictionary containing all properties from PHP-Parser JSON.
+        """
+        return self.properties or {}
+
+    # Dict-like access methods
+
+    def __getitem__(self, key: str) -> Any:
+        """Access node properties using dict-like syntax.
+
+        Enables node["nodeType"], node["name"], node["startLine"], etc.
+
+        Args:
+            key: Property name to access.
+
+        Returns:
+            Property value.
+
+        Raises:
+            KeyError: If property doesn't exist.
+        """
+        props = self.all_properties
+        if key not in props:
+            raise KeyError(f"Property '{key}' not found in node {self._nid}")
+        return props[key]
+
+    def __contains__(self, key: str) -> bool:
+        """Check if property exists using 'in' operator.
+
+        Enables: if "name" in node: ...
+
+        Args:
+            key: Property name to check.
+
+        Returns:
+            True if property exists, False otherwise.
+        """
+        return key in self.all_properties
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get property value with default fallback.
+
+        Args:
+            key: Property name to access.
+            default: Default value if property doesn't exist.
+
+        Returns:
+            Property value or default.
+        """
+        return self.all_properties.get(key, default)
+
+    # PHP-Parser standard attributes (metadata properties)
+
+    def _int_property(self, name: str) -> int:
+        """Get an integer property, coercing ASCII integer strings.
+
+        Args:
+            name: Property name to retrieve.
+
+        Returns:
+            Integer value.
+
+        Raises:
+            TypeError: If property is not an int or an ASCII integer
+                string (optional leading ``-``).
+        """
+        value = self.get_property(name)
+        # bool is an int subtype but never a valid position value.
+        if isinstance(value, int) and not isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            digits = value.removeprefix("-")
+            # int() alone also accepts non-ASCII digits, whitespace,
+            # "+", and "_" separators — none are position values.
+            if digits.isascii() and digits.isdigit():
+                return int(value)
+        raise TypeError(f"Invalid {name} for node {self._nid}: {value!r}")
+
+    @property
+    def start_line(self) -> int:
+        """Get starting line number."""
+        return self._int_property("startLine")
+
+    @property
+    def end_line(self) -> int:
+        """Get ending line number."""
+        return self._int_property("endLine")
+
+    @property
+    def start_file_pos(self) -> int:
+        """Get starting file position (byte offset)."""
+        return self._int_property("startFilePos")
+
+    @property
+    def end_file_pos(self) -> int:
+        """Get ending file position (byte offset)."""
+        return self._int_property("endFilePos")
+
+    @property
+    def start_token_pos(self) -> int:
+        """Get starting token position."""
+        return self._int_property("startTokenPos")
+
+    @property
+    def end_token_pos(self) -> int:
+        """Get ending token position."""
+        return self._int_property("endTokenPos")
+
+    @property
+    def comments(self) -> list[dict[str, Any]]:
+        """Get comments associated with this node.
+
+        Returns:
+            List of PHP-Parser Comment JSON objects (may be empty).
+        """
+        props = self.all_properties
+        if "comments" not in props:
+            # PHP-Parser omits the attribute when a node has no comments.
+            return []
+        value = props["comments"]
+        if isinstance(value, list):
+            return value
+        raise TypeError(f"Invalid comments for node {self._nid}: {value!r}")
+
+    @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.
+        """
+        return self._path_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.
+        """
+        return self._path_property("absolutePath")
+
+    def _path_property(self, prop_name: str) -> str | None:
+        # File and Project nodes carry the path themselves; every other
+        # node resolves it from its containing file via ID prefix convention.
+        if self.node_type in ("File", "Project"):
+            value = self.get_property(prop_name)
+            return value if isinstance(value, str) else None
+        return self._get_file_property(prop_name)
+
+    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.
+        """
+        parsed = NodeId.parse(self._nid)
+        if parsed is None or not parsed.file_hash:
+            return None
+
+        file_id = parsed.file_hash
+        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

php_parser_py/_graph/_node_id.py

@@ -0,0 +1,56 @@
+"""NodeId value object for the PHP AST node-ID scheme."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NodeId:
+    """Encapsulates the ``{file_hash}_{counter}`` node-ID scheme.
+
+    Single home for the ID convention used both when allocating IDs during
+    mapping and when parsing IDs back into file scope.
+
+    Attributes:
+        file_hash: File-scope prefix; empty string for code-only parsing.
+        counter: Per-file increment.
+    """
+
+    file_hash: str
+    counter: int
+
+    @property
+    def value(self) -> str:
+        """Render the ID string for this node.
+
+        Returns:
+            ``{file_hash}_{counter}`` when a file hash is set, else
+            ``node_{counter}``.
+        """
+        if self.file_hash:
+            return f"{self.file_hash}_{self.counter}"
+        return f"node_{self.counter}"
+
+    @classmethod
+    def parse(cls, node_id: str) -> NodeId | None:
+        """Split a stored ID into its prefix and counter.
+
+        Inverse of :pyattr:`value`. Splits at the last underscore.
+
+        Args:
+            node_id: Node ID string.
+
+        Returns:
+            NodeId when the ID matches ``{prefix}_{digits}``; None otherwise.
+        """
+        last_underscore = node_id.rfind("_")
+        if last_underscore == -1:
+            return None
+        counter = node_id[last_underscore + 1 :]
+        if not counter.isdigit():
+            return None
+        prefix = node_id[:last_underscore]
+        if prefix == "node":
+            return cls("", int(counter))
+        return cls(prefix, int(counter))

php_parser_py/_mapping/__init__.py

@@ -0,0 +1,14 @@
+"""Mapping package: the single owner of the JSON<->graph contract.
+
+Exposes the inverse pair ``build`` (forward: JSON->graph) and ``serialize``
+(backward: graph->JSON) as module-level entry points, sharing one
+field-classification rule so they stay inverse.
+"""
+
+from __future__ import annotations
+
+from ._build import build
+from ._contract import EdgeSlot
+from ._serialize import serialize, statement_ids
+
+__all__ = ["build", "serialize", "statement_ids", "EdgeSlot"]

php_parser_py/_mapping/_build.py

@@ -0,0 +1,227 @@
+"""Forward direction: PHP-Parser JSON -> populated AST graph.
+
+Holds the stateful ``_Builder`` allocator behind the module-level ``build``
+entry point, the forward public surface of the mapping package.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cpg2py import Storage
+
+from .._graph import AST, Modifier, NodeId
+from .._types import PROJECT_ROOT_ID, FileRecord, ProjectLayout
+from ._contract import (
+    ATTRIBUTE_KEYS_PROPERTY,
+    LIST_LENGTHS_PROPERTY,
+    PROJECT_SENTINEL_POSITIONS,
+    EdgeSlot,
+    _classify_field,
+)
+
+_FILE_END_DEFAULTS: dict[str, int] = {"endLine": 1, "endFilePos": 0, "endTokenPos": 0}
+
+# Anchor node ID for code-only ASTs; the AST root default stays "project".
+_CODE_ROOT_ID = "__code_root__"
+
+
+def build(json_trees: list[dict[str, object]], layout: ProjectLayout) -> AST:
+    """Populate a fresh ``AST`` from PHP-Parser JSON trees.
+
+    Forward entry of the mapping package; inverse of ``serialize``.
+
+    Args:
+        json_trees: Normalized list of root node dicts (code-only mode).
+        layout: Project/file structure and per-file hashes.
+
+    Returns:
+        AST with project -> file -> statement hierarchy, or a flat statement
+        list when ``layout`` carries no files.
+
+    Raises:
+        ValueError: From ``Modifier.add_node`` on a duplicate ID.
+    """
+    builder = _Builder()
+    if layout.project_path is None:
+        return builder.build_code(json_trees)
+    return builder.build_project(layout)
+
+
+class _Builder:
+    """Stateful JSON->graph builder with a per-file ID allocator.
+
+    Attributes:
+        _next_index: Stateful per-file ID allocator counter.
+        _prefix: Current file-hash prefix; empty string for code-only parsing.
+    """
+
+    def __init__(self) -> None:
+        """Initialize a builder with a fresh allocator state."""
+        self._next_index = 1
+        self._prefix = ""
+
+    def build_code(self, json_trees: list[dict[str, object]]) -> AST:
+        """Build statements anchored under a synthetic code-root node."""
+        modifier = Modifier(AST(Storage(), root_node_id=_CODE_ROOT_ID))
+        # A real anchor node makes top-level membership explicit: serialize
+        # exports the anchor's stmts edges. Inferring roots from missing
+        # parent edges would promote subtrees orphaned by remove_node.
+        modifier.add_node(_CODE_ROOT_ID, "Project", **PROJECT_SENTINEL_POSITIONS)
+        self._reset_scope("")
+        for idx, item in enumerate(json_trees):
+            self._process_node(modifier, item, EdgeSlot("stmts", idx), _CODE_ROOT_ID)
+        return modifier.ast
+
+    def build_project(self, layout: ProjectLayout) -> AST:
+        """Build the project -> files -> statements hierarchy."""
+        project_path = layout.project_path
+        if project_path is None:
+            raise ValueError("ProjectLayout.project_path is required for build")
+        modifier = Modifier(AST(Storage()))
+        modifier.add_node(
+            PROJECT_ROOT_ID,
+            "Project",
+            absolutePath=str(project_path),
+            **PROJECT_SENTINEL_POSITIONS,
+        )
+        for record in layout.files:
+            self._add_file_node(modifier, record, project_path)
+        return modifier.ast
+
+    def _add_file_node(
+        self, modifier: Modifier, record: FileRecord, project_path: Path
+    ) -> None:
+        # Create the file node, link it to project, process its statements.
+        end_pos = self._file_end_positions(record.statements)
+        modifier.add_node(
+            record.file_hash,
+            "File",
+            absolutePath=str(record.path),
+            relativePath=_relative_path(record.path, project_path),
+            startLine=1,
+            startFilePos=0,
+            startTokenPos=0,
+            **end_pos,
+        )
+        modifier.add_edge(PROJECT_ROOT_ID, record.file_hash, field="files")
+        self._reset_scope(record.file_hash)
+        for idx, item in enumerate(record.statements):
+            self._process_node(modifier, item, EdgeSlot("stmts", idx), record.file_hash)
+
+    def _process_node(
+        self,
+        modifier: Modifier,
+        node_data: object,
+        slot: EdgeSlot | None,
+        parent_id: str | None = None,
+    ) -> None:
+        # Convert one JSON node and its subtree into graph nodes and edges.
+        # Explicit-stack DFS: recursion would cap the AST depth at a
+        # fraction of the interpreter stack, failing trees json.loads
+        # itself delivered. Children are pushed reversed so IDs are
+        # allocated in the same pre-order as the recursive walk.
+        stack: list[tuple[object, EdgeSlot | None, str | None]] = [
+            (node_data, slot, parent_id)
+        ]
+        while stack:
+            data, current_slot, parent = stack.pop()
+            if not isinstance(data, dict) or "nodeType" not in data:
+                continue
+            node_id = self._allocate_id()
+            properties, child_fields = self._split_fields(data)
+            node_type = properties.pop("nodeType")
+            if not isinstance(node_type, str):
+                continue
+            modifier.add_node(node_id, node_type, **properties)
+            if parent is not None and current_slot is not None:
+                self._link_child(modifier, parent, node_id, current_slot)
+            stack.extend(reversed(_child_work(child_fields, node_id)))
+
+    @staticmethod
+    def _link_child(
+        modifier: Modifier, parent_id: str, node_id: str, slot: EdgeSlot
+    ) -> None:
+        # Add the PARENT_OF edge carrying the slot metadata.
+        if slot.index is not None:
+            modifier.add_edge(parent_id, node_id, field=slot.field, index=slot.index)
+        else:
+            modifier.add_edge(parent_id, node_id, field=slot.field)
+
+    @staticmethod
+    def _split_fields(
+        node_data: dict[str, object],
+    ) -> tuple[dict[str, object], list[tuple[str, object]]]:
+        # Partition fields into scalar properties and child-edge subnodes.
+        properties: dict[str, object] = {}
+        child_fields: list[tuple[str, object]] = []
+        trailing_lengths: dict[str, int] = {}
+        for key, value in node_data.items():
+            if not _classify_field(key, value):
+                _absorb_scalar(properties, key, value)
+                continue
+            child_fields.append((key, value))
+            # Trailing nulls carry no child edge; record the full length
+            # so serialize can rebuild them.
+            if isinstance(value, list) and value[-1] is None:
+                trailing_lengths[key] = len(value)
+        if trailing_lengths:
+            properties[LIST_LENGTHS_PROPERTY] = trailing_lengths
+        return properties, child_fields
+
+    @staticmethod
+    def _file_end_positions(stmts: list[dict[str, object]]) -> dict[str, int]:
+        # Compute the file node's end positions from statement attributes.
+        ends = dict(_FILE_END_DEFAULTS)
+        for stmt in stmts:
+            attrs = stmt.get("attributes", {})
+            if not isinstance(attrs, dict):
+                continue
+            for key, current in list(ends.items()):
+                val = attrs.get(key)
+                if isinstance(val, int) and val > current:
+                    ends[key] = val
+        return ends
+
+    def _reset_scope(self, prefix: str) -> None:
+        # Begin allocating IDs for a new file scope.
+        self._prefix = prefix
+        self._next_index = 1
+
+    def _allocate_id(self) -> str:
+        # Allocate the next unique node ID for the current scope.
+        node_id = NodeId(self._prefix, self._next_index)
+        self._next_index += 1
+        return node_id.value
+
+
+def _child_work(
+    child_fields: list[tuple[str, object]], parent_id: str
+) -> list[tuple[object, EdgeSlot, str]]:
+    # Expand classified child fields into (data, slot, parent) work items.
+    items: list[tuple[object, EdgeSlot, str]] = []
+    for field_name, value in child_fields:
+        if isinstance(value, list):
+            for idx, item in enumerate(value):
+                items.append((item, EdgeSlot(field_name, idx), parent_id))
+        else:
+            items.append((value, EdgeSlot(field_name), parent_id))
+    return items
+
+
+def _relative_path(file_path: Path, project_path: Path) -> str:
+    # Path of file relative to project, falling back to the file name.
+    try:
+        return str(file_path.relative_to(project_path))
+    except ValueError:
+        return file_path.name
+
+
+def _absorb_scalar(properties: dict[str, object], key: str, value: object) -> None:
+    # Flatten an attributes bundle, recording its keys so serialize can
+    # re-file exactly these properties; else store the scalar directly.
+    if key == "attributes" and isinstance(value, dict):
+        properties[ATTRIBUTE_KEYS_PROPERTY] = list(value)
+        properties.update(value)
+    else:
+        properties[key] = value

php_parser_py/_mapping/_contract.py

@@ -0,0 +1,71 @@
+"""JSON<->graph mapping contract used by both directions.
+
+Holds the single field-classification rule and the edge-slot data holder so
+``build`` and ``serialize`` stay inverse.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Graph property recording {field name: full list length} for child list
+# fields ending in null (e.g. list($a, ,) destructuring skips). Trailing
+# nulls carry no child edge, so serialize needs the recorded length to
+# rebuild them. Written by build, consumed and omitted by serialize.
+LIST_LENGTHS_PROPERTY = "pppyListLengths"
+
+# Graph property recording the key list of a node's flattened attributes
+# bundle. build absorbs attributes into plain properties; serialize needs
+# the recorded keys to re-file exactly those properties back into the
+# attributes dict — a fixed whitelist would misfile any attribute
+# PHP-Parser adds (docLabel, rawValue, ...) as a top-level node field.
+# Written by build, consumed and omitted by serialize.
+ATTRIBUTE_KEYS_PROPERTY = "pppyAttributeKeys"
+
+PROJECT_SENTINEL_POSITIONS: dict[str, int] = {
+    "startLine": -1,
+    "endLine": -1,
+    "startFilePos": -1,
+    "endFilePos": -1,
+    "startTokenPos": -1,
+    "endTokenPos": -1,
+}
+
+
+@dataclass(frozen=True)
+class EdgeSlot:
+    """Structural metadata for one PARENT_OF edge.
+
+    Attributes:
+        field: Subnode key on the parent (e.g. "stmts", "name").
+        index: Array position for ordered list fields; None for single-object
+            fields.
+    """
+
+    field: str
+    index: int | None = None
+
+
+def _classify_field(key: str, value: object) -> bool:
+    """Decide whether a JSON field is a child-edge subnode.
+
+    The one authoritative rule used by both ``build`` and ``serialize``: a
+    value is a child-edge subnode when it is a node dict (has ``nodeType``)
+    or a list containing at least one node dict. List items may be null
+    (array destructuring skips), so every element is examined, not just the
+    first. The ``attributes`` key is always a scalar property bundle.
+
+    Args:
+        key: JSON field key.
+        value: JSON field value.
+
+    Returns:
+        True when the value is a child-edge subnode; False when scalar.
+    """
+    if key == "attributes":
+        return False
+    if isinstance(value, dict):
+        return "nodeType" in value
+    if isinstance(value, list):
+        return any(isinstance(item, dict) and "nodeType" in item for item in value)
+    return False