codeanalyzer-python 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

codeanalyzer/dataflow/defuse.py

@@ -0,0 +1,113 @@
+################################################################################
+# Copyright IBM Corporation 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Stage 3b of the level-3 dataflow ladder: reaching definitions → DDG edges.
+
+Classic forward may-analysis with a worklist over the statement-level CFG.
+SSA is an implementation shortcut some ecosystems get for free; the contract
+is the def-use edges, and Python hand-builds them.
+
+Kill discipline (sound-leaning):
+
+- A def of a bare local/param path strong-kills earlier defs of the exact
+  same path.
+- Defs of attribute paths strong-kill only the identical path string (a write
+  through one name never kills a potentially-aliased other name).
+- Subscript (``[*]``) and k-truncated (``.*``) paths are weak updates — they
+  kill nothing.
+
+A use matches a reaching def when the paths interfere textually (exact /
+prefix / wildcard — :func:`access_paths.interferes`) or when the may-alias
+oracle says two suffixed paths can denote one location.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Set, Tuple
+
+from codeanalyzer.dataflow.access_paths import StatementFacts, interferes, suffix_of
+from codeanalyzer.dataflow.alias import TypeBasedAliasOracle
+from codeanalyzer.dataflow.cfg import ControlFlowGraph
+
+
+@dataclass(frozen=True)
+class DDGEdge:
+    source: int  # the def node
+    target: int  # the use node
+    var: str  # the access path being read
+
+
+def _strong_kill(path: str) -> bool:
+    return not path.endswith("*")
+
+
+def reaching_definitions(
+    cfg: ControlFlowGraph, facts: Dict[int, StatementFacts]
+) -> Dict[int, Set[Tuple[str, int]]]:
+    """IN sets: ``{node: {(path, def_node), ...}}`` via worklist iteration."""
+    preds = cfg.predecessors()
+    succs = cfg.successors()
+    node_ids = [n.id for n in cfg.nodes]
+
+    gen: Dict[int, Set[Tuple[str, int]]] = {}
+    for nid in node_ids:
+        gen[nid] = {(d, nid) for d in facts[nid].defs}
+
+    in_sets: Dict[int, Set[Tuple[str, int]]] = {nid: set() for nid in node_ids}
+    out_sets: Dict[int, Set[Tuple[str, int]]] = {nid: set() for nid in node_ids}
+
+    worklist = list(node_ids)
+    while worklist:
+        nid = worklist.pop(0)
+        new_in: Set[Tuple[str, int]] = set()
+        for p, _ in preds[nid]:
+            new_in |= out_sets[p]
+        strong = {d for d in facts[nid].defs if _strong_kill(d)}
+        new_out = {(p, m) for (p, m) in new_in if p not in strong} | gen[nid]
+        if new_in != in_sets[nid] or new_out != out_sets[nid]:
+            in_sets[nid] = new_in
+            out_sets[nid] = new_out
+            for s, _ in succs[nid]:
+                if s not in worklist:
+                    worklist.append(s)
+    return in_sets
+
+
+def ddg_edges(
+    cfg: ControlFlowGraph,
+    facts: Dict[int, StatementFacts],
+    oracle: TypeBasedAliasOracle,
+) -> List[DDGEdge]:
+    """Def-use edges: for every use at node n, an edge from each reaching def
+    whose path interferes (textually or through may-alias)."""
+    in_sets = reaching_definitions(cfg, facts)
+    edges: Set[DDGEdge] = set()
+    for node in cfg.nodes:
+        uses = facts[node.id].uses
+        if not uses:
+            continue
+        reaching = in_sets[node.id]
+        # A (path, n) pair reaches n itself only through a real cycle, so a
+        # self-edge here is precisely the loop-carried dependency.
+        for use in uses:
+            for def_path, def_node in reaching:
+                if interferes(use, def_path) or (
+                    (suffix_of(use) or suffix_of(def_path))
+                    and oracle.may_alias(use, def_path)
+                ):
+                    edges.add(DDGEdge(source=def_node, target=node.id, var=use))
+    return sorted(edges, key=lambda e: (e.source, e.target, e.var))

codeanalyzer/dataflow/dominance.py

@@ -0,0 +1,140 @@
+################################################################################
+# Copyright IBM Corporation 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Stage 2 of the level-3 dataflow ladder: dominance and control dependence.
+
+Post-dominators are computed with the Cooper–Harper–Kennedy iterative
+algorithm over the reverse CFG. Infinite loops are already normalized by the
+CFG builder (synthetic escape edge to EXIT), so the post-dominator tree always
+has the unique root EXIT.
+
+Control dependence follows Ferrante–Ottenstein–Warren: for each CFG edge
+``(a, b)`` where ``b`` does not post-dominate ``a``, every node on the
+post-dominator-tree path from ``b`` up to (but not including) ``a``'s
+immediate post-dominator is control-dependent on ``a``.
+
+Nodes with no branch-node control dependence are control-dependent on ENTRY —
+the conventional region root, which keeps every statement anchored in the PDG
+and gives interprocedural traversals a path from a callee's ENTRY to its
+unconditional statements.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Set, Tuple
+
+from codeanalyzer.dataflow.cfg import ControlFlowGraph
+
+
+def _postorder(adj: Dict[int, List[int]], root: int) -> List[int]:
+    """Iterative DFS postorder over ``adj`` from ``root``."""
+    order: List[int] = []
+    visited: Set[int] = set()
+    stack: List[Tuple[int, int]] = [(root, 0)]
+    visited.add(root)
+    while stack:
+        node, i = stack.pop()
+        children = adj.get(node, [])
+        if i < len(children):
+            stack.append((node, i + 1))
+            child = children[i]
+            if child not in visited:
+                visited.add(child)
+                stack.append((child, 0))
+        else:
+            order.append(node)
+    return order
+
+
+def post_dominators(cfg: ControlFlowGraph) -> Dict[int, int]:
+    """Immediate post-dominator of every node, as ``{node: ipdom}``.
+
+    EXIT is its own post-dominator (the tree root). Cooper–Harper–Kennedy
+    ("A Simple, Fast Dominance Algorithm") run on the reverse CFG.
+    """
+    # Reverse CFG: successors of n are the CFG predecessors of n.
+    radj: Dict[int, List[int]] = {n.id: [] for n in cfg.nodes}
+    rpred: Dict[int, List[int]] = {n.id: [] for n in cfg.nodes}
+    for e in cfg.edges:
+        if e.source == e.target:
+            continue  # self-loops carry no dominance information
+        radj[e.target].append(e.source)
+        rpred[e.source].append(e.target)
+
+    root = cfg.exit_id
+    post = _postorder(radj, root)
+    number = {n: i for i, n in enumerate(post)}  # postorder number
+    rpo = list(reversed(post))  # reverse postorder: root first
+
+    ipdom: Dict[int, int] = {root: root}
+
+    def intersect(a: int, b: int) -> int:
+        while a != b:
+            while number[a] < number[b]:
+                a = ipdom[a]
+            while number[b] < number[a]:
+                b = ipdom[b]
+        return a
+
+    changed = True
+    while changed:
+        changed = False
+        for node in rpo:
+            if node == root:
+                continue
+            preds = [p for p in rpred[node] if p in ipdom]
+            if not preds:
+                continue
+            new = preds[0]
+            for p in preds[1:]:
+                new = intersect(new, p)
+            if ipdom.get(node) != new:
+                ipdom[node] = new
+                changed = True
+
+    return ipdom
+
+
+def control_dependence(cfg: ControlFlowGraph) -> List[Tuple[int, int]]:
+    """CDG edges ``(branch_node, dependent_node)`` per Ferrante–Ottenstein–
+    Warren, plus ENTRY-region edges for nodes with no other controller."""
+    ipdom = post_dominators(cfg)
+
+    deps: Set[Tuple[int, int]] = set()
+    for e in cfg.edges:
+        a, b = e.source, e.target
+        if a == b:
+            continue
+        # b post-dominates a iff b is an ancestor of a in the pdom tree.
+        runner = b
+        stop = ipdom.get(a)
+        # Walk from b up the post-dominator tree to (not including) ipdom(a).
+        while runner != stop and runner != a:
+            deps.add((a, runner))
+            nxt = ipdom.get(runner)
+            if nxt is None or nxt == runner:
+                break
+            runner = nxt
+
+    # ENTRY as the region root for otherwise-uncontrolled nodes.
+    controlled = {t for (_, t) in deps}
+    for n in cfg.nodes:
+        if n.id in (cfg.entry_id, cfg.exit_id):
+            continue
+        if n.id not in controlled:
+            deps.add((cfg.entry_id, n.id))
+
+    return sorted(deps)

codeanalyzer/dataflow/identity.py

@@ -0,0 +1,91 @@
+"""Bijection between internal IR node ids (ints, per function) and their
+canonical ids.
+
+Two forms per node:
+
+* **local** — the intra-callable id used as the ``body`` map key and as every
+  ``cfg``/``cdg``/``ddg`` edge endpoint: ``"@entry"``/``"@exit"`` for the
+  synthetic CFG bookends, ``"line:col"`` for real statements. This matches the
+  key format L1 already uses for ``call`` nodes (see ``schema/l1_body.py``), so
+  an L1 body node and its coinciding CFG node land on the same key and L1 ⊆ L3
+  holds.
+* **global** — ``"<callable can:// id>@<local>"``, the fully addressable id for
+  cross-callable references and the Neo4j PyCFGNode keys (a later task).
+"""
+from __future__ import annotations
+from collections import defaultdict
+from typing import Dict, Iterable, Optional, Tuple
+
+
+class IdentityMap:
+    def __init__(self, callable_id: str, id_to_local: Dict[int, str]):
+        self._callable_id = callable_id
+        self._map = id_to_local
+
+    @classmethod
+    def for_function(cls, callable_id: str, pdg, param_nodes=None) -> "IdentityMap":
+        cfg = pdg.cfg
+        m: Dict[int, str] = {}
+        for n in cfg.nodes:
+            if n.id == cfg.entry_id:
+                m[n.id] = "@entry"
+            elif n.id == cfg.exit_id:
+                m[n.id] = "@exit"
+            else:
+                m[n.id] = f"{n.start_line}:{n.start_column}"
+        im = cls(callable_id, m)
+        if param_nodes:
+            im._assign_param_locals(param_nodes)
+        return im
+
+    def _assign_param_locals(self, param_nodes) -> None:
+        """Fold the L4 synthetic param vertices into ``_map`` so ``local`` /
+        ``global_id`` resolve them uniformly with CFG nodes.
+
+        Canonical locals, per node ``kind`` (idx = position within the node's
+        ``(kind, call_node)`` group, in ``param_nodes`` list order):
+
+        * ``formal_in``  → ``"@formal_in:<idx>"`` (always indexed);
+        * ``formal_out`` → ``"@formal_out"`` when the function has exactly one,
+          else ``"@formal_out:<idx>"``;
+        * ``actual_in``  → ``"<callsite-local>/actual_in:<idx>"`` (always
+          indexed), ``<callsite-local> = self.local(pn.call_node)``;
+        * ``actual_out`` → ``"<callsite-local>/actual_out"`` when the callsite
+          has exactly one, else ``"<callsite-local>/actual_out:<idx>"``.
+        """
+        counts: Dict[Tuple[str, Optional[int]], int] = defaultdict(int)
+        for pn in param_nodes:
+            counts[(pn.kind, pn.call_node)] += 1
+
+        seen: Dict[Tuple[str, Optional[int]], int] = defaultdict(int)
+        for pn in param_nodes:
+            key = (pn.kind, pn.call_node)
+            idx = seen[key]
+            seen[key] += 1
+            n = counts[key]
+            if pn.kind == "formal_in":
+                local = f"@formal_in:{idx}"
+            elif pn.kind == "formal_out":
+                local = "@formal_out" if n == 1 else f"@formal_out:{idx}"
+            elif pn.kind == "actual_in":
+                cs = self.local(pn.call_node)
+                local = f"{cs}/actual_in:{idx}"
+            elif pn.kind == "actual_out":
+                cs = self.local(pn.call_node)
+                local = f"{cs}/actual_out" if n == 1 else f"{cs}/actual_out:{idx}"
+            else:
+                raise ValueError(f"unknown param node kind: {pn.kind!r}")
+            self._map[pn.id] = local
+
+    def local(self, node_id: int) -> str:
+        """Intra-callable id: ``"@entry"``/``"@exit"`` or ``"line:col"``."""
+        return self._map[node_id]
+
+    def global_id(self, node_id: int) -> str:
+        """Fully addressable id: ``"<callable-id>@<local>"``."""
+        loc = self._map[node_id]
+        # local statements are "line:col"; bookends already carry the leading "@"
+        return f"{self._callable_id}{loc}" if loc.startswith("@") else f"{self._callable_id}@{loc}"
+
+    def node_ids(self) -> Iterable[int]:
+        return self._map.keys()

codeanalyzer/dataflow/pdg.py

@@ -0,0 +1,100 @@
+################################################################################
+# Copyright IBM Corporation 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Stage 4 of the level-3 dataflow ladder: PDG assembly.
+
+Per callable, the PDG is the union of the stage-2 control-dependence edges
+(``CDG``) and the stage-3 def-use edges (``DDG``), over the same
+``(signature, node_id)`` nodes. Nothing new is computed here — this module is
+bookkeeping plus the intraprocedural backward slice that gates it: reverse
+reachability over CDG ∪ DDG from a criterion node, expected to match a
+hand-computed node set exactly on the fixture.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+from codeanalyzer.dataflow.access_paths import (
+    FunctionScope,
+    StatementFacts,
+    build_scope,
+    statement_facts,
+)
+from codeanalyzer.dataflow.alias import TypeBasedAliasOracle
+from codeanalyzer.dataflow.cfg import ControlFlowGraph, build_cfg
+from codeanalyzer.dataflow.defuse import ddg_edges
+from codeanalyzer.dataflow.dominance import control_dependence
+
+
+@dataclass(frozen=True)
+class PDGEdge:
+    source: int
+    target: int
+    type: str  # "CDG" | "DDG"
+    var: Optional[str] = None  # access path on DDG edges
+
+
+@dataclass
+class FunctionPDG:
+    """One callable's intraprocedural graphs, keyed externally by signature."""
+
+    cfg: ControlFlowGraph
+    edges: List[PDGEdge]
+    scope: FunctionScope
+    facts: Dict[int, StatementFacts] = field(default_factory=dict)
+
+
+def build_pdg(
+    func: ast.AST,
+    enclosing_locals: Set[str],
+    oracle: TypeBasedAliasOracle,
+    k: int = 3,
+    global_qualifier: Optional[str] = None,
+) -> FunctionPDG:
+    """CFG → dominance → def-use → PDG for one callable."""
+    cfg = build_cfg(func)
+    scope = build_scope(func, enclosing_locals)
+    facts = statement_facts(cfg, func, scope, k, global_qualifier)
+
+    edges: List[PDGEdge] = [
+        PDGEdge(source=a, target=b, type="CDG") for a, b in control_dependence(cfg)
+    ]
+    edges.extend(
+        PDGEdge(source=e.source, target=e.target, type="DDG", var=e.var)
+        for e in ddg_edges(cfg, facts, oracle)
+    )
+    edges.sort(key=lambda e: (e.source, e.target, e.type, e.var or ""))
+    return FunctionPDG(cfg=cfg, edges=edges, scope=scope, facts=facts)
+
+
+def intraprocedural_backward_slice(pdg: FunctionPDG, criterion: int) -> Set[int]:
+    """Reverse reachability over CDG ∪ DDG from the criterion node (the
+    criterion itself is in the slice). The stage-4 gate."""
+    reverse: Dict[int, List[int]] = {}
+    for e in pdg.edges:
+        reverse.setdefault(e.target, []).append(e.source)
+    seen: Set[int] = set()
+    stack = [criterion]
+    while stack:
+        n = stack.pop()
+        if n in seen:
+            continue
+        seen.add(n)
+        stack.extend(reverse.get(n, []))
+    return seen