codegraph-ir 0.1.0__py3-none-any.whl

cgir/__init__.py

@@ -0,0 +1,6 @@
+"""CodeGraph IR — a semantic IR layer over repo graphs.
+
+See ``Code-IR.md`` at the repo root for the product specification.
+"""
+
+__version__ = "0.1.0"

cgir/analyses/__init__.py

@@ -0,0 +1,7 @@
+"""Analysis passes over RepoGraph.
+
+P0 working: :mod:`cgir.analyses.symbols`, :mod:`cgir.analyses.call_graph`.
+P0 stubs:   :mod:`cgir.analyses.effects`, :mod:`cgir.analyses.purity`.
+P1 stubs:   :mod:`cgir.analyses.cfg`, :mod:`cgir.analyses.reaching_defs`,
+            :mod:`cgir.analyses.pdg`.
+"""

cgir/analyses/call_graph.py

@@ -0,0 +1,114 @@
+"""Build CALLS edges from resolved symbol tables.
+
+Language-neutral: the active :class:`~cgir.languages.LanguageAdapter`
+supplies each function's call sites (dotted callee, arg names, line); this
+module resolves each callee through the owning module's symbol table and
+emits the edge. Unresolved calls are dropped — third-party effects show up
+via :mod:`cgir.analyses.effects` instead.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cgir.analyses.symbols import SymbolTable, module_of
+from cgir.ir.edges import Edge, EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+from cgir.languages import LanguageAdapter, SourceCache
+
+_SELF_RECEIVERS: frozenset[str] = frozenset({"this", "self"})
+
+
+def build_call_graph(
+    graph: RepoGraph,
+    tables: dict[str, SymbolTable],
+    repo_path: Path,
+    adapter: LanguageAdapter | None = None,
+) -> None:
+    cache = SourceCache(repo_path, adapter)
+    for func in list(graph.nodes()):
+        if func.kind not in {NodeKind.Function, NodeKind.Method}:
+            continue
+        module_id = module_of(graph, func)
+        if module_id is None or func.path is None:
+            continue
+        table = tables.get(module_id)
+        if table is None:
+            continue
+        parsed = cache.get(func.path)
+        if parsed is None:
+            continue
+        source, root, file_adapter = parsed
+        func_ts = file_adapter.locate_function(root, func.name, (func.start_line or 1) - 1)
+        if func_ts is None:
+            continue
+        class_fields = _owning_class_fields(graph, func)
+        for callee_name, arg_names, line in file_adapter.call_sites(func_ts, source):
+            target = _resolve_callee(tables, table, callee_name)
+            if target is None and class_fields:
+                target = _resolve_field_call(graph, table, class_fields, callee_name)
+            if target is None:
+                continue
+            # Note: multi-edges collapse per (caller, callee) pair, so the
+            # recorded args/line describe one representative call site.
+            graph.add_edge(
+                Edge(
+                    src=func.id,
+                    dst=target,
+                    kind=EdgeKind.CALLS,
+                    attrs={"args": arg_names, "line": line},
+                )
+            )
+
+
+def _owning_class_fields(graph: RepoGraph, func: Node) -> dict[str, str]:
+    """The field→type map of the class owning a method (empty for free functions)."""
+    for edge in graph.in_edges(func.id, EdgeKind.CONTAINS):
+        parent = graph.get_node(edge.src)
+        if parent.kind == NodeKind.Class:
+            fields = parent.attrs.get("fields")
+            return fields if isinstance(fields, dict) else {}
+    return {}
+
+
+def _resolve_field_call(
+    graph: RepoGraph, table: SymbolTable, class_fields: dict[str, str], dotted: str
+) -> str | None:
+    """Resolve ``this.<field>.<method>`` via the field's declared type.
+
+    ``this.svc.translate`` where ``svc: ChaptersService`` resolves to the
+    method on the class that ``ChaptersService`` binds to (DI / receiver
+    calls). Requires the type to resolve to an in-repo Class node.
+    """
+    parts = dotted.split(".")
+    if len(parts) < 3 or parts[0] not in _SELF_RECEIVERS:
+        return None
+    type_name = class_fields.get(parts[1])
+    if type_name is None:
+        return None
+    binding = table.bindings.get(type_name)
+    if binding is None or not binding.startswith("class:"):
+        return None
+    method_id = f"method:{binding[len('class:') :]}.{parts[2]}"
+    return method_id if graph.has_node(method_id) else None
+
+
+def _resolve_callee(tables: dict[str, SymbolTable], table: SymbolTable, dotted: str) -> str | None:
+    """Resolve a (possibly dotted) callee through the local symbol table.
+
+    ``chapter.get_chapter`` where ``chapter`` binds to a module resolves
+    into that module's own table — the edge lands on the function, not the
+    module. Non-module attribute bases (``self.repo.get``) stay at the
+    binding of the head, which is usually unbound and dropped.
+    """
+    head, _, rest = dotted.partition(".")
+    target = table.bindings.get(head)
+    if target is None:
+        return None
+    if rest and target.startswith("module:"):
+        sub = tables.get(target)
+        if sub is None:
+            return None
+        return sub.bindings.get(rest.split(".", 1)[0])
+    return target

cgir/analyses/cfg.py

@@ -0,0 +1,320 @@
+"""Intra-procedural control-flow graph construction — language-neutral.
+
+For each Function/Method node we walk the body via the active
+:class:`~cgir.languages.LanguageAdapter` and emit:
+
+* ``Assignment`` for binding statements (``x = e``, ``x += e``)
+* ``Return`` for returns (CFG sinks)
+* ``Branch`` for each conditional arm, exception handler, and match case
+* ``Loop`` for loop headers (for-targets recorded in ``writes``)
+* ``Statement`` for everything else — including resource headers (``with``),
+  which record their aliases in ``writes``, and mutator calls in ``mutates``
+
+Edges:
+
+* ``Function -[CONTAINS]-> <cfg-node>``  for every CFG node we emit
+* ``<node> -[CONTROLS]-> <next-node>``   for control-flow successors
+
+The *topology* rules here are language-universal (branch fall-through, loop
+back-edges, try/finally joins, case chains); everything grammar-specific —
+what node type is a loop, where its condition lives, which names it binds —
+comes from the adapter as a normalized
+:class:`~cgir.languages.base.StatementDesc`:
+
+* The Function node is the CFG entry; ``Return`` is a sink.
+* A branch without an else falls through (the Branch node joins the
+  post-branch successor set); else-if arms chain as nested Branch nodes,
+  each control-dependent on its parent.
+* A ``Loop`` header has two successors (body, fall-through); body tails
+  get a back-edge to the header.
+* Resource headers (``with``) introduce no control dependence — the body
+  keeps the outer controller.
+* ``try`` bodies keep the outer controller; each handler is a ``Branch``
+  whose predecessors include the try entry *and* the body tails; ``else``
+  chains off the no-exception path; ``finally`` joins every path.
+* ``match``/``switch`` cases chain like else-if arms, with the last case's
+  Branch left open as the no-match fall-through.
+
+``break``/``continue`` jump targets and loop ``else`` clauses are out of
+scope — flag rather than guess.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from tree_sitter import Node as TSNode
+
+from cgir.ir.edges import Edge, EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+from cgir.languages import LanguageAdapter, SourceCache
+from cgir.languages.base import (
+    AssignDesc,
+    BranchDesc,
+    LoopDesc,
+    MatchDesc,
+    ReturnDesc,
+    SimpleDesc,
+    TryDesc,
+    WithDesc,
+)
+
+
+def build(graph: RepoGraph, repo_path: Path, adapter: LanguageAdapter | None = None) -> None:
+    cache = SourceCache(repo_path, adapter)
+    for func in list(graph.nodes()):
+        if func.kind not in {NodeKind.Function, NodeKind.Method}:
+            continue
+        if func.path is None or func.start_line is None:
+            continue
+        parsed = cache.get(func.path)
+        if parsed is None:
+            continue
+        source, root, file_adapter = parsed
+        func_ts = file_adapter.locate_function(root, func.name, func.start_line - 1)
+        if func_ts is None:
+            continue
+        body = file_adapter.function_body(func_ts)
+        if body is None:
+            continue
+        builder = _CFGBuilder(graph=graph, owner=func, source=source, adapter=file_adapter)
+        builder.build_block(body, predecessors=[func.id], controller=None)
+
+
+@dataclass
+class _CFGBuilder:
+    graph: RepoGraph
+    owner: Node
+    source: bytes
+    adapter: LanguageAdapter
+    _counter: int = field(default=0, init=False)
+
+    def build_block(
+        self, block_ts: TSNode, predecessors: list[str], controller: str | None
+    ) -> list[str]:
+        """Build a straight-line block. Returns the open predecessors at the block's tail."""
+        current_preds = list(predecessors)
+        for child in self.adapter.block_statements(block_ts):
+            current_preds = self.build_stmt(child, current_preds, controller)
+        return current_preds
+
+    def build_stmt(self, ts_node: TSNode, preds: list[str], controller: str | None) -> list[str]:
+        desc = self.adapter.describe_statement(ts_node, self.source)
+        if isinstance(desc, BranchDesc):
+            return self._build_branch(ts_node, desc, preds, controller)
+        if isinstance(desc, LoopDesc):
+            return self._build_loop(ts_node, desc, preds, controller)
+        if isinstance(desc, ReturnDesc):
+            return self._build_return(ts_node, desc, preds, controller)
+        if isinstance(desc, WithDesc):
+            return self._build_with(ts_node, desc, preds, controller)
+        if isinstance(desc, TryDesc):
+            return self._build_try(desc, preds, controller)
+        if isinstance(desc, MatchDesc):
+            return self._build_match(desc, preds, controller)
+        if isinstance(desc, AssignDesc):
+            return self._build_assignment(ts_node, desc, preds, controller)
+        return self._emit_simple(ts_node, desc, preds, controller)
+
+    def _emit_simple(
+        self, ts_node: TSNode, desc: SimpleDesc, preds: list[str], controller: str | None
+    ) -> list[str]:
+        node_id = self._new_id("stmt")
+        attrs: dict[str, object] = {
+            "reads": desc.reads,
+            "mutates": desc.mutates,
+            "controlled_by": controller,
+        }
+        self._add_node(node_id, NodeKind.Statement, ts_node, attrs=attrs)
+        self._wire(preds, node_id)
+        return [node_id]
+
+    def _build_assignment(
+        self, ts_node: TSNode, desc: AssignDesc, preds: list[str], controller: str | None
+    ) -> list[str]:
+        node_id = self._new_id("assign")
+        attrs: dict[str, object] = {
+            "writes": desc.writes,
+            "mutates": desc.mutates,
+            "reads": desc.reads,
+            "controlled_by": controller,
+        }
+        self._add_node(node_id, NodeKind.Assignment, ts_node, attrs=attrs)
+        self._wire(preds, node_id)
+        return [node_id]
+
+    def _build_return(
+        self, ts_node: TSNode, desc: ReturnDesc, preds: list[str], controller: str | None
+    ) -> list[str]:
+        node_id = self._new_id("return")
+        attrs: dict[str, object] = {
+            "reads": desc.reads,
+            "mutates": desc.mutates,
+            "controlled_by": controller,
+        }
+        self._add_node(node_id, NodeKind.Return, ts_node, attrs=attrs)
+        self._wire(preds, node_id)
+        # Return is a sink — no open successors for the caller to wire.
+        return []
+
+    def _build_branch(
+        self, ts_node: TSNode, desc: BranchDesc, preds: list[str], controller: str | None
+    ) -> list[str]:
+        branch_id = self._new_id("branch")
+        attrs: dict[str, object] = {"reads": desc.reads, "controlled_by": controller}
+        self._add_node(branch_id, NodeKind.Branch, ts_node, attrs=attrs)
+        self._wire(preds, branch_id)
+
+        exits: list[str] = []
+        if desc.consequence is not None:
+            exits.extend(self.build_block(desc.consequence, [branch_id], controller=branch_id))
+
+        if desc.next_branch is not None:
+            # else-if arm: its own Branch, control-dependent on this one.
+            next_desc = self.adapter.describe_statement(desc.next_branch, self.source)
+            if isinstance(next_desc, BranchDesc):
+                exits.extend(
+                    self._build_branch(desc.next_branch, next_desc, [branch_id], branch_id)
+                )
+            else:  # defensive: treat unexpected shapes as an else block
+                exits.extend(self.build_stmt(desc.next_branch, [branch_id], branch_id))
+        elif desc.else_block is not None:
+            exits.extend(self.build_block(desc.else_block, [branch_id], controller=branch_id))
+        else:
+            # No else: the branch itself is an open predecessor for fall-through.
+            exits.append(branch_id)
+        return exits
+
+    def _build_loop(
+        self, ts_node: TSNode, desc: LoopDesc, preds: list[str], controller: str | None
+    ) -> list[str]:
+        loop_id = self._new_id("loop")
+        attrs: dict[str, object] = {
+            "writes": desc.writes,
+            "reads": desc.reads,
+            "controlled_by": controller,
+        }
+        self._add_node(loop_id, NodeKind.Loop, ts_node, attrs=attrs)
+        self._wire(preds, loop_id)
+
+        if desc.body is not None:
+            body_tail = self.build_block(desc.body, [loop_id], controller=loop_id)
+            for tail in body_tail:
+                self.graph.add_edge(Edge(src=tail, dst=loop_id, kind=EdgeKind.CONTROLS))
+
+        # Fall-through exit: loop header itself.
+        return [loop_id]
+
+    def _build_with(
+        self, ts_node: TSNode, desc: WithDesc, preds: list[str], controller: str | None
+    ) -> list[str]:
+        header_id = self._new_id("with")
+        attrs: dict[str, object] = {
+            "writes": desc.writes,
+            "reads": desc.reads,
+            "mutates": [],
+            "controlled_by": controller,
+        }
+        self._add_node(header_id, NodeKind.Statement, ts_node, attrs=attrs)
+        self._wire(preds, header_id)
+
+        if desc.body is None:
+            return [header_id]
+        # The body always executes: it keeps the *outer* controller.
+        return self.build_block(desc.body, [header_id], controller=controller)
+
+    def _build_try(self, desc: TryDesc, preds: list[str], controller: str | None) -> list[str]:
+        body_tails = (
+            self.build_block(desc.body, preds, controller) if desc.body is not None else list(preds)
+        )
+
+        no_exception_tails = body_tails
+        handler_exits: list[str] = []
+        for handler in desc.handlers:
+            # An exception may fire before any try-body statement completes,
+            # so the handler's predecessors include the try entry.
+            handler_preds = _dedupe(list(preds) + body_tails)
+            branch_id = self._new_id("except")
+            attrs: dict[str, object] = {
+                "writes": handler.writes,
+                "reads": [],
+                "controlled_by": controller,
+            }
+            self._add_node(branch_id, NodeKind.Branch, handler.node, attrs=attrs)
+            self._wire(handler_preds, branch_id)
+            if handler.block is not None:
+                handler_exits.extend(self.build_block(handler.block, [branch_id], branch_id))
+            else:
+                handler_exits.append(branch_id)
+
+        if desc.else_block is not None:
+            no_exception_tails = self.build_block(desc.else_block, no_exception_tails, controller)
+
+        exits = _dedupe(no_exception_tails + handler_exits)
+
+        if desc.finally_block is not None:
+            exits = self.build_block(desc.finally_block, exits, controller)
+        return exits
+
+    def _build_match(self, desc: MatchDesc, preds: list[str], controller: str | None) -> list[str]:
+        exits: list[str] = []
+        current_preds = list(preds)
+        current_controller = controller
+        last_branch: str | None = None
+        for case in desc.cases:
+            branch_id = self._new_id("case")
+            attrs: dict[str, object] = {"reads": case.reads, "controlled_by": current_controller}
+            self._add_node(branch_id, NodeKind.Branch, case.node, attrs=attrs)
+            self._wire(current_preds, branch_id)
+
+            if case.consequence is not None:
+                exits.extend(self.build_block(case.consequence, [branch_id], branch_id))
+
+            current_preds = [branch_id]
+            current_controller = branch_id
+            last_branch = branch_id
+
+        if last_branch is not None:
+            # No case matched: fall through past the last case's Branch.
+            exits.append(last_branch)
+        return _dedupe(exits)
+
+    def _add_node(
+        self,
+        node_id: str,
+        kind: NodeKind,
+        ts_node: TSNode,
+        attrs: dict[str, object] | None = None,
+    ) -> None:
+        self.graph.add_node(
+            Node(
+                id=node_id,
+                kind=kind,
+                name=_short_name(ts_node, self.source),
+                path=self.owner.path,
+                start_line=ts_node.start_point[0] + 1,
+                end_line=ts_node.end_point[0] + 1,
+                attrs=dict(attrs) if attrs else {},
+            )
+        )
+        self.graph.add_edge(Edge(src=self.owner.id, dst=node_id, kind=EdgeKind.CONTAINS))
+
+    def _wire(self, preds: list[str], dst: str) -> None:
+        for pred in preds:
+            self.graph.add_edge(Edge(src=pred, dst=dst, kind=EdgeKind.CONTROLS))
+
+    def _new_id(self, prefix: str) -> str:
+        self._counter += 1
+        return f"{prefix}:{self.owner.id}#{self._counter}"
+
+
+def _dedupe(ids: list[str]) -> list[str]:
+    return list(dict.fromkeys(ids))
+
+
+def _short_name(ts_node: TSNode, source: bytes) -> str:
+    raw = source[ts_node.start_byte : ts_node.end_byte].decode("utf-8", errors="replace")
+    first_line = raw.splitlines()[0] if raw else ""
+    return first_line.strip()[:80]

cgir/analyses/effects.py

@@ -0,0 +1,95 @@
+"""Side-effect classification — language-neutral algorithm over a LanguageAdapter.
+
+Effect taxonomy (the language-neutral ComponentSpec vocabulary):
+    io              terminal / device IO
+    raise           contains a raise (informational — see below)
+    net             network access
+    fs              filesystem access
+    nondeterm       randomness / clock reads
+    db              database access
+    calls_effectful (transitive only) — a callee has an *impure* effect
+
+``raise`` is recorded but **not impure** (settled Sprint 13): exceptions
+are control flow / part of the contract, so a raise-only function keeps
+purity 1.0 and does not taint callers. :data:`IMPURE_EFFECT_TAGS` is the
+gate used by purity, classification, and the transitive closure.
+
+This module owns only the *algorithm*: build per-module import-alias maps
+(language-neutral, from ``Import`` node attrs), ask the active
+:class:`~cgir.languages.LanguageAdapter` for each function's direct effect
+tags, then propagate ``calls_effectful`` transitively over ``CALLS`` to a
+fixed point. Which calls count as which effect is the adapter's business
+(``PythonAdapter.direct_effects`` and its stdlib tables).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cgir.analyses.symbols import module_of
+from cgir.ir.edges import EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+from cgir.languages import LanguageAdapter, SourceCache
+
+DIRECT_EFFECT_TAGS: frozenset[str] = frozenset({"io", "raise", "net", "fs", "nondeterm", "db"})
+IMPURE_EFFECT_TAGS: frozenset[str] = DIRECT_EFFECT_TAGS - {"raise"}
+TRANSITIVE_TAG = "calls_effectful"
+
+
+def classify(
+    graph: RepoGraph, repo_path: Path, adapter: LanguageAdapter | None = None
+) -> dict[str, list[str]]:
+    """Return ``{function_id: sorted([effect_tag, ...])}`` for every function/method."""
+    cache = SourceCache(repo_path, adapter)
+    func_nodes = [n for n in graph.nodes() if n.kind in {NodeKind.Function, NodeKind.Method}]
+    alias_maps = _module_alias_maps(graph)
+
+    effects: dict[str, set[str]] = {}
+    for func in func_nodes:
+        module_id = module_of(graph, func)
+        aliases = alias_maps.get(module_id, {}) if module_id else {}
+        effects[func.id] = _direct_effects(cache, func, aliases)
+
+    # Propagate transitively over CALLS edges until fixed point. Only
+    # *impure* effects taint callers — raise-only callees don't.
+    changed = True
+    while changed:
+        changed = False
+        for func in func_nodes:
+            for edge in graph.out_edges(func.id, EdgeKind.CALLS):
+                callee = effects.get(edge.dst, set())
+                if (
+                    callee & IMPURE_EFFECT_TAGS or TRANSITIVE_TAG in callee
+                ) and TRANSITIVE_TAG not in effects[func.id]:
+                    effects[func.id].add(TRANSITIVE_TAG)
+                    changed = True
+
+    return {nid: sorted(tags) for nid, tags in effects.items()}
+
+
+def _module_alias_maps(graph: RepoGraph) -> dict[str, dict[str, str]]:
+    """Per module: ``{local_name: absolute_dotted_target}`` from Import nodes."""
+    maps: dict[str, dict[str, str]] = {}
+    for module in graph.nodes(NodeKind.Module):
+        table: dict[str, str] = {}
+        for child in graph.children(module.id, NodeKind.Import):
+            target = str(child.attrs.get("target") or child.name)
+            alias = child.attrs.get("alias")
+            local = alias if isinstance(alias, str) else target.rsplit(".", 1)[-1]
+            table[local] = target
+        maps[module.id] = table
+    return maps
+
+
+def _direct_effects(cache: SourceCache, func: Node, aliases: dict[str, str]) -> set[str]:
+    if func.path is None or func.start_line is None:
+        return set()
+    parsed = cache.get(func.path)
+    if parsed is None:
+        return set()
+    source, root, adapter = parsed
+    func_ts = adapter.locate_function(root, func.name, func.start_line - 1)
+    if func_ts is None:
+        return set()
+    return adapter.direct_effects(func_ts, source, aliases)

cgir/analyses/entrypoints.py

@@ -0,0 +1,55 @@
+"""Entrypoint detection from decorator texts (Sprint 17).
+
+The ingester records each decorated definition's decorator texts (sans
+``@``); :func:`detect` maps them to a human-readable entrypoint label:
+
+* ``router.get("/x")`` / ``app.post(...)`` → ``HTTP GET /x`` (FastAPI style)
+* ``app.route("/x")`` → ``HTTP /x`` (Flask style; method set not parsed)
+* ``app.command()`` / ``click.command()`` → ``CLI <func>`` (typer/click)
+* ``shared_task`` / ``celery.task`` → ``task <func>``
+
+Purely lexical — a decorator named like a router that isn't one will
+false-positive; per spec, flag rather than solve. Framework dispatch is
+exactly the dynamic behavior static call graphs can't see, so these
+labels are how CGIR shows "called by the framework".
+"""
+
+from __future__ import annotations
+
+import re
+
+_HTTP_METHODS: frozenset[str] = frozenset(
+    {"get", "post", "put", "delete", "patch", "head", "options", "websocket"}
+)
+_HTTP_RECEIVERS: frozenset[str] = frozenset({"app", "router", "api", "blueprint", "bp"})
+_TASK_MARKERS: frozenset[str] = frozenset({"task", "shared_task"})
+
+_FIRST_STR_ARG = re.compile(r"\(\s*[rbf]*[\"']([^\"']*)[\"']")
+
+
+def detect(decorators: list[str], func_name: str) -> str | None:
+    """Map decorator texts to an entrypoint label, or None."""
+    for decorator in decorators:
+        head = decorator.split("(", 1)[0].strip()
+        parts = head.split(".")
+        if len(parts) == 2 and parts[0] in _HTTP_RECEIVERS:
+            if parts[1] in _HTTP_METHODS:
+                path = _first_str_arg(decorator)
+                return (
+                    f"HTTP {parts[1].upper()} {path}".rstrip()
+                    if path
+                    else (f"HTTP {parts[1].upper()}")
+                )
+            if parts[1] == "route":
+                path = _first_str_arg(decorator)
+                return f"HTTP {path}" if path else "HTTP"
+        if parts[-1] == "command" and len(parts) >= 2:
+            return f"CLI {func_name}"
+        if parts[-1] in _TASK_MARKERS:
+            return f"task {func_name}"
+    return None
+
+
+def _first_str_arg(decorator: str) -> str | None:
+    match = _FIRST_STR_ARG.search(decorator)
+    return match.group(1) if match else None

cgir/analyses/param_flow.py

@@ -0,0 +1,75 @@
+"""Parameter-flow analysis: which caller params reach which callee.
+
+Pure-graph may-analysis over the CFG ``reads``/``writes`` attrs populated
+by :mod:`cgir.analyses.cfg` and the call-site ``args`` recorded on
+``CALLS`` edges by :mod:`cgir.analyses.call_graph`:
+
+* Each parameter taints its own name.
+* Any CFG node that reads a tainted name taints every name it writes
+  (fixed point, order-insensitive — a *may*-flow, per spec: flag rather
+  than prove).
+* A parameter flows into a call iff the call's argument identifiers
+  intersect the parameter's tainted names.
+
+Drives the arg-flow edges in the HTML Flow view (data passed *down* into
+callees, complementing the return-type edges that flow up).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cgir.ir.edges import EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+
+_CFG_KINDS: frozenset[NodeKind] = frozenset(
+    {
+        NodeKind.Statement,
+        NodeKind.Assignment,
+        NodeKind.Branch,
+        NodeKind.Loop,
+        NodeKind.Return,
+    }
+)
+
+
+def compute(graph: RepoGraph) -> dict[str, list[dict[str, Any]]]:
+    """Per caller id: ``[{"callee": id, "params": [names...]}, ...]``."""
+    result: dict[str, list[dict[str, Any]]] = {}
+    for func in graph.nodes():
+        if func.kind not in {NodeKind.Function, NodeKind.Method}:
+            continue
+        entries = _entries_for(graph, func)
+        if entries:
+            result[func.id] = entries
+    return result
+
+
+def _entries_for(graph: RepoGraph, func: Node) -> list[dict[str, Any]]:
+    params = [p.name for p in graph.children(func.id, NodeKind.Parameter)]
+    if not params:
+        return []
+    cfg_nodes = [c for c in graph.children(func.id) if c.kind in _CFG_KINDS]
+
+    taint: dict[str, set[str]] = {p: {p} for p in params}
+    changed = True
+    while changed:
+        changed = False
+        for node in cfg_nodes:
+            reads = set(node.attrs.get("reads") or []) if node.attrs else set()
+            writes = set(node.attrs.get("writes") or []) if node.attrs else set()
+            if not writes:
+                continue
+            for param in params:
+                if reads & taint[param] and not writes <= taint[param]:
+                    taint[param] |= writes
+                    changed = True
+
+    entries: list[dict[str, Any]] = []
+    for edge in graph.out_edges(func.id, EdgeKind.CALLS):
+        args = set(edge.attrs.get("args") or [])
+        flowing = [p for p in params if args & taint[p]]
+        if flowing:
+            entries.append({"callee": edge.dst, "params": flowing})
+    return entries