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.

fix(health): keep spawned jobs, inert call sites and bounded loops out of the perf queue (#3395)

Raghav Chamadiya220145e59a89
diff --git a/docs/layers/PERFORMANCE.md b/docs/layers/PERFORMANCE.md
index 067ee18b4..e68e0be8a 100644
--- a/docs/layers/PERFORMANCE.md
+++ b/docs/layers/PERFORMANCE.md
@@ -44,7 +44,7 @@ Each opportunity gets one state:
| `plan_ready` | A fix strategy whose transformation is proven safe |
| `advisory` | A strategy with a prerequisite Repowise cannot prove, such as bounded concurrency before parallelizing awaits against a database |
| `investigate` | No supported strategy; a person has to decide |
-| `expected` | The repetition is real and nothing should change, such as deleting N files, or the function is switched off by a constant flag (reason `gated_off`) or runs once per deploy, boot or incident (reason `cold_path`) |
+| `expected` | The repetition is real and nothing should change, such as deleting N files, or the function is switched off by a constant flag (reason `gated_off`) or runs once per deploy, boot or incident (reason `cold_path`), or its loop runs a fixed number of times (reason `bounded_loop`) |
A plan lists its edits, one step per call site and loop, each naming the call it
repeats. When every site reaches one sink, the step that adds a bulk form of that
@@ -58,6 +58,7 @@ The default queue holds production opportunities in the `plan_ready` and
`advisory` states. They are ranked by cost first; state only breaks ties.
Only opportunities whose cost is measured are in it. A loop whose size nothing measured is `cost_proof = unproven`, never leads, and shows only with the `proof=unproven` filter.
Each opportunity also says what runs its loop (`execution_role`: request, event consumer, scheduled job, startup, CLI, UI, tooling, test or unknown), and loops run per request rank above the rest. Roles are read for Python and TypeScript/JavaScript; other languages show `unknown`. The `role` filter lists any one role, or `all`.
+Work a request hands to `asyncio.create_task` and never waits for is a background job, not part of the request. An opportunity takes its role and loop size from the same live call sites, so a call site switched off by a constant flag or already chunked never leads it.
Everything else is counted by reason, not hidden:
diff --git a/packages/core/src/repowise/core/analysis/change_health/service.py b/packages/core/src/repowise/core/analysis/change_health/service.py
index 85e573035..682114057 100644
--- a/packages/core/src/repowise/core/analysis/change_health/service.py
+++ b/packages/core/src/repowise/core/analysis/change_health/service.py
@@ -489,6 +489,7 @@ _EXPECTED_TEXT: dict[str | None, str] = {
"loop_already_chunked": _INHERENT,
"gated_off": "Nothing to change while a constant-False flag switches this function off.",
"cold_path": "Runs once per deploy, boot or incident; not worth scheduling.",
+ "bounded_loop": "Nothing to change: the loop runs a fixed number of times.",
None: _INHERENT,
}
diff --git a/packages/core/src/repowise/core/analysis/execution_graph.py b/packages/core/src/repowise/core/analysis/execution_graph.py
index 755d92eb2..f01db7195 100644
--- a/packages/core/src/repowise/core/analysis/execution_graph.py
+++ b/packages/core/src/repowise/core/analysis/execution_graph.py
@@ -103,6 +103,32 @@ def _line_values(attrs: Mapping[str, Any]) -> tuple[int, ...]:
return tuple(line for line in raw if isinstance(line, int) and line > 0)
+def _spawn_lines(attrs: Mapping[str, Any]) -> frozenset[int]:
+ """Call lines that hand the callee to a task scheduler (``create_task(f())``)."""
+ return frozenset(line for line in attrs.get("spawn_lines") or () if isinstance(line, int))
+
+
+def _split_spawned(
+ source: str,
+ target: str,
+ lines: tuple[int, ...],
+ spawned: frozenset[int],
+ callers_with_site_metadata: set[str],
+ spawn_only: dict[str, list[str]],
+) -> tuple[int, ...]:
+ """The call lines that run the callee in its caller.
+
+ A spawned site is still an edge but never resolves as a call: its caller is
+ recorded as having site facts, so the name fallback cannot bind it either.
+ """
+ if not spawned:
+ return lines
+ callers_with_site_metadata.add(source)
+ if spawned.issuperset(lines):
+ _append_unique(spawn_only, source, target)
+ return tuple(line for line in lines if line not in spawned)
+
+
class ExecutionGraphIndex:
"""The shared read-only index over reliable execution edges.
@@ -125,6 +151,7 @@ class ExecutionGraphIndex:
"name",
"nodes",
"reverse",
+ "spawn_only",
)
def __init__(
@@ -150,6 +177,7 @@ class ExecutionGraphIndex:
call_only_seen: set[tuple[str, str]] = set()
callers_with_site_metadata: set[str] = set()
ranges: dict[str, list[tuple[int, int, str]]] = {}
+ spawn_only: dict[str, list[str]] = {}
if graph is not None:
try:
@@ -179,6 +207,16 @@ class ExecutionGraphIndex:
for source, target, data in graph_edges:
attrs = data or {}
edge_type = attrs.get("edge_type")
+ lines = _line_values(attrs) if edge_type == "calls" else ()
+ if lines:
+ lines = _split_spawned(
+ source,
+ target,
+ lines,
+ _spawn_lines(attrs),
+ callers_with_site_metadata,
+ spawn_only,
+ )
self._ingest_edge(
declaration_map,
declaration_seen if deduplicate_graph else None,
@@ -195,7 +233,7 @@ class ExecutionGraphIndex:
target,
edge_type,
attrs.get("resolution_origin"),
- _line_values(attrs) if edge_type == "calls" else (),
+ lines,
)
for source, targets in (declares or {}).items():
@@ -237,6 +275,8 @@ class ExecutionGraphIndex:
self._ranges = {path: tuple(values) for path, values in ranges.items()}
self._span_end = {node_id: end for values in ranges.values() for _, end, node_id in values}
self.in_degree = {node: len(callers) for node, callers in self.reverse.items()}
+ #: Edges whose every call site hands the callee to a task scheduler.
+ self.spawn_only = {key: frozenset(values) for key, values in spawn_only.items()}
@staticmethod
def _ingest_edge(
@@ -381,20 +421,23 @@ class ExecutionGraphIndex:
*,
max_depth: int | None = None,
stop_at: Container[str] = frozenset(),
+ skip: Mapping[str, Container[str]] | None = None,
) -> set[str]:
"""Reliable execution nodes reachable from all *seeds* in one BFS.
A node in *stop_at* is never entered, so nothing past it is reached
- through it.
+ through it. ``skip[node]`` names targets not followed from *node*.
"""
+ skip = skip or {}
reached = set(seeds)
queue: deque[tuple[str, int]] = deque((seed, 0) for seed in sorted(reached))
while queue:
node, depth = queue.popleft()
if max_depth is not None and depth >= max_depth:
continue
+ skipped = skip.get(node, ())
for target in self.forward.get(node, ()):
- if target not in reached and target not in stop_at:
+ if target not in reached and target not in stop_at and target not in skipped:
reached.add(target)
queue.append((target, depth + 1))
return reached
diff --git a/packages/core/src/repowise/core/analysis/execution_roles.py b/packages/core/src/repowise/core/analysis/execution_roles.py
index 2ac5b9500..43c23376d 100644
--- a/packages/core/src/repowise/core/analysis/execution_roles.py
+++ b/packages/core/src/repowise/core/analysis/execution_roles.py
@@ -420,14 +420,22 @@ class ExecutionRoles:
A hot walk stops at another role's declared seed (a route handler, a
registered job): that is where the other role's work begins. A seed
named only by convention does not stop it, because calling a function
- runs it whatever it is called.
+ runs it whatever it is called. A coroutine handed to a task scheduler
+ (``create_task(job())``) is not run by its caller: no walk follows that
+ edge, and the coroutine is a background job of its own.
"""
seeds = seed_roles(graph)
+ for targets in index.spawn_only.values():
+ for node in targets:
+ seeds.add("scheduled_job", node, strong=False)
reached: dict[str, ExecutionRole] = {}
for role in _HOT:
if seeds.by_role[role]:
stop_at = seeds.strong - seeds.by_role[role]
- for node in index.forward_reachable(seeds.by_role[role], stop_at=stop_at):
+ walk = index.forward_reachable(
+ seeds.by_role[role], stop_at=stop_at, skip=index.spawn_only
+ )
+ for node in walk:
reached.setdefault(node, role)
for role in ("startup", "cli"):
for node in seeds.by_role[role]:
diff --git a/packages/core/src/repowise/core/analysis/health/perf/actionability.py b/packages/core/src/repowise/core/analysis/health/perf/actionability.py
index 41e19b3dc..45c4889dd 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/actionability.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/actionability.py
@@ -28,11 +28,12 @@ OpportunityConfidence = Literal["high", "medium", "low"]
# ``expected``: the repetition is real and there is nothing to change, either
# by its nature or for a reason :func:`expected_reason` reads off the group
# (``gated_off``: a constant-false flag switches the function off;
-# ``cold_path``: it runs once per deploy, boot or incident).
+# ``cold_path``: it runs once per deploy, boot or incident;
+# ``bounded_loop``: the loop runs a fixed number of times).
ActionabilityState = Literal["plan_ready", "advisory", "investigate", "expected"]
-#: Reasons :func:`expected_reason` gives, in precedence order. The default
-#: queue counts each under its own name rather than as ``expected``.
+#: Reasons :func:`expected_reason` gives that the default queue counts under
+#: their own name, in precedence order; ``bounded_loop`` counts as ``expected``.
EXPECTED_REASONS: tuple[str, ...] = ("gated_off", "cold_path")
# Refusals that are facts about the code, not missing proofs: nothing to investigate.
@@ -291,14 +292,15 @@ def assess_fix(
return FixAssessment(None, ("supported_strategy_for_marker",))
-def expected_reason(members: Sequence[Any]) -> str | None:
+def expected_reason(members: Sequence[Any], magnitude: str | None = None) -> str | None:
"""Why a group needs no change whatever its strategy, or ``None``.
``gated_off``: every member sits in a function a constant-false flag in
its own file switches off. ``cold_path``: every loop owner is named for a
migration, startup, shutdown or crash recovery (:mod:`.cold_paths`), so it
- runs once per deploy, boot or incident. Reasons are checked in precedence
- order.
+ runs once per deploy, boot or incident. ``bounded_loop``: the group's loop
+ *magnitude* is proven bounded, so its cost does not grow. Reasons are
+ checked in precedence order.
"""
if not members:
return None
@@ -306,7 +308,7 @@ def expected_reason(members: Sequence[Any]) -> str | None:
return "gated_off"
if all(is_cold_path(facts.file_path, facts.function_name) for facts in members):
return "cold_path"
- return None
+ return "bounded_loop" if magnitude == "bounded" else None
def actionability(
diff --git a/packages/core/src/repowise/core/analysis/health/perf/dialects/python.py b/packages/core/src/repowise/core/analysis/health/perf/dialects/python.py
index e346d4a3d..f4af3d8b6 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/dialects/python.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/dialects/python.py
@@ -10,6 +10,7 @@ from __future__ import annotations
import builtins
import re
+from collections.abc import Iterator
from typing import TYPE_CHECKING, ClassVar
from ..loop_facts import BatchForm
@@ -172,7 +173,6 @@ _PY_NONLIST_BUILTINS: frozenset[str] = frozenset({"set", "dict", "frozenset"})
_PY_RESULT_PROJECTIONS: frozenset[str] = frozenset(
{"all", "scalars", "fetchall", "json", "data", "rows"}
)
-_PY_BOUND_NAME_RE = re.compile(r"(?i)retr|attempt")
# Raw SQL capped in its own text: ``sa.text("... LIMIT 1000")``.
_PY_SQL_LIMIT_RE = re.compile(rb"(?is)\bselect\b.*\blimit\s+\d+\b")
_PY_SQL_COMMENT_RE = re.compile(rb"--[^\n]*|/\*.*?\*/", re.S)
@@ -193,6 +193,88 @@ _PY_SEM_NAME_RE = re.compile(r"(?i)(sem|semaphore|limiter|limit)$")
_PY_MODEL_NAME_RE = re.compile(r"^[A-Z]\w*[a-z]\w*$")
+_PY_DEF_KINDS = frozenset({"function_definition", "lambda", "class_definition"})
+# Nodes an identifier sits in when it is the name being bound, not read.
+_PY_BINDING_PARENTS = frozenset(
+ {
+ "global_statement", "nonlocal_statement", "as_pattern_target", "aliased_import",
+ "import_from_statement", "import_statement", "parameters", "lambda_parameters",
+ "named_expression",
+ }
+)
+_PY_BINDING_WRAPPERS = frozenset(
+ {
+ "pattern_list", "tuple_pattern", "list_pattern", "typed_parameter", "default_parameter",
+ "typed_default_parameter", "list_splat_pattern", "dotted_name",
+ }
+)
+
+
+def _binds(ident: Node) -> bool:
+ """Whether *ident* is a name being bound (assigned, imported, a parameter)."""
+ cur, parent = ident, ident.parent
+ while parent is not None and parent.type in _PY_BINDING_WRAPPERS:
+ cur, parent = parent, parent.parent
+ if parent is None:
+ return False
+ if parent.type in ("assignment", "augmented_assignment", "for_statement", "for_in_clause"):
+ return parent.child_by_field_name("left") == cur
+ if parent.type in ("function_definition", "class_definition"):
+ return parent.child_by_field_name("name") == cur
+ return parent.type in _PY_BINDING_PARENTS
+
+
+def _bindings(scope: Node, name: bytes) -> list[Node]:
+ """Identifiers binding *name* in *scope* itself, not in a nested scope."""
+ found: list[Node] = []
+ stack = list(scope.children)
+ while stack:
+ node = stack.pop()
+ if node.type in _PY_DEF_KINDS:
+ stack.extend(c for c in (node.child_by_field_name("name"),) if c is not None)
+ continue
+ if node.type == "identifier" and node.text == name and _binds(node):
+ found.append(node)
+ stack.extend(node.children)
+ return found
+
+
+def _module_int_constant(name: Node) -> bool:
+ """An ALL_CAPS name its own module binds exactly once, to an integer literal
+ (``MAX = 5``), and no enclosing function rebinds or shadows.
+
+ The spelling alone proves nothing (``NUM_USERS`` grows), so a name rebound,
+ imported, augmented, written through ``global``, shadowed by a parameter or
+ a local, or bound to anything but a literal stays unknown.
+ """
+ text = name.text or b""
+ if name.type != "identifier" or len(text) < 2 or not text.decode().isupper():
+ return False
+ scope = name.parent
+ while scope is not None and scope.parent is not None:
+ if scope.type in ("function_definition", "lambda") and _bindings(scope, text):
+ return False
+ scope = scope.parent
+ if scope is None or any(
+ n.type == "global_statement" and any(c.text == text for c in n.named_children)
+ for n in _walk_tree(scope)
+ ):
+ return False
+ bound = _bindings(scope, text)
+ if len(bound) != 1 or bound[0].parent is None or bound[0].parent.type != "assignment":
+ return False
+ right = bound[0].parent.child_by_field_name("right")
+ return right is not None and right.type == "integer"
+
+
+def _walk_tree(node: Node) -> Iterator[Node]:
+ stack = [node]
+ while stack:
+ current = stack.pop()
+ yield current
+ stack.extend(current.children)
+
+
class PythonPerfDialect(BasePerfDialect):
language = "python"
lock_acquire_functions = frozenset({"acquire", "__enter__"})
@@ -928,7 +1010,8 @@ class PythonPerfDialect(BasePerfDialect):
def _range_magnitude(
self, call: Node, loop: Node, probe: SinkProbe, *, hop: bool
) -> LoopMagnitude | None:
- """``range(len(rows))`` grows with ``rows``; ``range(MAX_RETRIES)`` is bounded."""
+ """``range(len(rows))`` grows with ``rows``; ``range(3)`` and ``range(MAX)``
+ with ``MAX = 3`` bound once in the module are bounded."""
args = [c for c in call.child_by_field_name("arguments").children if c.is_named]
if not args:
return None
@@ -938,13 +1021,8 @@ class PythonPerfDialect(BasePerfDialect):
if len(inner) == 1:
return self._grows(self._magnitude(inner[0], loop, probe, hop=hop))
return None
- path = self._dotted_path(stop) if stop.type in ("identifier", "attribute") else None
- last = path.rsplit(".", 1)[-1] if path else ""
- if (stop.type == "identifier" and last.isupper() and len(last) > 1) or (
- last and _PY_BOUND_NAME_RE.search(last)
- ):
- return "bounded"
- return None
+ # A name alone (``MAX_RETRIES``, ``self.max_attempts``) proves nothing.
+ return "bounded" if stop.type == "integer" or _module_int_constant(stop) else None
def _slice_magnitude(self, subscript: Node) -> LoopMagnitude | None:
"""``xs[:5]`` / ``xs[:LIMIT]`` / ``xs[i:i + 4]``: a constant-width slice."""
@@ -957,11 +1035,7 @@ class PythonPerfDialect(BasePerfDialect):
if stop is None:
return None
if start is None:
- text = (stop.text or b"").decode()
- constant = stop.type == "integer" or (
- stop.type == "identifier" and text.isupper() and len(text) > 1
- )
- return "bounded" if constant else None
+ return "bounded" if stop.type == "integer" or _module_int_constant(stop) else None
if stop.type == "binary_operator":
left, right = stop.child_by_field_name("left"), stop.child_by_field_name("right")
same_start = left is not None and self._dotted_path(left) == self._dotted_path(start)
diff --git a/packages/core/src/repowise/core/analysis/health/perf/dialects/ts_js.py b/packages/core/src/repowise/core/analysis/health/perf/dialects/ts_js.py
index 68822bab6..e3f1e81fe 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/dialects/ts_js.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/dialects/ts_js.py
@@ -147,9 +147,75 @@ def _is_data_projection(node: Node) -> bool:
return node.type == "member_expression" and prop is not None and prop.text == b"data"
+_TS_FUNCTION_KINDS = frozenset(
+ {
+ "function_declaration", "function_expression", "arrow_function", "method_definition",
+ "generator_function_declaration", "generator_function",
+ }
+)
+
+
+def _ts_walk(node: Node):
+ stack = [node]
+ while stack:
+ current = stack.pop()
+ yield current
+ stack.extend(current.children)
+
+
+def _declares(scope: Node, name: bytes) -> bool:
+ """Whether a declarator, parameter or import anywhere in *scope* binds *name*."""
+ for node in _ts_walk(scope):
+ if node.type == "variable_declarator":
+ key = node.child_by_field_name("name")
+ if key is not None and key.text == name:
+ return True
+ elif node.type == "identifier" and node.text == name and node.parent is not None:
+ parent = node.parent
+ if parent.type in ("formal_parameters", "required_parameter", "optional_parameter"):
+ return True
+ if parent.type == "arrow_function" and parent.child_by_field_name("parameter") == node:
+ return True
+ return False
+
+
+def _top_level_number_const(root: Node, name: bytes) -> bool:
+ """``const NAME = 5`` as the only top-level binding of NAME, exported or not."""
+ found: list[Node] = []
+ for stmt in root.children:
+ decl = stmt.child_by_field_name("declaration") if stmt.type == "export_statement" else stmt
+ if decl is None:
+ continue
+ if decl.type in ("lexical_declaration", "variable_declaration"):
+ found += [
+ (decl, d) for d in decl.named_children
+ if d.type == "variable_declarator"
+ and (key := d.child_by_field_name("name")) is not None and key.text == name
+ ]
+ elif decl.type != "expression_statement" and _declares(decl, name):
+ return False # a function, class or import binds it too
+ if len(found) != 1:
+ return False
+ decl, declarator = found[0]
+ value = declarator.child_by_field_name("value")
+ return decl.children[0].type == "const" and value is not None and value.type == "number"
+
+
+def _module_number_constant(name: bytes, node: Node) -> bool:
+ """``const NAME = 5`` at the top of *node*'s file, with no enclosing function
+ binding NAME again (a parameter or a local of the same name shadows it)."""
+ cur = node.parent
+ while cur is not None and cur.parent is not None:
+ if cur.type in _TS_FUNCTION_KINDS and _declares(cur, name):
+ return False
+ cur = cur.parent
+ return cur is not None and _top_level_number_const(cur, name)
+
+
def _slice_is_bounded(call: Node) -> bool:
- """``.slice(a, N)`` where N is an integer literal or an ALL_CAPS named
- constant — a constant-width read, not the whole collection."""
+ """``.slice(a, N)`` where N is an integer literal or an ALL_CAPS constant
+ its own file binds to one: a constant-width read, not the whole collection.
+ The spelling alone proves nothing."""
args = call.child_by_field_name("arguments")
named = [c for c in args.children if c.is_named] if args is not None else []
if len(named) != 2:
@@ -158,7 +224,7 @@ def _slice_is_bounded(call: Node) -> bool:
if end.type == "number":
return True
name = identifier_name(end)
- return name is not None and name.isupper()
+ return bool(name and name.isupper()) and _module_number_constant(end.text or b"", end)
def _sole_where_pair(call: Node) -> tuple[Node, Node] | None:
diff --git a/packages/core/src/repowise/core/analysis/health/perf/opportunities.py b/packages/core/src/repowise/core/analysis/health/perf/opportunities.py
index 3428ff954..af6da8b17 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/opportunities.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/opportunities.py
@@ -20,6 +20,7 @@ from dataclasses import dataclass
from typing import Any
from ...execution_roles import hottest_role
+from ..worth import dormant
from .actionability import (
ActionabilityState,
FixSafety,
@@ -152,78 +153,135 @@ def _reachability(values: set[Any]) -> bool | None:
return False if values == {False} else None
+def _inert(facts: Any) -> bool:
+ """A member that is no cost to fix: switched off by a constant-false flag,
+ or a loop that already walks its keys in chunks."""
+ return dormant(facts.details) or bool(facts.details.get("chunked_iteration"))
+
+
+@dataclass(frozen=True, slots=True)
+class _Reading:
+ """What a group's live members say, read once."""
+
+ live: list[Any]
+ markers: tuple[str, ...]
+ marker: str
+ sites: set[Any]
+ files: set[str]
+ provenance: str
+ reachable: bool | None
+ role: str
+ sinks: tuple[str, ...]
+ magnitude: str
+
+
+def _read_live(members: list[Any]) -> _Reading:
+ """Read a group's facts off its live members.
+
+ Inert members (:func:`_inert`) decide nothing while a live member exists.
+ The loop size is read only off the members the group's role comes from:
+ a request loop nobody measured never borrows a startup loop's growth, and
+ a group is ``bounded`` only when every loop of its hottest role is.
+ """
+ live = [facts for facts in members if not _inert(facts)] or members
+ markers = tuple(sorted({facts.marker for facts in live}))
+ marker = dominant_marker(markers)
+ sites = {facts.site for facts in live}
+ role = hottest_role(facts.execution_role for facts in live)
+ return _Reading(
+ live=live,
+ markers=markers,
+ marker=marker,
+ sites=sites,
+ files={site[0] for site in sites},
+ provenance=weakest_provenance({facts.provenance for facts in live}),
+ reachable=_reachability({facts.reliable_entry_reachability for facts in live}),
+ role=role,
+ sinks=tuple(sorted({facts.terminal_sink for facts in live if facts.terminal_sink})),
+ magnitude=loop_magnitude(
+ marker, [f.details for f in live if hottest_role((f.execution_role,)) == role]
+ ),
+ )
+
+
+def _facets(r: _Reading, confidence: str) -> dict[str, str]:
+ return {
+ "actionability_confidence": confidence,
+ "exposure": exposure(r.reachable),
+ "amplification": amplification(r.marker),
+ "leverage": leverage(len(r.sites)),
+ "change_risk": change_risk(len(r.files)),
+ "loop_magnitude": r.magnitude,
+ "execution_role": r.role,
+ }
+
+
def _assemble(key: Any, members: list[Any], cap: int) -> PerformanceOpportunity:
"""Read one group's answers off its owners. Decides nothing itself.
Context, boundary, and intervention are kernel inputs, so the group
already agrees on them by construction. Taking them off the key keeps one
owner for each instead of reclassifying a representative row. Sinks are
- members' facts, so they are listed rather than assumed shared.
+ members' facts, so they are listed rather than assumed shared. Everything
+ else comes from :func:`_read_live`; inert members are listed last.
"""
context = key_context(key)
boundary = key_boundary(key)
- markers = tuple(sorted({facts.marker for facts in members}))
- marker = dominant_marker(markers)
- sites = {facts.site for facts in members}
- files = {site[0] for site in sites}
- provenance = weakest_provenance({facts.provenance for facts in members})
- evidence_confidence = provenance_confidence(provenance)
- reachable = _reachability({facts.reliable_entry_reachability for facts in members})
- role = hottest_role(facts.execution_role for facts in members)
- sinks = tuple(sorted({facts.terminal_sink for facts in members if facts.terminal_sink}))
+ r = _read_live(members)
+ evidence_confidence = provenance_confidence(r.provenance)
assessment = assess_fix(
- marker,
- markers,
+ r.marker,
+ r.markers,
boundary,
- [facts.details for facts in members],
- cross_function=any(facts.cross_function for facts in members),
+ [facts.details for facts in r.live],
+ cross_function=any(facts.cross_function for facts in r.live),
)
acted = actionability(
assessment,
evidence_confidence,
- expected_reason=expected_reason(members),
+ expected_reason=expected_reason(members, r.magnitude),
)
- magnitude = loop_magnitude(marker, [facts.details for facts in members])
+ inputs = {
+ "multiplier_shape": r.marker,
+ "boundary_kind": boundary,
+ "execution_context": context,
+ "execution_role": r.role,
+ "affected_call_sites": len(r.sites),
+ "provenance": r.provenance,
+ "loop_magnitude": r.magnitude,
+ }
factors = rank_factors(
- marker=marker,
+ marker=r.marker,
boundary=boundary,
context=context,
- role=role,
- site_count=len(sites),
- provenance=provenance,
- magnitude=magnitude,
+ role=r.role,
+ site_count=len(r.sites),
+ provenance=r.provenance,
+ magnitude=r.magnitude,
)
- facets = {
- "actionability_confidence": acted.confidence,
- "exposure": exposure(reachable),
- "amplification": amplification(marker),
- "leverage": leverage(len(sites)),
- "change_risk": change_risk(len(files)),
- "loop_magnitude": magnitude,
- "execution_role": role,
- }
+ facets = _facets(r, acted.confidence)
return PerformanceOpportunity(
opportunity_id=stable_id(key),
performance_model_version=PERFORMANCE_MODEL_VERSION,
- biomarker_type=marker,
- biomarker_types=markers,
+ biomarker_type=r.marker,
+ biomarker_types=r.markers,
boundary_kind=boundary,
execution_context=context,
- terminal_sink=sinks[0] if len(sinks) == 1 else None,
- shared_path_suffix=shared_path_suffix([facts.path for facts in members if facts.path]),
+ terminal_sink=r.sinks[0] if len(r.sinks) == 1 else None,
+ shared_path_suffix=shared_path_suffix([facts.path for facts in r.live if facts.path]),
intervention_symbol=key_intervention_symbol(key),
intervention_kind=key_intervention_kind(key),
- terminal_sinks=sinks,
+ terminal_sinks=r.sinks,
resource_fingerprints=tuple(
sorted({facts.resource_fingerprint for facts in members if facts.resource_fingerprint})
),
- affected_call_sites_total=len(sites),
- affected_files_total=len(files),
+ affected_call_sites_total=len(r.sites),
+ affected_files_total=len(r.files),
observations_total=len(members),
- evidence=tuple(evidence_row(facts) for facts in members[:cap]),
+ evidence=tuple(evidence_row(facts) for facts in sorted(members, key=_inert)[:cap]),
evidence_truncated=len(members) > cap,
- reliable_entry_reachability=reachable,
- provenance=provenance,
+ reliable_entry_reachability=r.reachable,
+ provenance=r.provenance,
confidence=evidence_confidence,
facets=facets,
actionability_state=acted.state,
@@ -231,20 +289,9 @@ def _assemble(key: Any, members: list[Any], cap: int) -> PerformanceOpportunity:
prerequisites=acted.prerequisites,
rank_score=sum(factors.values()),
rank_factors=factors,
- why_ranked=why_ranked(
- factors,
- {
- "multiplier_shape": marker,
- "boundary_kind": boundary,
- "execution_context": context,
- "execution_role": role,
- "affected_call_sites": len(sites),
- "provenance": provenance,
- "loop_magnitude": magnitude,
- },
- ),
+ why_ranked=why_ranked(factors, inputs),
fix=acted.fix,
- may_lead=may_lead(marker, {facts.details.get("orm") for facts in members}, facets),
+ may_lead=may_lead(r.marker, {facts.details.get("orm") for facts in r.live}, facets),
)
diff --git a/packages/core/src/repowise/core/analysis/test_reachability.py b/packages/core/src/repowise/core/analysis/test_reachability.py
index 8d08deaf9..18edafd61 100644
--- a/packages/core/src/repowise/core/analysis/test_reachability.py
+++ b/packages/core/src/repowise/core/analysis/test_reachability.py
@@ -301,6 +301,8 @@ async def call_graph_from_db(session: AsyncSession, repo_id: str) -> CallGraphVi
except (TypeError, ValueError):
call_lines = []
edge_rows.append((src, dst, edge_type, origin, call_lines))
+ # No spawn lines here: test reachability reads only forward/reverse, never
+ # first-hop sites, ``spawn_only`` or roles, and a spawned callee is still reached.
return ExecutionGraphIndex(edge_rows=edge_rows)
diff --git a/packages/core/src/repowise/core/ingestion/call_resolver.py b/packages/core/src/repowise/core/ingestion/call_resolver.py
index ef5f9bea9..7854c1e51 100644
--- a/packages/core/src/repowise/core/ingestion/call_resolver.py
+++ b/packages/core/src/repowise/core/ingestion/call_resolver.py
@@ -848,6 +848,8 @@ class CallResolver(LanguageStrategiesMixin, ReceiverTypingMixin):
# tier that answered, so it is stamped once here.
if call.edge_type != "calls":
resolved = replace(resolved, edge_type=call.edge_type)
+ if call.spawned:
+ resolved = replace(resolved, spawned=True)
results.append(resolved)
return results
diff --git a/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py b/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py
index ae956fa19..58b770953 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_rehydrate.py
@@ -57,6 +57,30 @@ _NODE_ATTR_KEYS = (
_PARSE_ONLY_SYMBOL_ATTRS = ("decorators", "modifiers")
+def _restore_spawn_lines(graph: Any, parsed: Any) -> None:
+ """Mark the call lines of *parsed* that hand a coroutine to a task scheduler.
+
+ ``graph_edges`` stores call lines but not which of them spawn, so a
+ rehydrated ``calls`` edge takes them back from the re-parse: the caller's
+ spawned call to the callee's name at a line the edge already records.
+ """
+ module = f"{parsed.file_info.path}::__module__"
+ for call in parsed.calls:
+ caller = call.caller_symbol_id or module
+ if not call.spawned or caller not in graph:
+ continue
+ for callee, data in graph[caller].items():
+ if (
+ data.get("edge_type") == "calls"
+ and call.line in (data.get("call_lines") or ())
+ and graph.nodes[callee].get("name") == call.target_name
+ ):
+ lines = data.setdefault("spawn_lines", [])
+ if call.line not in lines:
+ lines.append(call.line)
+ lines.sort()
+
+
class RehydrateMixin:
"""Construct a :class:`GraphBuilder` from persisted rows instead of ASTs."""
@@ -143,16 +167,18 @@ class RehydrateMixin:
return builder
def restore_parse_only_attrs(self, parsed_files: Iterable[Any]) -> None:
- """Stamp the parse-only symbol attributes back onto rehydrated nodes.
+ """Stamp the parse-only symbol attributes back onto rehydrated nodes,
+ and the spawned call lines back onto their edges.
The first symbol under an id keeps its values, as in ``add_file``,
where the first declared overload keeps the node.
"""
- nodes = self._graph.nodes # type: ignore[attr-defined]
+ graph = self._graph # type: ignore[attr-defined]
for parsed in parsed_files:
for sym in parsed.symbols:
- node = nodes.get(sym.id)
+ node = graph.nodes.get(sym.id)
if node is None:
continue
for key in _PARSE_ONLY_SYMBOL_ATTRS:
node.setdefault(key, getattr(sym, key))
+ _restore_spawn_lines(graph, parsed)
diff --git a/packages/core/src/repowise/core/ingestion/graph/_resolvers.py b/packages/core/src/repowise/core/ingestion/graph/_resolvers.py
index e136e3bc0..3bd10f835 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_resolvers.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_resolvers.py
@@ -653,6 +653,7 @@ class ResolveMixin:
"edge_type": "calls",
"call_lines": [rc.line],
"supplied_props": rc.supplied_props,
+ **({"spawn_lines": [rc.line]} if rc.spawned else {}),
}
if rc.edge_type == "calls"
else {"edge_type": "references"}
@@ -686,6 +687,10 @@ class ResolveMixin:
if rc.line not in lines:
lines.append(rc.line)
lines.sort()
+ spawned = existing.setdefault("spawn_lines", []) if rc.spawned else None
+ if spawned is not None and rc.line not in spawned:
+ spawned.append(rc.line)
+ spawned.sort()
if rc.confidence > existing.get("confidence", 0):
existing["confidence"] = rc.confidence
existing["resolution_origin"] = rc.origin
diff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.py
index 8c44cab61..e6ce1a396 100644
--- a/packages/core/src/repowise/core/ingestion/models.py
+++ b/packages/core/src/repowise/core/ingestion/models.py
@@ -334,6 +334,9 @@ class CallSite:
# ``obj.m()``, Ruby ``obj.m(x)``). Its bare-name reading is asked only
# when no receiver strategy answers, never beside one.
bare_name_fallback: bool = False
+ # Handed straight to a task scheduler (``asyncio.create_task(f())``): it runs
+ # later, beside its caller, so the caller neither waits for it nor repeats it.
+ spawned: bool = False
# Raw extractor kinds, not the TS ``HeritageKind`` (a different payload);
diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.py
index 99fc634c3..f61d444ef 100644
--- a/packages/core/src/repowise/core/ingestion/parser.py
+++ b/packages/core/src/repowise/core/ingestion/parser.py
@@ -125,6 +125,7 @@ from .parser_helpers import (
)
from .python_local_refs import extract_python_local_refs
from .python_overload import is_python_overload as _is_python_overload
+from .python_tasks import is_fire_and_forget
from .sfc_source import component_call_sites, prepare_source
from .special_handlers import SPECIAL_HANDLER_LANGUAGES, parse_special
from .symbol_identity import disambiguate_colliding_ids, symbol_discriminator
@@ -2065,6 +2066,11 @@ class ASTParser:
else "calls"
),
supplied_props=_jsx_supplied_props(site_node, src),
+ # Ceiling: schedulers matched by name, the task followed
+ # within its own function only (see ``python_tasks``).
+ spawned=(
+ file_info.language == "python" and is_fire_and_forget(site_node, src)
+ ),
),
)
)
diff --git a/packages/core/src/repowise/core/ingestion/python_tasks.py b/packages/core/src/repowise/core/ingestion/python_tasks.py
new file mode 100644
index 000000000..3283917f6
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/python_tasks.py
@@ -0,0 +1,200 @@
+"""Python fire-and-forget tasks: a coroutine its caller hands off and never waits for.
+
+``asyncio.create_task(job())`` whose task is dropped, or only kept in a set so
+it is not garbage collected, runs beside its caller: the caller does not pay
+for it and does not repeat it. Anything less certain reads as the caller's own
+work: a task awaited, gathered, returned or passed on; a container of tasks
+used for anything but adding and removing; a scheduler other than ``asyncio``
+itself (a ``TaskGroup`` the caller waits for looks the same as one it does not).
+
+Read within one function and matched by name, so the answer errs towards
+"the caller pays", which keeps a cost visible rather than hiding it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from tree_sitter import Node
+
+from .extractors import node_text
+
+#: ``asyncio`` calls that schedule the coroutine they are handed.
+_SCHEDULERS = frozenset({"create_task", "ensure_future", "run_coroutine_threadsafe"})
+#: Container methods that only keep a task alive or let it go.
+_KEEPS = frozenset({"add", "append", "appendleft", "extend", "discard", "remove", "pop"})
+#: Task methods that neither wait for nor consume the result.
+_TASK_METHODS = frozenset(
+ {"add_done_callback", "remove_done_callback", "cancel", "set_name", "get_name", "done"}
+)
+_SCOPES = frozenset({"function_definition", "lambda"})
+_CONTAINER_LITERALS = frozenset(
+ {"list", "tuple", "set", "list_comprehension", "set_comprehension", "generator_expression"}
+)
+
+
+def _walk(node: Node) -> Iterator[Node]:
+ stack = [node]
+ while stack:
+ current = stack.pop()
+ yield current
+ stack.extend(current.children)
+
+
+def _method(call: Node, src: str) -> tuple[str | None, str]:
+ """``(receiver text, method name)`` of a call; ``None`` receiver for a bare call."""
+ function = call.child_by_field_name("function")
+ if function is None:
+ return None, ""
+ if function.type != "attribute":
+ return None, node_text(function, src)
+ receiver = function.child_by_field_name("object")
+ name = function.child_by_field_name("attribute")
+ return (
+ node_text(receiver, src) if receiver is not None else None,
+ node_text(name, src) if name is not None else "",
+ )
+
+
+def _scheduler_of(site: Node, src: str) -> Node | None:
+ """The ``asyncio`` scheduling call *site* is the first argument of, else ``None``.
+
+ Only ``asyncio.create_task(...)`` or a bare ``create_task(...)``: a task
+ group or a loop object may be one the caller waits for.
+ """
+ args = site.parent
+ outer = args.parent if args is not None and args.type == "argument_list" else None
+ if outer is None or outer.type != "call":
+ return None
+ receiver, name = _method(outer, src)
+ if name not in _SCHEDULERS or receiver not in (None, "asyncio"):
+ return None
+ first = next((c for c in args.children if c.is_named), None)
+ return outer if first == site else None
+
+
+def _scope_of(node: Node) -> Node:
+ cur = node
+ while cur.parent is not None and cur.type not in _SCOPES:
+ cur = cur.parent
+ return cur
+
+
+def _assigned_holder(assignment: Node, value: Node, scheduler: Node, src: str) -> tuple[str, str | None]:
+ left = assignment.child_by_field_name("left")
+ if left is not None and left.type == "subscript":
+ return "container", node_text(left.child_by_field_name("value"), src)
+ if left is not None and left.type in ("identifier", "attribute"):
+ return ("task" if value == scheduler else "container"), node_text(left, src)
+ return "used", None
+
+
+def _holder(scheduler: Node, src: str) -> tuple[str, str | None]:
+ """How the task is held: ``("dropped", None)``, ``("task", name)`` for a name
+ bound to it, ``("container", name)`` for a container it is put in, or
+ ``("used", None)`` when anything else consumes it."""
+ value = scheduler
+ while value.parent is not None and value.parent.type in _CONTAINER_LITERALS:
+ value = value.parent
+ parent = value.parent
+ if parent is None:
+ return "used", None
+ if parent.type == "expression_statement" and value == scheduler:
+ return "dropped", None
+ if parent.type == "assignment" and parent.child_by_field_name("right") == value:
+ return _assigned_holder(parent, value, scheduler, src)
+ store = parent.parent if parent.type == "argument_list" else None
+ if store is not None and store.type == "call":
+ receiver, name = _method(store, src)
+ if name in _KEEPS and receiver:
+ return "container", receiver
+ return "used", None
+
+
+def _uses(scope: Node, name: str, src: str) -> Iterator[Node]:
+ """Every use of *name* in *scope* except a plain rebinding of it."""
+ for node in _walk(scope):
+ if node.type not in ("identifier", "attribute") or node_text(node, src) != name:
+ continue
+ parent = node.parent
+ if parent is not None and parent.type == "assignment" and parent.child_by_field_name("left") == node:
+ continue
+ yield node
+
+
+def _method_on(node: Node, methods: frozenset[str], src: str) -> bool:
+ """``node.<method>`` for one of *methods* (called or passed as a callback)."""
+ parent = node.parent
+ if parent is None or parent.type != "attribute" or parent.child_by_field_name("object") != node:
+ return False
+ return node_text(parent.child_by_field_name("attribute"), src) in methods
+
+
+def _kept_in(node: Node, src: str) -> str | None:
+ """The container a task use puts it in: ``c.add(task)`` or ``c[k] = task``."""
+ parent = node.parent
+ if parent is None:
+ return None
+ if parent.type == "argument_list" and parent.parent is not None:
+ receiver, name = _method(parent.parent, src)
+ return receiver if name in _KEEPS else None
+ if parent.type == "assignment" and parent.child_by_field_name("right") == node:
+ left = parent.child_by_field_name("left")
+ if left is not None and left.type == "subscript":
+ return node_text(left.child_by_field_name("value"), src)
+ return None
+
+
+def _task_containers(scope: Node, name: str, src: str) -> set[str] | None:
+ """The containers the task *name* is kept in, or ``None`` when any use of
+ it might wait for or consume it."""
+ containers: set[str] = set()
+ for node in _uses(scope, name, src):
+ if _method_on(node, _TASK_METHODS, src):
+ continue
+ kept = _kept_in(node, src)
+ if kept is None:
+ return None
+ containers.add(kept)
+ return containers
+
+
+def _stored_into(node: Node) -> bool:
+ """``node[key] = ...``: the container is written, not read."""
+ target = node.parent
+ store = target.parent if target is not None and target.type == "subscript" else None
+ return (
+ store is not None
+ and target.child_by_field_name("value") == node
+ and store.type == "assignment"
+ and store.child_by_field_name("left") == target
+ )
+
+
+def _only_kept(scope: Node, container: str, src: str) -> bool:
+ """Whether *container* is only added to and removed from in *scope*."""
+ return all(
+ _method_on(node, _KEEPS, src) or _stored_into(node)
+ for node in _uses(scope, container, src)
+ )
+
+
+def is_fire_and_forget(site: Node, src: str) -> bool:
+ """Whether the Python call at *site* is a coroutine ``asyncio`` schedules
+ and its function provably never waits for."""
+ scheduler = _scheduler_of(site, src)
+ if scheduler is None:
+ return False
+ kind, name = _holder(scheduler, src)
+ if kind == "dropped":
+ return True
+ if kind == "used" or name is None:
+ return False
+ scope = _scope_of(scheduler)
+ containers = {name} if kind == "container" else _task_containers(scope, name, src)
+ if containers is None:
+ return False
+ return all(_only_kept(scope, container, src) for container in containers)
+
+
+__all__ = ["is_fire_and_forget"]
diff --git a/packages/core/src/repowise/core/ingestion/resolved_call.py b/packages/core/src/repowise/core/ingestion/resolved_call.py
index 3576d1fd4..a227355e3 100644
--- a/packages/core/src/repowise/core/ingestion/resolved_call.py
+++ b/packages/core/src/repowise/core/ingestion/resolved_call.py
@@ -18,3 +18,4 @@ class ResolvedCall:
origin: ResolutionOrigin # which strategy produced it
edge_type: CallSiteEdgeType = "calls" # carried through from the CallSite
supplied_props: frozenset[str] | None = None # prop names supplied in JSX element (None if unknown/spread)
+ spawned: bool = False # carried through from the CallSite
diff --git a/tests/fixtures/perf_corpus/golden_opportunities.json b/tests/fixtures/perf_corpus/golden_opportunities.json
index b3615977c..c477397b9 100644
--- a/tests/fixtures/perf_corpus/golden_opportunities.json
+++ b/tests/fixtures/perf_corpus/golden_opportunities.json
@@ -1742,91 +1742,6 @@
}
]
},
- {
- "actionability_reason": "strategy_requires_validation",
- "actionability_state": "advisory",
- "affected_call_sites_total": 1,
- "affected_files_total": 1,
- "biomarker_type": "io_in_loop",
- "biomarker_types": [
- "io_in_loop"
- ],
- "boundary_kind": "network",
- "confidence": "high",
- "evidence": [
- {
- "biomarker_type": "io_in_loop",
- "file_path": "src/app/retry.py",
- "finding_id": "finding_0e8c0794491c7384f4c4",
- "function_name": "post_with_retry",
- "line_end": 52,
- "line_start": 50,
- "path": [],
- "provenance": "direct",
- "reason": "retry_loop: io_in_loop at src/app/retry.py:50 repeats work per iteration."
- }
- ],
- "evidence_truncated": false,
- "execution_context": "production",
- "facets": {
- "actionability_confidence": "medium",
- "amplification": "per_iteration",
- "change_risk": "contained",
- "execution_role": "unknown",
- "exposure": "unknown",
- "leverage": "isolated",
- "loop_magnitude": "bounded"
- },
- "fix": {
- "rationale": "The shared I/O sink is proven; no concrete batch API or result-equivalence proof is available.",
- "safety": "advisory",
- "strategy": "batch_or_prefetch_io"
- },
- "intervention_kind": "function",
- "intervention_symbol": "src/app/retry.py::post_with_retry",
- "may_lead": false,
- "observations_total": 1,
- "opportunity_id": "perf3_bd36a05060a6d02a1245",
- "performance_model_version": 3,
- "prerequisites": [
- "batch_api_contract",
- "result_equivalence"
- ],
- "provenance": "direct",
- "rank_factors": {
- "affected_call_sites": 2,
- "boundary_kind": 4,
- "execution_context": 3,
- "execution_role": 1,
- "loop_magnitude": 0,
- "multiplier_shape": 4,
- "provenance": 3
- },
- "rank_score": 17,
- "reliable_entry_reachability": null,
- "resource_fingerprints": [],
- "shared_path_suffix": [],
- "siblings": [],
- "terminal_sink": null,
- "terminal_sinks": [],
- "why_ranked": [
- {
- "factor": "boundary_kind",
- "points": 4,
- "value": "network"
- },
- {
- "factor": "multiplier_shape",
- "points": 4,
- "value": "io_in_loop"
- },
- {
- "factor": "execution_context",
- "points": 3,
- "value": "production"
- }
- ]
- },
{
"actionability_reason": "strategy_requires_validation",
"actionability_state": "advisory",
@@ -2292,6 +2207,84 @@
}
]
},
+ {
+ "actionability_reason": "bounded_loop",
+ "actionability_state": "expected",
+ "affected_call_sites_total": 1,
+ "affected_files_total": 1,
+ "biomarker_type": "io_in_loop",
+ "biomarker_types": [
+ "io_in_loop"
+ ],
+ "boundary_kind": "network",
+ "confidence": "high",
+ "evidence": [
+ {
+ "biomarker_type": "io_in_loop",
+ "file_path": "src/app/retry.py",
+ "finding_id": "finding_0e8c0794491c7384f4c4",
+ "function_name": "post_with_retry",
+ "line_end": 52,
+ "line_start": 50,
+ "path": [],
+ "provenance": "direct",
+ "reason": "retry_loop: io_in_loop at src/app/retry.py:50 repeats work per iteration."
+ }
+ ],
+ "evidence_truncated": false,
+ "execution_context": "production",
+ "facets": {
+ "actionability_confidence": "low",
+ "amplification": "per_iteration",
+ "change_risk": "contained",
+ "execution_role": "unknown",
+ "exposure": "unknown",
+ "leverage": "isolated",
+ "loop_magnitude": "bounded"
+ },
+ "fix": null,
+ "intervention_kind": "function",
+ "intervention_symbol": "src/app/retry.py::post_with_retry",
+ "may_lead": false,
+ "observations_total": 1,
+ "opportunity_id": "perf3_bd36a05060a6d02a1245",
+ "performance_model_version": 3,
+ "prerequisites": [],
+ "provenance": "direct",
+ "rank_factors": {
+ "affected_call_sites": 2,
+ "boundary_kind": 4,
+ "execution_context": 3,
+ "execution_role": 1,
+ "loop_magnitude": 0,
+ "multiplier_shape": 4,
+ "provenance": 3
+ },
+ "rank_score": 17,
+ "reliable_entry_reachability": null,
+ "resource_fingerprints": [],
+ "shared_path_suffix": [],
+ "siblings": [],
+ "terminal_sink": null,
+ "terminal_sinks": [],
+ "why_ranked": [
+ {
+ "factor": "boundary_kind",
+ "points": 4,
+ "value": "network"
+ },
+ {
+ "factor": "multiplier_shape",
+ "points": 4,
+ "value": "io_in_loop"
+ },
+ {
+ "factor": "execution_context",
+ "points": 3,
+ "value": "production"
+ }
+ ]
+ },
{
"actionability_reason": "strategy_requires_validation",
"actionability_state": "advisory",
diff --git a/tests/fixtures/perf_corpus/golden_plans.json b/tests/fixtures/perf_corpus/golden_plans.json
index 35672613c..1629e0b2f 100644
--- a/tests/fixtures/perf_corpus/golden_plans.json
+++ b/tests/fixtures/perf_corpus/golden_plans.json
@@ -1469,77 +1469,6 @@
"source_biomarker": "io_in_loop",
"target_symbol": "src/app/reports.py::handle"
},
- {
- "blast_radius": {
- "call_sites": 1,
- "file_count": 1,
- "files": [
- "src/app/retry.py"
- ]
- },
- "confidence": "medium",
- "evidence": {
- "affected_files_total": 1,
- "biomarker_type": "io_in_loop",
- "biomarker_types": [
- "io_in_loop"
- ],
- "boundary_kind": "network",
- "execution_context": "production",
- "observations_total": 1,
- "provenance": "direct",
- "rank_factors": {
- "affected_call_sites": 2,
- "boundary_kind": 4,
- "execution_context": 3,
- "execution_role": 1,
- "loop_magnitude": 0,
- "multiplier_shape": 4,
- "provenance": 3
- },
- "rank_score": 17,
- "rationale": "The shared I/O sink is proven; no concrete batch API or result-equivalence proof is available.",
- "reliable_entry_reachability": null
- },
- "file_path": "src/app/retry.py",
- "impact_delta": 0.0,
- "line_end": 52,
- "line_start": 50,
- "plan": {
- "affected_locations": [
- {
- "file_path": "src/app/retry.py",
- "function_name": "post_with_retry",
- "line_end": 52,
- "line_start": 50
- }
- ],
- "affected_locations_total": 1,
- "api": null,
- "evidence_truncated": false,
- "intervention_symbol": "src/app/retry.py::post_with_retry",
- "judgment_steps": 1,
- "mechanical_steps": 0,
- "opportunity_id": "perf3_bd36a05060a6d02a1245",
- "paths": [],
- "paths_total": 1,
- "safety": "advisory",
- "steps": [
- {
- "action": "Collect the keys before the loop and replace the per-key call with one batched call",
- "applicability": "judgment",
- "file_path": "src/app/retry.py",
- "line": 50,
- "order": 1,
- "symbol": "post_with_retry"
- }
- ],
- "strategy": "batch_or_prefetch_io"
- },
- "refactoring_type": "performance_fix",
- "source_biomarker": "io_in_loop",
- "target_symbol": "src/app/retry.py::post_with_retry"
- },
{
"blast_radius": {
"call_sites": 1,
diff --git a/tests/unit/health/test_perf_corpus_golden.py b/tests/unit/health/test_perf_corpus_golden.py
index fc90ba73b..86057d4f4 100644
--- a/tests/unit/health/test_perf_corpus_golden.py
+++ b/tests/unit/health/test_perf_corpus_golden.py
@@ -149,7 +149,8 @@ def test_linking_stamps_the_id_the_builder_derives() -> None:
("batch_form_equivalent", 1, {"batch_or_prefetch_io"}),
("batch_form_limited", 1, {"batch_or_prefetch_io"}),
("bounded_fan_out", 1, {"parallelize_independent_awaits"}),
- ("retry_loop", 1, {"batch_or_prefetch_io"}),
+ # A bounded retry loop runs a fixed number of times: nothing to batch.
+ ("retry_loop", 1, {None}),
# Execution context is an identity input: one shape, three contexts.
("context_split", 3, {"batch_or_prefetch_io"}),
# io_in_loop and nested_loop_with_io share one cross-function identity
@@ -279,7 +280,6 @@ def test_reachability_aggregates_any_true_over_all_false() -> None:
# The bulk form exists, but a per-key limit means it may not read the same rows.
("batch_form_limited", "advisory", ("result_equivalence",), '.in_("repo_id", keys)'),
("bounded_fan_out", "plan_ready", (), "self._sem"),
- ("retry_loop", "advisory", ("batch_api_contract", "result_equivalence"), None),
],
)
def test_promotion_facts_clear_exactly_their_prerequisite(case, state, prerequisites, api) -> None:
@@ -289,6 +289,16 @@ def test_promotion_facts_clear_exactly_their_prerequisite(case, state, prerequis
assert item.fix is not None and item.fix.api == api
+def test_a_bounded_loop_is_expected_and_leaves_the_default_queue() -> None:
+ (item,) = build_performance_opportunities(rows_for("retry_loop"))
+ assert (item.actionability_state, item.actionability_reason, item.fix) == (
+ "expected",
+ "bounded_loop",
+ None,
+ )
+ assert perf_queue_verdict(item).reason == "expected"
+
+
def test_a_loop_that_grows_with_data_outranks_a_bounded_one() -> None:
(grows,) = build_performance_opportunities(rows_for("batch_form_equivalent"))
(bounded,) = build_performance_opportunities(rows_for("retry_loop"))
diff --git a/tests/unit/health/test_perf_loop_facts_python.py b/tests/unit/health/test_perf_loop_facts_python.py
index 1d26bd529..32740f720 100644
--- a/tests/unit/health/test_perf_loop_facts_python.py
+++ b/tests/unit/health/test_perf_loop_facts_python.py
@@ -86,23 +86,41 @@ def test_a_read_capped_in_the_query_does_not_grow():
assert facts.magnitude == "unknown"
-def test_magnitude_range_all_caps_constant_bounded():
- """B1: ``range(N)`` where N is an ALL_CAPS identifier."""
+def test_magnitude_range_all_caps_parameter_is_unknown():
+ """``range(N)`` where N is an ALL_CAPS parameter: no literal proves it."""
facts = _loop(
b"from sqlalchemy import select\n"
b"async def f(session, MAX_RETRIES):\n"
b" for i in range(MAX_RETRIES):\n"
b" await session.execute(select(i))\n"
)
- assert facts.magnitude == "bounded"
+ assert facts is None or facts.magnitude == "unknown"
-def test_magnitude_range_attempts_name_bounded():
- """B1: the last dotted segment matches ``retr|attempt`` (case-insensitive)."""
+ "src",
+ [
+ b"async def f(session, cfg):\n for i in range(cfg.max_attempts):\n",
+ b"from config import MAX_RETRIES\nasync def f(session):\n"
+ b" for i in range(MAX_RETRIES):\n",
+ b"class C:\n async def f(self, session):\n for i in range(self.max_retries):\n"
+ b" ",
+ ],
+)
+def test_a_retry_name_alone_never_proves_a_loop_bounded(src):
+ """A bounded loop is hidden as expected, so the name needs the proof a number has."""
+ facts = _loop(
+ b"from sqlalchemy import select\n" + src + b" await session.execute(select(i))\n"
+ )
+ assert facts is None or facts.magnitude == "unknown"
+
+
+def test_magnitude_range_retry_constant_bound_to_a_literal_bounded():
facts = _loop(
b"from sqlalchemy import select\n"
- b"async def f(session, cfg):\n"
- b" for i in range(cfg.max_attempts):\n"
+ b"MAX_RETRIES = 3\n"
+ b"async def f(session):\n"
+ b" for i in range(MAX_RETRIES):\n"
b" await session.execute(select(i))\n"
)
assert facts.magnitude == "bounded"
@@ -120,16 +138,62 @@ def test_magnitude_slice_constant_upper_bound_bounded():
def test_magnitude_slice_named_constant_bounded():
- """B1: ``xs[:LIMIT]``."""
+ """B1: ``xs[:LIMIT]`` where the module binds ``LIMIT`` to an integer literal."""
facts = _loop(
b"from sqlalchemy import select\n"
- b"async def f(session, xs, LIMIT):\n"
+ b"LIMIT = 50\n"
+ b"async def f(session, xs):\n"
b" for x in xs[:LIMIT]:\n"
b" await session.execute(select(x))\n"
)
assert facts.magnitude == "bounded"
+ "src",
+ [
+ # A parameter spelled in capitals is still a parameter.
+ b"async def f(session, xs, LIMIT):\n for x in xs[:LIMIT]:\n"
+ b" await session.execute(select(x))\n",
+ # Bound, but not to a literal: the user count grows.
+ b"NUM_USERS = load_users()\nasync def f(session):\n for i in range(NUM_USERS):\n"
+ b" await session.execute(select(i))\n",
+ # Never bound in this module.
+ b"from config import NUM_USERS\nasync def f(session):\n"
+ b" for i in range(NUM_USERS):\n await session.execute(select(i))\n",
+ # Rebound later in the module.
+ b"MAX = 5\nMAX = load()\nasync def f(session):\n for i in range(MAX):\n"
+ b" await session.execute(select(i))\n",
+ # Augmented.
+ b"MAX = 5\nMAX += extra()\nasync def f(session):\n for i in range(MAX):\n"
+ b" await session.execute(select(i))\n",
+ # Written through ``global`` by some function.
+ b"MAX = 5\ndef grow(n):\n global MAX\n MAX = n\nasync def f(session):\n"
+ b" for i in range(MAX):\n await session.execute(select(i))\n",
+ # Shadowed by a local of the loop's function.
+ b"MAX = 5\nasync def f(session):\n MAX = count_rows()\n for i in range(MAX):\n"
+ b" await session.execute(select(i))\n",
+ # Shadowed by a parameter.
+ b"MAX = 5\nasync def f(session, MAX):\n for i in range(MAX):\n"
+ b" await session.execute(select(i))\n",
+ ],
+)
+def test_capitals_alone_never_prove_a_loop_bounded(src):
+ facts = _loop(b"from sqlalchemy import select\n" + src)
+ assert facts is None or facts.magnitude == "unknown"
+
+
+def test_magnitude_range_module_int_constant_bounded():
+ facts = _loop(
+ b"from sqlalchemy import select\n"
+ b"MAX_PAGES = 5\n"
+ b"async def f(session):\n"
+ b" for i in range(MAX_PAGES):\n"
+ b" await session.execute(select(i))\n"
+ )
+ assert facts.magnitude == "bounded"
+
+
def test_magnitude_slice_variable_width_int_literal_bounded():
"""B1: ``xs[a:a+4]`` — same start name, integer-literal width."""
facts = _loop(
diff --git a/tests/unit/health/test_perf_loop_facts_ts.py b/tests/unit/health/test_perf_loop_facts_ts.py
index 40790b3ed..10362bba9 100644
--- a/tests/unit/health/test_perf_loop_facts_ts.py
+++ b/tests/unit/health/test_perf_loop_facts_ts.py
@@ -436,3 +436,55 @@ async function f(xs) {
}
"""
assert _io_hits(src) == []
+
+
+def test_magnitude_bounded_via_a_file_number_constant():
+ src = """
+const PAGE = 5;
+async function f(items) {
+ for (const x of items.slice(0, PAGE)) {
+ await prisma.post.deleteMany({ where: { userId: x.id } });
+ }
+}
+"""
+ hits = _io_hits(src)
+ assert hits[0].loop is not None and hits[0].loop.magnitude == "bounded"
+
+
+def test_capitals_alone_never_bound_a_slice():
+ src = """
+async function f(items, LIMIT) {
+ for (const x of items.slice(0, LIMIT)) {
+ await prisma.post.deleteMany({ where: { userId: x.id } });
+ }
+}
+"""
+ hits = _io_hits(src)
+ assert hits[0].loop is None or hits[0].loop.magnitude == "unknown"
+
+
+def test_an_inner_binding_shadows_the_file_constant():
+ src = """
+const PAGE = 5;
+async function f(items, rows) {
+ const PAGE = rows.length;
+ for (const x of items.slice(0, PAGE)) {
+ await prisma.post.deleteMany({ where: { userId: x.id } });
+ }
+}
+"""
+ hits = _io_hits(src)
+ assert hits[0].loop is None or hits[0].loop.magnitude == "unknown"
+
+
+def test_a_parameter_shadows_the_file_constant():
+ src = """
+const PAGE = 5;
+async function f(items, PAGE) {
+ for (const x of items.slice(0, PAGE)) {
+ await prisma.post.deleteMany({ where: { userId: x.id } });
+ }
+}
+"""
+ hits = _io_hits(src)
+ assert hits[0].loop is None or hits[0].loop.magnitude == "unknown"
diff --git a/tests/unit/health/test_perf_spawned_and_mixed_groups.py b/tests/unit/health/test_perf_spawned_and_mixed_groups.py
new file mode 100644
index 000000000..d59155de5
--- /dev/null
+++ b/tests/unit/health/test_perf_spawned_and_mixed_groups.py
@@ -0,0 +1,266 @@
+"""A spawned coroutine is not its caller's work, and a group's facts come from
+its live members: the mechanical misfacts that filled the perf default queue."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+from repowise.core.analysis.execution_graph import ExecutionGraphIndex
+from repowise.core.analysis.execution_roles import ExecutionRoles
+from repowise.core.analysis.health.models import HealthFindingData, Severity
+from repowise.core.analysis.health.perf.opportunities import build_performance_opportunities
+from repowise.core.analysis.health.queue.eligibility import (
+ perf_queue_counts,
+ perf_queue_verdict,
+ queue_proof,
+)
+from repowise.core.ingestion import ASTParser, FileTraverser, GraphBuilder
+from tests.unit.ingestion.test_graph_rehydrate import _serialize
+
+_ROUTES = """
+import asyncio
+from fastapi import APIRouter
+
+router = APIRouter()
+_tasks = set()
+
+
+async def sync(repo_id: str):
+ task = asyncio.create_task(execute_job(repo_id), name="job")
+ _tasks.add(task)
+ task.add_done_callback(_tasks.discard)
+ for name in ("a", "b"):
+ asyncio.create_task(watch(name))
+ return {"ok": True}
+
+
+async def run_now(repo_id: str):
+ await direct(repo_id)
+
+
+async def execute_job(repo_id):
+ await persist(repo_id)
+
+
+async def persist(repo_id):
+ return repo_id
+
+
+async def watch(name):
+ return name
+
+
+async def direct(repo_id):
+ await shared(repo_id)
+ asyncio.create_task(shared(repo_id))
+
+
+async def shared(repo_id):
+ return repo_id
+
+
+async def awaited_later(x):
+ t = asyncio.create_task(step(x))
+ await t
+
+
+async def awaited_inline(x):
+ await asyncio.create_task(step(x))
+
+
+async def gathered(xs):
+ tasks = [asyncio.create_task(step(x)) for x in xs]
+ await asyncio.gather(*tasks)
+
+
+async def grouped(xs):
+ async with asyncio.TaskGroup() as tg:
+ for x in xs:
+ tg.create_task(step(x))
+
+
+async def tg_param(tg, x):
+ tg.create_task(step(x))
+
+
+async def iterated(xs):
+ tasks = []
+ for x in xs:
+ tasks.append(asyncio.create_task(step(x)))
+ for t in tasks:
+ await t
+
+
+async def returned(xs):
+ tasks = [asyncio.create_task(step(x)) for x in xs]
+ return tasks
+
+
+class Runner:
+ async def joined(self, xs):
+ tasks = [asyncio.create_task(step(x)) for x in xs]
+ await self._join(tasks)
+
+
+async def step(x):
+ return x
+"""
+
+
+def _parse(tmp_path: Path):
+ (tmp_path / "routes.py").write_text(textwrap.dedent(_ROUTES), encoding="utf-8")
+ parser = ASTParser()
+ return [
+ parser.parse_file(fi, Path(fi.abs_path).read_bytes())
+ for fi in FileTraverser(tmp_path).traverse()
+ ]
+
+
+def _graph(tmp_path: Path):
+ parsed = _parse(tmp_path)
+ builder = GraphBuilder(tmp_path)
+ for pf in parsed:
+ builder.add_file(pf)
+ builder.build()
+ return parsed, builder
+
+
+def _spawned(parsed) -> dict[tuple[str, str], bool]:
+ return {
+ (c.caller_symbol_id.rsplit("::", 1)[-1], c.target_name): c.spawned
+ for pf in parsed
+ for c in pf.calls
+ if c.caller_symbol_id
+ }
+
+
+def test_only_a_task_nobody_waits_for_is_spawned(tmp_path: Path) -> None:
+ calls = _spawned(_parse(tmp_path))
+ # Dropped, or only kept alive in a set: fire-and-forget.
+ assert calls[("sync", "execute_job")] is True
+ assert calls[("sync", "watch")] is True
+ # Awaited, gathered or owned by a TaskGroup: the caller's own work.
+ assert calls[("awaited_later", "step")] is False
+ assert calls[("awaited_inline", "step")] is False
+ assert calls[("gathered", "step")] is False
+ assert calls[("grouped", "step")] is False
+ # A receiver not proven to be asyncio may be a group someone waits for.
+ assert calls[("tg_param", "step")] is False
+ # A container read in any way but adding and removing: its tasks are waited.
+ assert calls[("iterated", "step")] is False
+ assert calls[("returned", "step")] is False
+ assert calls[("joined", "step")] is False
+
+
+def test_a_spawned_call_site_never_resolves_as_a_call_its_caller_makes(tmp_path: Path) -> None:
+ _parsed, builder = _graph(tmp_path)
+ graph = builder.graph()
+ edge = graph["routes.py::sync"]["routes.py::watch"]
+ assert edge["spawn_lines"] == edge["call_lines"]
+ index = ExecutionGraphIndex(graph)
+ line = edge["call_lines"][0]
+ assert index.resolve_call_targets("routes.py::sync", line, "watch") == ((), "call-site")
+ assert "routes.py::watch" in index.spawn_only["routes.py::sync"]
+ # Still an edge: dead code and test reachability keep seeing the callee.
+ assert "routes.py::watch" in index.forward["routes.py::sync"]
+ # Called and spawned from one function: the awaited site still resolves.
+ assert "routes.py::shared" not in index.spawn_only.get("routes.py::direct", ())
+
+
+def test_a_request_that_spawns_a_job_does_not_make_the_job_a_request(tmp_path: Path) -> None:
+ _parsed, builder = _graph(tmp_path)
+ graph = builder.graph()
+ roles = ExecutionRoles.build(graph, ExecutionGraphIndex(graph))
+ assert roles.role_of("routes.py::sync", "routes.py") == "request"
+ assert roles.role_of("routes.py::execute_job", "routes.py") == "scheduled_job"
+ assert roles.role_of("routes.py::persist", "routes.py") == "scheduled_job"
+ # Spawned somewhere, but also awaited on a request's path: still the request's.
+ assert roles.role_of("routes.py::shared", "routes.py") == "request"
+
+
+def test_a_rehydrated_graph_gives_the_same_spawns_and_roles(tmp_path: Path) -> None:
+ parsed, fresh = _graph(tmp_path)
+ nodes, edges = _serialize(fresh)
+ rehydrated = GraphBuilder.from_persisted(nodes, edges, fresh.file_metrics_snapshot())
+ rehydrated.restore_parse_only_attrs(parsed)
+ fresh_index = ExecutionGraphIndex(fresh.graph())
+ re_index = ExecutionGraphIndex(rehydrated.graph())
+ assert re_index.spawn_only == fresh_index.spawn_only != {}
+ fresh_roles = ExecutionRoles.build(fresh.graph(), fresh_index).reached
+ assert ExecutionRoles.build(rehydrated.graph(), re_index).reached == fresh_roles
+
+
+def _finding(line: int, role: str | None = None, **details: object) -> HealthFindingData:
+ return HealthFindingData(
+ biomarker_type="io_in_loop",
+ severity=Severity.MEDIUM,
+ file_path="svc/load.py",
+ function_name="load_all",
+ line_start=line,
+ line_end=line,
+ details={
+ "boundary_kind": "db",
+ "cross_function": False,
+ "path": [],
+ **({"execution_role": role} if role else {}),
+ **details,
+ },
+ health_impact=0.0,
+ dimension="performance",
+ )
+
+
+def test_a_gated_member_neither_leads_nor_lends_its_role() -> None:
+ (item,) = build_performance_opportunities(
+ [
+ _finding(10, "request", gated_off=True, loop_magnitude="grows_with_data"),
+ _finding(30, "unknown"),
+ ]
+ )
+ assert item.actionability_reason != "gated_off"
+ assert item.evidence[0]["line_start"] == 30
+ assert item.facets["execution_role"] == "unknown"
+ assert item.facets["loop_magnitude"] == "unknown"
+ assert item.observations_total == 2 and item.affected_call_sites_total == 1
+
+
+def test_a_chunked_member_does_not_lead_a_live_one() -> None:
+ (item,) = build_performance_opportunities(
+ [_finding(10, "request", chunked_iteration=True), _finding(30, "request")]
+ )
+ assert item.evidence[0]["line_start"] == 30
+ # Every member chunked: the loop is already the batch.
+ (chunked,) = build_performance_opportunities([_finding(10, "request", chunked_iteration=True)])
+ assert chunked.actionability_reason == "loop_already_chunked"
+
+
+def test_growth_is_read_off_the_members_the_role_comes_from() -> None:
+ """A request loop nobody measured does not borrow a startup loop's growth."""
+ (item,) = build_performance_opportunities(
+ [_finding(10, "startup", loop_magnitude="grows_with_data"), _finding(30, "request")]
+ )
+ assert item.facets["execution_role"] == "request"
+ assert item.facets["loop_magnitude"] == "unknown"
+ assert perf_queue_verdict(item).reason == "unmeasured_cost"
+ assert queue_proof(item) == "unproven"
+ (grows,) = build_performance_opportunities(
+ [_finding(10, "request", loop_magnitude="grows_with_data"), _finding(30, "startup")]
+ )
+ assert grows.facets["loop_magnitude"] == "grows_with_data"
+
+
+def test_a_bounded_loop_has_nothing_to_change() -> None:
+ (item,) = build_performance_opportunities(
+ [_finding(10, "request", loop_magnitude="bounded"), _finding(12, "request", loop_magnitude="bounded")]
+ )
+ assert (item.actionability_state, item.actionability_reason) == ("expected", "bounded_loop")
+ assert perf_queue_verdict(item).reason == "expected"
+ # The queue summary counts it under ``expected``, the reason the store keeps.
+ assert perf_queue_counts([item])["excluded"]["expected"] == 1
+ (mixed,) = build_performance_opportunities(
+ [_finding(10, "request", loop_magnitude="bounded"), _finding(12, "request")]
+ )
+ assert mixed.actionability_state != "expected"
diff --git a/tests/unit/server/test_performance_opportunities.py b/tests/unit/server/test_performance_opportunities.py
index 64df7b83c..cafcd3e29 100644
--- a/tests/unit/server/test_performance_opportunities.py
+++ b/tests/unit/server/test_performance_opportunities.py
@@ -548,8 +548,13 @@ async def test_cold_and_unproven_background_roles_sit_one_filter_away(
served.details["execution_role"] = "request"
cli = _finding("src/e.py", 60, ["src/e.py::run", "src/db.py::fetch"])
cli.details["execution_role"] = "cli"
+ # A per-call cost: a bounded loop would be ``expected`` before its role is read.
job = _finding(
- "src/f.py", 70, ["src/f.py::run", "src/db.py::fetch"], magnitude="bounded"
+ "src/f.py",
+ 70,
+ ["src/f.py::run", "src/db.py::fetch"],
+ marker="unbounded_read_reduced_in_memory",
+ magnitude=None,
)
job.details["execution_role"] = "scheduled_job"
repo_id, _ = await _seed(app, client, [served, cli, job])