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

codeanalyzer/dataflow/summaries.py

@@ -0,0 +1,217 @@
+################################################################################
+# 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 6 of the level-3 dataflow ladder: bottom-up function summaries.
+
+A summary is relational: which formal inputs (parameters, captures, read
+globals) may flow to which formal outputs (the return value, caller-visible
+parameter mutations, written globals). Summaries compose bottom-up over the
+SCC condensation DAG of the call-graph oracle; within an SCC (mutual
+recursion) all members iterate to a monotone fixpoint — the domains (formal
+keys and qualified global names) are finite and effects only grow, so
+termination is structural. k-limiting bounds the access-path vocabulary.
+
+At statement granularity a callsite node is already a transformer (all its
+defs depend on all its uses), so the composition step callee summaries
+actually contribute is the *global footprint*: a callsite node gains the
+callee's transitive global reads as uses and writes as defs, the reaching
+definitions are re-solved, and flows are re-derived. External/unmodeled
+callees default to conservative pass-through (their argument paths are
+already weak-defined and used at the call statement).
+
+Summary flow keys: ``param:NAME``, ``capture:NAME``, ``global:MODULE::NAME``
+for inputs; ``return``, ``param:NAME`` (mutation), ``global:MODULE::NAME``
+for outputs.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set, Tuple
+
+from codeanalyzer.dataflow.access_paths import RETURN_PATH, base_of, suffix_of
+from codeanalyzer.dataflow.alias import TypeBasedAliasOracle
+from codeanalyzer.dataflow.defuse import DDGEdge, ddg_edges
+from codeanalyzer.dataflow.pdg import FunctionPDG
+from codeanalyzer.dataflow.scc import strongly_connected_components
+
+
+@dataclass(frozen=True)
+class CallSite:
+    """One resolved call at one CFG statement node (builder-provided)."""
+
+    node_id: int
+    targets: Tuple[str, ...]  # callee signatures declared in the symbol table
+    # callee param name -> actual access path (None: a non-path expression)
+    arg_paths: Tuple[Tuple[str, Optional[str]], ...] = ()
+    line: int = -1
+
+    def arg_path_of(self, param: str) -> Optional[str]:
+        for name, path in self.arg_paths:
+            if name == param:
+                return path
+        return None
+
+
+@dataclass
+class FunctionInfo:
+    """Everything the interprocedural stages need about one callable."""
+
+    signature: str
+    pdg: FunctionPDG
+    oracle: TypeBasedAliasOracle
+    call_sites: List[CallSite] = field(default_factory=list)
+    # Nested callables defined at a statement node: (def_node_id, nested_sig).
+    nested_defs: List[Tuple[int, str]] = field(default_factory=list)
+
+
+@dataclass
+class FunctionSummary:
+    global_reads: Set[str] = field(default_factory=set)
+    global_writes: Set[str] = field(default_factory=set)
+    mutated_params: Set[str] = field(default_factory=set)
+    flows: Set[Tuple[str, str]] = field(default_factory=set)
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, FunctionSummary)
+            and self.global_reads == other.global_reads
+            and self.global_writes == other.global_writes
+            and self.mutated_params == other.mutated_params
+            and self.flows == other.flows
+        )
+
+
+def _is_global(path: str) -> bool:
+    return "::" in base_of(path)
+
+
+def augmented_facts(info: FunctionInfo, summaries: Dict[str, FunctionSummary]):
+    """Per-node facts with callee global footprints injected at callsites."""
+    facts = {nid: f for nid, f in info.pdg.facts.items()}
+    out = {}
+    for nid, f in facts.items():
+        out[nid] = type(f)(defs=set(f.defs), uses=set(f.uses))
+    for cs in info.call_sites:
+        for target in cs.targets:
+            s = summaries.get(target)
+            if s is None:
+                continue
+            out[cs.node_id].uses |= s.global_reads
+            out[cs.node_id].defs |= s.global_writes
+    return out
+
+
+def solve_function(
+    info: FunctionInfo, summaries: Dict[str, FunctionSummary]
+) -> Tuple[FunctionSummary, Dict[int, object], List[DDGEdge]]:
+    """One summary iteration: inject callee footprints, re-solve reaching
+    definitions, derive flows. Returns (summary, augmented facts, DDG)."""
+    facts = augmented_facts(info, summaries)
+    ddg = ddg_edges(info.pdg.cfg, facts, info.oracle)
+
+    # Forward adjacency over DDG ∪ CDG (a statement transforms all its
+    # inputs into all its outputs — statement-granularity posture).
+    adj: Dict[int, List[int]] = {}
+    for e in ddg:
+        adj.setdefault(e.source, []).append(e.target)
+    for e in info.pdg.edges:
+        if e.type == "CDG":
+            adj.setdefault(e.source, []).append(e.target)
+
+    entry = info.pdg.cfg.entry_id
+    scope = info.pdg.scope
+
+    # Seeds: the ENTRY-def DDG edges, grouped by formal key.
+    seeds: Dict[str, Set[int]] = {}
+    for e in ddg:
+        if e.source != entry:
+            continue
+        b = base_of(e.var)
+        if b == scope.self_name or b in scope.params:
+            key = f"param:{b}"
+        elif b in scope.captures:
+            key = f"capture:{b}"
+        elif _is_global(e.var):
+            key = f"global:{b}"
+        else:
+            continue
+        seeds.setdefault(key, set()).add(e.target)
+
+    def reach(start: Set[int]) -> Set[int]:
+        seen: Set[int] = set()
+        stack = list(start)
+        while stack:
+            n = stack.pop()
+            if n in seen:
+                continue
+            seen.add(n)
+            stack.extend(adj.get(n, []))
+        return seen
+
+    summary = FunctionSummary()
+    param_names = set(scope.params)
+    if scope.self_name:
+        param_names.add(scope.self_name)
+
+    for nid, f in facts.items():
+        if nid == entry:
+            continue
+        for d in f.defs:
+            b = base_of(d)
+            if _is_global(d):
+                summary.global_writes.add(b)
+            elif b in param_names and suffix_of(d):
+                summary.mutated_params.add(b)
+        for u in f.uses:
+            if _is_global(u):
+                summary.global_reads.add(base_of(u))
+
+    for key, start in seeds.items():
+        for nid in reach(start):
+            f = facts[nid]
+            if RETURN_PATH in f.defs:
+                summary.flows.add((key, "return"))
+            for d in f.defs:
+                b = base_of(d)
+                if _is_global(d):
+                    summary.flows.add((key, f"global:{b}"))
+                elif b in param_names and suffix_of(d):
+                    summary.flows.add((key, f"param:{b}"))
+
+    return summary, facts, ddg
+
+
+def compute_summaries(
+    infos: Dict[str, FunctionInfo],
+    call_edges: List[Tuple[str, str]],
+) -> Dict[str, FunctionSummary]:
+    """Bottom-up composition over the SCC condensation DAG, monotone fixpoint
+    within each SCC."""
+    order = strongly_connected_components(sorted(infos), call_edges)
+    summaries: Dict[str, FunctionSummary] = {}
+    for scc in order:
+        members = [s for s in scc if s in infos]
+        changed = True
+        while changed:
+            changed = False
+            for sig in members:
+                new, _, _ = solve_function(infos[sig], summaries)
+                if summaries.get(sig) != new:
+                    summaries[sig] = new
+                    changed = True
+    return summaries

codeanalyzer/dataflow/syntactic.py

@@ -0,0 +1,26 @@
+################################################################################
+# 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.
+################################################################################
+
+"""The L3 (syntactic) alias oracle: two access paths alias iff they are the
+identical path. Bypasses the type-based may-alias so def-use yields only
+name-equality (textual) edges — the alias-derived edges are the L4 delta."""
+
+from __future__ import annotations
+
+
+class SyntacticOracle:
+    def may_alias(self, path_a: str, path_b: str) -> bool:
+        return path_a == path_b

codeanalyzer/neo4j/__init__.py

@@ -19,7 +19,7 @@ plus the two writers (cypher snapshot / bolt incremental). Nothing here runs
 unless ``--emit neo4j`` (or ``--emit schema``) is selected.
 """
 from codeanalyzer.neo4j.bolt import BoltConfig, bolt_writer
-from codeanalyzer.neo4j.catalog import (
+from codeanalyzer.neo4j.schema import (
     MARKER_LABELS,
     NODE_LABELS,
     REL_TYPES,

codeanalyzer/neo4j/bolt.py

@@ -44,7 +44,10 @@ from codeanalyzer.neo4j.rows import EdgeRow, GraphRows, NodeRow, chunk
 from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES
 from codeanalyzer.utils import logger
 
-DESCENDANTS = "[:PY_DECLARES|PY_HAS_METHOD|PY_HAS_ATTRIBUTE|PY_DECLARES_VAR|PY_HAS_CALLSITE*1..]"
+DESCENDANTS = (
+    "[:PY_DECLARES|PY_HAS_METHOD|PY_HAS_ATTRIBUTE|PY_DECLARES_VAR"
+    "|PY_HAS_CALLSITE|PY_HAS_CFG_NODE*1..]"
+)
 BATCH = 1000
 
 
@@ -193,21 +196,33 @@ def _upsert_nodes(session, neo4j, nodes: List[NodeRow]) -> None:
 def _upsert_edges(session, neo4j, edges: List[EdgeRow]) -> None:
     groups: Dict[str, List[EdgeRow]] = {}
     for e in edges:
-        key = f"{e.type}|{e.from_ref.label}.{e.from_ref.key_prop}|{e.to_ref.label}.{e.to_ref.key_prop}"
+        key = (
+            f"{e.type}|{e.from_ref.label}.{e.from_ref.key_prop}"
+            f"|{e.to_ref.label}.{e.to_ref.key_prop}|{e.key is not None}"
+        )
         groups.setdefault(key, []).append(e)
 
     for group in groups.values():
         first = group[0]
         from_ref, to_ref = first.from_ref, first.to_ref
+        # Discriminated relationships MERGE on ``{_k}`` so several distinct
+        # edges of one type coexist between the same endpoint pair (per-var
+        # PY_DDG, the true/false PY_CFG_NEXT pair). See EdgeRow.key.
+        rel_key = " {_k: row.k}" if first.key is not None else ""
         cypher = (
             f"UNWIND $rows AS row "
             f"MATCH (a:{from_ref.label} {{{from_ref.key_prop}: row.f}}) "
             f"MATCH (b:{to_ref.label} {{{to_ref.key_prop}: row.t}}) "
-            f"MERGE (a)-[r:{first.type}]->(b) SET r += row.p"
+            f"MERGE (a)-[r:{first.type}{rel_key}]->(b) SET r += row.p"
         )
         for batch in chunk(group, BATCH):
             payload = [
-                {"f": e.from_ref.value, "t": e.to_ref.value, "p": _to_params(e.props, neo4j)}
+                {
+                    "f": e.from_ref.value,
+                    "t": e.to_ref.value,
+                    "k": e.key,
+                    "p": _to_params(e.props, neo4j),
+                }
                 for e in batch
             ]
             with session() as s:

codeanalyzer/neo4j/cypher.py

@@ -115,24 +115,30 @@ def _node_statements(nodes: List[NodeRow]) -> List[str]:
 def _edge_statements(edges: List[EdgeRow]) -> List[str]:
     groups: Dict[str, List[EdgeRow]] = {}
     for e in edges:
-        key = f"{e.type}|{e.from_ref.label}.{e.from_ref.key_prop}|{e.to_ref.label}.{e.to_ref.key_prop}"
+        key = (
+            f"{e.type}|{e.from_ref.label}.{e.from_ref.key_prop}"
+            f"|{e.to_ref.label}.{e.to_ref.key_prop}|{e.key is not None}"
+        )
         groups.setdefault(key, []).append(e)
 
     blocks: List[str] = []
     for group in groups.values():
         first = group[0]
         from_ref, to_ref = first.from_ref, first.to_ref
+        # Discriminated relationships MERGE on ``{_k}`` — see EdgeRow.key.
+        rel_key = " {_k: row.k}" if first.key is not None else ""
         for batch in chunk(group, BATCH):
             rows_lit = ",\n".join(
                 f"  {{f: {cypher_value(e.from_ref.value)}, t: {cypher_value(e.to_ref.value)}, "
-                f"p: {cypher_map(e.props)}}}"
+                + (f"k: {cypher_value(e.key)}, " if first.key is not None else "")
+                + f"p: {cypher_map(e.props)}}}"
                 for e in batch
             )
             blocks.append(
                 f"UNWIND [\n{rows_lit}\n] AS row\n"
                 f"MATCH (a:{from_ref.label} {{{from_ref.key_prop}: row.f}})\n"
                 f"MATCH (b:{to_ref.label} {{{to_ref.key_prop}: row.t}})\n"
-                f"MERGE (a)-[r:{first.type}]->(b)\n"
+                f"MERGE (a)-[r:{first.type}{rel_key}]->(b)\n"
                 f"SET r += row.p;"
             )
     return blocks

codeanalyzer/neo4j/emit.py

@@ -28,17 +28,18 @@ from pathlib import Path
 from typing import Optional
 
 from codeanalyzer.neo4j.bolt import BoltConfig, bolt_writer
-from codeanalyzer.neo4j.catalog import build_schema_document
+from codeanalyzer.neo4j.schema import build_schema_document
 from codeanalyzer.neo4j.cypher import render_cypher
 from codeanalyzer.neo4j.project import project
 from codeanalyzer.options import AnalysisOptions
-from codeanalyzer.schema import PyApplication
+from codeanalyzer.schema import Analysis
+from codeanalyzer.schema.assign_ids import assign_ids
 from codeanalyzer.utils import logger
 
 
 def emit_schema(output: Optional[Path]) -> None:
     """Emit the Neo4j schema contract (``schema.json``) — a static artifact derived
-    from the in-repo catalog, independent of any analyzed project. With no
+    from the in-repo schema, independent of any analyzed project. With no
     ``output`` it prints to stdout."""
     doc = json.dumps(build_schema_document(), indent=2) + "\n"
     if output is None:
@@ -49,11 +50,15 @@ def emit_schema(output: Optional[Path]) -> None:
     logger.info(f"Neo4j schema written to {output / 'schema.json'}")
 
 
-def emit_neo4j(app: PyApplication, options: AnalysisOptions) -> None:
+def emit_neo4j(analysis: Analysis, options: AnalysisOptions) -> None:
     """Project the analysis to a graph and write it: a live Bolt push when
     ``--neo4j-uri`` is set, otherwise a self-contained ``graph.cypher`` snapshot."""
     app_name = options.app_name or Path(options.input).resolve().name
-    rows = project(app, app_name)
+    # ``assign_ids`` is idempotent: it stamps every module/class/callable with its
+    # canonical ``can://`` id and returns the ``signature -> id`` map the projection
+    # keys nodes on, so the JSON and Neo4j projections agree.
+    sig_to_id = assign_ids(analysis.application, app_name)
+    rows = project(analysis.application, app_name, sig_to_id, analyzer=analysis.analyzer)
 
     if options.neo4j_uri:
         cfg = BoltConfig(