Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(health): add def/use and reaching definitions over the CFG (#613)

Raghav Chamadiya22261908107b
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/languages.py b/packages/core/src/repowise/core/analysis/health/complexity/languages.py
index 80d8f0081..34c980794 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/languages.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/languages.py
@@ -131,6 +131,29 @@ class LanguageNodeMap:
call_kinds: frozenset[str] = frozenset()
async_function_kinds: frozenset[str] = frozenset()
+ # ------------------------------------------------------------------
+ # Dataflow def/use pass (intra-procedural CFG + reaching definitions).
+ # All three default to empty, making the read-vs-write distinction
+ # OPT-IN per language: a language that maps none produces no def/use
+ # signal (and so no reaching definitions), the safe "no signal" default.
+ # The per-language ``DefUseDialect`` (``dataflow/dialects/``) consumes
+ # these to recognise the assignment shapes whose targets are writes.
+ #
+ # * ``assignment_kinds`` — node type(s) for a plain assignment whose
+ # ``left`` field is the write target (Python ``assignment``; TS/JS
+ # ``assignment_expression``).
+ # * ``augmented_assign_kinds`` — compound-assignment node type(s)
+ # (``x += 1``) whose target is BOTH read and written.
+ # * ``local_decl_kinds`` — node type(s) that introduce a fresh local
+ # binding distinct from assignment (Go ``short_var_declaration``,
+ # Rust ``let_declaration``). Empty for languages such as Python where
+ # assignment is the only binding form; the dialect handles the
+ # remaining Python def sites (``for`` target, ``with ... as``, walrus,
+ # comprehension target) structurally.
+ assignment_kinds: frozenset[str] = frozenset()
+ augmented_assign_kinds: frozenset[str] = frozenset()
+ local_decl_kinds: frozenset[str] = frozenset()
+
_PY = LanguageNodeMap(
function_kinds=frozenset({"function_definition", "async_function_definition"}),
@@ -151,6 +174,8 @@ _PY = LanguageNodeMap(
assert_call_kinds=frozenset({"call"}),
call_kinds=frozenset({"call"}),
async_function_kinds=frozenset({"async_function_definition"}),
+ assignment_kinds=frozenset({"assignment"}),
+ augmented_assign_kinds=frozenset({"augmented_assignment"}),
)
_TS = LanguageNodeMap(
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/__init__.py b/packages/core/src/repowise/core/analysis/health/dataflow/__init__.py
index 7f7bfaf0e..85a1a4440 100644
--- a/packages/core/src/repowise/core/analysis/health/dataflow/__init__.py
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/__init__.py
@@ -1,28 +1,51 @@
"""Intra-procedural dataflow layer for the health pass.
-This subpackage builds a per-function control-flow graph (CFG) as the
-foundation for dataflow-aware refactoring signals (Extract Method) and the
-later def/use + reaching-definitions passes. It is deliberately standalone:
-nothing here is wired into the health engine yet, so the layer can be built
-and measured in isolation before it joins a hot path.
+This subpackage builds, per function, a control-flow graph (CFG), a def/use
+classification, and reaching-definitions sets -- the semantic foundation for
+dataflow-aware refactoring signals (Extract Method) and cross-layer consumers.
+It is deliberately standalone: nothing here is wired into the health engine yet,
+so the layer can be built and measured in isolation before it joins a hot path.
-**Performance contract (load-bearing).** A CFG is built ONLY for a function a
-structural biomarker already flagged (``large_method`` / ``brain_method`` /
-``complex_method``). The pass takes a pre-filtered flagged-function set, never
-the full function corpus -- see :func:`gating.is_flagged_function` and
-:func:`gating.build_cfgs_for_file`. Building for every function could add a
-double-digit percentage to the parse/walk layer, so we never do. A size guard
-caps pathological functions (emit nothing past the cap), and any per-function
-failure degrades to silence (no CFG, no raise).
+**Layering (language-agnostic core, per-language dialects).**
-Phase scope: Python only. The CFG builder is structural and largely
-language-agnostic; the jump-node classification it relies on is Python-specific
-for now and generalises behind a dialect in a later phase.
+- :mod:`cfg` -- statement sequencer, basic-block splitter, CFG builder.
+- :mod:`defuse` -- per-block def/use aggregation over the CFG, delegating the
+ read-vs-write classification to a language :class:`DefUseDialect`.
+- :mod:`reaching` -- the reaching-definitions worklist fixpoint (pure graph +
+ def facts; no language knowledge).
+- :mod:`dialects` -- the ``DefUseDialect`` registry; one module per language,
+ zero core edits to add one.
+- :mod:`analyze` -- composes the three stages behind one call.
+- :mod:`gating` -- the flagged-only predicate and the CFG-only file harness.
+
+**Performance contract (load-bearing).** Full dataflow is built ONLY for a
+function a structural biomarker already flagged (``large_method`` /
+``brain_method`` / ``complex_method``). The pass takes a pre-filtered
+flagged-function set, never the full function corpus -- see
+:func:`gating.is_flagged_function`, :func:`gating.build_cfgs_for_file`, and
+:func:`analyze.analyze_file`. A CFG size guard caps pathological functions and
+the reaching fixpoint has a convergence guard; any per-function failure (unmapped
+language, guard trip, non-convergence) degrades to silence, never a raise.
"""
from __future__ import annotations
+from .analyze import (
+ FileAnalysisResult,
+ FileAnalysisStats,
+ FunctionAnalysis,
+ analyze_file,
+ analyze_function,
+)
from .cfg import CFG, BasicBlock, Statement, build_cfg
+from .defuse import BlockDefUse, Definition, FunctionDefUse, compute_def_use
+from .dialects.base import (
+ DEFUSE_DIALECTS,
+ DefUseDialect,
+ Occurrence,
+ StatementDefUse,
+ get_defuse_dialect,
+)
from .gating import (
CFGPassStats,
FileCFGResult,
@@ -31,16 +54,33 @@ from .gating import (
is_flagged,
is_flagged_function,
)
+from .reaching import ReachingDefinitions, compute_reaching
__all__ = [
"CFG",
+ "DEFUSE_DIALECTS",
"BasicBlock",
+ "BlockDefUse",
"CFGPassStats",
+ "DefUseDialect",
+ "Definition",
+ "FileAnalysisResult",
+ "FileAnalysisStats",
"FileCFGResult",
+ "FunctionAnalysis",
"FunctionCFG",
+ "FunctionDefUse",
+ "Occurrence",
+ "ReachingDefinitions",
"Statement",
+ "StatementDefUse",
+ "analyze_file",
+ "analyze_function",
"build_cfg",
"build_cfgs_for_file",
+ "compute_def_use",
+ "compute_reaching",
+ "get_defuse_dialect",
"is_flagged",
"is_flagged_function",
]
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/analyze.py b/packages/core/src/repowise/core/analysis/health/dataflow/analyze.py
new file mode 100644
index 000000000..874db0408
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/analyze.py
@@ -0,0 +1,159 @@
+"""End-to-end dataflow analysis: CFG + def/use + reaching definitions.
+
+The public entry points compose the three language-agnostic stages (CFG build,
+def/use aggregation, reaching-definitions fixpoint) behind a single call,
+dispatching the only language-specific piece -- the def/use dialect -- through
+the registry. :func:`analyze_function` runs one function; :func:`analyze_file`
+applies the same flagged-only gate as the CFG harness so the pass stays within
+budget, building full dataflow only for functions a structural biomarker already
+flagged.
+
+Every failure mode degrades to silence: an unmapped language (no dialect),
+a CFG size-guard trip, or a non-converged fixpoint yields no analysis for that
+function, never a raise.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import structlog
+
+from ..complexity.ast_utils import _collect_function_nodes, _find_function_entry_name
+from .cfg import CFG, CFGGuardTrippedError, build_cfg
+from .defuse import FunctionDefUse, compute_def_use
+from .dialects.base import get_defuse_dialect
+from .gating import is_flagged
+from .parsing import function_metrics, parse_source
+from .reaching import ReachingDefinitions, compute_reaching
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+ from ..complexity.languages import LanguageNodeMap
+
+log = structlog.get_logger(__name__)
+
+
+@dataclass
+class FunctionAnalysis:
+ """A function's CFG, def/use facts, and reaching definitions."""
+
+ name: str
+ start_line: int # 1-indexed
+ end_line: int # 1-indexed
+ ccn: int
+ nloc: int
+ cfg: CFG
+ def_use: FunctionDefUse
+ reaching: ReachingDefinitions
+
+
+@dataclass
+class FileAnalysisStats:
+ """Counters proving the flagged-only gate held over a file."""
+
+ functions_seen: int = 0
+ functions_analyzed: int = 0
+ guard_tripped: int = 0
+ not_converged: int = 0
+
+
+@dataclass
+class FileAnalysisResult:
+ functions: list[FunctionAnalysis] = field(default_factory=list)
+ stats: FileAnalysisStats = field(default_factory=FileAnalysisStats)
+
+
+def analyze_function(
+ fn_node: Node,
+ language: str,
+ lmap: LanguageNodeMap,
+) -> tuple[CFG, FunctionDefUse, ReachingDefinitions] | None:
+ """Build CFG + def/use + reaching definitions for one function node.
+
+ Returns ``None`` when the language has no def/use dialect, the CFG size
+ guard trips, or the fixpoint fails to converge (degrade to silence).
+ """
+ dialect = get_defuse_dialect(language)
+ if dialect is None:
+ return None
+ try:
+ cfg = build_cfg(fn_node, lmap)
+ except CFGGuardTrippedError:
+ return None
+ def_use = compute_def_use(cfg, fn_node, lmap, dialect)
+ reaching = compute_reaching(cfg, def_use)
+ if not reaching.converged:
+ return None
+ return cfg, def_use, reaching
+
+
+def analyze_file(
+ abs_path: str,
+ language: str,
+ source: bytes,
+ *,
+ flagged_only: bool = True,
+) -> FileAnalysisResult:
+ """Parse *source* once and run full dataflow analysis on flagged functions.
+
+ Mirrors :func:`gating.build_cfgs_for_file` but carries the analysis through
+ def/use and reaching definitions. Returns an empty result (never raises) on
+ any parse failure or unmapped language.
+ """
+ result = FileAnalysisResult()
+ parsed = parse_source(abs_path, language, source)
+ if parsed is None:
+ return result
+ root, lmap = parsed
+
+ dialect = get_defuse_dialect(language)
+ if dialect is None:
+ # No def/use support for this language: count what we saw, build nothing.
+ result.stats.functions_seen = len(_collect_function_nodes(root, lmap))
+ return result
+
+ for fn_node in _collect_function_nodes(root, lmap):
+ result.stats.functions_seen += 1
+ metrics = function_metrics(fn_node, lmap, source)
+ if metrics is None:
+ continue
+ ccn, nloc = metrics
+
+ if flagged_only and not is_flagged(ccn=ccn, nloc=nloc):
+ continue
+
+ try:
+ cfg = build_cfg(fn_node, lmap)
+ except CFGGuardTrippedError:
+ result.stats.guard_tripped += 1
+ continue
+ except Exception as exc:
+ log.debug("dataflow_analyze_build_failed", path=abs_path, error=str(exc))
+ continue
+
+ cfg.function_name = _find_function_entry_name(fn_node, lmap)
+ cfg.function_start_line = fn_node.start_point[0] + 1
+ def_use = compute_def_use(cfg, fn_node, lmap, dialect)
+ reaching = compute_reaching(cfg, def_use)
+ if not reaching.converged:
+ result.stats.not_converged += 1
+ continue
+
+ result.stats.functions_analyzed += 1
+ result.functions.append(
+ FunctionAnalysis(
+ name=cfg.function_name,
+ start_line=cfg.function_start_line,
+ end_line=fn_node.end_point[0] + 1,
+ ccn=ccn,
+ nloc=nloc,
+ cfg=cfg,
+ def_use=def_use,
+ reaching=reaching,
+ )
+ )
+
+ return result
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/cfg.py b/packages/core/src/repowise/core/analysis/health/dataflow/cfg.py
index 283202c4a..7ba8673ff 100644
--- a/packages/core/src/repowise/core/analysis/health/dataflow/cfg.py
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/cfg.py
@@ -76,6 +76,16 @@ class Statement:
kind: str
start_line: int # 1-indexed
end_line: int # 1-indexed
+ # True when this records a compound construct's *head* (an ``if`` / ``while``
+ # / ``for`` test) rather than a whole simple statement. Downstream def/use
+ # extraction reads only the condition / loop clause for a head, since the
+ # construct's body lives in successor blocks.
+ is_head: bool = False
+ # The originating tree-sitter node, kept for in-memory passes that need to
+ # re-inspect the statement (def/use classification). Excluded from equality
+ # and repr so block serialization and the determinism tests stay stable, and
+ # because nodes are only valid while their parse tree is alive.
+ node: Node | None = field(default=None, compare=False, repr=False)
@dataclass
@@ -218,7 +228,7 @@ class _CFGBuilder:
def _record_stmt(self, block: BasicBlock, node: Node) -> None:
block.statements.append(
- Statement(node.type, node.start_point[0] + 1, node.end_point[0] + 1)
+ Statement(node.type, node.start_point[0] + 1, node.end_point[0] + 1, node=node)
)
def _record_head(self, block: BasicBlock, node: Node) -> None:
@@ -226,7 +236,7 @@ class _CFGBuilder:
cond = node.child_by_field_name("condition")
line = node.start_point[0] + 1
end = (cond.end_point[0] + 1) if cond is not None else line
- block.statements.append(Statement(node.type, line, end))
+ block.statements.append(Statement(node.type, line, end, is_head=True, node=node))
# -- block / clause access ------------------------------------------------
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/defuse.py b/packages/core/src/repowise/core/analysis/health/dataflow/defuse.py
new file mode 100644
index 000000000..609d67755
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/defuse.py
@@ -0,0 +1,111 @@
+"""Per-block def/use aggregation over a function's CFG.
+
+This module is language-agnostic: it walks the CFG's blocks and statements and
+delegates the read-vs-write classification of each statement to the language's
+:class:`DefUseDialect`. The output -- a :class:`Definition` for every write site
+plus the variable reads per block -- is exactly the input the reaching-
+definitions fixpoint (:mod:`reaching`) consumes. Adding a language is a new
+dialect; this orchestration never changes.
+
+A :class:`Definition` is a single write site identified by a stable, ascending
+``index`` (assigned in block-id then statement order) so def sets can be
+represented as integer sets for a fast, deterministic fixpoint.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .dialects.base import Occurrence
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+ from ..complexity.languages import LanguageNodeMap
+ from .cfg import CFG
+ from .dialects.base import BaseDefUseDialect
+
+
+@dataclass(frozen=True)
+class Definition:
+ """One write site: ``var`` assigned at ``line`` inside block ``block_id``.
+
+ ``index`` is a stable per-function ordinal (the def's identity in the
+ reaching-definitions fixpoint). Parameters are definitions too, attributed
+ to the CFG entry block.
+ """
+
+ var: str
+ block_id: int
+ index: int
+ line: int # 1-indexed
+
+
+@dataclass
+class BlockDefUse:
+ """The write sites and variable reads within a single basic block."""
+
+ block_id: int
+ defs: list[Definition] = field(default_factory=list)
+ uses: list[Occurrence] = field(default_factory=list)
+
+
+@dataclass
+class FunctionDefUse:
+ """Def/use facts for a whole function.
+
+ ``blocks`` is keyed by block id; ``definitions`` is every write site ordered
+ by ``index`` (so ``definitions[i].index == i``); ``params`` is the parameter
+ occurrences seeded at the entry block.
+ """
+
+ blocks: dict[int, BlockDefUse]
+ definitions: list[Definition]
+ params: tuple[Occurrence, ...]
+
+ def block(self, block_id: int) -> BlockDefUse | None:
+ return self.blocks.get(block_id)
+
+
+def compute_def_use(
+ cfg: CFG,
+ fn_node: Node,
+ lmap: LanguageNodeMap,
+ dialect: BaseDefUseDialect,
+) -> FunctionDefUse:
+ """Build per-block def/use facts for *cfg* using *dialect*.
+
+ Parameters are seeded as definitions at the entry block; each statement's
+ writes become :class:`Definition` records with ascending indices, and its
+ reads are accumulated per block.
+ """
+ blocks: dict[int, BlockDefUse] = {}
+ definitions: list[Definition] = []
+ counter = 0
+
+ def _add_def(occ: Occurrence, block_id: int) -> None:
+ nonlocal counter
+ bdu = blocks.setdefault(block_id, BlockDefUse(block_id))
+ definition = Definition(var=occ.name, block_id=block_id, index=counter, line=occ.line)
+ counter += 1
+ bdu.defs.append(definition)
+ definitions.append(definition)
+
+ # Parameters reach the body: seed them at the entry block.
+ params = dialect.parameter_defs(fn_node.child_by_field_name("parameters"))
+ blocks.setdefault(cfg.entry_id, BlockDefUse(cfg.entry_id))
+ for occ in params:
+ _add_def(occ, cfg.entry_id)
+
+ for block in cfg.blocks: # ordered by id => deterministic def indices
+ bdu = blocks.setdefault(block.id, BlockDefUse(block.id))
+ for stmt in block.statements:
+ if stmt.node is None:
+ continue
+ sdu = dialect.statement_def_use(stmt.node, lmap, head_only=stmt.is_head)
+ for occ in sdu.defs:
+ _add_def(occ, block.id)
+ bdu.uses.extend(sdu.uses)
+
+ return FunctionDefUse(blocks=blocks, definitions=definitions, params=params)
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/dialects/__init__.py b/packages/core/src/repowise/core/analysis/health/dataflow/dialects/__init__.py
new file mode 100644
index 000000000..d173a7548
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/dialects/__init__.py
@@ -0,0 +1,41 @@
+"""Per-language def/use dialects, aggregated into ``DEFUSE_DIALECTS``.
+
+Adding a language's def/use support is two edits and one new module (mirroring
+``perf/dialects/__init__.py``):
+
+1. drop ``dataflow/dialects/<lang>.py`` exporting a ``DIALECT`` instance,
+2. register it under every ``LanguageTag`` it serves in ``_REGISTER`` below,
+3. add ``assignment_kinds`` / ``augmented_assign_kinds`` / ``local_decl_kinds``
+ to its ``LanguageNodeMap`` in ``complexity/languages.py``.
+
+No edits to ``defuse.py`` or ``reaching.py``. A language absent here => the
+def/use pass is silent for it (no dialect = no signal), the safe default.
+"""
+
+from __future__ import annotations
+
+from . import python as _python
+from .base import (
+ DEFUSE_DIALECTS,
+ BaseDefUseDialect,
+ DefUseDialect,
+ Occurrence,
+ StatementDefUse,
+ get_defuse_dialect,
+)
+
+# (LanguageTag, dialect instance). One dialect can serve several tags. Each
+# key is a ``LanguageTag`` from ``ingestion/models.py``.
+_REGISTER: tuple[tuple[str, BaseDefUseDialect], ...] = (("python", _python.DIALECT),)
+
+for _tag, _dialect in _REGISTER:
+ DEFUSE_DIALECTS[_tag] = _dialect
+
+__all__ = [
+ "DEFUSE_DIALECTS",
+ "BaseDefUseDialect",
+ "DefUseDialect",
+ "Occurrence",
+ "StatementDefUse",
+ "get_defuse_dialect",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/dialects/base.py b/packages/core/src/repowise/core/analysis/health/dataflow/dialects/base.py
new file mode 100644
index 000000000..f09a4f349
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/dialects/base.py
@@ -0,0 +1,177 @@
+"""The ``DefUseDialect`` plugin contract + the ``DEFUSE_DIALECTS`` registry.
+
+The dataflow def/use pass is language-agnostic: every grammar difference lives
+in a ``DefUseDialect``. This mirrors the per-language plugin idiom the rest of
+the pipeline already uses (``perf/dialects/``, ``complexity/languages.py``,
+``resolvers/``, ...) -- one module per language, registered in a dict, zero
+edits to the core (``defuse.py`` / ``reaching.py``) to add one.
+
+A dialect answers exactly one question, in two shapes:
+
+================================ ============================================
+Member What it answers
+================================ ============================================
+``statement_def_use(node, lmap, the variables a single statement *writes*
+``head_only)`` (defs) and *reads* (uses). ``head_only`` is
+ set for a compound construct's head (an
+ ``if`` / ``while`` / ``for`` test) so the
+ dialect inspects only the condition / loop
+ clause, not the body (which lives in other
+ CFG blocks).
+``parameter_defs(params_node)`` the parameter names a function signature
+ binds -- seeded as defs at the CFG entry.
+================================ ============================================
+
+:class:`BaseDefUseDialect` carries the language-agnostic machinery a concrete
+dialect reuses: identifier-name extraction and a member-access / keyword-aware
+*read* collector (so ``obj.attr`` reads ``obj`` but not the member name, and
+``f(key=x)`` reads ``x`` but not the keyword ``key``). A new language subclasses
+it, declares its member-access and keyword node kinds, and implements the
+write-site extraction for its assignment shapes -- typically ~100 lines, and the
+def/use core plus the reaching-definitions fixpoint never change.
+
+Every facet defaults to "no signal": a language with no registered dialect
+produces no def/use and therefore no reaching definitions, the same
+precision-first contract the perf pillar depends on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+ from ...complexity.languages import LanguageNodeMap
+
+
+@dataclass(frozen=True)
+class Occurrence:
+ """One variable reference at a source line: a def or a use of ``name``."""
+
+ name: str
+ line: int # 1-indexed
+
+
+@dataclass(frozen=True)
+class StatementDefUse:
+ """The variables one statement writes (``defs``) and reads (``uses``).
+
+ Order is source order, de-duplication is left to the caller; both are
+ deterministic for a given statement so downstream fixpoints are stable.
+ """
+
+ defs: tuple[Occurrence, ...]
+ uses: tuple[Occurrence, ...]
+
+
+@runtime_checkable
+class DefUseDialect(Protocol):
+ """The contract a per-language def/use dialect satisfies."""
+
+ language: str
+
+ def statement_def_use(
+ self, node: Node, lmap: LanguageNodeMap, *, head_only: bool
+ ) -> StatementDefUse: ...
+
+ def parameter_defs(self, params_node: Node | None) -> tuple[Occurrence, ...]: ...
+
+
+class BaseDefUseDialect:
+ """Shared machinery for concrete dialects.
+
+ Subclasses set :attr:`member_access_kinds` / :attr:`keyword_kinds` (usually
+ sourced from the language's ``LanguageNodeMap``) and implement
+ :meth:`statement_def_use`. The read collector and identifier helpers here
+ are grammar-neutral enough to serve every full-tier language without
+ override.
+ """
+
+ #: Language tag this dialect serves (informational; the registry is the
+ #: source of truth for dispatch).
+ language: str = ""
+
+ #: Node types representing ``receiver.member`` access. When collecting
+ #: reads, only the receiver is a variable; the member name is skipped.
+ member_access_kinds: frozenset[str] = frozenset()
+
+ #: Node types for a keyword / named argument (``f(key=value)``). Only the
+ #: value is a variable read; the keyword name is skipped.
+ keyword_kinds: frozenset[str] = frozenset()
+
+ #: Identifier leaf node types that name a variable.
+ identifier_kinds: frozenset[str] = frozenset({"identifier"})
+
+ # -- identifier helpers ---------------------------------------------------
+
+ def _name(self, node: Node | None) -> str | None:
+ if node is None or node.type not in self.identifier_kinds or node.text is None:
+ return None
+ return node.text.decode("utf-8", "replace")
+
+ def _occ(self, node: Node) -> Occurrence:
+ return Occurrence(
+ name=(node.text or b"").decode("utf-8", "replace"), line=node.start_point[0] + 1
+ )
+
+ # -- read (use) collection ------------------------------------------------
+
+ def collect_reads(self, node: Node | None, out: list[Occurrence]) -> None:
+ """Append every variable *read* under *node* to *out*, in source order.
+
+ Member names (``obj.attr`` -> only ``obj``) and keyword-argument names
+ (``f(key=x)`` -> only ``x``) are not variable reads and are skipped, so
+ the use set stays precision-first. Nested function / lambda bodies are
+ NOT descended into -- their reads belong to a different scope.
+ """
+ if node is None:
+ return
+ t = node.type
+ if t in self.identifier_kinds:
+ out.append(self._occ(node))
+ return
+ if t in self.member_access_kinds:
+ # Only the receiver is a variable read; the member name is not.
+ receiver = node.child_by_field_name("object") or node.child_by_field_name("value")
+ if receiver is not None:
+ self.collect_reads(receiver, out)
+ elif node.named_child_count:
+ self.collect_reads(node.named_children[0], out)
+ return
+ if t in self.keyword_kinds:
+ self.collect_reads(node.child_by_field_name("value"), out)
+ return
+ if self._is_scope_boundary(node):
+ return
+ for child in node.named_children:
+ self.collect_reads(child, out)
+
+ def _is_scope_boundary(self, node: Node) -> bool:
+ """True if *node* opens a nested scope whose reads are not this
+ statement's (a nested function / lambda). Default: never. Subclasses
+ override for their function/lambda node kinds."""
+ return False
+
+ # -- defaults a subclass may override -------------------------------------
+
+ def parameter_defs(self, params_node: Node | None) -> tuple[Occurrence, ...]:
+ """Parameter names bound by a signature, as entry defs. Default: none."""
+ return ()
+
+ def statement_def_use(
+ self, node: Node, lmap: LanguageNodeMap, *, head_only: bool
+ ) -> StatementDefUse: # pragma: no cover - abstract
+ raise NotImplementedError
+
+
+# The registry, populated by ``dialects/__init__.py`` from each language module.
+# Keyed by ``LanguageTag``; a missing key => the def/use pass is silent for that
+# language (no dialect = no signal).
+DEFUSE_DIALECTS: dict[str, BaseDefUseDialect] = {}
+
+
+def get_defuse_dialect(language: str) -> BaseDefUseDialect | None:
+ """Return the def/use dialect for *language*, or ``None`` when unmapped."""
+ return DEFUSE_DIALECTS.get(language)
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/dialects/python.py b/packages/core/src/repowise/core/analysis/health/dataflow/dialects/python.py
new file mode 100644
index 000000000..feab84f6f
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/dialects/python.py
@@ -0,0 +1,198 @@
+"""Python ``DefUseDialect``.
+
+Classifies each identifier in a statement as a write (def) or a read (use).
+Python's write sites are: assignment LHS (``x = ...``), augmented-assignment LHS
+(``x += ...`` -- both read and write), tuple/list unpacking (``a, b = ...``),
+the walrus operator (``(x := ...)``), ``for`` targets (statement and
+comprehension), and ``with ... as`` aliases. Attribute and subscript targets
+(``obj.attr = ...`` / ``arr[i] = ...``) bind no *local* variable, so their base
+identifiers are reads, not defs -- the precision-first choice that keeps reaching
+definitions sound for the locals they actually track.
+
+All grammar specifics live here; the core (``defuse.py`` / ``reaching.py``) and
+the reaching-definitions fixpoint are language-agnostic.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import BaseDefUseDialect, Occurrence, StatementDefUse
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+ from ...complexity.languages import LanguageNodeMap
+
+# Write-site node kinds (kept in lockstep with the Python ``LanguageNodeMap``'s
+# ``assignment_kinds`` / ``augmented_assign_kinds``; declared here so the
+# traversal needs no lmap threading and stays thread-safe under parallel files).
+_ASSIGN_KINDS = frozenset({"assignment"})
+_AUG_KINDS = frozenset({"augmented_assignment"})
+
+# Tuple / list unpacking target containers.
+_TARGET_CONTAINERS = frozenset(
+ {"pattern_list", "tuple_pattern", "list_pattern", "tuple", "list", "expression_list"}
+)
+# Splat targets: ``*rest`` / ``**kw`` on the LHS.
+_SPLAT_TARGETS = frozenset({"list_splat_pattern", "dictionary_splat_pattern", "list_splat"})
+# Subscript target (``arr[i] = ...``) -- not a local def; bases are reads.
+_SUBSCRIPT_KINDS = frozenset({"subscript"})
+# Nested scopes whose identifiers belong to a different function.
+_SCOPE_BOUNDARIES = frozenset({"lambda", "function_definition", "async_function_definition"})
+
+
+class PythonDefUseDialect(BaseDefUseDialect):
+ language = "python"
+ member_access_kinds = frozenset({"attribute"})
+ keyword_kinds = frozenset({"keyword_argument"})
+
+ def _is_scope_boundary(self, node: Node) -> bool:
+ return node.type in _SCOPE_BOUNDARIES
+
+ # -- public contract ------------------------------------------------------
+
+ def statement_def_use(
+ self, node: Node, lmap: LanguageNodeMap, *, head_only: bool
+ ) -> StatementDefUse:
+ defs: list[Occurrence] = []
+ uses: list[Occurrence] = []
+ if head_only:
+ self._head(node, lmap, defs, uses)
+ else:
+ self._process(node, defs, uses)
+ return StatementDefUse(defs=tuple(defs), uses=tuple(uses))
+
+ def parameter_defs(self, params_node: Node | None) -> tuple[Occurrence, ...]:
+ if params_node is None:
+ return ()
+ out: list[Occurrence] = []
+ for child in params_node.named_children:
+ name_node = self._param_name_node(child)
+ if name_node is not None:
+ out.append(self._occ(name_node))
+ return tuple(out)
+
+ # -- head (compound construct condition / loop clause) --------------------
+
+ def _head(
+ self, node: Node, lmap: LanguageNodeMap, defs: list[Occurrence], uses: list[Occurrence]
+ ) -> None:
+ if node.type in lmap.loop_kinds:
+ left = node.child_by_field_name("left")
+ if left is not None: # for-style loop: ``for <target> in <iterable>``
+ self._targets(left, defs, uses)
+ self._process(node.child_by_field_name("right"), defs, uses)
+ else: # while-style loop: condition only
+ self._process(node.child_by_field_name("condition"), defs, uses)
+ elif node.type in lmap.branch_kinds:
+ self._process(node.child_by_field_name("condition"), defs, uses)
+ else:
+ self._process(node, defs, uses)
+
+ # -- the unified expression / statement walk ------------------------------
+
+ def _process(self, node: Node | None, defs: list[Occurrence], uses: list[Occurrence]) -> None:
+ """Walk *node*, recording defs at write-sites and uses at reads.
+
+ Handles every Python write-site wherever it nests (so a walrus or a
+ comprehension target inside an expression is captured), treats member
+ access and keyword names as non-variables, and does not descend into a
+ nested function / lambda (a different scope).
+ """
+ if node is None:
+ return
+ t = node.type
+ if t in _ASSIGN_KINDS:
+ self._targets(node.child_by_field_name("left"), defs, uses)
+ self.collect_reads(node.child_by_field_name("type"), uses) # annotation
+ self._process(node.child_by_field_name("right"), defs, uses)
+ return
+ if t in _AUG_KINDS:
+ left = node.child_by_field_name("left")
+ self._targets(left, defs, uses) # write
+ self.collect_reads(left, uses) # ...and read (read-modify-write)
+ self._process(node.child_by_field_name("right"), defs, uses)
+ return
+ if t == "named_expression": # walrus ``x := value``
+ self._targets(node.child_by_field_name("name"), defs, uses)
+ self._process(node.child_by_field_name("value"), defs, uses)
+ return
+ if t == "for_in_clause": # comprehension ``for <target> in <iter>``
+ self._targets(node.child_by_field_name("left"), defs, uses)
+ self._process(node.child_by_field_name("right"), defs, uses)
+ return
+ if t == "with_item":
+ self._with_item(node, defs, uses)
+ return
+ if t in self.member_access_kinds:
+ self.collect_reads(node, uses) # receiver is a read; member is not
+ return
+ if t in self.keyword_kinds:
+ self._process(node.child_by_field_name("value"), defs, uses)
+ return
+ if t in self.identifier_kinds:
+ uses.append(self._occ(node))
+ return
+ if self._is_scope_boundary(node):
+ return
+ for child in node.named_children:
+ self._process(child, defs, uses)
+
+ def _with_item(self, node: Node, defs: list[Occurrence], uses: list[Occurrence]) -> None:
+ value = node.child_by_field_name("value")
+ if value is not None and value.type == "as_pattern":
+ # ``ctx() as name`` -> the context expression is a read, the alias a def.
+ named = value.named_children
+ if named:
+ self._process(named[0], defs, uses)
+ self._targets(value.child_by_field_name("alias"), defs, uses)
+ else:
+ self._process(value, defs, uses)
+
+ # -- write-target extraction ----------------------------------------------
+
+ def _targets(self, node: Node | None, defs: list[Occurrence], uses: list[Occurrence]) -> None:
+ """Record the plain-local write targets in an assignment LHS.
+
+ A bare identifier (or one nested in tuple/list unpacking or a splat) is a
+ def. An attribute or subscript target binds no local, so its base
+ identifiers are recorded as reads instead.
+ """
+ if node is None:
+ return
+ t = node.type
+ if t in self.identifier_kinds:
+ defs.append(self._occ(node))
+ return
+ if t in _TARGET_CONTAINERS or t in _SPLAT_TARGETS:
+ for child in node.named_children:
+ self._targets(child, defs, uses)
+ return
+ if t in self.member_access_kinds or t in _SUBSCRIPT_KINDS:
+ self.collect_reads(node, uses)
+ return
+ if t == "as_pattern_target":
+ for child in node.named_children:
+ self._targets(child, defs, uses)
+ return
+ # parenthesized / typed target wrappers: descend.
+ for child in node.named_children:
+ self._targets(child, defs, uses)
+
+ # -- parameter-name extraction --------------------------------------------
+
+ def _param_name_node(self, node: Node) -> Node | None:
+ if node.type in self.identifier_kinds:
+ return node
+ named = node.child_by_field_name("name")
+ if named is not None and named.type in self.identifier_kinds:
+ return named
+ # typed_parameter / splat: first identifier descendant.
+ for child in node.named_children:
+ if child.type in self.identifier_kinds:
+ return child
+ return None
+
+
+DIALECT = PythonDefUseDialect()
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/gating.py b/packages/core/src/repowise/core/analysis/health/dataflow/gating.py
index d55027699..65c7a7cfb 100644
--- a/packages/core/src/repowise/core/analysis/health/dataflow/gating.py
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/gating.py
@@ -25,10 +25,8 @@ import structlog
from ..biomarkers.complex_method import ComplexMethodDetector
from ..biomarkers.large_method import LargeMethodDetector
from ..complexity.ast_utils import _collect_function_nodes, _find_function_entry_name
-from ..complexity.cyclomatic import _walk_function_body
-from ..complexity.languages import get_language_map
-from ..complexity.nloc import _count_nloc
from .cfg import CFG, CFGGuardTrippedError, build_cfg
+from .parsing import function_metrics, parse_source
log = structlog.get_logger(__name__)
@@ -112,38 +110,17 @@ def build_cfgs_for_file(
default and the only production-intended mode is ``True``.
"""
result = FileCFGResult()
- lmap = get_language_map(language)
- if lmap is None:
+ parsed = parse_source(abs_path, language, source)
+ if parsed is None:
return result
+ root, lmap = parsed
- try:
- from tree_sitter import Parser
-
- from repowise.core.ingestion.parser import _get_language
- except Exception as exc:
- log.debug("dataflow_cfg_import_failed", error=str(exc))
- return result
-
- grammar = _get_language(language)
- if grammar is None:
- return result
-
- try:
- parser = Parser(grammar)
- tree = parser.parse(source)
- except Exception as exc:
- log.debug("dataflow_cfg_parse_failed", path=abs_path, error=str(exc))
- return result
-
- for fn_node in _collect_function_nodes(tree.root_node, lmap):
+ for fn_node in _collect_function_nodes(root, lmap):
result.stats.functions_seen += 1
- body = fn_node.child_by_field_name("body") or fn_node
- try:
- ccn, _max_nest, _cog, _bumps, _conds = _walk_function_body(body, lmap)
- nloc = _count_nloc(body, source)
- except Exception as exc:
- log.debug("dataflow_cfg_metrics_failed", path=abs_path, error=str(exc))
+ metrics = function_metrics(fn_node, lmap, source)
+ if metrics is None:
continue
+ ccn, nloc = metrics
if flagged_only and not is_flagged(ccn=ccn, nloc=nloc):
continue
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/parsing.py b/packages/core/src/repowise/core/analysis/health/dataflow/parsing.py
new file mode 100644
index 000000000..5e18f4460
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/parsing.py
@@ -0,0 +1,70 @@
+"""Shared parse + per-function metric helpers for the dataflow harnesses.
+
+Both the CFG-only harness (:mod:`gating`) and the full def/use + reaching
+harness (:mod:`analyze`) need to parse a file once and compute the two cheap
+metrics the flagged-only gate keys on (``ccn`` and ``nloc``). Centralising the
+fragile lazy-import + parse here keeps that error handling in one place and the
+two harnesses thin. Every helper degrades to ``None`` on failure, never raising.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import structlog
+
+from ..complexity.cyclomatic import _walk_function_body
+from ..complexity.languages import LanguageNodeMap, get_language_map
+from ..complexity.nloc import _count_nloc
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+log = structlog.get_logger(__name__)
+
+
+def parse_source(
+ abs_path: str, language: str, source: bytes
+) -> tuple[Node, LanguageNodeMap] | None:
+ """Parse *source* once. Returns ``(root_node, lmap)`` or ``None``.
+
+ ``None`` when the language is unsupported, the tree-sitter pack is missing,
+ or parsing fails -- the same degrade-to-silence contract the walker uses.
+ """
+ lmap = get_language_map(language)
+ if lmap is None:
+ return None
+
+ try:
+ from tree_sitter import Parser
+
+ from repowise.core.ingestion.parser import _get_language
+ except Exception as exc:
+ log.debug("dataflow_import_failed", error=str(exc))
+ return None
+
+ grammar = _get_language(language)
+ if grammar is None:
+ return None
+
+ try:
+ parser = Parser(grammar)
+ tree = parser.parse(source)
+ except Exception as exc:
+ log.debug("dataflow_parse_failed", path=abs_path, error=str(exc))
+ return None
+
+ return tree.root_node, lmap
+
+
+def function_metrics(fn_node: Node, lmap: LanguageNodeMap, source: bytes) -> tuple[int, int] | None:
+ """Return ``(ccn, nloc)`` for *fn_node*, or ``None`` if metric extraction
+ fails (so the caller can skip the function)."""
+ body = fn_node.child_by_field_name("body") or fn_node
+ try:
+ ccn, _max_nest, _cog, _bumps, _conds = _walk_function_body(body, lmap)
+ nloc = _count_nloc(body, source)
+ except Exception as exc:
+ log.debug("dataflow_metrics_failed", error=str(exc))
+ return None
+ return ccn, nloc
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/reaching.py b/packages/core/src/repowise/core/analysis/health/dataflow/reaching.py
new file mode 100644
index 000000000..740f8f16d
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/reaching.py
@@ -0,0 +1,128 @@
+"""Reaching-definitions fixpoint over a function CFG.
+
+A classic forward, may-analysis worklist dataflow, fully language-agnostic: it
+needs only the CFG shape (:mod:`cfg`) and the per-block def facts
+(:mod:`defuse`). For each program point it computes which definitions (write
+sites) may reach it along some path.
+
+Per block ``b`` with predecessors ``pred(b)``::
+
+ GEN[b] = the last definition of each variable written in b
+ KILL[b] = every definition of any variable b writes, except GEN[b]
+ IN[b] = union over p in pred(b) of OUT[p]
+ OUT[b] = GEN[b] union (IN[b] minus KILL[b])
+
+Definition sets are integer sets keyed by :attr:`defuse.Definition.index`, so
+the lattice is finite and the worklist always converges in a bounded number of
+rounds. A convergence guard caps the iterations anyway and reports
+``converged=False`` if it is ever tripped, so a pathological input degrades to
+silence (the caller drops the result) rather than spinning.
+
+The result is deterministic: identical CFG + def facts yield identical IN/OUT
+sets regardless of worklist scheduling.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from .cfg import CFG
+ from .defuse import Definition, FunctionDefUse
+
+
+@dataclass
+class ReachingDefinitions:
+ """IN / OUT reaching-definition sets per block (def indices).
+
+ ``definitions`` is the function's write sites (index-aligned), so a def
+ index can be resolved back to its variable and line. ``converged`` is False
+ only when the iteration guard tripped, in which case the sets are partial
+ and the caller should treat the function as having no signal.
+ """
+
+ in_sets: dict[int, frozenset[int]]
+ out_sets: dict[int, frozenset[int]]
+ definitions: list[Definition]
+ converged: bool = True
+
+ def reaching_in(self, block_id: int) -> list[Definition]:
+ """Definitions reaching the *start* of *block_id*, ordered by index."""
+ idx = self.in_sets.get(block_id, frozenset())
+ return [self.definitions[i] for i in sorted(idx)]
+
+ def reaching_out(self, block_id: int) -> list[Definition]:
+ """Definitions reaching the *end* of *block_id*, ordered by index."""
+ idx = self.out_sets.get(block_id, frozenset())
+ return [self.definitions[i] for i in sorted(idx)]
+
+
+def compute_reaching(
+ cfg: CFG,
+ fdu: FunctionDefUse,
+ *,
+ max_iterations: int | None = None,
+) -> ReachingDefinitions:
+ """Run the reaching-definitions fixpoint over *cfg* with *fdu*'s def facts."""
+ # All definitions of each variable -> the KILL sets.
+ defs_by_var: dict[str, set[int]] = {}
+ for d in fdu.definitions:
+ defs_by_var.setdefault(d.var, set()).add(d.index)
+
+ gen: dict[int, frozenset[int]] = {}
+ kill: dict[int, frozenset[int]] = {}
+ for block in cfg.blocks:
+ bdu = fdu.block(block.id)
+ block_defs = bdu.defs if bdu is not None else []
+ # GEN: the last definition of each variable written in this block.
+ last_per_var: dict[str, int] = {}
+ for d in block_defs:
+ last_per_var[d.var] = d.index
+ gen_b = frozenset(last_per_var.values())
+ killed: set[int] = set()
+ for var in last_per_var:
+ killed |= defs_by_var.get(var, set())
+ gen[block.id] = gen_b
+ kill[block.id] = frozenset(killed) - gen_b
+
+ in_sets: dict[int, frozenset[int]] = {b.id: frozenset() for b in cfg.blocks}
+ out_sets: dict[int, frozenset[int]] = {b.id: gen[b.id] for b in cfg.blocks}
+
+ # A finite may-analysis converges in O(blocks) rounds; the cap is generous
+ # and only a pathological CFG could trip it (-> degrade to silence).
+ cap = max_iterations if max_iterations is not None else (len(cfg.blocks) + 2) ** 2 + 16
+ worklist: deque[int] = deque(b.id for b in cfg.blocks)
+ queued = {b.id for b in cfg.blocks}
+ iterations = 0
+ converged = True
+
+ while worklist:
+ if iterations > cap:
+ converged = False
+ break
+ iterations += 1
+ bid = worklist.popleft()
+ queued.discard(bid)
+ block = cfg.block(bid)
+
+ in_b: frozenset[int] = frozenset()
+ for pred in block.predecessors:
+ in_b |= out_sets[pred]
+ in_sets[bid] = in_b
+
+ out_b = gen[bid] | (in_b - kill[bid])
+ if out_b != out_sets[bid]:
+ out_sets[bid] = out_b
+ for succ in block.successors:
+ if succ not in queued:
+ worklist.append(succ)
+ queued.add(succ)
+
+ return ReachingDefinitions(
+ in_sets=in_sets,
+ out_sets=out_sets,
+ definitions=fdu.definitions,
+ converged=converged,
+ )
diff --git a/tests/unit/health/test_dataflow_reaching.py b/tests/unit/health/test_dataflow_reaching.py
new file mode 100644
index 000000000..b41d7b0ca
--- /dev/null
+++ b/tests/unit/health/test_dataflow_reaching.py
@@ -0,0 +1,373 @@
+"""Unit tests for the dataflow def/use + reaching-definitions pass.
+
+Best-effort like the complexity-walker tests: each test skips when the Python
+tree-sitter pack is missing rather than failing.
+"""
+
+from __future__ import annotations
+
+import textwrap
+
+import pytest
+
+from repowise.core.analysis.health.complexity.ast_utils import _collect_function_nodes
+from repowise.core.analysis.health.complexity.languages import get_language_map
+from repowise.core.analysis.health.dataflow import (
+ analyze_file,
+ analyze_function,
+ compute_def_use,
+ compute_reaching,
+)
+from repowise.core.analysis.health.dataflow.dialects.base import get_defuse_dialect
+
+
+def _require_python() -> None:
+ try:
+ from repowise.core.ingestion.parser import _get_language
+ except Exception:
+ pytest.skip("tree-sitter language pack missing for python")
+ if _get_language("python") is None:
+ pytest.skip("tree-sitter language pack missing for python")
+
+
+def _first_fn(src: str):
+ _require_python()
+ from tree_sitter import Parser
+
+ from repowise.core.ingestion.parser import _get_language
+
+ lmap = get_language_map("python")
+ parser = Parser(_get_language("python"))
+ tree = parser.parse(textwrap.dedent(src).encode())
+ nodes = _collect_function_nodes(tree.root_node, lmap)
+ assert nodes, "no function node parsed"
+ return nodes[0], lmap
+
+
+def _analyze(src: str):
+ fn_node, lmap = _first_fn(src)
+ out = analyze_function(fn_node, "python", lmap)
+ assert out is not None, "analysis returned None"
+ return out # (cfg, def_use, reaching)
+
+
+def _def_use_names(src: str) -> tuple[set[str], set[str]]:
+ """All def and use variable names across the function (params included)."""
+ _cfg, def_use, _reaching = _analyze(src)
+ defs = {d.var for d in def_use.definitions}
+ uses = {u.name for bdu in def_use.blocks.values() for u in bdu.uses}
+ return defs, uses
+
+
+# -- def/use classification -----------------------------------------------------
+
+
+def test_simple_assignment():
+ defs, uses = _def_use_names(
+ """
+ def f(a):
+ x = a + 1
+ return x
+ """
+ )
+ assert "x" in defs
+ assert "a" in uses
+
+
+def test_augmented_assignment_is_def_and_use():
+ defs, uses = _def_use_names(
+ """
+ def f(a):
+ x = 0
+ x += a
+ return x
+ """
+ )
+ assert "x" in defs
+ # x is read in ``x += a`` (read-modify-write) and a is read.
+ assert "x" in uses
+ assert "a" in uses
+
+
+def test_tuple_unpacking_defines_all_targets():
+ defs, _uses = _def_use_names(
+ """
+ def f(pair):
+ a, b = pair
+ return a + b
+ """
+ )
+ assert {"a", "b"} <= defs
+
+
+def test_for_target_is_def_iterable_is_use():
+ _cfg, def_use, _r = _analyze(
+ """
+ def f(items):
+ total = 0
+ for x in items:
+ total += x
+ return total
+ """
+ )
+ defs = {d.var for d in def_use.definitions}
+ uses = {u.name for bdu in def_use.blocks.values() for u in bdu.uses}
+ assert "x" in defs # the for-target is a def
+ assert "items" in uses # the iterable is a use
+
+
+def test_with_as_alias_is_def():
+ defs, uses = _def_use_names(
+ """
+ def f(path):
+ with open(path) as fh:
+ data = fh.read()
+ return data
+ """
+ )
+ assert "fh" in defs
+ assert "path" in uses # the context expression is a use
+
+
+def test_walrus_is_def():
+ defs, _uses = _def_use_names(
+ """
+ def f(a):
+ if (n := compute(a)) > 0:
+ return n
+ return 0
+ """
+ )
+ assert "n" in defs
+
+
+def test_comprehension_target_is_def():
+ defs, uses = _def_use_names(
+ """
+ def f(source):
+ data = [v * 2 for v in source if v > 0]
+ return data
+ """
+ )
+ assert {"data", "v"} <= defs
+ assert "source" in uses
+
+
+def test_parameters_are_defs():
+ _cfg, def_use, _r = _analyze(
+ """
+ def f(a, b=1, *args, **kw):
+ return a
+ """
+ )
+ param_names = {o.name for o in def_use.params}
+ assert {"a", "b", "args", "kw"} <= param_names
+
+
+def test_attribute_and_subscript_targets_are_not_local_defs():
+ defs, uses = _def_use_names(
+ """
+ def f(obj, arr, i, v):
+ obj.attr = v
+ arr[i] = v
+ return obj
+ """
+ )
+ # No local named ``attr`` is defined; the bases / indices are reads.
+ assert "attr" not in defs
+ assert {"obj", "arr", "i", "v"} <= uses
+
+
+def test_member_and_keyword_names_are_not_uses():
+ _cfg, def_use, _r = _analyze(
+ """
+ def f(client, x):
+ y = client.fetch(timeout=x)
+ return y
+ """
+ )
+ uses = {u.name for bdu in def_use.blocks.values() for u in bdu.uses}
+ assert "client" in uses
+ assert "x" in uses
+ # ``fetch`` is a member name and ``timeout`` a keyword name -> not variables.
+ assert "fetch" not in uses
+ assert "timeout" not in uses
+
+
+# -- reaching definitions -------------------------------------------------------
+
+
+def _reaching_vars_at_exit(src: str) -> list[tuple[str, int]]:
+ cfg, _def_use, reaching = _analyze(src)
+ return [(d.var, d.line) for d in reaching.reaching_in(cfg.exit_id)]
+
+
+def test_both_branch_defs_reach_join():
+ cfg, _du, reaching = _analyze(
+ """
+ def f(c):
+ if c:
+ y = 1
+ else:
+ y = 2
+ return y
+ """
+ )
+ # At the return (which precedes exit), both definitions of y reach.
+ reaching_y = [d for d in reaching.reaching_in(cfg.exit_id) if d.var == "y"]
+ assert len(reaching_y) == 2
+
+
+def test_redefinition_kills_earlier_def():
+ cfg, _du, reaching = _analyze(
+ """
+ def f(a):
+ x = a
+ x = a + 1
+ return x
+ """
+ )
+ # Only the second definition of x reaches the end (straight-line kill).
+ reaching_x = [d for d in reaching.reaching_in(cfg.exit_id) if d.var == "x"]
+ assert len(reaching_x) == 1
+ assert reaching_x[0].line == 4
+
+
+def test_loop_def_and_preloop_def_both_reach():
+ cfg, _du, reaching = _analyze(
+ """
+ def f(items):
+ total = 0
+ for x in items:
+ total = total + x
+ return total
+ """
+ )
+ # The loop may run zero times, so both the pre-loop total and the in-loop
+ # total reach the return -- a may-analysis keeps both.
+ reaching_total = [d for d in reaching.reaching_in(cfg.exit_id) if d.var == "total"]
+ assert len(reaching_total) == 2
+
+
+def test_parameter_def_reaches_use():
+ cfg, _du, reaching = _analyze(
+ """
+ def f(a):
+ b = 1
+ if a:
+ b = 2
+ return a + b
+ """
+ )
+ # The parameter ``a`` (defined at entry) reaches the return.
+ names = {d.var for d in reaching.reaching_in(cfg.exit_id)}
+ assert "a" in names
+
+
+# -- determinism ----------------------------------------------------------------
+
+
+def test_reaching_is_deterministic():
+ src = """
+ def f(c, items):
+ x = 0
+ for it in items:
+ if it > c:
+ x = x + it
+ else:
+ x = x - it
+ try:
+ check(x)
+ except ValueError:
+ x = 0
+ return x
+ """
+
+ def serialize():
+ _cfg, _du, reaching = _analyze(src)
+ return {
+ bid: sorted((d.var, d.line) for d in reaching.reaching_in(bid))
+ for bid in sorted(reaching.in_sets)
+ }
+
+ first = serialize()
+ for _ in range(3):
+ assert serialize() == first
+
+
+# -- budget / gating ------------------------------------------------------------
+
+
+def test_analyze_file_flagged_only_gate():
+ lines = ["def big(x):", " y = 0"]
+ for i in range(12):
+ lines += [f" if x == {i}:", f" y = {i}"]
+ lines += [" return y", "", "def tiny():", " return 1", ""]
+ result = analyze_file("mem.py", "python", "\n".join(lines).encode())
+ if result.stats.functions_seen == 0:
+ pytest.skip("tree-sitter language pack missing for python")
+ assert result.stats.functions_seen == 2
+ assert result.stats.functions_analyzed == 1
+ assert [fa.name for fa in result.functions] == ["big"]
+ # The analyzed function carries a converged reaching result.
+ assert result.functions[0].reaching.converged
+
+
+def test_convergence_guard_degrades_to_silence():
+ # A tiny iteration cap forces non-convergence; compute_reaching must report
+ # it rather than spin, and the result is then dropped by callers.
+ cfg, def_use, _r = _analyze(
+ """
+ def f(c, items):
+ x = 0
+ for it in items:
+ if c:
+ x = it
+ else:
+ x = x + 1
+ return x
+ """
+ )
+ forced = compute_reaching(cfg, def_use, max_iterations=1)
+ assert forced.converged is False
+
+
+# -- graceful degradation -------------------------------------------------------
+
+
+def test_unmapped_language_returns_none():
+ # A function node parsed as Python but analyzed under a language with no
+ # dialect yields no analysis.
+ fn_node, lmap = _first_fn(
+ """
+ def f(a):
+ return a
+ """
+ )
+ assert get_defuse_dialect("cobol") is None
+ assert analyze_function(fn_node, "cobol", lmap) is None
+
+
+def test_analyze_file_unsupported_language_is_silent():
+ result = analyze_file("x.unknown", "cobol", b"whatever")
+ assert result.functions == []
+ assert result.stats.functions_seen == 0
+
+
+def test_def_use_orchestration_directly():
+ # compute_def_use + compute_reaching can be driven without the file harness.
+ fn_node, lmap = _first_fn(
+ """
+ def f(a):
+ x = a
+ return x
+ """
+ )
+ from repowise.core.analysis.health.dataflow import build_cfg
+
+ dialect = get_defuse_dialect("python")
+ cfg = build_cfg(fn_node, lmap)
+ def_use = compute_def_use(cfg, fn_node, lmap, dialect)
+ reaching = compute_reaching(cfg, def_use)
+ assert reaching.converged
+ assert "x" in {d.var for d in def_use.definitions}