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): detect cross-function io-in-loop / N+1 via call-graph reachability (#532)

Raghav Chamadiya3632c5d2c8a5
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/io_in_loop.py b/packages/core/src/repowise/core/analysis/health/biomarkers/io_in_loop.py
index ed44fedc6..2bab43fe7 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/io_in_loop.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/io_in_loop.py
@@ -1,9 +1,18 @@
-"""IO-in-loop — an execution sink at an I/O boundary inside a loop body.
+"""IO-in-loop — an execution sink at an I/O boundary reached from a loop body.
-The Tier-A core of the ``performance`` dimension: a database round-trip, HTTP
-call, filesystem read, or subprocess spawn that runs **once per loop
-iteration** (the classic N+1 shape). One finding per occurrence, anchored to
-its line and tagged with the boundary kind.
+The core of the ``performance`` dimension: a database round-trip, HTTP call,
+filesystem read, or subprocess spawn that runs **once per loop iteration** (the
+classic N+1 shape). One finding per occurrence, anchored to its line and tagged
+with the boundary kind.
+
+Two cases share this detector and the same ``performance`` budget:
+
+ * **same-function** (Tier A, PR3) — the sink is written directly inside the
+ loop; ``PerfHit.path`` is empty.
+ * **cross-function** (Tier B, PR4) — the loop calls a helper that, within a
+ few call hops, executes the sink; ``PerfHit.path`` carries the resolved
+ ``A -> ... -> sink`` symbol chain for explainability. This is the
+ interprocedural case file-local linters cannot see.
This is a *high-precision, low-recall* signal by design (measured 79% on the
Phase-0 gate, CI 68-87). The precision comes from three constraints enforced
@@ -25,6 +34,7 @@ unsupported languages and parse failures yield nothing, never a false positive.
from __future__ import annotations
+from ..complexity import PerfHit
from ..models import Severity
from .base import BiomarkerResult, FileContext
@@ -49,18 +59,44 @@ class IoInLoopDetector:
if hit.kind != _KIND:
continue
phrasing = _BOUNDARY_PHRASING.get(hit.detail, "an I/O call")
- out.append(
- BiomarkerResult(
- biomarker_type=self.name,
- severity=Severity.MEDIUM,
- function_name=hit.function,
- line_start=hit.line,
- line_end=hit.line,
- details={"boundary_kind": hit.detail},
- reason=f"{phrasing} runs once per loop iteration (N+1 / IO-in-loop)",
+ if hit.path:
+ out.append(self._cross_function(hit, phrasing))
+ else:
+ out.append(
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=Severity.MEDIUM,
+ function_name=hit.function,
+ line_start=hit.line,
+ line_end=hit.line,
+ details={"boundary_kind": hit.detail, "cross_function": False},
+ reason=f"{phrasing} runs once per loop iteration (N+1 / IO-in-loop)",
+ )
)
- )
return out
+ @staticmethod
+ def _cross_function(hit: PerfHit, phrasing: str) -> BiomarkerResult:
+ # Render the resolved symbol chain (``file.py::A`` -> ...) as bare
+ # function names for the reason, and keep the full path in details.
+ names = [seg.rsplit("::", 1)[-1] for seg in hit.path]
+ chain = " -> ".join(names)
+ return BiomarkerResult(
+ biomarker_type=_KIND,
+ severity=Severity.MEDIUM,
+ function_name=hit.function,
+ line_start=hit.line,
+ line_end=hit.line,
+ details={
+ "boundary_kind": hit.detail,
+ "cross_function": True,
+ "path": list(hit.path),
+ },
+ reason=(
+ f"{phrasing} is reached once per loop iteration through "
+ f"{chain} (cross-function N+1)"
+ ),
+ )
+
BIOMARKER = IoInLoopDetector()
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/__init__.py b/packages/core/src/repowise/core/analysis/health/complexity/__init__.py
index 555dca087..61fc7b32c 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/__init__.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/__init__.py
@@ -8,6 +8,7 @@ from .walker import (
ErrorHandlingHit,
FileComplexity,
FunctionComplexity,
+ PerfFnFacts,
PerfHit,
walk_file,
walk_file_complexity,
@@ -19,6 +20,7 @@ __all__ = [
"ErrorHandlingHit",
"FileComplexity",
"FunctionComplexity",
+ "PerfFnFacts",
"PerfHit",
"walk_file",
"walk_file_complexity",
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/walker.py b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
index e56a69cd2..43ba31ff5 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -163,6 +163,40 @@ class PerfHit:
line: int # 1-indexed
function: str | None = None
detail: str = ""
+ # Reachability path for a cross-function hit: the resolved symbol-node
+ # chain ``A -> B -> ... -> sink`` (PR4). Empty for same-function hits —
+ # its emptiness is what distinguishes the two cases downstream.
+ path: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PerfFnFacts:
+ """Per-function facts the cross-function perf bridge needs (PR4).
+
+ Collected on the same whole-tree perf pass as ``PerfHit``. Two signals:
+
+ - ``loop_call_targets`` — the rightmost names of calls made inside a loop
+ body that are NOT themselves a direct I/O sink (those are already a
+ same-function ``io_in_loop`` hit). Each is a candidate helper whose body
+ might reach a sink transitively — the entry points of the reachability
+ walk.
+ - ``bare_sink_kind`` — the boundary kind of an I/O sink this function
+ executes at ``loop_depth 0`` (its own top level, not nested in a loop),
+ else ``None``. A function with a bare sink is a *reachability target*:
+ when a loop in another function calls into it, that sink runs once per
+ iteration. The ``loop_depth 0`` requirement is deliberate — a sink the
+ function runs inside its own loop is already counted there.
+
+ ``func_start`` is the 1-indexed line of the enclosing function's ``def``
+ (0 for module scope, which maps to the synthetic ``::__module__`` node);
+ the bridge resolves it to a graph symbol node by line containment.
+ """
+
+ function: str | None
+ func_start: int
+ # ``(callee_name, call_line)`` pairs for the loop-nested non-sink calls.
+ loop_call_targets: tuple[tuple[str, int], ...]
+ bare_sink_kind: str | None
@dataclass
@@ -187,6 +221,11 @@ class FileComplexity:
# boundary kind (db / network / filesystem / subprocess / lock). The
# per-file import bridge; PR4's cross-function reachability consumes it.
io_boundary_names: dict[str, str] = field(default_factory=dict)
+ # Per-function facts feeding PR4's cross-function N+1 detection: which
+ # callees each function invokes inside a loop body, and whether the
+ # function holds a bare (non-loop) I/O sink. Empty when the language opts
+ # out of the perf pass. Consumed by ``perf.crossfn``, not by a biomarker.
+ perf_fn_facts: list[PerfFnFacts] = field(default_factory=list)
# Leaf node types that carry a declared name at the bottom of a C/C++
@@ -1078,17 +1117,23 @@ def _is_string_concat(node: Node, language: str) -> bool:
def _collect_perf_hits(
root: Node, language: str, lmap: LanguageNodeMap
-) -> tuple[list[PerfHit], dict[str, str]]:
- """Whole-tree perf pass → ``(hits, io_boundary_names)``.
-
- Iterative DFS carrying ``(node, loop_depth, in_async, func_name)`` — the
- proven Phase-0 shape. Loop-body scoping and constant-loop skipping are
- applied so only genuinely per-iteration calls are flagged. Returns no hits
- for languages that opt out of the perf pass (empty ``call_kinds``).
+) -> tuple[list[PerfHit], dict[str, str], list[PerfFnFacts]]:
+ """Whole-tree perf pass → ``(hits, io_boundary_names, fn_facts)``.
+
+ Iterative DFS carrying ``(node, loop_depth, in_async, func_name,
+ func_start)`` — the proven Phase-0 shape, extended with the enclosing
+ function's start line so per-function facts can be keyed to a graph symbol
+ node. Loop-body scoping and constant-loop skipping are applied so only
+ genuinely per-iteration calls are flagged. Returns nothing for languages
+ that opt out of the perf pass (empty ``call_kinds``).
+
+ Alongside the same-function ``hits``, it accumulates ``fn_facts`` (one
+ :class:`PerfFnFacts` per enclosing function that has any loop-nested call
+ or a bare sink) — the input to PR4's cross-function reachability.
"""
call_kinds = lmap.call_kinds
if not call_kinds:
- return [], {}
+ return [], {}, []
io_names = collect_io_names(root, language)
has_db_import = any(k == "db" for k in io_names.values())
@@ -1099,10 +1144,21 @@ def _collect_perf_hits(
async_fn_kinds = lmap.async_function_kinds
hits: list[PerfHit] = []
- # (node, loop_depth, in_async, func_name)
- stack: list[tuple[Node, int, bool, str | None]] = [(root, 0, False, None)]
+ # Per-enclosing-function accumulators keyed by the function's start line
+ # (0 = module scope). ``(name, loop_targets{name->min line}, [bare_sink])``.
+ fn_acc: dict[int, tuple[str | None, dict[str, int], list[str | None]]] = {}
+
+ def _acc(func_start: int, func_name: str | None) -> tuple[dict[str, int], list[str | None]]:
+ entry = fn_acc.get(func_start)
+ if entry is None:
+ entry = (func_name, {}, [None])
+ fn_acc[func_start] = entry
+ return entry[1], entry[2]
+
+ # (node, loop_depth, in_async, func_name, func_start)
+ stack: list[tuple[Node, int, bool, str | None, int]] = [(root, 0, False, None, 0)]
while stack:
- node, loop_depth, in_async, func_name = stack.pop()
+ node, loop_depth, in_async, func_name, func_start = stack.pop()
t = node.type
is_loop = t in loop_kinds
@@ -1113,8 +1169,10 @@ def _collect_perf_hits(
is_async_fn = t in async_fn_kinds or (entering_fn and _has_async_modifier(node))
next_async = True if is_async_fn else (False if entering_fn else in_async)
next_func = func_name
+ next_start = func_start
if t in fn_kinds:
next_func = _perf_func_name(node) or func_name
+ next_start = node.start_point[0] + 1
if t in call_kinds:
method = _callee_method_name(node) or ""
@@ -1122,18 +1180,31 @@ def _collect_perf_hits(
parent = node.parent
awaited = parent is not None and "await" in parent.type
line = node.start_point[0] + 1
+ kind = classify_call_sink(
+ language,
+ root_name,
+ method,
+ awaited=awaited,
+ is_attribute=_callee_is_attribute(node),
+ io_names=io_names,
+ has_db_import=has_db_import,
+ )
if loop_depth >= 1:
- kind = classify_call_sink(
- language,
- root_name,
- method,
- awaited=awaited,
- is_attribute=_callee_is_attribute(node),
- io_names=io_names,
- has_db_import=has_db_import,
- )
if kind is not None:
hits.append(PerfHit("io_in_loop", line, next_func, kind))
+ elif method:
+ # A loop-nested call to a non-sink helper: a candidate
+ # entry for cross-function reachability (PR4). Keep the
+ # first line we see the helper called at, for the finding.
+ targets = _acc(next_start, next_func)[0]
+ if method not in targets:
+ targets[method] = line
+ elif kind is not None:
+ # A sink at loop_depth 0 makes this function a reachability
+ # target: a loop elsewhere calling into it runs the sink N times.
+ sink_slot = _acc(next_start, next_func)[1]
+ if sink_slot[0] is None:
+ sink_slot[0] = kind
if is_py and in_async and not awaited:
api = _blocking_sync_api(root_name, method)
if api is not None:
@@ -1150,13 +1221,13 @@ def _collect_perf_hits(
# with ``==`` (identity by tree + byte range), never ``is``.
for c in node.children:
cd = loop_depth + 1 if c == body else loop_depth
- stack.append((c, cd, next_async, next_func))
+ stack.append((c, cd, next_async, next_func, next_start))
else:
for c in node.children:
- stack.append((c, loop_depth + 1, next_async, next_func))
+ stack.append((c, loop_depth + 1, next_async, next_func, next_start))
else:
for c in node.children:
- stack.append((c, loop_depth, next_async, next_func))
+ stack.append((c, loop_depth, next_async, next_func, next_start))
# Dedup chained sinks: ``result.scalars().all()`` parses as two call nodes
# on one line (the ``.scalars()`` sink and the ``.all()`` materializer) —
@@ -1170,7 +1241,19 @@ def _collect_perf_hits(
seen.add(key)
deduped.append(h)
deduped.sort(key=lambda h: (h.line, h.kind))
- return deduped, io_names
+
+ fn_facts = [
+ PerfFnFacts(
+ function=name,
+ func_start=start,
+ loop_call_targets=tuple(sorted(targets.items())),
+ bare_sink_kind=sink[0],
+ )
+ for start, (name, targets, sink) in fn_acc.items()
+ if targets or sink[0] is not None
+ ]
+ fn_facts.sort(key=lambda f: f.func_start)
+ return deduped, io_names, fn_facts
# ----------------------------------------------------------------------
@@ -1465,7 +1548,7 @@ def walk_file(
fc_by_node_id[fn_node.id] = fc
classes = _collect_classes(tree.root_node, lmap, source, fc_by_node_id)
- perf_hits, io_boundary_names = _collect_perf_hits(tree.root_node, language, lmap)
+ perf_hits, io_boundary_names, perf_fn_facts = _collect_perf_hits(tree.root_node, language, lmap)
return FileComplexity(
functions=functions,
classes=classes,
@@ -1473,6 +1556,7 @@ def walk_file(
error_handling_hits=_collect_error_handling(tree.root_node, language, lmap),
perf_hits=perf_hits,
io_boundary_names=io_boundary_names,
+ perf_fn_facts=perf_fn_facts,
)
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 1e2bb209a..6e65a7955 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -37,6 +37,7 @@ from .complexity import FileComplexity, FunctionComplexity, walk_file
from .coverage import is_test_file as _coverage_is_test_file
from .duplication import DuplicationReport, detect_clones
from .models import HealthFileMetricData, HealthFindingData, HealthReport
+from .perf import collect_crossfn_io_in_loop
from .scoring import attach_impacts, compute_kpis, score_file
log = structlog.get_logger(__name__)
@@ -362,6 +363,9 @@ class HealthAnalyzer:
repo_dependents_p80 = _compute_repo_dependents_p80(self.parsed_files, self.graph)
repo_active_contributors = _compute_repo_active_contributors(self.git_meta_map)
+ # Cross-function N+1: augment perf_hits before the biomarker stage.
+ self._apply_crossfn_perf(walked)
+
for pf, fcx in walked:
# Side-effect: bump Symbol.complexity_estimate when we can
# match by enclosing line range. Symbols not matched keep
@@ -505,6 +509,10 @@ class HealthAnalyzer:
repo_dependents_p80 = _compute_repo_dependents_p80(self.parsed_files, self.graph)
repo_active_contributors = _compute_repo_active_contributors(self.git_meta_map)
+ # Cross-function N+1: augment perf_hits before the biomarker stage.
+ walked = list(walked)
+ self._apply_crossfn_perf(walked)
+
findings: list[HealthFindingData] = []
metrics: list[HealthFileMetricData] = []
for pf, fcx in walked:
@@ -551,6 +559,27 @@ class HealthAnalyzer:
# Helpers
# ------------------------------------------------------------------
+ def _apply_crossfn_perf(self, walked: list[tuple[Any, FileComplexity]]) -> None:
+ """Splice cross-function ``io_in_loop`` hits into the walked files.
+
+ Runs the bounded reachability pass once over the resolved ``calls``
+ graph and appends the cross-function hits onto the matching file's
+ ``perf_hits`` in place, so the ``io_in_loop`` biomarker handles
+ same-function and cross-function hits through one path. Failure-isolated
+ and a no-op without a graph — never blocks the rest of the report.
+ """
+ if self.graph is None:
+ return
+ try:
+ crossfn = collect_crossfn_io_in_loop(walked, self.graph)
+ except Exception as exc:
+ log.debug("health_crossfn_perf_failed", error=str(exc))
+ return
+ for _pf, fcx in walked:
+ extra = crossfn.get(_pf.file_info.path)
+ if extra:
+ fcx.perf_hits = [*fcx.perf_hits, *extra]
+
def _function_blame_rows(self, walked: list[tuple[Any, FileComplexity]]) -> list[dict]:
"""Build the per-function blame rollup from the walked files + the
FULL-tier blame indexes attached to ``git_meta_map``.
diff --git a/packages/core/src/repowise/core/analysis/health/perf/__init__.py b/packages/core/src/repowise/core/analysis/health/perf/__init__.py
index 02523003f..ea9870f99 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/__init__.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/__init__.py
@@ -1,13 +1,23 @@
"""Performance-risk analysis helpers (the ``performance`` health dimension).
-Today this package holds the I/O-boundary call-site classifier
-(:mod:`.io_boundaries`) that the complexity walker's perf pass uses to turn a
-loop-nested call into a typed ``io_in_loop`` finding. PR4 will add the
-cross-function reachability engine alongside it.
+This package holds the I/O-boundary call-site classifier (:mod:`.io_boundaries`)
+that the complexity walker's perf pass uses to turn a loop-nested call into a
+typed ``io_in_loop`` finding, the sink-agnostic bounded reachability engine
+(:mod:`.reachability`, Primitive 3), and the cross-function N+1 bridge
+(:mod:`.crossfn`) built on top of both.
"""
from __future__ import annotations
+from .crossfn import collect_crossfn_io_in_loop
from .io_boundaries import classify_call_sink, collect_io_names
+from .reachability import ReachInfo, path_to_sink, reachable_to_sink
-__all__ = ["classify_call_sink", "collect_io_names"]
+__all__ = [
+ "ReachInfo",
+ "classify_call_sink",
+ "collect_crossfn_io_in_loop",
+ "collect_io_names",
+ "path_to_sink",
+ "reachable_to_sink",
+]
diff --git a/packages/core/src/repowise/core/analysis/health/perf/crossfn.py b/packages/core/src/repowise/core/analysis/health/perf/crossfn.py
new file mode 100644
index 000000000..23f2c74b4
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/perf/crossfn.py
@@ -0,0 +1,243 @@
+"""Cross-function io-in-loop / N+1 detection (the Tier-B moat).
+
+The same-function detector (``complexity.walker`` + ``biomarkers.io_in_loop``)
+catches a sink *written directly inside* a loop. The pattern no commodity
+linter ships is the **cross-function** one: a loop in function ``A`` calls a
+helper ``B`` (directly, or transitively within a few hops) and ``B`` executes an
+I/O boundary. Each loop iteration pays for ``B``'s round-trip — an N+1 — but the
+loop and the sink live in different functions, so a file-local pass cannot see
+it.
+
+This module is the bridge between three things that already exist:
+
+ * the walker's per-function facts (:class:`PerfFnFacts`) — which callees each
+ function invokes inside a loop body, and which functions hold a *bare*
+ (non-loop) sink;
+ * the resolved symbol-level ``calls`` graph the engine already has (file +
+ symbol nodes, ``calls`` edges between ``path::name`` symbol ids);
+ * the sink-agnostic :mod:`.reachability` walk (Primitive 3).
+
+It runs **once per analyze()** and is ``O(V + E)`` bounded by ``max_depth``:
+one pass to index symbol nodes, one pass to extract ``calls`` adjacency, one
+multi-source reverse BFS from the sink-holding functions, then a cheap
+per-function lookup. No new graph is built; the depth bound and the
+BFS-from-sinks memoization keep it inside the index-time budget.
+
+Soundness (honest limits — these cap recall, never precision):
+
+ * **Static call graph.** Dynamic dispatch, monkeypatching, callbacks passed
+ as values, and reflection produce no ``calls`` edge, so a sink reached only
+ that way is invisible. ORM lazy-loading (a sink that fires on attribute
+ access, not a visible call) is likewise out of reach.
+ * **Depth bound.** ``max_depth`` bounds the reachability walk *from the
+ loop-nested callee* to the sink (per the design); the loop owner ``A`` is
+ one further labelling hop in the reported path, not a counted reachability
+ hop. Chains longer than that from the callee are not followed.
+ * **First-hop name match.** The loop-nested callee is matched to one of the
+ loop owner's *resolved* graph callees by name. The resolver did the real
+ binding; the name only selects which of the owner's calls were in a loop.
+ Two distinct callees sharing a name under one function (rare) could let an
+ out-of-loop edge stand in for the in-loop one.
+ * **Incremental runs.** When only a subset of files is walked, a sink-holding
+ callee that was not itself re-walked is absent from the sink set; full
+ detection requires a whole-repo analyze (the index recomputes there).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from .reachability import path_to_sink, reachable_to_sink
+
+if TYPE_CHECKING:
+ # Imported lazily at runtime (see ``_hits_for_function``) to avoid a cycle:
+ # the walker pulls in ``perf.io_boundaries`` while the ``complexity``
+ # package is still initialising, so ``crossfn`` cannot import it eagerly.
+ from ..complexity import FileComplexity, PerfFnFacts, PerfHit
+
+# Cross-function hits carry this so the biomarker can phrase them distinctly
+# while still scoring under the same ``io_in_loop`` / ``performance`` budget.
+CROSSFN_KIND = "io_in_loop"
+
+
+def _module_node_id(path: str) -> str:
+ return f"{path}::__module__"
+
+
+class _CallGraphIndex:
+ """One-pass index of the dependency graph for the cross-function pass.
+
+ Holds only what the pass needs: symbol-node name lookup, a ``calls``
+ adjacency in both directions, and a resolver from ``(file, def-line)`` to a
+ symbol-node id. Built once; never mutates the source graph.
+ """
+
+ __slots__ = ("_by_file_line", "_ranges", "forward", "name", "nodes", "reverse")
+
+ def __init__(self, graph: Any) -> None:
+ self.nodes: set[str] = set()
+ self.name: dict[str, str] = {}
+ self.forward: dict[str, list[str]] = {}
+ self.reverse: dict[str, list[str]] = {}
+ # Exact (path, start_line) -> symbol id, plus a per-file range list for
+ # the containment fallback when a def line doesn't match exactly.
+ self._by_file_line: dict[tuple[str, int], str] = {}
+ self._ranges: dict[str, list[tuple[int, int, str]]] = {}
+
+ for node_id, attrs in graph.nodes(data=True):
+ self.nodes.add(node_id)
+ if attrs.get("node_type") != "symbol":
+ continue
+ self.name[node_id] = attrs.get("name") or ""
+ path = attrs.get("file_path")
+ if not path:
+ continue
+ start = attrs.get("start_line")
+ end = attrs.get("end_line")
+ if isinstance(start, int):
+ self._by_file_line.setdefault((path, start), node_id)
+ if isinstance(end, int):
+ self._ranges.setdefault(path, []).append((start, end, node_id))
+
+ for src, dst, data in graph.edges(data=True):
+ if data.get("edge_type") != "calls":
+ continue
+ self.forward.setdefault(src, []).append(dst)
+ self.reverse.setdefault(dst, []).append(src)
+
+ def resolve_function(self, path: str, func_start: int) -> str | None:
+ """Symbol-node id for the function defined at ``func_start`` in ``path``.
+
+ ``func_start == 0`` is module scope (the synthetic ``::__module__``
+ node). Otherwise prefer an exact def-line match, then fall back to the
+ innermost symbol whose line range contains ``func_start`` (tolerates a
+ decorator/def off-by-one without matching an enclosing scope).
+ """
+ if func_start == 0:
+ mod = _module_node_id(path)
+ return mod if mod in self.nodes else None
+ exact = self._by_file_line.get((path, func_start))
+ if exact is not None:
+ return exact
+ best: str | None = None
+ best_start = -1
+ for start, end, node_id in self._ranges.get(path, ()):
+ if start <= func_start <= end and start > best_start:
+ best, best_start = node_id, start
+ return best
+
+
+def collect_crossfn_io_in_loop(
+ walked: Iterable[tuple[Any, FileComplexity]],
+ graph: Any,
+ *,
+ max_depth: int = 3,
+) -> dict[str, list[PerfHit]]:
+ """Cross-function ``io_in_loop`` hits, keyed by the loop-owning file path.
+
+ ``walked`` is the engine's ``(parsed_file, FileComplexity)`` list; ``graph``
+ is the resolved dependency graph (file + symbol nodes with ``calls``
+ edges), or ``None``. Each returned :class:`PerfHit` carries the sink's
+ boundary kind in ``detail`` and the ``A -> ... -> sink`` symbol path in
+ ``path`` (non-empty ``path`` is what marks a hit as cross-function).
+ """
+ walked_list = list(walked)
+ if graph is None or not walked_list:
+ return {}
+
+ # Cheap pre-checks over the already-computed facts, before touching the
+ # graph at all: a cross-function N+1 needs BOTH a function holding a bare
+ # sink (a reachability target) and a function with a loop-nested call (an
+ # entry). On a repo with neither, this returns without scanning the graph.
+ has_sink = any(
+ fact.bare_sink_kind is not None for _pf, fcx in walked_list for fact in fcx.perf_fn_facts
+ )
+ has_entry = any(
+ fact.loop_call_targets for _pf, fcx in walked_list for fact in fcx.perf_fn_facts
+ )
+ if not (has_sink and has_entry):
+ return {}
+
+ index = _CallGraphIndex(graph)
+ if not index.forward:
+ return {} # no resolved call edges → nothing cross-function to find
+
+ # --- sink set: functions that execute a bare (loop_depth 0) I/O sink ------
+ sink_kind: dict[str, str] = {}
+ for pf, fcx in walked_list:
+ path = pf.file_info.path
+ for fact in fcx.perf_fn_facts:
+ if fact.bare_sink_kind is None:
+ continue
+ sid = index.resolve_function(path, fact.func_start)
+ if sid is not None:
+ sink_kind.setdefault(sid, fact.bare_sink_kind)
+
+ if not sink_kind:
+ return {}
+
+ reach = reachable_to_sink(
+ sink_kind.keys(),
+ lambda node: index.reverse.get(node, ()),
+ max_depth=max_depth,
+ )
+
+ # --- match each loop owner's loop-nested callees against the reach map ----
+ out: dict[str, list[PerfHit]] = {}
+ for pf, fcx in walked_list:
+ path = pf.file_info.path
+ for fact in fcx.perf_fn_facts:
+ if not fact.loop_call_targets:
+ continue
+ hits = _hits_for_function(path, fact, index, reach, sink_kind)
+ if hits:
+ out.setdefault(path, []).extend(hits)
+ return out
+
+
+def _hits_for_function(
+ path: str,
+ fact: PerfFnFacts,
+ index: _CallGraphIndex,
+ reach: dict[str, Any],
+ sink_kind: dict[str, str],
+) -> list[PerfHit]:
+ from ..complexity import PerfHit
+
+ a_sid = index.resolve_function(path, fact.func_start)
+ if a_sid is None:
+ return []
+ callees = index.forward.get(a_sid)
+ if not callees:
+ return []
+ # Index the owner's resolved callees by name for the first-hop match.
+ callees_by_name: dict[str, list[str]] = {}
+ for c in callees:
+ callees_by_name.setdefault(index.name.get(c, ""), []).append(c)
+
+ hits: list[PerfHit] = []
+ seen: set[str] = set()
+ for target_name, call_line in fact.loop_call_targets:
+ if target_name in seen:
+ continue
+ for callee in callees_by_name.get(target_name, ()):
+ info = reach.get(callee)
+ if info is None:
+ continue
+ chain = path_to_sink(callee, reach)
+ if not chain:
+ continue
+ seen.add(target_name)
+ kind = sink_kind.get(info.sink, "")
+ hits.append(
+ PerfHit(
+ kind=CROSSFN_KIND,
+ line=call_line,
+ function=fact.function,
+ detail=kind,
+ path=(a_sid, *chain),
+ )
+ )
+ break
+ return hits
diff --git a/packages/core/src/repowise/core/analysis/health/perf/reachability.py b/packages/core/src/repowise/core/analysis/health/perf/reachability.py
new file mode 100644
index 000000000..7b0b871f8
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/perf/reachability.py
@@ -0,0 +1,119 @@
+"""Bounded-depth reachability to a typed sink (sink-agnostic).
+
+This is *Primitive 3* of the performance-pillar arc: the engine that answers
+"starting from this node and following call edges, does a path of at most
+``max_depth`` hops reach a node that satisfies a sink predicate?" — and, when
+it does, returns the path for explainability.
+
+It is built for cross-function N+1 detection (a loop in function ``A`` calls a
+helper that, transitively, executes an I/O boundary), but **nothing here is
+performance-specific**. The two things that vary between use cases are both
+parameters:
+
+ * **the sink set** — the caller passes the node ids that *are* sinks. For
+ performance that is "functions holding a bare I/O sink"; the identical walk
+ serves static security taint (``sink = dangerous API``) and architecture
+ conformance (``sink = forbidden layer``) by passing a different set.
+ * **the adjacency** — the caller passes a ``predecessors`` callable (the
+ *reverse* of the edge direction being followed). The walk never imports a
+ graph library; it only calls ``predecessors(node)``.
+
+**Why a reverse BFS from the sinks.** The question "can N reach a sink within K
+forward hops?" is answered for *every* N at once by a single multi-source BFS
+that starts at the sinks and walks edges backwards. Each node and edge within
+the depth bound is visited once, so the whole repo's reachability is computed
+in one ``O(V + E)`` pass (bounded by ``max_depth``) and is memoized by
+construction — there is no per-query re-walk and no risk of blow-up on a dense
+call graph. This is what keeps the cross-function pass inside the index-time
+budget.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ReachInfo:
+ """How a node reaches its nearest sink along the bounded walk.
+
+ ``distance`` is the number of forward hops to ``sink`` (0 when the node is
+ itself a sink). ``next_hop`` is the successor one step closer to the sink
+ (``None`` for a sink). Follow ``next_hop`` repeatedly to recover the path.
+ """
+
+ distance: int
+ next_hop: str | None
+ sink: str
+
+
+def reachable_to_sink(
+ sink_nodes: Iterable[str],
+ predecessors: Callable[[str], Iterable[str]],
+ *,
+ max_depth: int = 3,
+) -> dict[str, ReachInfo]:
+ """Map every node within ``max_depth`` forward hops of a sink to a :class:`ReachInfo`.
+
+ ``sink_nodes`` are the nodes that satisfy the (caller-defined) sink
+ predicate. ``predecessors(node)`` yields the nodes with a forward edge
+ *into* ``node`` (i.e. reverse adjacency). The result contains an entry for
+ each sink (distance 0) and for each node that can reach some sink in
+ ``1..max_depth`` forward hops; nodes that cannot reach a sink are absent.
+
+ Deterministic: BFS visits nodes in non-decreasing distance, so the first
+ (and recorded) distance for any node is the minimum, and the recorded
+ ``sink`` is the nearest one (ties broken by BFS/seed order).
+ """
+ if max_depth < 0:
+ return {}
+
+ info: dict[str, ReachInfo] = {}
+ queue: deque[str] = deque()
+ for s in sink_nodes:
+ if s not in info:
+ info[s] = ReachInfo(distance=0, next_hop=None, sink=s)
+ queue.append(s)
+
+ while queue:
+ node = queue.popleft()
+ cur = info[node]
+ if cur.distance >= max_depth:
+ continue
+ for pred in predecessors(node):
+ if pred in info:
+ continue # already reached at an equal-or-shorter distance
+ info[pred] = ReachInfo(
+ distance=cur.distance + 1,
+ next_hop=node,
+ sink=cur.sink,
+ )
+ queue.append(pred)
+ return info
+
+
+def path_to_sink(node: str, info: dict[str, ReachInfo], *, max_len: int = 16) -> list[str]:
+ """Reconstruct ``[node, ..., sink]`` by following ``next_hop`` pointers.
+
+ Returns ``[]`` when ``node`` has no :class:`ReachInfo` (it does not reach a
+ sink within the bound). ``max_len`` is a defensive cap so a corrupted
+ pointer chain can never loop forever; it is never hit for a BFS-built map
+ bounded at a small ``max_depth``.
+ """
+ if node not in info:
+ return []
+ path: list[str] = [node]
+ cur = info[node]
+ seen = {node}
+ while cur.next_hop is not None and len(path) < max_len:
+ nxt = cur.next_hop
+ if nxt in seen: # impossible for a BFS map; defensive only
+ break
+ path.append(nxt)
+ seen.add(nxt)
+ cur = info.get(nxt)
+ if cur is None:
+ break
+ return path
diff --git a/tests/unit/health/test_perf_crossfn.py b/tests/unit/health/test_perf_crossfn.py
new file mode 100644
index 000000000..09d596aa5
--- /dev/null
+++ b/tests/unit/health/test_perf_crossfn.py
@@ -0,0 +1,283 @@
+"""Cross-function io-in-loop / N+1 (PR4 — the Tier-B moat).
+
+Three layers:
+
+ * ``reachability`` — the sink-agnostic bounded BFS in isolation.
+ * the walker's per-function facts (``loop_call_targets`` / ``bare_sink_kind``).
+ * the end-to-end bridge over a real resolved ``calls`` graph, including the
+ cross-*file* case, plus the guardrails (same-function hits unchanged, the
+ defect score untouched).
+
+Like the other walker tests, tree-sitter grammar availability is best-effort.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.analysis.health.biomarkers.base import FileContext
+from repowise.core.analysis.health.biomarkers.io_in_loop import IoInLoopDetector
+from repowise.core.analysis.health.biomarkers.registry import detect_all
+from repowise.core.analysis.health.complexity import PerfHit, walk_file
+from repowise.core.analysis.health.perf import (
+ collect_crossfn_io_in_loop,
+ path_to_sink,
+ reachable_to_sink,
+)
+from repowise.core.analysis.health.scoring import score_file
+from repowise.core.ingestion import ASTParser, FileTraverser, GraphBuilder
+
+# ---------------------------------------------------------------------------
+# reachability — the sink-agnostic primitive
+# ---------------------------------------------------------------------------
+
+
+def _adj(edges: dict[str, list[str]]):
+ """Build a ``predecessors`` callable from a forward edge map.
+
+ Reachability walks edges *backwards* from sinks, so it consumes the reverse
+ adjacency: for a forward edge ``a -> b`` it must yield ``a`` from ``b``.
+ """
+ reverse: dict[str, list[str]] = {}
+ for src, dsts in edges.items():
+ for d in dsts:
+ reverse.setdefault(d, []).append(src)
+ return lambda node: reverse.get(node, ())
+
+
+def test_reachability_direct_sink():
+ info = reachable_to_sink({"sink"}, _adj({}), max_depth=3)
+ assert info["sink"].distance == 0
+ assert info["sink"].next_hop is None
+ assert path_to_sink("sink", info) == ["sink"]
+
+
+def test_reachability_chain_within_depth():
+ # a -> b -> c -> sink (3 hops)
+ fwd = {"a": ["b"], "b": ["c"], "c": ["sink"]}
+ info = reachable_to_sink({"sink"}, _adj(fwd), max_depth=3)
+ assert info["a"].distance == 3
+ assert path_to_sink("a", info) == ["a", "b", "c", "sink"]
+
+
+def test_reachability_respects_depth_bound():
+ # a -> b -> c -> d -> sink (4 hops) — beyond a depth-3 bound from ``a``.
+ fwd = {"a": ["b"], "b": ["c"], "c": ["d"], "d": ["sink"]}
+ info = reachable_to_sink({"sink"}, _adj(fwd), max_depth=3)
+ assert "a" not in info # 4 hops > 3
+ assert info["b"].distance == 3
+ assert "sink" in info
+
+
+def test_reachability_unreachable_node_absent():
+ fwd = {"a": ["b"], "lonely": ["other"]}
+ info = reachable_to_sink({"sink"}, _adj(fwd), max_depth=3)
+ assert info == {"sink": info["sink"]}
+ assert path_to_sink("lonely", info) == []
+
+
+def test_reachability_records_nearest_sink():
+ # a reaches s1 in 1 hop and s2 in 2 hops → nearest is s1.
+ fwd = {"a": ["s1"], "s1": ["s2"]}
+ info = reachable_to_sink({"s1", "s2"}, _adj(fwd), max_depth=3)
+ assert info["a"].sink == "s1"
+ assert info["a"].distance == 1
+
+
+# ---------------------------------------------------------------------------
+# walker per-function facts
+# ---------------------------------------------------------------------------
+
+
+def _facts(source: bytes, lang: str = "python"):
+ return {f.function: f for f in walk_file(f"t.{lang[:2]}", lang, source).perf_fn_facts}
+
+
+def test_walker_records_bare_sink_kind():
+ src = (
+ b"from sqlalchemy import select\n"
+ b"def helper(session, r):\n"
+ b" return session.execute(select(r))\n"
+ )
+ facts = _facts(src)
+ assert facts["helper"].bare_sink_kind == "db"
+ assert facts["helper"].loop_call_targets == ()
+
+
+def test_walker_records_loop_call_targets_not_sinks():
+ src = b"def run(repos):\n for r in repos:\n helper(r)\n"
+ facts = _facts(src)
+ targets = dict(facts["run"].loop_call_targets)
+ assert "helper" in targets
+ assert targets["helper"] == 3 # the call line
+ assert facts["run"].bare_sink_kind is None
+
+
+def test_walker_sink_inside_loop_is_not_a_bare_sink():
+ """A sink already nested in a loop is a same-function hit, not a cross-fn
+ reachability target — bare_sink_kind stays None for that function."""
+ src = (
+ b"from sqlalchemy import select\n"
+ b"def f(session, repos):\n"
+ b" for r in repos:\n"
+ b" session.execute(select(r))\n"
+ )
+ facts = _facts(src)
+ # ``f`` has a same-function io_in_loop hit, so it is not a bare-sink target.
+ assert facts.get("f") is None or facts["f"].bare_sink_kind is None
+
+
+# ---------------------------------------------------------------------------
+# end-to-end bridge over a real resolved calls graph
+# ---------------------------------------------------------------------------
+
+
+def _build(tmp_path: Path, files: dict[str, str]):
+ """Write *files*, build the graph, and return ``(walked, graph)``."""
+ for name, src in files.items():
+ p = tmp_path / name
+ p.parent.mkdir(parents=True, exist_ok=True)
+ p.write_text(src, encoding="utf-8")
+ trav = FileTraverser(tmp_path)
+ parser = ASTParser()
+ gb = GraphBuilder(repo_path=tmp_path)
+ walked = []
+ for fi in trav.traverse():
+ data = Path(fi.abs_path).read_bytes()
+ parsed = parser.parse_file(fi, data)
+ gb.add_file(parsed)
+ walked.append((parsed, walk_file(fi.abs_path, fi.language, data)))
+ return walked, gb.build()
+
+
+_SCHEDULER = """
+from sqlalchemy import select
+
+
+class Scheduler:
+ def __init__(self, session):
+ self.session = session
+
+ def _poll(self, repo):
+ return self.session.execute(select(repo))
+
+ def run(self, repos):
+ out = []
+ for repo in repos:
+ out.append(self._poll(repo))
+ return out
+"""
+
+
+def test_crossfn_scheduler_pattern_is_caught(tmp_path):
+ walked, graph = _build(tmp_path, {"scheduler.py": _SCHEDULER})
+ res = collect_crossfn_io_in_loop(walked, graph)
+ hits = [h for hs in res.values() for h in hs]
+ assert len(hits) == 1
+ h = hits[0]
+ assert h.kind == "io_in_loop"
+ assert h.detail == "db"
+ assert h.function == "run"
+ # The path is the resolved A -> B chain and ends at the sink holder.
+ assert h.path[0].endswith("::run")
+ assert h.path[-1].endswith("::_poll")
+
+
+def test_crossfn_path_renders_in_the_biomarker(tmp_path):
+ walked, graph = _build(tmp_path, {"scheduler.py": _SCHEDULER})
+ res = collect_crossfn_io_in_loop(walked, graph)
+ hit = next(h for hs in res.values() for h in hs)
+ ctx = FileContext(
+ file_path="scheduler.py",
+ language="python",
+ nloc=20,
+ has_test_file=False,
+ module="scheduler",
+ perf_hits=[hit],
+ )
+ (finding,) = IoInLoopDetector().detect(ctx)
+ assert finding.biomarker_type == "io_in_loop"
+ assert finding.details["cross_function"] is True
+ assert finding.details["boundary_kind"] == "db"
+ assert finding.details["path"] == list(hit.path)
+ assert "cross-function N+1" in finding.reason
+ assert "run -> _poll" in finding.reason
+
+
+def test_crossfn_across_files(tmp_path):
+ """The loop and the sink live in different *files* — the case no file-local
+ linter can see."""
+ files = {
+ "db.py": (
+ "from sqlalchemy import select\n\n\n"
+ "def fetch_one(session, rid):\n"
+ " return session.execute(select(rid))\n"
+ ),
+ "service.py": (
+ "from db import fetch_one\n\n\n"
+ "def fetch_all(session, ids):\n"
+ " rows = []\n"
+ " for rid in ids:\n"
+ " rows.append(fetch_one(session, rid))\n"
+ " return rows\n"
+ ),
+ }
+ walked, graph = _build(tmp_path, files)
+ res = collect_crossfn_io_in_loop(walked, graph)
+ hits = [h for hs in res.values() for h in hs]
+ assert len(hits) == 1, "expected one cross-file N+1"
+ h = hits[0]
+ assert h.function == "fetch_all"
+ assert h.path[0].endswith("service.py::fetch_all")
+ assert h.path[-1].endswith("db.py::fetch_one")
+
+
+def test_crossfn_pure_helper_is_not_flagged(tmp_path):
+ """A loop calling a helper that does NO I/O produces no cross-fn finding."""
+ src = "def square(x):\n return x * x\n\n\ndef run(xs):\n return [square(x) for x in xs]\n"
+ walked, graph = _build(tmp_path, {"pure.py": src})
+ assert collect_crossfn_io_in_loop(walked, graph) == {}
+
+
+def test_crossfn_same_function_hits_unchanged(tmp_path):
+ """The same-function pass still fires exactly as in PR3, and the cross-fn
+ pass adds nothing for a directly-nested sink."""
+ src = (
+ "from sqlalchemy import select\n\n\n"
+ "def f(session, repos):\n"
+ " for r in repos:\n"
+ " session.execute(select(r))\n"
+ )
+ walked, graph = _build(tmp_path, {"direct.py": src})
+ (_, fc) = walked[0]
+ same_fn = [h for h in fc.perf_hits if h.kind == "io_in_loop" and not h.path]
+ assert len(same_fn) == 1
+ assert collect_crossfn_io_in_loop(walked, graph) == {}
+
+
+def test_crossfn_no_graph_is_noop():
+ assert collect_crossfn_io_in_loop([], None) == {}
+
+
+# ---------------------------------------------------------------------------
+# guardrail: cross-fn findings score performance only, never defect
+# ---------------------------------------------------------------------------
+
+
+def test_crossfn_finding_scores_performance_not_defect():
+ hit = PerfHit("io_in_loop", 14, "run", "db", path=("m.py::run", "m.py::_poll"))
+ ctx = FileContext(
+ file_path="m.py",
+ language="python",
+ nloc=10,
+ has_test_file=False,
+ module="m",
+ perf_hits=[hit],
+ )
+ results = detect_all(ctx)
+ perf = [r for r in results if r.biomarker_type == "io_in_loop"]
+ assert len(perf) == 1 and perf[0].details["cross_function"] is True
+ scores, deductions = score_file(results)
+ assert scores["defect"] == 10.0
+ assert scores["performance"] < 10.0
+ assert all(d == 0.0 for d in deductions)