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 io-in-loop performance detector (#530)

Raghav Chamadiyac16df9b58025
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
index 60b1cf561..802a571cc 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py
@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
from typing import Any, Protocol
from ....ingestion.git_indexer.function_blame import BlameIndex
-from ..complexity import ClassComplexity, ErrorHandlingHit, FunctionComplexity
+from ..complexity import ClassComplexity, ErrorHandlingHit, FunctionComplexity, PerfHit
from ..duplication import ClonePair
from ..models import Severity
@@ -101,6 +101,18 @@ class FileContext:
# unsupported or parsing failed — the documented "no signal" outcome.
# Consumed by the ``error_handling`` biomarker.
error_handling_hits: list[ErrorHandlingHit] = field(default_factory=list)
+ # Performance-risk occurrences (io-in-loop, string-concat-in-loop,
+ # blocking-sync-in-async) collected by the complexity walker's whole-tree
+ # perf pass. Empty when the language opts out of the perf pass or parsing
+ # failed — the documented "no signal" outcome. Consumed by the perf
+ # biomarkers (``io_in_loop`` / ``string_concat_in_loop`` /
+ # ``blocking_sync_in_async``).
+ perf_hits: list[PerfHit] = field(default_factory=list)
+ # Names imported from an I/O-typed library in this file (the import
+ # bridge). Empty when none / language opts out. Carried for PR4's
+ # cross-function reachability; the same-function perf biomarkers read the
+ # already-resolved ``perf_hits`` instead.
+ io_boundary_names: set[str] = field(default_factory=set)
# A repo whose trailing-90-day window has at most this many active human
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/blocking_sync_in_async.py b/packages/core/src/repowise/core/analysis/health/biomarkers/blocking_sync_in_async.py
new file mode 100644
index 000000000..88a1700a7
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/blocking_sync_in_async.py
@@ -0,0 +1,47 @@
+"""Blocking-sync-in-async — a synchronous blocking call inside ``async def``.
+
+A synchronous ``time.sleep`` / ``requests.get`` / ``subprocess.run`` /
+``os.system`` / bare ``open`` inside an ``async def`` blocks the whole event
+loop for its entire duration, stalling every other coroutine. A ``performance``
+dimension signal mirroring ruff's ASYNC210 / ASYNC230 / ASYNC251.
+
+Precision-first: the walker's perf pass uses a small known-API allowlist of
+*always-synchronous* calls and fires only when the call is NOT awaited, so an
+``await`` on an async client never trips it. Python only in v1 (its async-fn
+node type is unambiguous); this detector lifts the pre-collected hits into
+findings.
+"""
+
+from __future__ import annotations
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_KIND = "blocking_sync_in_async"
+
+
+class BlockingSyncInAsyncDetector:
+ name = _KIND
+ category = "performance"
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ out: list[BiomarkerResult] = []
+ for hit in ctx.perf_hits:
+ if hit.kind != _KIND:
+ continue
+ api = hit.detail or "a blocking call"
+ out.append(
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=Severity.MEDIUM,
+ function_name=hit.function,
+ line_start=hit.line,
+ line_end=hit.line,
+ details={"api": hit.detail},
+ reason=f"{api} blocks the event loop inside an async function",
+ )
+ )
+ return out
+
+
+BIOMARKER = BlockingSyncInAsyncDetector()
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
new file mode 100644
index 000000000..ed44fedc6
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/io_in_loop.py
@@ -0,0 +1,66 @@
+"""IO-in-loop — an execution sink at an I/O boundary inside 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.
+
+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
+upstream in the walker's perf pass (``complexity.walker._collect_perf_hits``)
+and the boundary classifier (``perf.io_boundaries``):
+
+ 1. **Loop-body scoping** — only calls under a loop's ``body`` field count; a
+ query in the ``for x in q.all()`` *header* runs once, not per iteration.
+ 2. **Execution-sink gating** — ``select().where()`` query *builders* are not
+ round-trips; only ``.execute`` / ``.scalars`` / ``.commit`` / awaited HTTP
+ / ``subprocess.run`` / ``fetch`` and friends are.
+ 3. **Dependency classification** — the callee resolves to a *classified*
+ external boundary via the shared ``io_kind`` table (import bridge), not a
+ bare name heuristic.
+
+This detector just lifts the pre-collected, pre-gated hits into findings —
+unsupported languages and parse failures yield nothing, never a false positive.
+"""
+
+from __future__ import annotations
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_KIND = "io_in_loop"
+
+_BOUNDARY_PHRASING: dict[str, str] = {
+ "db": "a database call",
+ "network": "a network call",
+ "filesystem": "a filesystem call",
+ "subprocess": "a subprocess spawn",
+ "lock": "a lock acquisition",
+}
+
+
+class IoInLoopDetector:
+ name = _KIND
+ category = "performance"
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ out: list[BiomarkerResult] = []
+ for hit in ctx.perf_hits:
+ 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)",
+ )
+ )
+ return out
+
+
+BIOMARKER = IoInLoopDetector()
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
index 2787f89a8..79307ea3f 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/registry.py
@@ -12,6 +12,7 @@ from __future__ import annotations
from collections.abc import Sequence
from .base import Biomarker, BiomarkerResult, FileContext
+from .blocking_sync_in_async import BlockingSyncInAsyncDetector
from .brain_method import BrainMethodDetector
from .bumpy_road import BumpyRoadDetector
from .change_entropy import ChangeEntropyDetector
@@ -29,6 +30,7 @@ from .error_handling import ErrorHandlingDetector
from .function_hotspot import FunctionHotspotDetector
from .god_class import GodClassDetector
from .hidden_coupling import HiddenCouplingDetector
+from .io_in_loop import IoInLoopDetector
from .knowledge_loss import KnowledgeLossDetector
from .large_assertion_block import LargeAssertionBlockDetector
from .large_method import LargeMethodDetector
@@ -37,6 +39,7 @@ from .nested_complexity import NestedComplexityDetector
from .ownership_risk import OwnershipRiskDetector
from .primitive_obsession import PrimitiveObsessionDetector
from .prior_defect import PriorDefectDetector
+from .string_concat_in_loop import StringConcatInLoopDetector
from .untested_hotspot import UntestedHotspotDetector
_DETECTOR_FACTORIES: list[type[Biomarker]] = [
@@ -66,6 +69,10 @@ _DETECTOR_FACTORIES: list[type[Biomarker]] = [
LargeAssertionBlockDetector, # type: ignore[list-item]
DuplicatedAssertionBlockDetector, # type: ignore[list-item]
ErrorHandlingDetector, # type: ignore[list-item]
+ # Performance dimension (advisory weight; bounded by the perf cap).
+ IoInLoopDetector, # type: ignore[list-item]
+ StringConcatInLoopDetector, # type: ignore[list-item]
+ BlockingSyncInAsyncDetector, # type: ignore[list-item]
]
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/string_concat_in_loop.py b/packages/core/src/repowise/core/analysis/health/biomarkers/string_concat_in_loop.py
new file mode 100644
index 000000000..427187aa0
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/string_concat_in_loop.py
@@ -0,0 +1,45 @@
+"""String-concat-in-loop — ``+=`` string accumulation inside a loop.
+
+Building a string by repeated ``+=`` inside a loop is quadratic in many runtimes
+(each concat copies the whole accumulated string); a buffer + ``join`` is linear.
+A ``performance`` dimension signal, loop-form only — single-line concatenation is
+compiler-optimized and not flagged.
+
+Precision-first: the walker's perf pass flags this ONLY when the RHS is provably
+a string literal / template (``s += "..."`` / ``s += f"{x}"`` / ``s += "a" + b``),
+never an opaque ``s += chunk`` that could be numeric. This detector lifts the
+pre-collected hits into findings.
+"""
+
+from __future__ import annotations
+
+from ..models import Severity
+from .base import BiomarkerResult, FileContext
+
+_KIND = "string_concat_in_loop"
+
+
+class StringConcatInLoopDetector:
+ name = _KIND
+ category = "performance"
+
+ def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ out: list[BiomarkerResult] = []
+ for hit in ctx.perf_hits:
+ if hit.kind != _KIND:
+ continue
+ out.append(
+ BiomarkerResult(
+ biomarker_type=self.name,
+ severity=Severity.LOW,
+ function_name=hit.function,
+ line_start=hit.line,
+ line_end=hit.line,
+ details={},
+ reason="string built by += in a loop; use a buffer / join for linear cost",
+ )
+ )
+ return out
+
+
+BIOMARKER = StringConcatInLoopDetector()
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 9070a13d8..555dca087 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,
+ PerfHit,
walk_file,
walk_file_complexity,
)
@@ -18,6 +19,7 @@ __all__ = [
"ErrorHandlingHit",
"FileComplexity",
"FunctionComplexity",
+ "PerfHit",
"walk_file",
"walk_file_complexity",
]
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 3e229cf04..93e5320c8 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/languages.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/languages.py
@@ -113,6 +113,24 @@ class LanguageNodeMap:
assert_kinds: frozenset[str] = frozenset()
assert_call_kinds: frozenset[str] = frozenset()
+ # ------------------------------------------------------------------
+ # Performance pass (io_in_loop / string_concat_in_loop /
+ # blocking_sync_in_async). Both fields default to empty, making the
+ # perf pass OPT-IN per language:
+ #
+ # * ``call_kinds`` — node type(s) for a call expression (Python
+ # ``call``; JS/TS ``call_expression``). The perf walker needs these
+ # to find execution sinks; a language that maps none produces no
+ # perf hits (never a false positive).
+ # * ``async_function_kinds`` — function node type(s) that are
+ # *syntactically* async (Python ``async_function_definition``). Used
+ # by ``blocking_sync_in_async``. Languages whose async-ness is a
+ # modifier token on a shared node type (TS ``async`` arrow/function)
+ # are additionally sniffed for an ``async`` child token by the
+ # walker, so this set only needs the dedicated async node types.
+ call_kinds: frozenset[str] = frozenset()
+ async_function_kinds: frozenset[str] = frozenset()
+
_PY = LanguageNodeMap(
function_kinds=frozenset({"function_definition", "async_function_definition"}),
@@ -131,6 +149,8 @@ _PY = LanguageNodeMap(
# call.
assert_kinds=frozenset({"assert_statement"}),
assert_call_kinds=frozenset({"call"}),
+ call_kinds=frozenset({"call"}),
+ async_function_kinds=frozenset({"async_function_definition"}),
)
_TS = LanguageNodeMap(
@@ -166,6 +186,10 @@ _TS = LanguageNodeMap(
# ``expect(x).toBe(y)`` / ``assert.equal(...)`` — best-effort: any call
# whose callee chain mentions ``expect`` / ``assert*``.
assert_call_kinds=frozenset({"call_expression"}),
+ call_kinds=frozenset({"call_expression"}),
+ # TS/JS async is a modifier token, not a distinct node type; the walker
+ # sniffs the ``async`` child token instead, so this stays empty.
+ async_function_kinds=frozenset(),
)
_JS = _TS # identical control-flow nodes; tree-sitter-javascript shares shape.
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 4a121c40a..e56a69cd2 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -26,6 +26,12 @@ from typing import TYPE_CHECKING
import structlog
+from ..perf.io_boundaries import (
+ HTTP_VERBS,
+ PY_SUBPROC_METHODS,
+ classify_call_sink,
+ collect_io_names,
+)
from .languages import LanguageNodeMap, get_language_map
if TYPE_CHECKING:
@@ -132,6 +138,33 @@ class ErrorHandlingHit:
line: int # 1-indexed
+@dataclass(frozen=True)
+class PerfHit:
+ """One performance-risk occurrence in a file (the ``performance`` dimension).
+
+ Collected by the walker's whole-tree perf pass (see
+ ``_collect_perf_hits``) and lifted into findings by the perf biomarkers.
+ Precision-first: every hit is loop-body-scoped and execution-sink-gated so
+ an unsupported language / parse failure / builder-only call yields nothing.
+
+ ``kind`` is one of:
+
+ - ``io_in_loop`` — an execution sink at an I/O boundary (db / network /
+ filesystem / subprocess) inside a real, data-dependent loop body. The
+ boundary kind is carried in ``detail``.
+ - ``string_concat_in_loop`` — string accumulation (``+=`` onto a string)
+ inside a loop, instead of a buffer / ``join``.
+ - ``blocking_sync_in_async`` — a known blocking sync call (``time.sleep`` /
+ sync ``requests`` / ``subprocess`` / ``os.system`` / bare ``open``) inside
+ an ``async def``, not awaited. ``detail`` carries the offending API.
+ """
+
+ kind: str
+ line: int # 1-indexed
+ function: str | None = None
+ detail: str = ""
+
+
@dataclass
class FileComplexity:
"""Walker output for one file: per-function and per-class metrics.
@@ -147,6 +180,13 @@ class FileComplexity:
# the language is unsupported or parsing failed — "no signal", never a
# false positive.
error_handling_hits: list[ErrorHandlingHit] = field(default_factory=list)
+ # Performance-risk occurrences (whole-tree perf pass). Empty when the
+ # language opts out of the perf pass (no ``call_kinds``) or parsing failed.
+ perf_hits: list[PerfHit] = field(default_factory=list)
+ # Names imported from an I/O-typed library in this file, mapped to their
+ # 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)
# Leaf node types that carry a declared name at the bottom of a C/C++
@@ -862,6 +902,277 @@ def _collect_error_handling(
return hits
+# ----------------------------------------------------------------------
+# Performance-risk detection (io_in_loop / string_concat_in_loop /
+# blocking_sync_in_async — the ``performance`` health dimension)
+# ----------------------------------------------------------------------
+# One whole-tree pass mirroring ``_collect_error_handling`` but carrying the
+# per-node context the perf signal needs: loop depth, in-async, and the
+# enclosing function name. Two non-negotiable refinements (Phase-0 gate: they
+# took precision from 49% to 79%) are baked in:
+# 1. Loop-BODY scoping — only calls under a loop node's ``body`` field run
+# per-iteration; a call in the ``for x in <iterable>`` header runs once.
+# 2. Constant-bound-loop skip — ``for _ in range(<int literals>)`` and loops
+# over literal / ALL_CAPS-named-constant collections are not data-dependent.
+
+# Python string-literal node kinds (f-strings parse as ``string`` too).
+_PY_STRING_KINDS = frozenset({"string", "concatenated_string"})
+_TS_STRING_KINDS = frozenset({"string", "template_string"})
+_AUG_ASSIGN_KINDS = frozenset({"augmented_assignment", "augmented_assignment_expression"})
+
+
+def _callee_root_name(call_node: Node) -> str | None:
+ """Root identifier of a call's callee: ``a.b.c()`` -> 'a', ``foo()`` -> 'foo'."""
+ fn = call_node.child_by_field_name("function")
+ if fn is None:
+ named = [c for c in call_node.children if c.is_named]
+ fn = named[0] if named else None
+ if fn is None:
+ return None
+ node = fn
+ for _ in range(8):
+ if node.type in ("identifier", "property_identifier", "field_identifier"):
+ break
+ obj = node.child_by_field_name("object") or node.child_by_field_name("value")
+ if obj is None:
+ named = [c for c in node.children if c.is_named]
+ if not named:
+ break
+ node = named[0]
+ else:
+ node = obj
+ txt = (node.text or b"").decode("utf-8", "replace")
+ return txt.split(".")[0] if txt else None
+
+
+def _callee_method_name(call_node: Node) -> str | None:
+ """Rightmost member of the callee (``x.execute`` -> 'execute')."""
+ fn = call_node.child_by_field_name("function")
+ if fn is None:
+ return None
+ prop = (
+ fn.child_by_field_name("property")
+ or fn.child_by_field_name("field")
+ or fn.child_by_field_name("attribute")
+ )
+ if prop is not None and prop.text:
+ return prop.text.decode("utf-8", "replace")
+ if fn.type == "identifier" and fn.text:
+ return fn.text.decode("utf-8", "replace")
+ ids = [c for c in fn.children if c.type == "identifier"]
+ if ids and ids[-1].text:
+ return ids[-1].text.decode("utf-8", "replace")
+ return None
+
+
+def _callee_is_attribute(call_node: Node) -> bool:
+ """True if the callee is a member access (``x.foo()``), not a bare call."""
+ fn = call_node.child_by_field_name("function")
+ if fn is None:
+ return False
+ return fn.type in (
+ "attribute",
+ "member_expression",
+ "field_expression",
+ "selector_expression",
+ )
+
+
+def _perf_func_name(node: Node) -> str | None:
+ nm = node.child_by_field_name("name")
+ if nm is not None and nm.text:
+ return nm.text.decode("utf-8", "replace")
+ return None
+
+
+def _has_async_modifier(node: Node) -> bool:
+ """True if a function node carries an ``async`` modifier token (TS/JS)."""
+ return any(c.type == "async" for c in node.children)
+
+
+def _is_constant_for(node: Node) -> bool:
+ """True if a Python for-loop iterates a compile-time-constant bound.
+
+ Catches ``for _ in range(<int literals>)``, ``for x in (<literal>)``, and —
+ a refinement over the Phase-0 probe — ``for x in ALL_CAPS`` (a named
+ module constant by convention). ``while`` loops are never constant.
+ """
+ if node.type != "for_statement":
+ return False
+ right = node.child_by_field_name("right")
+ if right is None:
+ return False
+ if right.type in ("list", "tuple", "set"):
+ return True
+ # A bare ALL_CAPS identifier is a named constant by convention.
+ if right.type == "identifier" and right.text is not None:
+ name = right.text.decode("utf-8", "replace")
+ if name.isupper() and len(name) > 1:
+ return True
+ if right.type == "call":
+ fn = right.child_by_field_name("function")
+ if fn is None or (fn.text or b"").decode("utf-8", "replace") != "range":
+ return False
+ args = right.child_by_field_name("arguments")
+ if args is None:
+ return False
+ for a in args.children:
+ if not a.is_named:
+ continue
+ if a.type == "integer":
+ continue
+ if a.type == "unary_operator" and any(c.type == "integer" for c in a.children):
+ continue
+ return False # a non-literal arg (e.g. len(x)) ⇒ data-dependent
+ return True
+ return False
+
+
+def _blocking_sync_api(root: str, method: str) -> str | None:
+ """The offending API name if ``root.method`` is a known blocking sync call.
+
+ A small, high-precision allowlist (mirrors ruff ASYNC210/230/251): these
+ are always-synchronous stdlib / ``requests`` calls that block the event
+ loop when run inside an ``async def``.
+ """
+ if root == "time" and method == "sleep":
+ return "time.sleep"
+ if root == "requests" and method in HTTP_VERBS:
+ return f"requests.{method}"
+ if root == "subprocess" and method in PY_SUBPROC_METHODS:
+ return f"subprocess.{method}"
+ if root == "os" and method == "system":
+ return "os.system"
+ if root == "open" and method == "open":
+ return "open"
+ return None
+
+
+def _rhs_is_stringish(node: Node, language: str) -> bool:
+ """True if an augmented-assignment's RHS is provably string-typed.
+
+ Precision-first: only a string/template literal directly on the RHS (or as
+ an operand of a ``+`` on the RHS) counts. ``s += chunk`` where ``chunk`` is
+ an opaque variable is NOT flagged — we refuse to guess a numeric ``+=`` is
+ a string concat.
+ """
+ right = node.child_by_field_name("right")
+ if right is None:
+ return False
+ string_kinds = _PY_STRING_KINDS if language == "python" else _TS_STRING_KINDS
+ if right.type in string_kinds:
+ return True
+ if right.type in ("binary_operator", "binary_expression"):
+ return any(c.is_named and c.type in string_kinds for c in right.children)
+ return False
+
+
+def _is_string_concat(node: Node, language: str) -> bool:
+ """True if *node* is a ``+=`` string accumulation."""
+ if node.type not in _AUG_ASSIGN_KINDS:
+ return False
+ if not any(c.type == "+=" for c in node.children):
+ return False
+ return _rhs_is_stringish(node, language)
+
+
+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``).
+ """
+ call_kinds = lmap.call_kinds
+ if not call_kinds:
+ return [], {}
+
+ io_names = collect_io_names(root, language)
+ has_db_import = any(k == "db" for k in io_names.values())
+ is_py = language == "python"
+ loop_kinds = lmap.loop_kinds
+ fn_kinds = lmap.function_kinds
+ lambda_kinds = lmap.lambda_kinds
+ 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)]
+ while stack:
+ node, loop_depth, in_async, func_name = stack.pop()
+ t = node.type
+
+ is_loop = t in loop_kinds
+ if is_loop and is_py and _is_constant_for(node):
+ is_loop = False
+
+ entering_fn = t in fn_kinds or t in lambda_kinds
+ 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
+ if t in fn_kinds:
+ next_func = _perf_func_name(node) or func_name
+
+ if t in call_kinds:
+ method = _callee_method_name(node) or ""
+ root_name = _callee_root_name(node) or ""
+ parent = node.parent
+ awaited = parent is not None and "await" in parent.type
+ line = node.start_point[0] + 1
+ 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))
+ if is_py and in_async and not awaited:
+ api = _blocking_sync_api(root_name, method)
+ if api is not None:
+ hits.append(PerfHit("blocking_sync_in_async", line, next_func, api))
+ elif loop_depth >= 1 and _is_string_concat(node, language):
+ hits.append(PerfHit("string_concat_in_loop", node.start_point[0] + 1, next_func, ""))
+
+ if is_loop:
+ # Only the loop BODY runs per-iteration; the ``for x in <iterable>``
+ # header / ``while <cond>`` condition runs once.
+ body = node.child_by_field_name("body")
+ if body is not None:
+ # NB: tree-sitter Node wrappers are not singletons, so compare
+ # 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))
+ else:
+ for c in node.children:
+ stack.append((c, loop_depth + 1, next_async, next_func))
+ else:
+ for c in node.children:
+ stack.append((c, loop_depth, next_async, next_func))
+
+ # Dedup chained sinks: ``result.scalars().all()`` parses as two call nodes
+ # on one line (the ``.scalars()`` sink and the ``.all()`` materializer) —
+ # one logical query, one finding. Collapse per (kind, line, function).
+ seen: set[tuple[str, int, str | None]] = set()
+ deduped: list[PerfHit] = []
+ for h in hits:
+ key = (h.kind, h.line, h.function)
+ if key in seen:
+ continue
+ seen.add(key)
+ deduped.append(h)
+ deduped.sort(key=lambda h: (h.line, h.kind))
+ return deduped, io_names
+
+
# ----------------------------------------------------------------------
# Class-level analysis (LCOM4 / god-class)
# ----------------------------------------------------------------------
@@ -1154,11 +1465,14 @@ 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)
return FileComplexity(
functions=functions,
classes=classes,
file_nloc=_count_file_nloc_tree(tree.root_node, source),
error_handling_hits=_collect_error_handling(tree.root_node, language, lmap),
+ perf_hits=perf_hits,
+ io_boundary_names=io_boundary_names,
)
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index e491965bc..1e2bb209a 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -663,6 +663,8 @@ class HealthAnalyzer:
repo_function_mod_p80=repo_function_mod_p80,
repo_active_contributors_90d=repo_active_contributors_90d,
error_handling_hits=fcx.error_handling_hits,
+ perf_hits=fcx.perf_hits,
+ io_boundary_names=set(fcx.io_boundary_names),
)
biomarker_results = detect_all(ctx, disabled=disabled)
diff --git a/packages/core/src/repowise/core/analysis/health/perf/__init__.py b/packages/core/src/repowise/core/analysis/health/perf/__init__.py
new file mode 100644
index 000000000..02523003f
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/perf/__init__.py
@@ -0,0 +1,13 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from .io_boundaries import classify_call_sink, collect_io_names
+
+__all__ = ["classify_call_sink", "collect_io_names"]
diff --git a/packages/core/src/repowise/core/analysis/health/perf/io_boundaries.py b/packages/core/src/repowise/core/analysis/health/perf/io_boundaries.py
new file mode 100644
index 000000000..eb1a8b19e
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/perf/io_boundaries.py
@@ -0,0 +1,291 @@
+"""Resolve a loop-nested call site to a typed I/O boundary.
+
+The performance pass needs to answer one question per call: *is this an
+execution of an I/O boundary (db / network / filesystem / subprocess), or just
+ordinary computation?* That decomposes into two pieces, both here:
+
+1. **Dependency classification** — which imported names in a file originate from
+ an I/O library, and of what kind. This reuses the shared
+ :func:`...ingestion.external_systems.io_kind.classify_io_kind` table
+ (Primitive 1) rather than a perf-private list, so the same maintained
+ classification powers C4 typing, the perf pass, and a future security layer.
+ :func:`collect_io_names` walks a file's import nodes and binds each imported
+ identifier to its ``io_kind``.
+
+2. **Execution-sink gating** — a *query builder* (`select().where()`) is not a
+ round-trip; only *executing* it is. :func:`classify_call_sink` returns a
+ boundary kind ONLY for the execution sinks (``.execute`` / ``.scalars`` /
+ ``.commit`` / ``subprocess.run`` / awaited HTTP / ``fetch`` / prisma
+ verbs...), never for builder chaining. This is the refinement that took the
+ Phase-0 probe from a noisy lexicon to a high-precision signal.
+
+The riskiest stratum is the ambiguous DBAPI result accessors (``.all`` /
+``.first`` / ``.one``) and ``.commit`` — they collide with ordinary collection
+methods (``list.commit`` does not exist, but ``results.all`` and a GitPython
+``repo.commit()`` do). Those are gated on **DB-typed-receiver evidence**: the
+file must import a db library, or the call's receiver root must bind to one.
+This drops the GitPython ``repo.commit()`` false positives the probe flagged.
+
+This module is pure: it takes already-extracted ``(root, method, awaited,
+is_attribute)`` tuples plus the resolved ``io_names`` map. The AST extraction
+lives in the walker. Unknown inputs return ``None`` ("not an I/O sink") so the
+detector degrades to "no signal", never a false positive.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Protocol
+
+from ....ingestion.external_systems.io_kind import classify_io_kind
+
+# Languages whose call grammar + import shape this module understands. The perf
+# pass is opt-in elsewhere (an empty boundary map ⇒ no hits).
+TS_LIKE: frozenset[str] = frozenset({"typescript", "javascript"})
+
+# ---------------------------------------------------------------------------
+# Execution-sink lexicons (the gate). Method-name based.
+# ---------------------------------------------------------------------------
+HTTP_VERBS: frozenset[str] = frozenset(
+ {"get", "post", "put", "delete", "patch", "head", "options", "request", "send", "stream"}
+)
+
+# Python DBAPI / SQLAlchemy execution sinks. Split into three strata so the
+# ambiguous accessors can be gated harder than the unambiguous ones:
+# * UNAMBIGUOUS — names that essentially only exist on a cursor / session /
+# result object. Trusted on any attribute call.
+# * COMMIT — ``.commit`` is unambiguous as a DB verb but collides with
+# GitPython's ``repo.commit()``; gated on db evidence.
+# * AMBIGUOUS — ``.all`` / ``.first`` / ``.one`` collide with ordinary
+# collection/query helpers; the riskiest stratum, gated on db evidence.
+PY_DB_UNAMBIGUOUS: frozenset[str] = frozenset(
+ {
+ "execute",
+ "executemany",
+ "scalars",
+ "scalar",
+ "scalar_one",
+ "scalar_one_or_none",
+ "fetchone",
+ "fetchall",
+ "fetchmany",
+ }
+)
+PY_DB_COMMIT: frozenset[str] = frozenset({"commit"})
+PY_DB_AMBIGUOUS: frozenset[str] = frozenset({"all", "first", "one", "one_or_none"})
+PY_SUBPROC_METHODS: frozenset[str] = frozenset(
+ {"run", "call", "check_call", "check_output", "Popen"}
+)
+
+# TypeScript / JavaScript. Only DISTINCTIVE method names are trusted without
+# import resolution: bare create/update/delete/count/exec collide hard with
+# Map/Set/Array/RegExp and are pure noise. Generic fs/subprocess verbs are only
+# trusted when the root binds to an imported node:fs / child_process.
+PRISMA_METHODS: frozenset[str] = frozenset(
+ {
+ "findMany",
+ "findUnique",
+ "findFirst",
+ "findUniqueOrThrow",
+ "findFirstOrThrow",
+ "createMany",
+ "updateMany",
+ "deleteMany",
+ "upsert",
+ "aggregate",
+ "groupBy",
+ }
+)
+TS_FS_METHODS: frozenset[str] = frozenset(
+ {"readFileSync", "writeFileSync", "appendFileSync", "readdirSync"}
+)
+# Synchronous execution-sink verbs across the TS I/O ecosystems. Used to gate a
+# call on an imported I/O package: a *round-trip* method (or an awaited call),
+# never a sync helper like ``axios.isCancel`` / ``axios.create`` / a query
+# *builder* like ``.where()``. Async sinks (``axios.get``, prisma queries,
+# ``fs/promises`` reads) are caught by the ``awaited`` arm instead.
+TS_SINK_METHODS: frozenset[str] = (
+ HTTP_VERBS
+ | PRISMA_METHODS
+ | TS_FS_METHODS
+ | frozenset(
+ {
+ "query",
+ "execute",
+ "exec",
+ "execSync",
+ "spawn",
+ "spawnSync",
+ "execFile",
+ "execFileSync",
+ "raw",
+ "$queryRaw",
+ "$executeRaw",
+ }
+ )
+)
+
+# Tokens that are syntax, not bindable import names.
+_IMPORT_KW: frozenset[str] = frozenset(
+ {"import", "from", "as", "require", "const", "let", "var", "default", "type", "typeof"}
+)
+
+
+class _NodeLike(Protocol):
+ """Duck type of a tree-sitter node (avoids importing tree_sitter here)."""
+
+ type: str
+ text: bytes | None
+
+ @property
+ def children(self) -> list[_NodeLike]: ...
+
+
+def _decode(node: _NodeLike) -> str:
+ return (node.text or b"").decode("utf-8", "replace")
+
+
+def _classify_import(node: _NodeLike) -> tuple[str | None, list[str]]:
+ """``(io_kind, bound_names)`` for an import node, else ``(None, [])``.
+
+ The module is classified through the shared :func:`classify_io_kind` table:
+ every candidate token (a quoted TS source like ``"node:fs"`` /
+ ``"@prisma/client"``, or a Python dotted module's full path + top-level
+ package) is tried until one resolves. When it does, every importable
+ identifier in the statement is bound to that kind. Over-binding is
+ deliberate and harmless: an imported name only becomes a finding when it is
+ later *called as an execution sink*, which a non-I/O symbol never is.
+ """
+ text = _decode(node)
+ candidates: set[str] = set()
+ # TS / JS module sources are quoted string literals.
+ for m in re.findall(r"""["']([^"']+)["']""", text):
+ candidates.add(m)
+ candidates.add(m.split("/")[0])
+ # Python dotted modules / bare identifiers.
+ for tok in re.findall(r"[A-Za-z0-9_.:@/]+", text):
+ candidates.add(tok)
+ candidates.add(tok.split(".")[0])
+
+ kind: str | None = None
+ for cand in candidates:
+ resolved = classify_io_kind(cand)
+ if resolved:
+ kind = resolved
+ break
+ if kind is None:
+ return None, []
+
+ bound = [
+ t for t in re.split(r"[^A-Za-z0-9_]+", text) if t.isidentifier() and t not in _IMPORT_KW
+ ]
+ return kind, bound
+
+
+def collect_io_names(tree_root: _NodeLike, language: str) -> dict[str, str]:
+ """Map every imported identifier that resolves to an I/O library → io_kind.
+
+ A whole-tree scan of import nodes (import statements live at module scope
+ but a defensive full walk also catches function-local imports). Names that
+ do not originate from a classified I/O library are simply absent.
+ """
+ names: dict[str, str] = {}
+ stack: list[_NodeLike] = [tree_root]
+ while stack:
+ node = stack.pop()
+ if "import" in node.type:
+ kind, bound = _classify_import(node)
+ if kind is not None:
+ for name in bound:
+ names.setdefault(name, kind)
+ for child in node.children:
+ stack.append(child)
+ return names
+
+
+def _py_sink_kind(
+ root: str,
+ method: str,
+ awaited: bool,
+ is_attribute: bool,
+ io_names: dict[str, str],
+ has_db_import: bool,
+) -> str | None:
+ root_kind = io_names.get(root)
+ db_evidence = has_db_import or root_kind == "db"
+
+ if method in PY_DB_UNAMBIGUOUS:
+ # A real DB sink is always a method on a session/cursor/result object;
+ # a bare identifier call (the builtin ``all(...)``) is not.
+ return "db" if is_attribute else None
+ if method in PY_DB_COMMIT:
+ # ``.commit`` is a DB verb but GitPython exposes ``repo.commit()``.
+ # Require db evidence in the file / on the receiver.
+ return "db" if (is_attribute and db_evidence) else None
+ if method in PY_DB_AMBIGUOUS:
+ # ``.all`` / ``.first`` / ``.one`` collide with ordinary collection
+ # helpers — the riskiest stratum. Gate on db evidence.
+ return "db" if (is_attribute and db_evidence) else None
+ if root == "subprocess" and method in PY_SUBPROC_METHODS:
+ return "subprocess"
+ if method == "Popen":
+ return "subprocess"
+ if root == "open" and method == "open": # bare ``open(...)`` builtin
+ return "filesystem"
+ if method == "urlopen":
+ return "network"
+ if root_kind == "network" and method in HTTP_VERBS:
+ return "network"
+ if awaited and root_kind == "network":
+ return "network"
+ return None
+
+
+def _ts_sink_kind(
+ root: str,
+ method: str,
+ awaited: bool,
+ io_names: dict[str, str],
+) -> str | None:
+ if method == "fetch": # the ``fetch(...)`` global — no import to resolve
+ return "network"
+ root_kind = io_names.get(root)
+ if root_kind is not None:
+ # A call on an imported I/O package (``axios.get`` / ``db.query``) is a
+ # sink only when it is a known round-trip verb or is awaited — NOT a
+ # sync helper (``axios.isCancel`` / ``axios.create``) or a query builder
+ # (``.where()`` / ``.select()``), which over-fired before this gate.
+ if method in TS_SINK_METHODS or awaited:
+ return root_kind
+ return None
+ if method in PRISMA_METHODS: # distinctive prisma-client verbs
+ return "db"
+ if method in TS_FS_METHODS: # distinctive sync-fs verbs
+ return "filesystem"
+ return None
+
+
+def classify_call_sink(
+ language: str,
+ root: str,
+ method: str,
+ *,
+ awaited: bool,
+ is_attribute: bool,
+ io_names: dict[str, str],
+ has_db_import: bool,
+) -> str | None:
+ """Boundary kind for a call site if it is an execution sink, else ``None``.
+
+ ``root`` is the callee's root identifier (``a.b.c()`` → ``"a"``); ``method``
+ is the rightmost member (``x.execute()`` → ``"execute"``); ``awaited`` is
+ whether the call is the operand of an ``await``; ``is_attribute`` is whether
+ the callee is a member access (vs a bare-identifier call). ``io_names`` maps
+ imported names to their ``io_kind`` (from :func:`collect_io_names`);
+ ``has_db_import`` is whether the file imports any db library.
+ """
+ if language == "python":
+ return _py_sink_kind(root, method, awaited, is_attribute, io_names, has_db_import)
+ if language in TS_LIKE:
+ return _ts_sink_kind(root, method, awaited, io_names)
+ return None
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index be737e856..98b5895da 100644
--- a/packages/core/src/repowise/core/analysis/health/scoring.py
+++ b/packages/core/src/repowise/core/analysis/health/scoring.py
@@ -206,6 +206,12 @@ _BIOMARKER_DIMENSIONS: dict[str, set[str]] = {
"god_class": {"defect", "maintainability"},
"large_method": {"defect", "maintainability"},
"nested_complexity": {"defect", "maintainability"},
+ # Performance-risk detectors contribute to ``performance`` ONLY. They are
+ # NOT defect predictors and must never move the surfaced (defect) score -
+ # that exclusion is what keeps the defect golden guarantee intact.
+ "io_in_loop": {"performance"},
+ "string_concat_in_loop": {"performance"},
+ "blocking_sync_in_async": {"performance"},
}
# Maintainability per-biomarker weight multipliers. Expert-set by definition -
@@ -257,6 +263,43 @@ _MAINTAINABILITY_HOME: frozenset[str] = frozenset(
)
+# ---------------------------------------------------------------------------
+# Performance dimension (PR3). Shipped at a small, ADVISORY weight - the whole
+# pillar is bounded by a single 1.0 category cap, so even a file riddled with
+# perf hits loses at most one health point on this dimension. Promotion to a
+# co-equal weight waits on PR4's cross-function precision study.
+# ---------------------------------------------------------------------------
+
+# Per-biomarker weight on the performance dimension. ``io_in_loop`` is the
+# gate-cleared core (measured 79% precision, Phase 0) and carries full weight;
+# ``string_concat_in_loop`` and ``blocking_sync_in_async`` ride the same pass
+# at a reduced advisory weight pending their own spot-check (see
+# MARKER_BACKLOG.md). Unknown biomarkers fall back to 1.0.
+_PERFORMANCE_WEIGHT_MULTIPLIER: dict[str, float] = {
+ "io_in_loop": 1.0,
+ "blocking_sync_in_async": 0.7,
+ "string_concat_in_loop": 0.5,
+}
+
+# All perf biomarkers share one ``performance`` category, so the single cap
+# below bounds the entire dimension's deduction.
+_PERFORMANCE_CATEGORY: dict[str, str] = {
+ "io_in_loop": "performance",
+ "string_concat_in_loop": "performance",
+ "blocking_sync_in_async": "performance",
+}
+
+# One bounded performance category cap. ~1.0 keeps performance advisory.
+_PERFORMANCE_CATEGORY_CAPS: dict[str, float] = {
+ "performance": 1.0,
+}
+
+# Perf biomarkers home to ``performance`` for display / per-pillar filtering.
+_PERFORMANCE_HOME: frozenset[str] = frozenset(
+ {"io_in_loop", "string_concat_in_loop", "blocking_sync_in_async"}
+)
+
+
def severity_deduction(sev: Severity) -> float:
return _SEVERITY_DEDUCTION.get(sev, 0.5)
@@ -272,12 +315,20 @@ def biomarker_category(name: str) -> str:
def dimensions_for(name: str) -> set[str]:
- """Dimensions a biomarker's deduction contributes to (always >= ``{"defect"}``)."""
+ """Dimensions a biomarker's deduction contributes to.
+
+ Unlisted biomarkers default to ``{"defect"}`` (the historical single score).
+ Performance-only detectors map to ``{"performance"}`` and are deliberately
+ excluded from ``defect`` - that exclusion is what keeps the defect golden
+ guarantee intact.
+ """
return _BIOMARKER_DIMENSIONS.get(name, {"defect"})
def biomarker_dimension(name: str) -> str:
"""The finding's single 'home' dimension for display / per-pillar filtering."""
+ if name in _PERFORMANCE_HOME:
+ return "performance"
if name in _MAINTAINABILITY_HOME:
return "maintainability"
return "defect"
@@ -293,6 +344,16 @@ def maintainability_category(name: str) -> str:
return _MAINTAINABILITY_CATEGORY.get(name, "size_and_complexity")
+def performance_weight(name: str) -> float:
+ """Performance multiplier; 1.0 for unknown biomarkers."""
+ return _PERFORMANCE_WEIGHT_MULTIPLIER.get(name, 1.0)
+
+
+def performance_category(name: str) -> str:
+ """Default to ``performance`` for unknown biomarkers (single capped category)."""
+ return _PERFORMANCE_CATEGORY.get(name, "performance")
+
+
def _score_dimension(
results_list: list[BiomarkerResult],
weight_fn: Callable[[str], float],
@@ -344,9 +405,10 @@ def score_file(results: Iterable[BiomarkerResult]) -> tuple[dict[str, float | No
- ``scores`` maps each dimension in ``DIMENSIONS`` to its score.
``scores["defect"]`` is the historical single score - byte-for-byte
identical to the pre-split ``score_file`` (the load-bearing guarantee).
- ``scores["performance"]`` is ``None`` until the performance detectors land
- (no biomarker contributes to it yet), signalling "not measured" rather
- than a misleading perfect 10.0.
+ ``scores["performance"]`` is now measured (PR3): a file with no perf
+ findings scores 10.0; the perf detectors deduct under a single bounded
+ ``performance`` cap. It is still capped low (advisory) and never blends
+ into ``defect``.
- ``defect_deductions`` is each finding's contribution to the DEFECT score
after category capping, parallel to *results*. It populates
``HealthFindingData.health_impact`` - a defect-pillar quantity - so the
@@ -354,9 +416,22 @@ def score_file(results: Iterable[BiomarkerResult]) -> tuple[dict[str, float | No
"""
results_list = list(results)
- defect_score, defect_deductions = _score_dimension(
- results_list, biomarker_weight, biomarker_category, CATEGORY_CAPS
+ # DEFECT: only biomarkers whose dimensions include ``defect`` deduct. EVERY
+ # historical biomarker does (``dimensions_for`` defaults to ``{"defect"}``),
+ # so this reproduces the pre-split single score byte-for-byte; the new
+ # performance-only detectors are excluded and never move the surfaced score.
+ # ``defect_deductions`` stays parallel to the FULL ``results_list`` (perf
+ # findings get 0.0 defect impact) so ``attach_impacts`` can zip 1:1.
+ defect_idx = [
+ i for i, r in enumerate(results_list) if "defect" in dimensions_for(r.biomarker_type)
+ ]
+ defect_results = [results_list[i] for i in defect_idx]
+ defect_score, defect_sub = _score_dimension(
+ defect_results, biomarker_weight, biomarker_category, CATEGORY_CAPS
)
+ defect_deductions = [0.0] * len(results_list)
+ for sub_i, orig_i in enumerate(defect_idx):
+ defect_deductions[orig_i] = defect_sub[sub_i]
maint_results = [
r for r in results_list if "maintainability" in dimensions_for(r.biomarker_type)
@@ -368,12 +443,20 @@ def score_file(results: Iterable[BiomarkerResult]) -> tuple[dict[str, float | No
_MAINTAINABILITY_CATEGORY_CAPS,
)
+ # PERFORMANCE: now that the detectors are registered, every file is measured
+ # - a clean file scores 10.0 (no perf findings), not ``None``.
+ perf_results = [r for r in results_list if "performance" in dimensions_for(r.biomarker_type)]
+ perf_score, _ = _score_dimension(
+ perf_results,
+ performance_weight,
+ performance_category,
+ _PERFORMANCE_CATEGORY_CAPS,
+ )
+
scores: dict[str, float | None] = {
"defect": defect_score,
"maintainability": maint_score,
- # No performance detectors exist yet; the dimension is defined but empty
- # until PR3 registers its biomarkers. ``None`` = not measured.
- "performance": None,
+ "performance": perf_score,
}
return scores, defect_deductions
diff --git a/tests/fixtures/lang_samples/python/perf_io_in_loop.py b/tests/fixtures/lang_samples/python/perf_io_in_loop.py
new file mode 100644
index 000000000..baded8e5a
--- /dev/null
+++ b/tests/fixtures/lang_samples/python/perf_io_in_loop.py
@@ -0,0 +1,85 @@
+"""Fixture for the performance pass (io_in_loop / string_concat / blocking_sync).
+
+Hand-counted expectations live in ``test_perf_io_in_loop.py``. Every POSITIVE is
+a genuine per-iteration I/O boundary; every NEGATIVE is a shape the loop-body
+scoping / constant-loop skip / execution-sink gate must NOT flag.
+"""
+
+import os
+import subprocess
+import time
+
+import httpx
+import requests
+from sqlalchemy import select
+
+
+# --- POSITIVES -------------------------------------------------------------
+def db_execute_in_loop(session, repos):
+ for repo in repos: # data-dependent loop
+ session.execute(select(repo)) # POSITIVE: db sink per iteration
+
+
+def subprocess_in_loop(paths):
+ for p in paths:
+ subprocess.run(["git", "status"], cwd=p) # POSITIVE: subprocess
+
+
+def http_in_loop(urls):
+ for u in urls:
+ requests.get(u) # POSITIVE: network
+
+
+async def await_http_in_loop(client, urls):
+ for u in urls:
+ await client.get(u) # NEGATIVE: client root unresolved -> no false fire
+
+
+def string_concat_in_loop(rows):
+ out = ""
+ for r in rows:
+ out += "line\n" # POSITIVE: string concat
+ return out
+
+
+async def blocking_in_async(urls):
+ time.sleep(1) # POSITIVE: blocking sleep in async
+ requests.get(urls[0]) # POSITIVE: blocking sync http in async
+
+
+# --- NEGATIVES -------------------------------------------------------------
+def sink_in_loop_header(session, q):
+ for row in session.execute(q).scalars().all(): # NEGATIVE: header runs once
+ process(row)
+
+
+def constant_range(paths):
+ for _ in range(3): # NEGATIVE: constant-bounded loop
+ subprocess.run(["ls"])
+
+
+def constant_literal(client):
+ for url in ("a", "b"): # NEGATIVE: literal collection
+ client.get(url)
+
+
+def query_builder_in_loop(repos):
+ for repo in repos:
+ select(repo).where(repo.id == 1) # NEGATIVE: builder, not executed
+
+
+def pure_call_in_loop(items):
+ total = 0
+ for x in items:
+ total += compute(x) # NEGATIVE: numeric += / pure call
+ return total
+
+
+def sink_outside_loop(session, q):
+ result = session.execute(q) # NEGATIVE: runs once, not in a loop
+ return result
+
+
+def open_in_loop(paths):
+ for p in paths:
+ open(p).read() # POSITIVE: filesystem (bare open)
diff --git a/tests/fixtures/lang_samples/typescript/perf_io_in_loop.ts b/tests/fixtures/lang_samples/typescript/perf_io_in_loop.ts
new file mode 100644
index 000000000..3a1e368ce
--- /dev/null
+++ b/tests/fixtures/lang_samples/typescript/perf_io_in_loop.ts
@@ -0,0 +1,34 @@
+// Fixture for the performance pass (TypeScript io_in_loop).
+// Hand-counted expectations live in test_perf_io_in_loop.py.
+
+import axios from "axios";
+
+// --- POSITIVES ---
+async function fetchInLoop(urls: string[]) {
+ for (const u of urls) {
+ await fetch(u); // POSITIVE: network (fetch global)
+ }
+}
+
+async function axiosInLoop(urls: string[]) {
+ for (const u of urls) {
+ await axios.get(u); // POSITIVE: network (imported axios)
+ }
+}
+
+async function prismaInLoop(ids: number[]) {
+ for (const id of ids) {
+ await prisma.user.findMany({ where: { id } }); // POSITIVE: db (prisma verb)
+ }
+}
+
+// --- NEGATIVES ---
+async function fetchOutsideLoop(u: string) {
+ return await fetch(u); // NEGATIVE: runs once
+}
+
+function mapDeleteInLoop(m: Map<string, number>, keys: string[]) {
+ for (const k of keys) {
+ m.delete(k); // NEGATIVE: Map.delete is not a db sink
+ }
+}
diff --git a/tests/unit/health/test_perf_io_in_loop.py b/tests/unit/health/test_perf_io_in_loop.py
new file mode 100644
index 000000000..d92b5710c
--- /dev/null
+++ b/tests/unit/health/test_perf_io_in_loop.py
@@ -0,0 +1,253 @@
+"""Unit tests for the performance pass + perf biomarkers (PR3).
+
+Covers the walker's ``_collect_perf_hits`` (loop-body scoping, constant-loop
+skip, execution-sink gating, dependency classification) and the three perf
+biomarkers that lift its hits into findings. Like the other walker tests,
+tree-sitter grammar availability is best-effort: a missing grammar skips.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+import pytest
+
+from repowise.core.analysis.health.biomarkers.base import FileContext
+from repowise.core.analysis.health.biomarkers.blocking_sync_in_async import (
+ BlockingSyncInAsyncDetector,
+)
+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.biomarkers.string_concat_in_loop import (
+ StringConcatInLoopDetector,
+)
+from repowise.core.analysis.health.complexity import PerfHit, walk_file
+from repowise.core.analysis.health.scoring import score_file
+
+_FIXTURE_DIR = Path(__file__).resolve().parents[2] / "fixtures" / "lang_samples"
+
+
+def _walk(rel: str, lang: str):
+ path = _FIXTURE_DIR / rel
+ fc = walk_file(str(path), lang, path.read_bytes())
+ return fc
+
+
+def _kinds(perf_hits) -> Counter:
+ return Counter(h.kind for h in perf_hits)
+
+
+# ---------------------------------------------------------------------------
+# Walker pass — inline micro-fixtures (precise, line-stable)
+# ---------------------------------------------------------------------------
+
+# (language, source, expected (kind, detail) multiset, note)
+_CASES = [
+ (
+ "python",
+ b"def f(session, repos):\n"
+ b" from sqlalchemy import select\n"
+ b" for r in repos:\n"
+ b" session.execute(select(r))\n",
+ [("io_in_loop", "db")],
+ "db execute in a data-dependent loop",
+ ),
+ (
+ "python",
+ b"import subprocess\n"
+ b"def f(paths):\n"
+ b" for p in paths:\n"
+ b" subprocess.run(['ls'], cwd=p)\n",
+ [("io_in_loop", "subprocess")],
+ "subprocess spawn per iteration",
+ ),
+ (
+ "python",
+ b"async def f(session, q):\n"
+ b" for row in session.execute(q).scalars().all():\n"
+ b" use(row)\n",
+ [],
+ "sink in the for-header runs once (loop-body scoping)",
+ ),
+ (
+ "python",
+ b"import subprocess\n"
+ b"def f():\n"
+ b" for _ in range(3):\n"
+ b" subprocess.run(['ls'])\n",
+ [],
+ "constant-bounded range loop is skipped",
+ ),
+ (
+ "python",
+ b"import subprocess\n"
+ b"ENDPOINTS = load()\n"
+ b"def f():\n"
+ b" for e in ENDPOINTS:\n"
+ b" subprocess.run(e)\n",
+ [],
+ "ALL_CAPS named-constant collection is skipped",
+ ),
+ (
+ "python",
+ b"from sqlalchemy import select\n"
+ b"def f(repos):\n"
+ b" for r in repos:\n"
+ b" select(r).where(r.id == 1)\n",
+ [],
+ "query builder (not executed) is not a sink",
+ ),
+ (
+ "python",
+ b"def f(items):\n"
+ b" total = 0\n"
+ b" for x in items:\n"
+ b" total += compute(x)\n"
+ b" return total\n",
+ [],
+ "numeric += / pure call in a loop is clean",
+ ),
+ (
+ "python",
+ b"import git\n"
+ b"def f(repos):\n"
+ b" for r in repos:\n"
+ b" r.commit()\n",
+ [],
+ "git repo.commit() without a db import is gated out",
+ ),
+ (
+ "python",
+ b"def f(rows):\n"
+ b" s = ''\n"
+ b" for r in rows:\n"
+ b" s += 'x'\n"
+ b" return s\n",
+ [("string_concat_in_loop", "")],
+ "string += in a loop",
+ ),
+ (
+ "python",
+ b"import time\n"
+ b"async def f():\n"
+ b" time.sleep(1)\n",
+ [("blocking_sync_in_async", "time.sleep")],
+ "blocking sleep in async",
+ ),
+ (
+ "typescript",
+ b"async function f(urls) {\n for (const u of urls) {\n await fetch(u);\n }\n}\n",
+ [("io_in_loop", "network")],
+ "fetch in a loop",
+ ),
+ (
+ "typescript",
+ b"function f(m, keys) {\n for (const k of keys) {\n m.delete(k);\n }\n}\n",
+ [],
+ "Map.delete is not a db sink",
+ ),
+ (
+ "typescript",
+ b"import axios from 'axios';\n"
+ b"function f(items) {\n"
+ b" for (const u of items) {\n"
+ b" if (axios.isCancel(u)) continue;\n"
+ b" axios.create();\n"
+ b" }\n"
+ b"}\n",
+ [],
+ "sync helpers on an imported I/O pkg (isCancel/create) are not sinks",
+ ),
+]
+
+
[email protected]("lang,source,expected,note", _CASES, ids=[c[3] for c in _CASES])
+def test_perf_pass_cases(lang, source, expected, note):
+ fc = walk_file(f"t.{lang[:2]}", lang, source)
+ got = sorted((h.kind, h.detail) for h in fc.perf_hits)
+ assert got == sorted(expected), note
+
+
+# ---------------------------------------------------------------------------
+# Fixture files (the plan's tests/fixtures/lang_samples/*/perf_*)
+# ---------------------------------------------------------------------------
+
+
+def test_python_fixture_counts():
+ fc = _walk("python/perf_io_in_loop.py", "python")
+ counts = _kinds(fc.perf_hits)
+ assert counts["io_in_loop"] == 4 # db, subprocess, network, filesystem
+ assert counts["string_concat_in_loop"] == 1
+ assert counts["blocking_sync_in_async"] == 2
+ boundaries = {h.detail for h in fc.perf_hits if h.kind == "io_in_loop"}
+ assert boundaries == {"db", "subprocess", "network", "filesystem"}
+ # The import bridge resolved the I/O libraries.
+ assert {"requests", "httpx", "subprocess"} <= set(fc.io_boundary_names)
+
+
+def test_typescript_fixture_counts():
+ fc = _walk("typescript/perf_io_in_loop.ts", "typescript")
+ counts = _kinds(fc.perf_hits)
+ assert counts["io_in_loop"] == 3 # fetch, axios, prisma
+ assert {h.detail for h in fc.perf_hits} == {"network", "db"}
+
+
+# ---------------------------------------------------------------------------
+# Biomarkers — lift PerfHits into findings
+# ---------------------------------------------------------------------------
+
+
+def _ctx(perf_hits: list[PerfHit]) -> FileContext:
+ return FileContext(
+ file_path="x.py",
+ language="python",
+ nloc=10,
+ has_test_file=False,
+ module="x",
+ perf_hits=perf_hits,
+ )
+
+
+def test_io_in_loop_detector_lifts_hits():
+ ctx = _ctx([PerfHit("io_in_loop", 12, "f", "db")])
+ findings = IoInLoopDetector().detect(ctx)
+ assert len(findings) == 1
+ f = findings[0]
+ assert f.biomarker_type == "io_in_loop"
+ assert f.line_start == 12
+ assert f.details["boundary_kind"] == "db"
+
+
+def test_detectors_only_consume_their_own_kind():
+ ctx = _ctx(
+ [
+ PerfHit("io_in_loop", 1, "f", "db"),
+ PerfHit("string_concat_in_loop", 2, "f", ""),
+ PerfHit("blocking_sync_in_async", 3, "f", "time.sleep"),
+ ]
+ )
+ assert len(IoInLoopDetector().detect(ctx)) == 1
+ assert len(StringConcatInLoopDetector().detect(ctx)) == 1
+ assert len(BlockingSyncInAsyncDetector().detect(ctx)) == 1
+
+
+def test_no_perf_hits_yields_no_findings():
+ assert IoInLoopDetector().detect(_ctx([])) == []
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: detect_all + score_file populate the performance dimension only
+# ---------------------------------------------------------------------------
+
+
+def test_perf_findings_score_performance_not_defect():
+ ctx = _ctx([PerfHit("io_in_loop", 5, "f", "db") for _ in range(2)])
+ results = detect_all(ctx)
+ perf = [r for r in results if r.biomarker_type == "io_in_loop"]
+ assert len(perf) == 2
+ scores, deductions = score_file(results)
+ assert scores["defect"] == 10.0 # perf never touches the surfaced score
+ assert scores["performance"] < 10.0
+ # Every perf finding carries 0 defect-pillar impact.
+ assert all(d == 0.0 for d in deductions)
diff --git a/tests/unit/health/test_scoring_dimensions.py b/tests/unit/health/test_scoring_dimensions.py
index d5cf26818..860bac83a 100644
--- a/tests/unit/health/test_scoring_dimensions.py
+++ b/tests/unit/health/test_scoring_dimensions.py
@@ -189,17 +189,68 @@ def test_score_file_returns_all_dimensions():
assert set(scores) == set(DIMENSIONS)
-def test_performance_is_none_until_detectors_land():
- """No performance biomarkers exist yet -> the dimension is null, not 10.0."""
+def test_performance_measured_with_no_findings_is_ten():
+ """The perf detectors are registered (PR3): a file with no perf findings is
+ measured at 10.0, not null. None of the defect/maintainability fixtures
+ carry perf biomarkers, so every one scores a clean 10.0 on performance."""
for fixture in _FIXTURES:
scores, _ = score_file(fixture)
- assert scores["performance"] is None
+ assert scores["performance"] == 10.0
def test_clean_file_is_ten_in_every_active_dimension():
scores, _ = score_file([])
assert scores["defect"] == 10.0
assert scores["maintainability"] == 10.0
+ assert scores["performance"] == 10.0
+
+
+# ---------------------------------------------------------------------------
+# Performance dimension
+# ---------------------------------------------------------------------------
+
+
+def test_perf_biomarker_does_not_touch_defect_or_maintainability():
+ """io_in_loop scores ONLY performance - the surfaced (defect) score and the
+ golden guarantee must be untouched by perf findings."""
+ findings = [_r("io_in_loop", Severity.MEDIUM)]
+ assert dimensions_for("io_in_loop") == {"performance"}
+ scores, deductions = score_file(findings)
+ assert scores["defect"] == 10.0
+ assert scores["maintainability"] == 10.0
+ assert scores["performance"] < 10.0
+ # Its defect-pillar health_impact is exactly 0 (it never moved defect).
+ assert deductions == [0.0]
+
+
+def test_perf_io_in_loop_deduction():
+ """io_in_loop MEDIUM (0.7) x weight 1.0 -> 9.3 performance."""
+ scores, _ = score_file([_r("io_in_loop", Severity.MEDIUM)])
+ assert scores["performance"] == 9.3
+
+
+def test_perf_category_cap_bounds_dimension():
+ """The single 1.0 performance cap bounds the whole pillar."""
+ findings = [_r("io_in_loop", Severity.MEDIUM) for _ in range(10)]
+ scores, _ = score_file(findings)
+ # 10 * 0.7 = 7.0 raw -> capped at 1.0 -> 9.0, never lower.
+ assert scores["performance"] == 9.0
+
+
+def test_perf_bonus_markers_advisory_weight():
+ """string_concat (0.5) and blocking_sync (0.7) ride at reduced weight."""
+ assert dimensions_for("string_concat_in_loop") == {"performance"}
+ assert dimensions_for("blocking_sync_in_async") == {"performance"}
+ s1, _ = score_file([_r("string_concat_in_loop", Severity.LOW)]) # 0.3 * 0.5
+ assert s1["performance"] == round(10.0 - 0.15, 2)
+ s2, _ = score_file([_r("blocking_sync_in_async", Severity.MEDIUM)]) # 0.7 * 0.7
+ assert s2["performance"] == round(10.0 - 0.49, 2)
+
+
+def test_perf_home_dimension():
+ assert biomarker_dimension("io_in_loop") == "performance"
+ assert biomarker_dimension("string_concat_in_loop") == "performance"
+ assert biomarker_dimension("blocking_sync_in_async") == "performance"
# ---------------------------------------------------------------------------