cpg2py 1.0.5__py3-none-any.whl → 1.2.0__py3-none-any.whl

cpg2py/_abc/storage.py

@@ -0,0 +1,258 @@
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+
+from .._logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class Storage:
+    """A directed multi-graph implementation supporting multiple edges between nodes."""
+
+    __NodeID = str
+    __EdgeID = Tuple[str, str, str]
+    __Property = Dict[str, Any]
+
+    def __init__(self):
+        """Initializes an empty directed graph."""
+        self.__nodes: Dict[str, Dict[str, Any]] = {}
+        self.__edges: Dict[Tuple[str, str, str], Dict[str, Any]] = {}
+        self.__struct: Dict[str, List[Tuple[str, str, str]]] = {}
+
+    ################################ GRAPH STRUCTURE APIs ################################
+
+    def add_node(self, nid: __NodeID) -> bool:
+        """
+        Adds a node to the graph.
+
+        Args:
+            nid: Node ID to add
+
+        Returns:
+            True if node was added, False if it already exists
+        """
+        nid = str(nid)
+        if nid in self.__nodes:
+            return False
+        self.__nodes[nid] = {}
+        self.__struct[nid] = []
+        return True
+
+    def contains_node(self, nid: __NodeID) -> bool:
+        """
+        Checks if a node exists in the graph.
+
+        Args:
+            nid: Node ID to check
+
+        Returns:
+            True if node exists, False otherwise
+        """
+        nid = str(nid)
+        return nid in self.__nodes
+
+    def add_edge(self, eid: __EdgeID) -> bool:
+        """
+        Adds a directed edge to the graph.
+
+        Args:
+            eid: Edge ID tuple (from_node, to_node, edge_type)
+
+        Returns:
+            True if edge was added, False if it already exists or nodes are missing
+        """
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        if eid in self.__edges:
+            return False
+        if eid[0] not in self.__nodes:
+            return False
+        if eid[1] not in self.__nodes:
+            return False
+        self.__edges[eid] = {}
+        self.__struct[eid[0]].append(eid)
+        self.__struct[eid[1]].append(eid)
+        return True
+
+    def contains_edge(self, eid: __EdgeID) -> bool:
+        """Checks if an edge exists in the graph."""
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        return eid in self.__edges
+
+    def out_edges(self, nid: __NodeID) -> Iterable[__EdgeID]:
+        """Returns a list of outgoing edges from a given node."""
+        nid = str(nid)
+        return (eid for eid in self.__struct.get(nid, []) if eid[0] == nid)
+
+    def in_edges(self, nid: __NodeID) -> Iterable[__EdgeID]:
+        """Returns a list of incoming edges to a given node."""
+        nid = str(nid)
+        return (eid for eid in self.__struct.get(nid, []) if eid[1] == nid)
+
+    def successors(self, nid: __NodeID) -> Iterable[__NodeID]:
+        """Returns all successor nodes of a given node."""
+        nid = str(nid)
+        return (eid[1] for eid in self.__struct.get(nid, []) if eid[0] == nid)
+
+    def predecessors(self, nid: __NodeID) -> Iterable[__NodeID]:
+        """Returns all predecessor nodes of a given node."""
+        nid = str(nid)
+        return (eid[0] for eid in self.__struct.get(nid, []) if eid[1] == nid)
+
+    ################################ GRAPH PROPERTIES APIs ################################
+
+    def set_node_props(self, node: __NodeID, props: __Property) -> bool:
+        """Sets the properties of a node."""
+        node = str(node)
+        if node not in self.__nodes:
+            return False
+        prev_data: dict = self.__nodes[node]
+        prev_data.update({str(k): v for k, v in props.items()})
+        return True
+
+    def get_node_props(self, node: __NodeID) -> Optional[__Property]:
+        """Returns the properties of a node."""
+        node = str(node)
+        return self.__nodes.get(node, None)
+
+    def set_node_prop(self, node: __NodeID, key: str, value: Any) -> bool:
+        """Sets the properties of a node."""
+        node, key = str(node), str(key)
+        if node not in self.__nodes:
+            return False
+        self.__nodes[node][key] = value
+        return True
+
+    def get_node_prop(self, node: __NodeID, key: str) -> Optional[Any]:
+        """Returns the properties of a node."""
+        node, key = str(node), str(key)
+        return self.__nodes.get(node, {}).get(key, None)
+
+    def set_edge_props(self, eid: __EdgeID, props: __Property) -> bool:
+        """Sets the properties of an edge."""
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        if eid not in self.__edges:
+            return False
+        prev_data: dict = self.__edges[eid]
+        prev_data.update({str(k): v for k, v in props.items()})
+        return True
+
+    def get_edge_props(self, eid: __EdgeID) -> Optional[__Property]:
+        """Returns the properties of an edge."""
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        return self.__edges.get(eid)
+
+    def set_edge_prop(self, eid: __EdgeID, key: str, value: Any) -> bool:
+        """Sets the properties of an edge."""
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        key = str(key)
+        if eid not in self.__edges:
+            return False
+        self.__edges[eid][key] = value
+        return True
+
+    def get_edge_prop(self, eid: __EdgeID, key: str) -> Optional[__Property]:
+        """Returns the properties of an edge."""
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        key = str(key)
+        return self.__edges.get(eid, {}).get(key, None)
+
+    def __repr__(self):
+        """Returns a string representation of the graph."""
+        return f"MultiDiGraph(nodes={len(list(self.__nodes))}, edges={len(list(self.__edges))})"
+
+    ################################ GRAPH COMMON APIs ################################
+
+    def get_nodes(self) -> Iterable[__NodeID]:
+        """Returns a list of all nodes in the graph."""
+        return self.__nodes.keys()
+
+    def get_edges(self) -> Iterable[__EdgeID]:
+        """Returns a list of all edges in the graph."""
+        return self.__edges.keys()
+
+    def remove_node(self, nid: __NodeID) -> bool:
+        """Removes a node from the graph."""
+        nid = str(nid)
+        if nid not in self.__nodes:
+            return False
+        self.__nodes.pop(nid)
+        for eid in self.__struct.pop(nid, []):
+            self.__edges.pop(eid, None)
+        return True
+
+    def remove_edge(self, eid: __EdgeID) -> bool:
+        """Removes an edge from the graph."""
+        eid = (str(eid[0]), str(eid[1]), str(eid[2]))
+        if eid not in self.__edges:
+            return False
+        self.__struct[eid[0]].remove(eid)
+        self.__struct[eid[1]].remove(eid)
+        self.__edges.pop(eid)
+        return True
+
+    def save_json(self, path: Union[Path, str]) -> None:
+        """
+        Serializes the graph (nodes and edges with properties) to a UTF-8 JSON file.
+
+        Args:
+            path: File path (Path or str).
+
+        Raises:
+            OSError: If the file cannot be written.
+            TypeError: If a property value is not JSON-serializable.
+        """
+        payload: Dict[str, Any] = {
+            "nodes": dict(self.__nodes),
+            "edges": [
+                {"from": eid[0], "to": eid[1], "type": eid[2], "props": props}
+                for eid, props in self.__edges.items()
+            ],
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=2)
+
+    def load_json(self, path: Union[Path, str]) -> None:
+        """
+        Replaces the current graph with the contents of the JSON file.
+
+        Clears existing nodes and edges, then loads nodes, edges, and their
+        properties. Expects top-level keys "nodes" and "edges".
+
+        Args:
+            path: File path (Path or str).
+
+        Raises:
+            OSError: If the file cannot be read.
+            ValueError: If JSON structure is invalid (missing "nodes" or "edges").
+            KeyError: If an edge object is missing "from", "to", or "type".
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            data: Dict[str, Any] = json.load(f)
+        if "nodes" not in data or "edges" not in data:
+            raise ValueError("JSON must contain top-level 'nodes' and 'edges'")
+        self.__nodes = {}
+        self.__edges = {}
+        self.__struct = {}
+        nodes_data: Dict[str, Dict[str, Any]] = data["nodes"]
+        for nid, props in nodes_data.items():
+            nid_str = str(nid)
+            self.__nodes[nid_str] = dict(props) if props else {}
+            self.__struct[nid_str] = []
+        for edge_obj in data["edges"]:
+            from_nid = str(edge_obj["from"])
+            to_nid = str(edge_obj["to"])
+            etype = str(edge_obj["type"])
+            props = edge_obj.get("props")
+            if props is None:
+                props = {}
+            eid = (from_nid, to_nid, etype)
+            if from_nid not in self.__nodes:
+                self.__nodes[from_nid] = {}
+                self.__struct[from_nid] = []
+            if to_nid not in self.__nodes:
+                self.__nodes[to_nid] = {}
+                self.__struct[to_nid] = []
+            self.__edges[eid] = dict(props)
+            self.__struct[from_nid].append(eid)
+            self.__struct[to_nid].append(eid)

cpg2py/_cpg/__init__.py

@@ -0,0 +1,5 @@
+from .edge import CpgEdge
+from .graph import CpgGraph
+from .node import CpgNode
+
+__all__ = ["CpgGraph", "CpgNode", "CpgEdge"]

cpg2py/_cpg/edge.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from .._abc import AbcEdgeQuerier
+
+
+class CpgEdge(AbcEdgeQuerier):
+    """Concrete edge implementation with CPG-specific property accessors."""
+
+    @property
+    def id(self) -> Tuple[str, str, str]:
+        return self.edge_id
+
+    @property
+    def start(self) -> Optional[int]:
+        start_str = str(self.get_property("start", "start:START_ID"))
+        return int(start_str) if start_str.isnumeric() else int(self.from_nid)
+
+    @property
+    def end(self) -> Optional[int]:
+        end_str = str(self.get_property("end", "end:END_ID"))
+        return int(end_str) if end_str.isnumeric() else int(self.to_nid)
+
+    @property
+    def type(self) -> Optional[str]:
+        return self.get_property("type", "type:TYPE")
+
+    @property
+    def var(self) -> Optional[str]:
+        return self.get_property("var")

cpg2py/_cpg/graph.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import functools
+from typing import Callable, Iterable, Optional
+
+from .._abc import AbcGraphQuerier, Storage
+from .._exceptions import EdgeNotFoundError, NodeNotFoundError, TopFileNotFoundError
+from .._logger import get_logger
+from .edge import CpgEdge
+from .node import CpgNode
+
+logger = get_logger(__name__)
+
+
+class CpgGraph(AbcGraphQuerier[CpgNode, CpgEdge]):
+    """
+    Graph implementation for Object Property Diagram (OPG) used by ODgen and FAST.
+
+    Provides concrete implementation of graph query operations for CPG data.
+
+    This class is parameterized with CpgNode and CpgEdge types, ensuring type safety
+    throughout the graph operations.
+    """
+
+    __EdgeCondition = Callable[[CpgEdge], bool]
+    __always_true = lambda _: True
+
+    def __init__(self, target: Storage) -> None:
+        super().__init__(target)
+
+    def node(self, whose_id_is: str) -> Optional[CpgNode]:
+        """
+        Returns a node by its ID.
+
+        Args:
+            whose_id_is: Node ID to look up
+
+        Returns:
+            Node instance if found
+
+        Raises:
+            NodeNotFoundError: If node is not found in the graph
+        """
+        try:
+            return CpgNode(self.storage, whose_id_is)
+        except NodeNotFoundError:
+            raise
+        except Exception as e:
+            logger.exception("Unexpected error while finding node with id %s", whose_id_is)
+            raise NodeNotFoundError(whose_id_is) from e
+
+    def edge(self, fid: str, tid: str, eid: str) -> Optional[CpgEdge]:
+        """
+        Returns an edge by its source, target, and edge type.
+
+        Args:
+            fid: Source node ID
+            tid: Target node ID
+            eid: Edge type/ID
+
+        Returns:
+            Edge instance if found
+
+        Raises:
+            EdgeNotFoundError: If edge is not found in the graph
+        """
+        try:
+            return CpgEdge(self.storage, fid, tid, eid)
+        except EdgeNotFoundError:
+            raise
+        except Exception as e:
+            logger.exception(
+                "Unexpected error while finding edge from %s to %s, eid is %s", fid, tid, eid
+            )
+            raise EdgeNotFoundError(fid, tid, str(eid)) from e
+
+    @functools.lru_cache()
+    def topfile_node(self, of_nid: str) -> CpgNode:
+        """
+        Finds the top file node from the input node.
+
+        Args:
+            of_nid: Starting node ID
+
+        Returns:
+            Top file node
+
+        Raises:
+            TopFileNotFoundError: If top file node cannot be found
+            NodeNotFoundError: If starting node is not found
+        """
+        of_node = self.node(of_nid)
+        if of_node.type == "File":
+            return of_node
+        if "TOPLEVEL_FILE" in of_node.flags:
+            return of_node
+        parents = self.prev(of_node, lambda e: e.type in ["PARENT_OF", "ENTRY", "EXIT"])
+        for pre in parents:
+            try:
+                top_file = self.topfile_node(pre.id)
+                return top_file
+            except TopFileNotFoundError:
+                continue
+        logger.error("Cannot find top file node from node %s", of_nid)
+        raise TopFileNotFoundError(of_nid)
+
+    def succ(self, of: CpgNode, who_satisifies: __EdgeCondition = __always_true) -> Iterable[CpgNode]:
+        """
+        Returns successor nodes connected to the input node.
+
+        Args:
+            of: Source node
+            who_satisifies: Optional edge condition filter
+
+        Yields:
+            Successor nodes matching the condition
+        """
+        return super().succ(of, who_satisifies)
+
+    def prev(self, of: CpgNode, who_satisifies: __EdgeCondition = __always_true) -> Iterable[CpgNode]:
+        """
+        Returns predecessor nodes connected to the input node.
+
+        Args:
+            of: Target node
+            who_satisifies: Optional edge condition filter
+
+        Yields:
+            Predecessor nodes matching the condition
+        """
+        return super().prev(of, who_satisifies)
+
+    def children(self, of: CpgNode, extra: __EdgeCondition = __always_true) -> Iterable[CpgNode]:
+        """
+        Returns child nodes connected via PARENT_OF edges.
+
+        Args:
+            of: Parent node
+            extra: Additional edge condition filter
+
+        Returns:
+            Iterable of child nodes
+        """
+        return self.succ(of, lambda e: extra(e) and (e.type == "PARENT_OF"))
+
+    def parent(self, of: CpgNode, extra: __EdgeCondition = __always_true) -> Iterable[CpgNode]:
+        """
+        Returns parent nodes connected via PARENT_OF edges.
+
+        Args:
+            of: Child node
+            extra: Additional edge condition filter
+
+        Returns:
+            Iterable of parent nodes
+        """
+        return self.prev(of, lambda e: extra(e) and (e.type == "PARENT_OF"))
+
+    def flow_to(self, of: CpgNode, extra: __EdgeCondition = __always_true) -> Iterable[CpgNode]:
+        """
+        Returns successor nodes connected via FLOWS_TO edges.
+
+        Args:
+            of: Source node
+            extra: Additional edge condition filter
+
+        Returns:
+            Iterable of flow successor nodes
+        """
+        return self.succ(of, lambda e: extra(e) and (e.type == "FLOWS_TO"))
+
+    def flow_from(self, of: CpgNode, extra: __EdgeCondition = __always_true) -> Iterable[CpgNode]:
+        """
+        Returns predecessor nodes connected via FLOWS_TO edges.
+
+        Args:
+            of: Target node
+            extra: Additional edge condition filter
+
+        Returns:
+            Iterable of flow predecessor nodes
+        """
+        return self.prev(of, lambda e: extra(e) and (e.type == "FLOWS_TO"))

cpg2py/_cpg/node.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .._abc import AbcNodeQuerier
+
+
+class CpgNode(AbcNodeQuerier):
+    """Concrete node implementation with CPG-specific property accessors."""
+
+    @property
+    def id(self) -> str:
+        return self.node_id
+
+    @property
+    def code(self) -> Optional[str]:
+        return self.get_property("code")
+
+    @property
+    def label(self) -> Optional[str]:
+        return self.get_property("labels:label", "labels")
+
+    @property
+    def flags(self) -> List[str]:
+        flags_str = self.get_property("flags:string_array", "flags:string[]", "flags")
+        return str(flags_str).split(" ") if flags_str is not None else []
+
+    @property
+    def line_num(self) -> Optional[int]:
+        linenum_str = str(self.get_property("lineno:int", "lineno"))
+        return int(linenum_str) if linenum_str.isnumeric() else None
+
+    @property
+    def children_num(self) -> Optional[int]:
+        num_str = str(self.get_property("childnum:int", "childnum"))
+        return int(num_str) if num_str.isnumeric() else None
+
+    @property
+    def func_id(self) -> Optional[int]:
+        fid_str = str(self.get_property("funcid:int", "funcid"))
+        return int(fid_str) if fid_str.isnumeric() else None
+
+    @property
+    def class_name(self) -> Optional[str]:
+        return self.get_property("classname")
+
+    @property
+    def namespace(self) -> Optional[str]:
+        return self.get_property("namespace")
+
+    @property
+    def name(self) -> Optional[str]:
+        return self.get_property("name")
+
+    @property
+    def end_num(self) -> Optional[int]:
+        end_str = str(self.get_property("endlineno:int", "endlineno"))
+        return int(end_str) if end_str.isnumeric() else None
+
+    @property
+    def comment(self) -> Optional[str]:
+        return self.get_property("doccomment")
+
+    @property
+    def type(self) -> Optional[str]:
+        return self.get_property("type")

cpg2py/_exceptions.py

@@ -0,0 +1,43 @@
+"""Custom exceptions for cpg2py package."""
+
+from typing import Optional
+
+
+class CPGError(Exception):
+    """Base exception for all CPG-related errors."""
+
+
+class NodeNotFoundError(CPGError):
+    """Raised when node identifier does not exist in storage."""
+
+    def __init__(self, node_id: str, message: Optional[str] = None) -> None:
+        self.node_id = node_id
+        if message is None:
+            message = f"Node with id '{node_id}' not found in graph"
+        super().__init__(message)
+
+
+class EdgeNotFoundError(CPGError):
+    """Raised when edge identifier tuple does not exist in storage."""
+
+    def __init__(
+        self, from_id: str, to_id: str, edge_type: str, message: Optional[str] = None
+    ) -> None:
+        self.from_id = from_id
+        self.to_id = to_id
+        self.edge_type = edge_type
+        if message is None:
+            message = (
+                f"Edge from '{from_id}' to '{to_id}' with type '{edge_type}' not found in graph"
+            )
+        super().__init__(message)
+
+
+class TopFileNotFoundError(CPGError):
+    """Raised when top file node cannot be found during upward traversal."""
+
+    def __init__(self, node_id: str, message: Optional[str] = None) -> None:
+        self.node_id = node_id
+        if message is None:
+            message = f"Cannot find top file node from node '{node_id}'"
+        super().__init__(message)

cpg2py/_logger.py

@@ -0,0 +1,53 @@
+"""
+Logging configuration for cpg2py package.
+"""
+
+import logging
+import sys
+from typing import Optional
+
+_logger: Optional[logging.Logger] = None
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    Returns a logger instance for the specified module.
+
+    Args:
+        name: Module name (defaults to 'cpg2py')
+
+    Returns:
+        Configured logger instance
+    """
+    global _logger
+
+    if _logger is None:
+        _logger = logging.getLogger("cpg2py")
+        _logger.setLevel(logging.WARNING)
+
+        if not _logger.handlers:
+            handler = logging.StreamHandler(sys.stderr)
+            handler.setLevel(logging.WARNING)
+
+            formatter = logging.Formatter(
+                "%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+            )
+            handler.setFormatter(formatter)
+            _logger.addHandler(handler)
+
+    if name:
+        return _logger.getChild(name)
+    return _logger
+
+
+def set_log_level(level: int) -> None:
+    """
+    Sets the logging level for the cpg2py logger.
+
+    Args:
+        level: Logging level (e.g., logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR)
+    """
+    logger = get_logger()
+    logger.setLevel(level)
+    for handler in logger.handlers:
+        handler.setLevel(level)