Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(refactoring): staged Extract Method plans for functions one helper cannot fix (#3387)
Raghav Chamadiyafbfef70b936e
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.mdindex 7b93fd7f9..ec5f1bf19 100644--- a/docs/layers/REFACTORING.md+++ b/docs/layers/REFACTORING.md@@ -247,6 +247,14 @@ Most plans answer a health finding, so per-path marker rules inreplaces the span, in the file's language, with parameter types where the codedeclares them. Plan detail shows both with a copy button. Where the code namesno helper or type, the text reads `<name>` or `<type>` for you to fill in.+- A Python, TypeScript or JavaScript function too complex for one helper can+ get a staged plan instead: several helpers the function calls in order, each+ small enough to leave the finding behind. Plan detail lists them as steps,+ with a shared parameter object when many values pass between them, and the+ plan's estimated gain is the whole drop in the function's complexity. The+ plan's own span, header and call are its first stage. When a function moves+ between a single helper and a staged plan, or its stages change, the plan+ gets a new id.- Move Method never targets a class the method only instantiates, or an ancestor ofits own class.- Split File works on any language with call resolution and suggests a split onlydiff --git a/packages/core/src/repowise/core/agent_prompts/refactoring.py b/packages/core/src/repowise/core/agent_prompts/refactoring.pyindex 550c6b9d5..890310618 100644--- a/packages/core/src/repowise/core/agent_prompts/refactoring.py+++ b/packages/core/src/repowise/core/agent_prompts/refactoring.py@@ -43,6 +43,8 @@ def _symbol_lines(step: Mapping[str, Any]) -> list[str]:out = []if symbol.get("signature_text"):out.append(f"New helper: `{symbol['signature_text']}`")+ if symbol.get("return_text"):+ out.append(f"End the helper with: `{symbol['return_text']}`")if call.get("new_text"):lines = f"{span.get('start')}-{span.get('end')}"out.append(f"Replace lines {lines} with: `{call['new_text']}`")diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/assigned.py b/packages/core/src/repowise/core/analysis/health/dataflow/assigned.pynew file mode 100644index 000000000..bf68213c6--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/dataflow/assigned.py@@ -0,0 +1,163 @@+"""Definite assignment: the names written on every path to a point.++Reaching definitions (:mod:`reaching`) is a *may* analysis: a read sees a+write if some path carries it there. Two consumers need the opposite, *must*:+the perf pass, to prove a read in a loop cannot see a previous iteration's+write, and a staged Extract Method plan, whose helper parameter must be bound+on every path to the call (a name bound only under ``if outline is not None:``+raises at a call the original code, reading it under the same condition,+never made).++Forward, intersection over predecessors (:func:`must_defined_in`)::++ IN[start] = the seed; IN[b] = intersection over p in pred(b) of OUT[p]+ OUT[b] = IN[b] union names written in b+"""++from __future__ import annotations++from bisect import bisect_left+from collections.abc import Callable, Collection+from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from .analyze import FunctionAnalysis+ from .cfg import CFG+ from .defuse import FunctionDefUse+++def must_defined_in(+ cfg: CFG,+ def_use: FunctionDefUse,+ blocks: Collection[int],+ start_id: int,+ *,+ seed: frozenset[str] = frozenset(),+ edge: Callable[[int, int], bool] | None = None,+ from_try_source: bool = False,+) -> dict[int, frozenset[str]]:+ """Per block of *blocks*, the names written on every path from+ *start_id* (which begins with *seed*) to its entry. Only predecessors in+ *blocks* that *edge* accepts count.++ Solved as a round fixpoint rather than one sweep in block-id+ order: id order is *not* a topological order (``_build_if`` allocates the+ join before either arm), so one ordered pass reached joins before their+ arms. A handler is entered by an exception that may have escaped any+ statement of the protected region, including its first, so it inherits+ what was defined *before* the region, not after it: each predecessor's+ entry state. With *from_try_source*, the region's source block (the+ handler's lowest-id predecessor: the CFG creates a ``try`` body's blocks+ after the block it starts from) gives its exit state instead, which is+ exactly the state before the region. A block no counted predecessor+ reaches claims nothing.++ The lattice descends from "everything", so a partial state is larger than+ the answer; if it somehow does not converge inside the bound, nothing is+ reported defined, which can only refuse.+ """+ members = frozenset(blocks)+ written: dict[int, frozenset[str]] = {}+ for bid in members:+ bdu = def_use.block(bid)+ written[bid] = frozenset(d.var for d in bdu.defs) if bdu is not None else frozenset()+ universe: frozenset[str] = seed.union(*written.values())+ if not universe:+ return dict.fromkeys(members, frozenset())+ preds = _preds(cfg, members, edge, from_try_source)+ defined_in: dict[int, frozenset[str]] = dict.fromkeys(members, frozenset())+ defined_out: dict[int, frozenset[str]] = dict.fromkeys(members, universe)+ defined_out[start_id] = seed | written[start_id]+ ordered = sorted(members)+ # Descending a lattice of height |universe| over |blocks| cells, so this is+ # a generous ceiling on a monotone iteration, not a tuning parameter.+ for _round in range((len(universe) + 1) * len(ordered) + 1):+ changed = False+ for bid in ordered:+ din = seed if bid == start_id else _block_in(preds[bid], defined_in, defined_out)+ dout = din | written[bid]+ if din != defined_in[bid] or dout != defined_out[bid]:+ defined_in[bid], defined_out[bid] = din, dout+ changed = True+ if not changed:+ return defined_in+ return dict.fromkeys(members, frozenset())+++def _preds(+ cfg: CFG,+ members: frozenset[int],+ edge: Callable[[int, int], bool] | None,+ from_try_source: bool,+) -> dict[int, tuple[tuple[int, bool], ...]]:+ """Per block, its counted predecessors, each with whether its exit state+ (True) or its entry state (False) flows in: a handler takes entry states,+ except from the region's source block under *from_try_source*."""+ out: dict[int, tuple[tuple[int, bool], ...]] = {}+ for bid in members:+ found = [+ p for p in cfg.block(bid).predecessors if p in members and (edge is None or edge(p, bid))+ ]+ handler = cfg.block(bid).kind == "handler"+ source = min(found) if handler and from_try_source and found else None+ out[bid] = tuple((p, not handler or p == source) for p in found)+ return out+++def _block_in(+ preds: tuple[tuple[int, bool], ...],+ defined_in: dict[int, frozenset[str]],+ defined_out: dict[int, frozenset[str]],+) -> frozenset[str]:+ """The intersection over *preds* of the states that flow in; nothing for+ a block no counted predecessor reaches."""+ states = [defined_out[p] if exit_state else defined_in[p] for p, exit_state in preds]+ return frozenset.intersection(*states) if states else frozenset()+++class DefiniteAssignment:+ """:func:`must_defined_in` over a whole function from its entry (seeded+ with its parameters), asked at many lines. Solved on the first question,+ so a function no candidate asks about costs nothing."""++ def __init__(self, analysis: FunctionAnalysis) -> None:+ self._analysis = analysis+ self._in: dict[int, frozenset[str]] | None = None+ self._lines: list[int] = []+ self._blocks: list[int] = []++ def _solve(self) -> dict[int, frozenset[str]]:+ cfg, def_use = self._analysis.cfg, self._analysis.def_use+ # Only reachable blocks: one no path enters (code after a ``return``)+ # carries nothing and would empty every join it feeds.+ reachable = cfg.reachable_ids()+ heads = sorted(+ (st.start_line, b.id) for b in cfg.blocks if b.id in reachable for st in b.statements+ )+ self._lines = [line for line, _ in heads]+ self._blocks = [bid for _, bid in heads]+ return must_defined_in(+ cfg,+ def_use,+ reachable,+ cfg.entry_id,+ seed=frozenset(p.name for p in def_use.params),+ from_try_source=True,+ )++ def before(self, line: int, end: int | None = None) -> frozenset[str] | None:+ """The names written on every path to the first reachable statement at+ or after *line*; None when none follows, or none starts by *end* (the+ lines are code no path reaches)."""+ if self._in is None:+ self._in = self._solve()+ k = bisect_left(self._lines, line)+ if k == len(self._lines) or (end is not None and self._lines[k] > end):+ return None+ start, bid = self._lines[k], self._blocks[k]+ bdu = self._analysis.def_use.block(bid)+ earlier = frozenset(d.var for d in (bdu.defs if bdu else ()) if d.line < start)+ return self._in[bid] | earlier+++__all__ = ["DefiniteAssignment", "must_defined_in"]diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/slice.py b/packages/core/src/repowise/core/analysis/health/dataflow/slice.pyindex 593a5a58b..eb757d6e6 100644--- a/packages/core/src/repowise/core/analysis/health/dataflow/slice.py+++ b/packages/core/src/repowise/core/analysis/health/dataflow/slice.py@@ -114,6 +114,10 @@ class _Scan(NamedTuple):receiver: Receiver | None = None# Built from the fields above by :func:`_scan_for`; derived when absent.kinds: FactKinds | None = None+ #: What leaves the function itself (``return``); a raise does not, for a+ #: staged plan's helper, which re-raises it unchanged.+ exits: frozenset[str] = frozenset()+ yields: frozenset[str] = frozenset()class _Metrics(NamedTuple):@@ -124,6 +128,8 @@ class _Metrics(NamedTuple):awaits: boolreceiver_use: bool = Falsereceiver_assigns: frozenset[str] = frozenset()+ #: Function exits and yields (``_Scan.exits``, exit macros, ``yield``).+ exits: int = 0class _Prefix(NamedTuple):@@ -137,10 +143,14 @@ class _Prefix(NamedTuple):code: list[int]receiver: list[int]assigns: list[frozenset[str]]+ exits: list[int]def find_extractions(- analysis: FunctionAnalysis, lmap: LanguageNodeMap, receiver: Receiver | None = None+ analysis: FunctionAnalysis,+ lmap: LanguageNodeMap,+ receiver: Receiver | None = None,+ prefixes: dict[int, _Prefix] | None = None,) -> list[Extraction]:"""Return safe Extract Method candidates for *analysis*, best first.@@ -148,6 +158,8 @@ def find_extractions(then earliest -- a deterministic order. Empty when the function has no ASTnode retained or no span clears the extractability gates. *receiver* isthe function's instance (``DefUseDialect.receiver``), None when unknown.+ *prefixes*, when given, receives each walked block's :class:`_Prefix` by+ block id, so a staged plan reads them instead of walking again."""fn_node = analysis.fn_nodeif fn_node is None:@@ -201,6 +213,8 @@ def find_extractions()if n >= _MIN_STMTS:pre = _block_prefix(stmts, scan, lines, lmap)+ if prefixes is not None:+ prefixes[block.id] = prefor i in range(n):for j in range(i, n):evaluated += 1@@ -399,6 +413,8 @@ def _scan_for(lmap: LanguageNodeMap, receiver: Receiver | None, fn_node: Node) -awaits=_awaits(lmap),lambdas=lmap.lambda_kinds,receiver=receiver,+ exits=lmap.return_kinds,+ yields=lmap.yield_kinds,)return scan._replace(kinds=_span_kinds(scan))@@ -411,7 +427,7 @@ def _block_prefix(statements and its jump bit the OR, and re-walking per span made thecandidate loop O(n^2 * subtree). The named-nested-function check ridesthe same sums for the same reason."""- pre = _Prefix([0], [0], [0], [0], [0], [0], [])+ pre = _Prefix([0], [0], [0], [0], [0], [0], [], [0])for st in stmts:m = _span_metrics([st], scan)pre.decisions.append(pre.decisions[-1] + m.decisions)@@ -421,6 +437,7 @@ def _block_prefix(pre.code.append(pre.code[-1] + _stmts_nloc([st], lines))pre.receiver.append(pre.receiver[-1] + m.receiver_use)pre.assigns.append(m.receiver_assigns)+ pre.exits.append(pre.exits[-1] + m.exits)return pre@@ -660,23 +677,24 @@ def _infer_in_out(after it that may observe one of those writes (*reads*,:func:`_reads_observing`). A read before the span that a write in itreaches around a loop is not an OUT: :func:`_loop_carry_free` refuses- those spans.+ those spans. Both line lists are sorted (:func:`_var_lines`), so the+ span tests are bisects."""params: list[str] = []returns: list[str] = []for var in sorted(set(def_lines) | set(use_lines)):dl = def_lines.get(var, [])ul = use_lines.get(var, [])- in_uses = [ln for ln in ul if s <= ln <= e]- in_defs = [ln for ln in dl if s <= ln <= e]+ u_lo, u_hi = bisect_left(ul, s), bisect_right(ul, e)+ d_lo, d_hi = bisect_left(dl, s), bisect_right(dl, e)- if in_uses and any(ln < s for ln in dl):- first_use = in_uses[0]+ if u_lo < u_hi and d_lo > 0:+ first_use = ul[u_lo]declared = first_use in declared_first.get(var, ())- if not declared and not any(ln < first_use for ln in in_defs):+ if not declared and not (d_lo < d_hi and dl[d_lo] < first_use):params.append(var)- if in_defs and any(+ if d_lo < d_hi and any(ln > e and any(s <= d <= e for d in seen) for ln, seen in reads.get(var, ())):returns.append(var)@@ -1275,7 +1293,9 @@ def _span_kinds(scan: _Scan) -> FactKinds:return FactKinds(decisions=scan.decisions,jumps=scan.jumps,+ exits=scan.exits,exit_macros=scan.exit_macros,+ yields=scan.yields,awaits=await_kinds,await_scopes=await_scope_kinds,lambdas=scan.lambdas,@@ -1306,6 +1326,7 @@ def _span_metrics(span: list[Node], scan: _Scan) -> _Metrics:tally.awaits,sink.uses if sink else False,frozenset(sink.assigns) if sink else frozenset(),+ tally.exits + tally.yields,)diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/stages.py b/packages/core/src/repowise/core/analysis/health/dataflow/stages.pynew file mode 100644index 000000000..655a3b79c--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/dataflow/stages.py@@ -0,0 +1,539 @@+"""Staged Extract Method: split a brain method into helpers called in order.++One helper cannot take a function of CCN 70 under the bar: the slicer's best+span is a small share of it. This module cuts the function's *effective body*+into K contiguous stages, each a helper the function then calls in sequence.++- **Effective body.** A ``try`` / ``with`` statement holding most of a block's+ decision points is a wrapper: its body is cut instead, and the wrapper (with+ its ``except`` / ``finally`` and anything around it) stays in the function.+- **Stages.** Each is a run of that body's statements with ``CCN <= 10`` and+ ``NLOC <= 60``, at least two decision points, and no ``return`` / ``yield``+ (a ``raise`` propagates from a helper unchanged; the body is never inside a+ loop, so a ``break`` / ``continue`` cannot leave the stage). Its inputs and+ outputs come from the same line liveness as a single span; an output not+ written on every path is also passed in (``inout``), so a skipped write hands+ back the value it came with. Every input must be written on every path into+ the stage (:mod:`assigned`): one bound only under a condition would raise+ at the call. A name a stage declares in a nested block (a loop's ``const``)+ is the stage's own, never an output. A guard (``if not x: raise``) whose+ names the code after the stage reads stays in the function: type checkers+ narrow ``x`` from it.+- **Cuts.** A small dynamic program over the statement boundaries: lift as many+ decision points as possible, then prefer narrow interfaces (fewest names+ crossing a cut), cuts at a banner comment, a ``timed()`` label or a blank+ line, stages that do not run across a banner, and fewer stages.+ Deterministic: ties keep the earliest cut. A timer started in one+ statement and stopped in another (``timings.start("x")`` ...+ ``timings.stop("x")``) is never split by a stage edge.+- **Context.** When more than five values are read by two or more stages and+ never rebound once the first stage starts, they travel on one parameter+ object instead of as separate parameters. The receiver never does.+- **Composition.** The definitions each read observes+ (:func:`reaching.observed_definitions`) are checked against the plan: a+ value defined outside a stage and read inside it must be one of its+ inputs, and one defined in a stage and read outside it one of its+ outputs. A plan that fails is refused whole.++Function-local imports are not inputs: a helper re-imports a name, and the+function drops an import nothing it keeps still reads.+"""++from __future__ import annotations++import re+from bisect import bisect_right+from collections import Counter+from dataclasses import dataclass+from typing import TYPE_CHECKING++from ..complexity.nloc import is_string_stmt+from .assigned import DefiniteAssignment+from .reaching import observed_definitions+from .slice import (+ _MIN_SLICE_NLOC,+ Extraction,+ _block_prefix,+ _closure_state,+ _closure_state_crosses,+ _declaration_escapes,+ _declaration_lines,+ _declared_before_read,+ _function_lines,+ _hoisted_bindings,+ _identifiers,+ _infer_in_out,+ _Prefix,+ _reads_observing,+ _receiver_facts,+ _scan_for,+ _stmt_assigns,+ _unwrap_container,+ _var_lines,+)+from .span import is_comment, section_heads++if TYPE_CHECKING:+ from tree_sitter import Node++ from ..complexity.languages import LanguageNodeMap+ from .analyze import FunctionAnalysis+ from .defuse import FunctionDefUse+ from .dialects.base import Receiver++STAGE_MAX_CCN = 10+STAGE_MAX_NLOC = 60+# A stage lifting one decision point is a renamed ``if``: it merges into a+# neighbour or stays in the function.+_STAGE_MIN_DECISIONS = 2+# More shared values than a signature carries well (the slicer's own cap).+_CONTEXT_OVER = 5+# A wrapper holding this share of a block's decision points is unwrapped.+_WRAPPER_SHARE = 0.6++# Cut costs, in one integer scale. A decision point left in the function+# outweighs everything else; then the interface, the cut hints, the count.+_KEPT_DECISION = 200+_PER_STAGE = 20+_PER_NAME = 6+_UNHINTED_CUT = 8+_BLANK_LINE_CUT = 4+_CROSSED_BANNER = 6++# A timer's start and stop by label, in any language's call syntax.+_TIMER_START = re.compile(r"""\.start\(\s*["']([^"'\n]+)["']""")+_TIMER_STOP = re.compile(r"""\.stop\(\s*["']([^"'\n]+)["']""")+++@dataclass(frozen=True)+class StagePlan:+ """The stages in source order, the names carried on the parameter+ object (empty: plain parameters), and per stage the names it reads that+ the function imports outside it, which the helper must import itself;+ ``moved_imports`` are those nothing left in the function reads.+ ``reason`` says why there are no stages; None when there are."""++ stages: tuple[Extraction, ...] = ()+ context: tuple[str, ...] = ()+ imports: tuple[tuple[str, ...], ...] = ()+ moved_imports: frozenset[str] = frozenset()+ reason: str | None = None++ @property+ def ccn_removed(self) -> int:+ return sum(x.ccn_removed for x in self.stages)++ @property+ def slice_nloc(self) -> int:+ return sum(x.slice_nloc for x in self.stages)+++def find_stages(+ analysis: FunctionAnalysis,+ lmap: LanguageNodeMap,+ receiver: Receiver | None = None,+ *,+ max_returns: int = 3,+ prefixes: dict[int, _Prefix] | None = None,+) -> StagePlan:+ """The staged split of *analysis*, or a :class:`StagePlan` with only a+ ``reason`` when none composes. *max_returns* caps a stage's outputs (a+ language whose call cannot unpack a tuple passes 1). *prefixes* are the+ per-block statement metrics :func:`slice.find_extractions` already+ walked; a block missing from them is walked here."""+ fn_node = analysis.fn_node+ if fn_node is None or fn_node.has_error:+ return StagePlan(reason="no_tree")+ body = fn_node.child_by_field_name("body")+ if body is None:+ return StagePlan(reason="no_tree")+ blocks = _Blocks(analysis, lmap, receiver, prefixes if prefixes is not None else {})+ block = _effective_block(_unwrap_container(body, lmap.block_kinds), blocks, lmap)+ code, pre = blocks.code(block)+ if len(code) < 2:+ return StagePlan(reason="one_statement")+ cutter = _Cutter(analysis, lmap, receiver, block, code, pre, max_returns)+ stages = cutter.cut()+ if len(stages) < 2:+ return StagePlan(reason="fewer_than_two_stages")+ context = _context(stages, cutter.def_lines, receiver)+ composed = _composes(analysis, stages, context)+ if composed is None:+ return StagePlan(reason="composition")+ imports, moved = composed+ return StagePlan(stages=stages, context=context, imports=imports, moved_imports=moved)+++class _Blocks:+ """Each block's code statements and their prefix sums, read from the+ slicer's walk (*prefixes*) and walked only for a block it skipped."""++ def __init__(+ self,+ analysis: FunctionAnalysis,+ lmap: LanguageNodeMap,+ receiver: Receiver | None,+ prefixes: dict[int, _Prefix],+ ) -> None:+ self.analysis, self.lmap, self.prefixes = analysis, lmap, prefixes+ self.scan = _scan_for(lmap, receiver, analysis.fn_node)++ def code(self, block: Node) -> tuple[list[Node], _Prefix]:+ """The block's statements without comments or a leading docstring,+ and their metrics as prefix sums."""+ named = block.named_children+ keep = [k for k, c in enumerate(named) if not is_comment(c)]+ if keep and is_string_stmt(named[keep[0]]):+ keep = keep[1:]+ full = self.prefixes.get(block.id)+ if full is None:+ lines = _function_lines(self.analysis.fn_node)+ full = self.prefixes[block.id] = _block_prefix(named, self.scan, lines, self.lmap)+ return [named[k] for k in keep], _select(full, keep)+++def _select(pre: _Prefix, keep: list[int]) -> _Prefix:+ """*pre* over the statements at *keep* only."""+ out = _Prefix([0], [0], [0], [0], [0], [0], [], [0])+ sums = ("decisions", "jumps", "awaits", "nested", "code", "receiver", "exits")+ for k in keep:+ for name in sums:+ series = getattr(out, name)+ full = getattr(pre, name)+ series.append(series[-1] + full[k + 1] - full[k])+ out.assigns.append(pre.assigns[k])+ return out+++def _effective_block(block: Node, blocks: _Blocks, lmap: LanguageNodeMap) -> Node:+ """*block*, or the body of the ``try`` / ``with`` wrapper holding most of+ its decision points, repeatedly."""+ wrappers = lmap.try_kinds | lmap.with_kinds+ while True:+ code, pre = blocks.code(block)+ per = [pre.decisions[k + 1] - pre.decisions[k] for k in range(len(code))]+ total = sum(per)+ if not total:+ return block+ top = code[max(range(len(code)), key=per.__getitem__)]+ inner = top.child_by_field_name("body") if top.type in wrappers else None+ if inner is None:+ return block+ inner = _unwrap_container(inner, lmap.block_kinds)+ if blocks.code(inner)[1].decisions[-1] < _WRAPPER_SHARE * total:+ return block+ block = inner+++class _Cutter:+ """The candidate stages of one block and the cut that keeps the best."""++ def __init__(+ self,+ analysis: FunctionAnalysis,+ lmap: LanguageNodeMap,+ receiver: Receiver | None,+ block: Node,+ code: list[Node],+ pre: _Prefix,+ max_returns: int,+ ) -> None:+ self.lmap, self.receiver, self.block, self.code = lmap, receiver, block, code+ self.max_returns = max_returns+ def_use = analysis.def_use+ self.def_lines, self.use_lines = _var_lines(def_use)+ self.declared_first = _declared_before_read(def_use)+ self.hoisted = _hoisted_bindings(self.def_lines, self.use_lines)+ self.decl_lines = _declaration_lines(def_use)+ self.shared = _closure_state(def_use, self.def_lines, self.use_lines)+ self.reads = _reads_observing(analysis, self.def_lines)+ self.pre = pre+ self._assigns: dict[tuple[int, str], bool] = {}+ self.cut_cost = _cut_costs(code)+ self.banners = [c == 0 for c in self.cut_cost]+ self.timer_pairs = _timer_pairs(code)+ self.guards = [_guard_names(st, lmap) for st in code]+ self.assigned = DefiniteAssignment(analysis)+ self.inner_bindings = _inner_bindings(def_use)++ def _sum(self, series: list[int], i: int, j: int) -> int:+ return series[j + 1] - series[i]++ def cut(self) -> tuple[Extraction, ...]:+ """The lowest-cost split of the block (module docstring, Cuts). Each+ run ``i..j`` is weighed once, by the prefix ending at ``j``."""+ n = len(self.code)+ cost: list[int] = [0] * (n + 1)+ back: list[tuple[int, Extraction | None]] = [(0, None)] * (n + 1)+ for k in range(1, n + 1):+ cost[k], back[k] = self._best_ending_at(k, cost)+ stages: list[Extraction] = []+ k = n+ while k > 0:+ k, stage = back[k]+ if stage is not None:+ stages.append(stage)+ return tuple(reversed(stages))++ def _best_ending_at(+ self, k: int, cost: list[int]+ ) -> tuple[int, tuple[int, Extraction | None]]:+ """The cheapest split of statements ``0..k-1``: the last one kept in+ the function, or the last stage ``i..k-1`` after the best split of+ ``0..i-1``."""+ pre = self.pre+ kept = self._sum(pre.decisions, k - 1, k - 1)+ best = cost[k - 1] + _KEPT_DECISION * kept + self._sum(pre.code, k - 1, k - 1)+ choice: tuple[int, Extraction | None] = (k - 1, None)+ for i in range(k - 1, -1, -1):+ if (+ self._sum(pre.decisions, i, k - 1) + 1 > STAGE_MAX_CCN+ or self._sum(pre.code, i, k - 1) > STAGE_MAX_NLOC+ ):+ break+ stage = self._stage(i, k - 1)+ if stage is None:+ continue+ c = cost[i] + _PER_STAGE + _PER_NAME * (len(stage.params) + len(stage.returns))+ c += 0 if i == 0 else self.cut_cost[i]+ c += _CROSSED_BANNER * sum(self.banners[i + 1 : k])+ if c < best:+ best, choice = c, (i, stage)+ return best, choice++ def _stage(self, i: int, j: int) -> Extraction | None:+ """Statements ``i..j`` as a stage, or None when they cannot be one+ (code no path reaches included: nothing is known to be bound there)."""+ if not self._shape_allows(i, j):+ return None+ span = self.code[i : j + 1]+ s, e = span[0].start_point[0] + 1, span[-1].end_point[0] + 1+ params, returns = _infer_in_out(+ self.def_lines, self.use_lines, s, e, self.declared_first, reads=self.reads+ )+ returns = self._own_bindings_dropped(span, s, e, returns)+ params = self._with_inouts(i, j, s, params, returns)+ if params is None or len(returns) > self.max_returns:+ return None+ bound = self.assigned.before(s, e)+ if bound is None or not set(params) <= bound:+ return None+ if not self._signature_holds(span, s, e, returns) or self._guard_needed_after(i, j, e):+ return None+ pre = self.pre+ uses, assigns = _receiver_facts(self.receiver, pre, i, j, 0)+ return Extraction(+ start_line=s,+ end_line=e,+ params=params,+ returns=returns,+ slice_nloc=self._sum(pre.code, i, j),+ ccn_removed=self._sum(pre.decisions, i, j),+ needs_async=self._sum(pre.awaits, i, j) > 0,+ uses_receiver=uses,+ receiver_assigns=assigns,+ )++ def _shape_allows(self, i: int, j: int) -> bool:+ """The checks prefix sums answer: size, no return / yield, no named+ nested function, and no timer started on one side of the cut and+ stopped on the other."""+ pre = self.pre+ if self._sum(pre.decisions, i, j) < _STAGE_MIN_DECISIONS:+ return False+ if self._sum(pre.code, i, j) < _MIN_SLICE_NLOC:+ return False+ if self._sum(pre.exits, i, j) or self._sum(pre.nested, i, j):+ return False+ return not any((i <= a <= j) != (i <= b <= j) for a, b in self.timer_pairs)++ def _own_bindings_dropped(+ self, span: list[Node], s: int, e: int, returns: tuple[str, ...]+ ) -> tuple[str, ...]:+ """*returns* without the names the stage only declares inside a nested+ block (a loop's ``const``): those bindings end with the block."""+ top = [+ (st.start_point[0] + 1, st.end_point[0] + 1)+ for st in span+ if st.type in self.lmap.local_decl_kinds+ ]++ def scoped(var: str) -> bool:+ lines = [(ln, inner) for ln, inner in self.inner_bindings.get(var, ()) if s <= ln <= e]+ return bool(lines) and all(+ inner and not any(lo <= ln <= hi for lo, hi in top) for ln, inner in lines+ )++ return tuple(r for r in returns if not scoped(r))++ def _guard_needed_after(self, i: int, j: int, e: int) -> bool:+ """Whether a guard in statements ``i..j`` names a value read after *e*."""+ return any(+ any(ln > e for name in names for ln in self.use_lines.get(name, ()))+ for names in self.guards[i : j + 1]+ if names+ )++ def _signature_holds(self, span: list[Node], s: int, e: int, returns: tuple[str, ...]) -> bool:+ """The single-span slicer's own refusals: a hoisted binding, a+ declaration the code after the stage still needs, a local a closure+ shares across the stage's edge."""+ if any(s <= first_def <= e and first_use < s for first_def, first_use in self.hoisted):+ return False+ if _declaration_escapes(+ s, e, returns, self.decl_lines, self.def_lines, self.use_lines, self.declared_first+ ):+ return False+ return self.shared is None or not _closure_state_crosses(+ self.shared, span, s, e, self.block, self.lmap+ )++ def _with_inouts(+ self, i: int, j: int, s: int, params: tuple[str, ...], returns: tuple[str, ...]+ ) -> tuple[str, ...] | None:+ """*params* plus each output some path does not write, which the stage+ must then take in to hand back; None when such an output has no value+ before the stage."""+ extra = []+ for var in returns:+ if var in params or any(self._writes(k, var) for k in range(i, j + 1)):+ continue+ if not any(ln < s for ln in self.def_lines.get(var, ())):+ return None+ extra.append(var)+ return tuple(sorted((*params, *extra))) if extra else params+++ def _writes(self, k: int, var: str) -> bool:+ """Whether statement *k* writes *var* on every path through it (the+ slicer's proof), once per statement and name: a run proves it when any+ of its statements does."""+ key = (k, var)+ if key not in self._assigns:+ defs = self.def_lines.get(var, [])+ self._assigns[key] = _stmt_assigns(self.code[k], var, defs, self.lmap)+ return self._assigns[key]+++def _timer_pairs(code: list[Node]) -> list[tuple[int, int]]:+ """``(a, b)``: statement ``a`` starts a timer (``timings.start("x")``)+ that statement ``b`` stops, the first such at or after ``a``."""+ starts: list[set[str]] = []+ stops: list[set[str]] = []+ for st in code:+ text = (st.text or b"").decode("utf-8", "replace")+ starts.append(set(_TIMER_START.findall(text)))+ stops.append(set(_TIMER_STOP.findall(text)))+ pairs = []+ for a, labels in enumerate(starts):+ for label in labels:+ b = next((b for b in range(a, len(code)) if label in stops[b]), None)+ if b is not None:+ pairs.append((a, b))+ return pairs+++def _cut_costs(code: list[Node]) -> list[int]:+ """What cutting before each statement costs: nothing under a banner+ comment or a ``timed()`` label, less after a blank line."""+ out = []+ for n, (st, comment) in enumerate(section_heads(code)):+ prev = code[n - 1] if n else None+ blank = prev is not None and st.start_point[0] - prev.end_point[0] > 1+ out.append(0 if comment else _BLANK_LINE_CUT if blank else _UNHINTED_CUT)+ return out+++def _guard_names(st: Node, lmap: LanguageNodeMap) -> frozenset[str]:+ """The names a guard statement tests: an ``if`` with no else arm whose+ last statement is itself a raise (Python ``if not x: raise E``) or throw+ (TS / JS ``if (!x) throw e;`` or ``{ ...; throw e; }``). Type checkers+ narrow ``x`` after such a guard, which a helper holding it would undo.+ Empty for anything else, a raise nested deeper included."""+ if st.type not in lmap.if_kinds or st.child_by_field_name("alternative") is not None:+ return frozenset()+ if any(c.type in ("else_clause", "elif_clause") for c in st.children):+ return frozenset()+ body = st.child_by_field_name("consequence")+ if body is None:+ return frozenset()+ stmts = [c for c in body.named_children if not is_comment(c)]+ # ``if (!x) throw e;`` has the throw itself as its consequence.+ last = body if body.type in lmap.raise_kinds or not stmts else stmts[-1]+ if last.type not in lmap.raise_kinds:+ return frozenset()+ condition = st.child_by_field_name("condition")+ return frozenset(_identifiers(condition)) if condition is not None else frozenset()+++def _inner_bindings(def_use: FunctionDefUse) -> dict[str, list[tuple[int, bool]]]:+ """Per name, each write's line and whether it opens a block-scoped+ binding (``let`` / ``const`` / a loop's declared variable)."""+ out: dict[str, list[tuple[int, bool]]] = {}+ for d in def_use.definitions:+ out.setdefault(d.var, []).append((d.line, d.declares))+ return out+++def _context(+ stages: tuple[Extraction, ...], def_lines: dict[str, list[int]], receiver: Receiver | None+) -> tuple[str, ...]:+ """The values for one parameter object: read by two or more stages, never+ an output, not written again once the first stage starts, and not the+ receiver (a method reaches its instance as itself, not off an object)."""+ first = stages[0].start_line+ own = receiver.names if receiver is not None else frozenset()+ outs = {r for x in stages for r in x.returns}+ counts = Counter(p for x in stages for p in x.params)+ shared = sorted(+ var+ for var, n in counts.items()+ if n >= 2+ and var not in outs+ and var not in own+ and all(ln < first for ln in def_lines.get(var, ()))+ )+ return tuple(shared) if len(shared) > _CONTEXT_OVER else ()+++def _composes(+ analysis: FunctionAnalysis, stages: tuple[Extraction, ...], context: tuple[str, ...]+) -> tuple[tuple[tuple[str, ...], ...], frozenset[str]] | None:+ """Per stage, the function-local imports it reads from outside itself,+ and those no read left in the function needs; None when some read would+ no longer see the value it saw (module docstring, Composition), by the+ definitions each read observes."""+ starts = [x.start_line for x in stages]+ ins = [set(x.params) | set(context) for x in stages]+ outs = [set(x.returns) for x in stages]+ imported: list[set[str]] = [set() for _ in stages]+ kept: set[str] = set()++ def stage_at(line: int) -> int | None:+ k = bisect_right(starts, line) - 1+ return k if k >= 0 and line <= stages[k].end_line else None++ definitions = analysis.reaching.definitions+ for use, seen in observed_definitions(analysis.def_use, analysis.reaching):+ if use.echo:+ continue+ m = stage_at(use.line)+ for d in (definitions[i] for i in seen):+ k = stage_at(d.line)+ if d.imports:+ if m is None:+ kept.add(use.name)+ elif k != m:+ imported[m].add(use.name)+ continue+ if k == m:+ continue+ if (m is not None and use.name not in ins[m]) or (+ k is not None and use.name not in outs[k]+ ):+ return None+ moved = frozenset().union(*imported) - kept+ return tuple(tuple(sorted(names)) for names in imported), moved+++__all__ = ["STAGE_MAX_CCN", "STAGE_MAX_NLOC", "StagePlan", "find_stages"]diff --git a/packages/core/src/repowise/core/analysis/health/perf/promotion.py b/packages/core/src/repowise/core/analysis/health/perf/promotion.pyindex 49d8f1cd4..784ce20be 100644--- a/packages/core/src/repowise/core/analysis/health/perf/promotion.py+++ b/packages/core/src/repowise/core/analysis/health/perf/promotion.py@@ -238,82 +238,23 @@ def _must_defined_before_block() -> dict[int, frozenset[str]]:"""Variables guaranteed written before each loop block, within one iteration.- A forward *must* (intersection) analysis over the loop's blocks, treating the- header as the iteration start (nothing defined yet) and ignoring the- back-edge, so it measures what a single pass from the header definitely- writes before a given block. A use whose variable is in this set was- redefined this iteration and cannot read a previous one.-- Solved as a worklist fixpoint rather than one sweep in block-id order. Id- order is *not* a topological order of the loop DAG: ``_build_if`` allocates- the join block before either arm, so a join's id is lower than the ids of- the predecessors flowing into it. A single ordered pass therefore reached- joins before their arms and, with the arms' results still missing, collapsed- every join to "nothing is definitely defined". Any ``if`` or ``try`` that- assigned before the awaited call made the whole loop unprovable, which is a- false refusal rather than an unsafe promotion, but it refused a large share- of ordinary loops.-- Direction matters for soundness. The lattice descends from "everything" to- the fixpoint, so a partially solved state is *larger* than the answer, and a- larger must-set promotes more. The iteration therefore runs to convergence- or, if it somehow does not converge inside the bound, reports nothing as- definitely defined, which can only refuse.+ A forward *must* analysis (:func:`dataflow.assigned.must_defined_in`) over+ the loop's blocks, treating the header as the iteration start (nothing+ defined yet) and ignoring the back-edge, so it measures what a single pass+ from the header definitely writes before a given block. A use whose+ variable is in this set was redefined this iteration and cannot read a+ previous one."""- defs_in_block: dict[int, frozenset[str]] = {}- for bid in loop_blocks:- bdu = def_use.block(bid)- defs_in_block[bid] = frozenset(d.var for d in bdu.defs) if bdu is not None else frozenset()-- # Only a variable the loop writes can ever be must-defined, since the header- # starts empty and the transfer only ever adds this block's own defs.- universe: frozenset[str] = frozenset().union(*defs_in_block.values())- if not universe:- return dict.fromkeys(loop_blocks, frozenset())-- preds: dict[int, tuple[int, ...]] = {- bid: tuple(- p- for p in cfg.block(bid).predecessors- if p in loop_blocks and not _is_back_edge(cfg, p, bid)- )- for bid in loop_blocks- }-- defined_in: dict[int, frozenset[str]] = dict.fromkeys(loop_blocks, frozenset())- defined_out: dict[int, frozenset[str]] = dict.fromkeys(loop_blocks, universe)- defined_out[header_id] = defs_in_block[header_id]-- ordered = sorted(loop_blocks)- # Descending a lattice of height |universe| over |blocks| cells, so this is- # a generous ceiling on a monotone iteration, not a tuning parameter.- for _round in range((len(universe) + 1) * len(ordered) + 1):- changed = False- for bid in ordered:- if bid == header_id:- din: frozenset[str] = frozenset()- else:- # A handler is entered by an exception that may have escaped any- # statement of the protected region, including its first, so it- # inherits what was defined *before* that region rather than- # after it. The CFG draws one edge from the region's entry block- # and the whole ``try`` body usually sits in that block, so- # reading the predecessor's exit state here would count- # assignments the exception may have skipped.- entry_state = cfg.block(bid).kind == "handler"- pred_states = [- defined_in[p] if entry_state else defined_out[p] for p in preds[bid]- ]- # No in-loop forward predecessor means the block is not reachable- # from the header within one iteration; claim nothing for it.- din = frozenset.intersection(*pred_states) if pred_states else frozenset()- dout = din | defs_in_block[bid]- if din != defined_in[bid] or dout != defined_out[bid]:- defined_in[bid], defined_out[bid] = din, dout- changed = True- if not changed:- return defined_in- return dict.fromkeys(loop_blocks, frozenset())+ # Deferred like the module's other dataflow imports (an import cycle).+ from ..dataflow.assigned import must_defined_in++ return must_defined_in(+ cfg,+ def_use,+ loop_blocks,+ header_id,+ edge=lambda src, dst: not _is_back_edge(cfg, src, dst),+ )def _is_back_edge(cfg: CFG, src: int, dst: int) -> bool:diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.py b/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.pyindex f024b247f..3b5b8d380 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.py@@ -76,6 +76,16 @@ Plan shape (open dict, no migration):and ``suggested_name`` is in the language's private form (Python ``_x``).- ``evidence`` = ``{"slice_nloc": int, "ccn_removed": int}`` -- the size andcomplexity (code lines, decision points) the residual method sheds.+- ``plan.stages`` -- only on a staged plan (``dataflow.stages``): a function+ no single helper brings under the bar (CCN over twice a stage's cap, Python+ and TS / JS) is split into helpers called in order. Each stage carries the+ same keys as a single-span plan plus ``ccn``, ``nloc`` and+ ``context_params`` (the names it reads through ``plan.parameter_object``,+ the shared values' object, or None). The top-level keys repeat stage 1, so+ a reader of a single-span plan reads the first step; ``orchestrator`` gives+ the function's CCN before and after, and ``evidence`` sums the stages, so+ the plan is credited the whole drop rather than one span's share. Detail+ only (``render.list_plan``).- ``blast_radius`` = ``{"scope": "local"}`` -- extraction is local (a newprivate helper, the public method's signature is unchanged), so nothingoutside the file moves. This is a *categorical* statement, not a count: it@@ -88,6 +98,7 @@ Plan shape (open dict, no migration):from __future__ import annotationsfrom collections.abc import Callable+from dataclasses import replacefrom typing import TYPE_CHECKING, Anyfrom ..biomarkers.brain_method import BrainMethodDetector@@ -96,7 +107,8 @@ from ..biomarkers.large_method import LargeMethodDetectorfrom ..complexity.cyclomatic import _is_boolean_operator, is_markupfrom ..complexity.languages import get_language_mapfrom ..complexity.nloc import is_string_stmt-from ..dataflow import find_extractions, get_defuse_dialect+from ..dataflow import Extraction, find_extractions, get_defuse_dialect+from ..dataflow.stages import STAGE_MAX_CCN, StagePlan, find_stagesfrom ..effort import effort_bucketfrom ..perf.dialects import PERF_DIALECTSfrom ..scoring import severity_deduction@@ -107,7 +119,7 @@ from .registry import RefactoringDetector, registerif TYPE_CHECKING:from ..complexity.languages import LanguageNodeMap- from ..dataflow import Definition, Extraction, FunctionAnalysis+ from ..dataflow import Definition, FunctionAnalysisfrom ..dataflow.dialects.base import BaseDefUseDialect, Receiverfrom ..models import Severity@@ -141,6 +153,11 @@ _MIN_OFFER_NLOC = 8# is safe but moves almost nothing._HIGH_MIN_SHARE = 0.1+# Above this no single helper of a stage's size brings the function under it.+_STAGE_MIN_CCN = 2 * STAGE_MAX_CCN + 1+# Keys a stage carries that the plan's own (stage 1) keys do not.+_STAGE_ONLY_KEYS = ("ccn", "nloc", "context_params")+@registerclass ExtractMethodDetector(RefactoringDetector):@@ -168,7 +185,16 @@ class ExtractMethodDetector(RefactoringDetector):markers = {getattr(f, "biomarker_type", "") for f in matched}fn_node = analysis.fn_nodereceiver = dialect.receiver(fn_node, lmap) if dialect and fn_node else None- best = _choose(analysis, find_extractions(analysis, lmap, receiver), markers)+ # The slicer's per-block walk, read again by a staged plan.+ prefixes: dict[int, Any] = {}+ candidates = find_extractions(analysis, lmap, receiver, prefixes)+ best = _choose(analysis, candidates, markers)+ staged = _staged(analysis, best, lmap, receiver, ctx.language, markers, prefixes)+ if staged is not None:+ out.append(+ self._staged_suggestion(ctx, analysis, staged, matched, names, receiver)+ )+ continueif best is None:continueimpact, share, source = self._impact_for(analysis, best, matched)@@ -220,6 +246,41 @@ class ExtractMethodDetector(RefactoringDetector):out.sort(key=lambda s: (-s.impact_delta, s.target_symbol, s.line_start or 0))return out+ def _staged_suggestion(+ self,+ ctx: RefactoringContext,+ analysis: FunctionAnalysis,+ staged: StagePlan,+ matched: list[Any],+ names: ScopeNames,+ receiver: Receiver | None,+ ) -> RefactoringSuggestion:+ """The plan for a staged split, credited the whole CCN drop."""+ total = Extraction(+ start_line=staged.stages[0].start_line,+ end_line=staged.stages[-1].end_line,+ params=(),+ returns=(),+ slice_nloc=staged.slice_nloc,+ ccn_removed=staged.ccn_removed,+ )+ impact, _share, source = self._impact_for(analysis, total, matched)+ return RefactoringSuggestion(+ refactoring_type=self.name,+ file_path=ctx.file_path,+ target_symbol=analysis.name,+ line_start=analysis.start_line,+ line_end=analysis.end_line,+ plan=_staged_fields(analysis, staged, ctx.language, names, receiver),+ evidence={"slice_nloc": total.slice_nloc, "ccn_removed": total.ccn_removed},+ impact_delta=round(float(impact), 3),+ effort_bucket=effort_bucket(total.slice_nloc),+ blast_radius={"scope": "local"},+ # Several edits to one function: a reviewer reads the plan first.+ confidence="medium",+ source_biomarker=source,+ )+@staticmethoddef _findings_for(analysis: FunctionAnalysis, findings: list[Any]) -> list[Any]:"""The file's method-smell findings on *analysis*. Matches by function@@ -290,6 +351,153 @@ def recovered_share(return min(1.0, ccn_share)+def _staged(+ analysis: FunctionAnalysis,+ best: Extraction | None,+ lmap: LanguageNodeMap,+ receiver: Receiver | None,+ language: str | None,+ markers: set[str],+ prefixes: dict[int, Any] | None = None,+) -> StagePlan | None:+ """The staged split, when the function is too complex for one helper and+ the split lifts at least twice what the best single span does (several+ edits for a point or two more is not the better plan); each stage must+ clear the floor a single span does."""+ # Only languages with a staged renderer, each with the outputs one call binds.+ max_returns = render.staged_outputs(language)+ if max_returns is None or analysis.ccn < _STAGE_MIN_CCN:+ return None+ plan = find_stages(analysis, lmap, receiver, max_returns=max_returns, prefixes=prefixes)+ if not plan.stages or (best is not None and plan.ccn_removed < 2 * best.ccn_removed):+ return None+ if not all(_worth_extracting(analysis, x, markers) for x in plan.stages):+ return None+ return plan+++def _staged_fields(+ analysis: FunctionAnalysis,+ staged: StagePlan,+ language: str | None,+ names: ScopeNames,+ receiver: Receiver | None,+) -> dict[str, Any]:+ """The staged plan: stage 1's keys, ``stages``, ``parameter_object`` and+ ``orchestrator`` (module docstring)."""+ lmap = get_language_map(language or "")+ dialect = get_defuse_dialect(language or "")+ obj = _parameter_object(analysis, staged, dialect, language, names)+ # Without an object (no free variable name for it) the values stay plain.+ context = staged.context if obj else ()+ imports = names.imports(analysis.fn_node)+ stages = []+ for x, reimports in zip(staged.stages, staged.imports, strict=True):+ name = render.private_name(+ language, names.claim(analysis, helper_name(analysis, x, lmap, language, imports))+ )+ carried = [p for p in x.params if p in context]+ own = replace(x, params=tuple(p for p in x.params if p not in context))+ lead = (render.Slot(obj["var"], obj["name"]),) if obj and carried else ()+ async_fields = _async_fields(analysis, x, lmap, language)+ symbol = _render_fields(+ analysis,+ own,+ dialect,+ language,+ name,+ _symbol_fields(x, receiver),+ async_host=async_fields.get("async_host", True),+ leading=lead,+ )+ _add_stage_notes(symbol["new_symbol"], lead, carried, reimports, staged.moved_imports)+ stages.append(+ {+ "span": {"start": x.start_line, "end": x.end_line},+ "params": [s.name for s in lead] + list(own.params),+ "returns": list(x.returns),+ "suggested_name": name,+ **async_fields,+ **symbol,+ "ccn": x.ccn_removed + 1,+ "nloc": x.slice_nloc,+ "context_params": carried,+ }+ )+ head = {k: v for k, v in stages[0].items() if k not in _STAGE_ONLY_KEYS}+ orchestrator = {"ccn_before": analysis.ccn, "ccn_after": analysis.ccn - staged.ccn_removed}+ return {**head, "stages": stages, "parameter_object": obj, "orchestrator": orchestrator}+++def _add_stage_notes(+ symbol: dict[str, Any],+ lead: tuple[render.Slot, ...],+ carried: list[str],+ reimports: tuple[str, ...],+ moved: frozenset[str],+) -> None:+ """What a stage's texts cannot say: the values it reads off the parameter+ object, the function-local imports it must repeat, and which of those the+ function no longer reads."""+ notes = list(symbol.get("notes") or [])+ if lead:+ reads = ", ".join(f"{lead[0].name}.{p}" for p in carried)+ notes.append(f"Read {', '.join(carried)} in the helper as {reads}.")+ if reimports:+ notes.append(+ f"Import {', '.join(reimports)} in the helper: the function imports "+ f"{'it' if len(reimports) == 1 else 'them'} inside its body."+ )+ gone = [n for n in reimports if n in moved]+ if gone:+ notes.append(+ f"Remove {', '.join(gone)} from the function's own import: nothing left in it "+ "reads " + ("it." if len(gone) == 1 else "them.")+ )+ if notes:+ symbol["notes"] = notes+++def _parameter_object(+ analysis: FunctionAnalysis,+ staged: StagePlan,+ dialect: BaseDefUseDialect | None,+ language: str | None,+ names: ScopeNames,+) -> dict[str, Any] | None:+ """The object carrying the stages' shared values, or None without one:+ its type and variable name, typed fields, the declaration and the+ statement building it just above stage 1's call."""+ if not staged.context:+ return None+ first = staged.stages[0].start_line+ probe = Extraction(first, first, staged.context, (), 0, 0)+ types = _declared_types(analysis, probe, dialect)+ fields = tuple(render.Slot(n, types.get(n)) for n in staged.context)+ # Every name the function writes or reads (a module global ``ctx`` too).+ def_use = analysis.def_use+ taken = {d.var for d in def_use.definitions}+ taken |= {u.name for bdu in def_use.blocks.values() for u in bdu.uses}+ taken |= {u.name for u in def_use.captured.reads}+ var = next((v for v in ("ctx", "context", "stage_ctx") if v not in taken), None)+ if var is None:+ return None+ name = names.claim(analysis, render.context_name(language, analysis.name))+ name = name or render.NAME_PLACEHOLDER+ texts = render.render_context(language or "", name, var, fields)+ if texts is None:+ return None+ return {+ "name": name,+ "var": var,+ "fields": [{"name": f.name, "type": f.type} for f in fields],+ "declaration_text": texts.declaration,+ "construct_text": texts.construct,+ "construct_before": first,+ "notes": list(texts.notes),+ }++def _async_fields(analysis: FunctionAnalysis,extraction: Extraction,@@ -341,19 +549,21 @@ def _render_fields(symbol: dict[str, Any],*,async_host: bool,+ leading: tuple[render.Slot, ...] = (),) -> dict[str, Any]:"""*symbol* with ``new_symbol`` given its typed ``params`` / ``returns``,``signature_text`` and any ``notes``, plus ``call_site`` (``render``).Types are read off the retained tree at each name's declaration, only forthis plan's few names; the texts are None when the helper's form is- unknown, and ``call_site`` also when the host cannot await the helper."""+ unknown, and ``call_site`` also when the host cannot await the helper.+ *leading* slots come first (a staged plan's parameter object)."""new_symbol = symbol["new_symbol"]types = _declared_types(analysis, extraction, dialect)# Only a Rust value moves when passed, so only Rust asks what is read later.after = _read_after(analysis, extraction) if language == "rust" else set()# A method reaches its instance through the receiver, not an argument.own = new_symbol["receiver"] if new_symbol["kind"] == "method" else None- params = tuple(+ params = leading + tuple(render.Slot(p, types.get(p), p in after) for p in extraction.params if p != own)returns = tuple(render.Slot(r, types.get(r)) for r in extraction.returns)@@ -373,6 +583,8 @@ def _render_fields(out_declared=declared,out_written_before=before,out_rebound=rebound,+ typed_host=fn_node is not None+ and fn_node.child_by_field_name("return_type") is not None,))rendered = {@@ -380,6 +592,7 @@ def _render_fields("params": render.symbol_params(params, returns),"returns": [{"name": r.name, "type": r.type} for r in returns],"signature_text": texts.signature if texts else None,+ "return_text": texts.returns if texts else None,}if texts and texts.notes:rendered["notes"] = list(texts.notes)diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/identity.py b/packages/core/src/repowise/core/analysis/health/refactoring/identity.pyindex be75caf86..556d78fe5 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/identity.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/identity.py@@ -171,9 +171,13 @@ def _extract_method_kernel(suggestion: Any, file_path: str) -> RefactoringKernelThe span itself is line-based, so only its length participates. Two spans inone function that agree on signature and length collide; :func:`assign_public_ids`breaks that tie deterministically rather than letting the ids merge.++ A staged plan's top-level signature is only its first stage's, so it also+ carries its stage count and each stage's span length: a different split is+ a different plan. A single-span plan's kernel is unchanged."""plan = _plan_of(suggestion)- return (+ kernel: RefactoringKernel = ("extract_method",file_path,field(suggestion, "target_symbol") or "",@@ -181,6 +185,14 @@ def _extract_method_kernel(suggestion: Any, file_path: str) -> RefactoringKerneltuple(str(name) for name in (plan.get("returns") or [])),_span_length(suggestion),)+ stages = [s for s in plan.get("stages") or [] if isinstance(s, dict)]+ if not stages:+ return kernel+ lengths = tuple(+ (s.get("span") or {}).get("end", 0) - (s.get("span") or {}).get("start", 0)+ for s in stages+ )+ return (*kernel, len(stages), lengths)def _move_method_kernel(suggestion: Any, file_path: str) -> RefactoringKernel:diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/recipe.py b/packages/core/src/repowise/core/analysis/health/refactoring/recipe.pyindex 0736c9518..691ed5bad 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/recipe.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/recipe.py@@ -125,13 +125,50 @@ def _s(count: int) -> str:def _extract_method(d: Mapping[str, Any], plan: Mapping[str, Any]) -> list[Step]:+ stages = [_dict(stage) for stage in _list(plan.get("stages"))]+ if stages:+ return _staged_steps(d, plan, stages)+ return [_extract_step(d, plan)]+++def _staged_steps(+ d: Mapping[str, Any], plan: Mapping[str, Any], stages: list[dict[str, Any]]+) -> list[Step]:+ """A staged plan: the shared parameter object first, then one extract step+ per stage in source order. Every line number is the original file's."""+ steps: list[Step] = []+ obj = _dict(plan.get("parameter_object"))+ if obj:+ text = (+ f"Add `{obj.get('name')}` holding the values the stages share, and build it "+ f"as `{obj.get('var')}` just above line {obj.get('construct_before')}: "+ f"`{obj.get('construct_text')}`."+ )+ symbol = {+ "name": obj.get("name"),+ "kind": "class",+ "async": False,+ "params": [],+ "returns": [],+ "signature_text": obj.get("declaration_text"),+ "notes": _strs(obj.get("notes")),+ }+ steps.append(_step("add_helper", d.get("file_path"), None, text, new_symbol=symbol))+ for n, stage in enumerate(stages, 1):+ step = _extract_step(d, stage)+ step["text"] = f"Stage {n} of {len(stages)}: {step['text']}"+ steps.append(step)+ return steps+++def _extract_step(d: Mapping[str, Any], plan: Mapping[str, Any]) -> Step:span = _dict(plan.get("span"))where = _span(span.get("start"), span.get("end"))host = _short(d.get("target_symbol"))name = plan.get("suggested_name") or NAME_PLACEHOLDERif where is None:text = f"Extract a slice of `{host}` into a helper."- return [_step("extract", d.get("file_path"), None, text)]+ return _step("extract", d.get("file_path"), None, text)symbol = _dict(plan.get("new_symbol"))is_async = bool(symbol.get("async", plan.get("needs_async")))named = (@@ -143,24 +180,23 @@ def _extract_method(d: Mapping[str, Any], plan: Mapping[str, Any]) -> list[Step]f"Move lines {where['start']}-{where['end']} of `{host}` into a new helper "f"`{name}`{named} in the same scope, and replace them with one call to it.")- return [- _step(- "extract",- d.get("file_path"),- where,- text,- new_symbol={- "name": name,- "kind": symbol.get("kind"),- "async": is_async,- "params": _strs(plan.get("params")),- "returns": _strs(plan.get("returns")),- "signature_text": symbol.get("signature_text"),- "notes": _extract_notes(plan, symbol, is_async),- },- **({"call_site": plan["call_site"]} if _dict(plan.get("call_site")) else {}),- )- ]+ return _step(+ "extract",+ d.get("file_path"),+ where,+ text,+ new_symbol={+ "name": name,+ "kind": symbol.get("kind"),+ "async": is_async,+ "params": _strs(plan.get("params")),+ "returns": _strs(plan.get("returns")),+ "signature_text": symbol.get("signature_text"),+ "return_text": symbol.get("return_text"),+ "notes": _extract_notes(plan, symbol, is_async),+ },+ **({"call_site": plan["call_site"]} if _dict(plan.get("call_site")) else {}),+ )def _extract_notes(@@ -375,6 +411,13 @@ def recipe_steps(detail: Mapping[str, Any]) -> list[Step]:def _summary(d: Mapping[str, Any], steps: list[Step]) -> str:kind, plan = d.get("refactoring_type"), _dict(d.get("plan"))+ if kind == "extract_method" and plan.get("stages"):+ residual = _dict(plan.get("orchestrator"))+ return (+ f"Split `{_short(d.get('target_symbol'))}` into {len(_list(plan['stages']))} "+ f"helpers it calls in order (cyclomatic complexity {residual.get('ccn_before')} "+ f"-> {residual.get('ccn_after')})."+ )if kind == "extract_method" and steps[0].get("span"):span, name = steps[0]["span"], steps[0]["new_symbol"]["name"]host = _short(d.get("target_symbol"))@@ -498,12 +541,18 @@ def _does_not(d: Mapping[str, Any], steps: list[Step]) -> list[dict[str, str | N"""What the edit must not do, each a phrase read after "Do not", with its reason."""out: list[dict[str, str | None]] = [dict(_KEEP_BEHAVIOUR)]kind = str(d.get("refactoring_type") or "")- span = steps[0].get("span")+ # A staged plan's edits run from its first stage to its last.+ spans = [s["span"] for s in steps if s.get("action") == "extract" and s.get("span")]+ span = {"start": spans[0]["start"], "end": spans[-1]["end"]} if spans else Noneif kind == "extract_method" and span:lines = f"{span['start']}-{span['end']}"+ added = (+ "the calls that replace them (and the object the stages share, if any)"+ if len(spans) > 1+ else "the call that replaces them"+ )out.append(- {"constraint": f"touch anything outside lines {lines} and the call that replaces them",- "reason": None}+ {"constraint": f"touch anything outside lines {lines} and {added}", "reason": None})elif kind in _DOES_NOT:constraint, reason = _DOES_NOT[kind]diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/render.py b/packages/core/src/repowise/core/analysis/health/refactoring/render.pyindex cce408481..55ea77aa2 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/render.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/render.py@@ -26,10 +26,11 @@ name is left out where the language allows it (Python, TS / JS) and written``<type>`` where it does not (Go, Java, Rust, C / C++); a missing name is``<name>``. Both are placeholders the agent must replace.-Ceilings: one output at most, as the slicer never offers more-(``dataflow.slice._MAX_RETURNS``); C7's staged plans bring tuple returns. A-C++ method defined out of line (``A::f``) has an unknown receiver, so it gets-no texts and the header is never qualified.+Ceilings: one output at most, except Python, where a staged plan's helper+may hand back a tuple (``a, b = _stage(...)``). A staged plan's parameter+object is written by :func:`render_context`. A C++ method defined out of line+(``A::f``) has an unknown receiver, so it gets no texts and the header is+never qualified."""from __future__ import annotations@@ -37,6 +38,8 @@ from __future__ import annotationsfrom dataclasses import dataclassfrom typing import Literal, NamedTuple, get_args+from .naming import split_words+ParamMode = Literal["in", "inout"]#: ``inout``: the helper takes the value and hands its new value back.PARAM_MODES: tuple[str, ...] = get_args(ParamMode)@@ -61,6 +64,9 @@ _FAMILY: dict[str, str] = {#: Languages whose signatures need every type written._TYPED = frozenset({"go", "java", "rust", "cpp"})#: Rust types that copy rather than move when passed by value.+#: Outputs one call of a staged plan's helper can bind, per language with a+#: staged renderer: a Python tuple, one TS / JS value.+_STAGED_OUTPUTS: dict[str, int] = {"python": 3, "ts": 1, "js": 1}_RUST_COPY = frozenset({*(f"{s}{n}" for s in "iu" for n in ("8", "16", "32", "64", "128", "size")),@@ -93,7 +99,8 @@ class HelperShape:await the helper. ``out_declared``: the output is first declared in thespan, so the call declares it; ``out_written_before``: it was writtenbefore the span (Go's ``:=`` would then declare nothing new);- ``out_rebound``: it is assigned again after the span.+ ``out_rebound``: it is assigned again after the span. ``typed_host``: the+ host declares its return type, so a helper with no output says so too."""language: str@@ -108,12 +115,15 @@ class HelperShape:out_declared: bool = Falseout_written_before: bool = Falseout_rebound: bool = False+ typed_host: bool = Falseclass Rendered(NamedTuple):signature: strcall: str | Nonenotes: tuple[str, ...]+ #: The helper's last line handing its outputs back, None without outputs.+ returns: str | None = Nonedef private_name(language: str | None, name: str | None) -> str | None:@@ -125,6 +135,12 @@ def private_name(language: str | None, name: str | None) -> str | None:return name+def staged_outputs(language: str | None) -> int | None:+ """How many outputs a staged plan's helper may return in *language*, None+ where no staged plan is rendered."""+ return _STAGED_OUTPUTS.get(_FAMILY.get(language or "", ""))++def symbol_params(params: tuple[Slot, ...], returns: tuple[Slot, ...]) -> list[dict]:"""``new_symbol.params``: name, type, and ``inout`` for a value the helperalso returns."""@@ -151,12 +167,47 @@ def render(shape: HelperShape) -> Rendered | None:"The function holding these lines is not async, so the call cannot await ""the helper where it stands.")- return Rendered(sig(shape), None, tuple(notes))- return Rendered(sig(shape), call(shape), tuple(notes))+ return Rendered(sig(shape), None, tuple(notes), _return_line(shape, family))+ return Rendered(sig(shape), call(shape), tuple(notes), _return_line(shape, family))+++def _return_line(s: HelperShape, family: str) -> str | None:+ """``return a, b`` (Python), ``return a;`` (C family), a Rust tail ``a``."""+ if not s.returns:+ return None+ names = ", ".join(r.name for r in s.returns)+ if family == "rust":+ return names+ return f"return {names}" if family in ("python", "go") else f"return {names};"+++def _undefined_arm_notes(s: HelperShape) -> list[str]:+ """A TS / JS output the author declared ``T | undefined`` that the helper+ always writes (it is not passed in): the declared type is kept, and the+ note says the narrower return type is safe."""+ taken = {p.name for p in s.params}+ out = []+ for r in s.returns:+ arms = [a.strip() for a in (r.type or "").split("|")]+ kept = [a for a in arms if a != "undefined"]+ if r.name not in taken and kept and len(kept) < len(arms):+ out.append(+ f"{r.name} is declared `{r.type}`, but every path through these lines "+ f"writes it, so the helper may return `{' | '.join(kept)}`."+ )+ return outdef _notes(s: HelperShape, family: str) -> list[str]:out = []+ if family in ("ts", "js"):+ out.extend(_undefined_arm_notes(s))+ if family == "ts":+ untyped = [p.name for p in s.params if not p.type]+ if untyped:+ out.append(+ f"Write the types of {', '.join(untyped)}: the code declares none for them."+ )if family == "rust":unknown = [p.name for p in _rust_unsure(s)]if unknown:@@ -184,7 +235,8 @@ def _args(shape: HelperShape) -> str:return ", ".join(p.name for p in shape.params)-def _out(shape: HelperShape) -> Slot | None:+def _single_out(shape: HelperShape) -> Slot | None:+ """The one output every renderer but Python's binds (see the ceilings)."""return shape.returns[0] if shape.returns else None@@ -199,8 +251,10 @@ def _py_sig(s: HelperShape) -> str:params = [f"{p.name}: {p.type}" if p.type else p.name for p in s.params]if _method(s) and s.receiver:params.insert(0, s.receiver)- out = _out(s)- ret = f" -> {out.type}" if out and out.type else ""+ types = [r.type for r in s.returns]+ ret = " -> None" if not types and s.typed_host else ""+ if types and all(types):+ ret = f" -> {types[0]}" if len(types) == 1 else f" -> tuple[{', '.join(map(str, types))}]"head = f"{'async ' if s.is_async else ''}def {_name(s)}({', '.join(params)}){ret}:"return ("@classmethod\n" + head) if _method(s) and s.receiver == "cls" else head@@ -208,8 +262,7 @@ def _py_sig(s: HelperShape) -> str:def _py_call(s: HelperShape) -> str:target = f"{s.receiver}." if _method(s) and s.receiver else ""expr = f"{'await ' if s.is_async else ''}{target}{_name(s)}({_args(s)})"- out = _out(s)- return f"{out.name} = {expr}" if out else expr+ return f"{', '.join(r.name for r in s.returns)} = {expr}" if s.returns else expr# -- TypeScript / JavaScript -------------------------------------------------@@ -217,7 +270,7 @@ def _py_call(s: HelperShape) -> str:def _ts_sig(s: HelperShape, typed: bool) -> str:params = ", ".join(f"{p.name}: {p.type}" if p.type else p.name for p in s.params)- out = _out(s)+ out = _single_out(s)ret = ""if out and out.type:ret = f": Promise<{out.type}>" if s.is_async else f": {out.type}"@@ -230,7 +283,7 @@ def _ts_sig(s: HelperShape, typed: bool) -> str:def _ts_call(s: HelperShape) -> str:target = "this." if _method(s) else ""expr = f"{'await ' if s.is_async else ''}{target}{_name(s)}({_args(s)})"- out = _out(s)+ out = _single_out(s)if out is None:return expr + ";"keyword = ("let " if s.out_rebound else "const ") if s.out_declared else ""@@ -242,7 +295,7 @@ def _ts_call(s: HelperShape) -> str:def _go_sig(s: HelperShape) -> str:params = ", ".join(f"{p.name} {_type(p, 'go')}" for p in s.params)- out = _out(s)+ out = _single_out(s)ret = f" {_type(out, 'go')}" if out else ""recv = f"{s.receiver_decl} " if _method(s) and s.receiver_decl else ""return f"func {recv}{_name(s)}({params}){ret} {{"@@ -251,7 +304,7 @@ def _go_sig(s: HelperShape) -> str:def _go_call(s: HelperShape) -> str:target = f"{s.receiver}." if _method(s) and s.receiver else ""expr = f"{target}{_name(s)}({_args(s)})"- out = _out(s)+ out = _single_out(s)if out is None:return expr# ``x, err :=`` in the span may only redeclare ``x``; alone it must assign.@@ -267,7 +320,7 @@ def _type_first(s: HelperShape, family: str) -> str:def _java_sig(s: HelperShape) -> str:- out = _out(s)+ out = _single_out(s)ret = _type(out, "java") if out else "void"static = "" if _method(s) else "static "return f"private {static}{ret} {_name(s)}({_type_first(s, 'java')}) {{"@@ -280,7 +333,7 @@ def _java_call(s: HelperShape) -> str:def _declared_call(s: HelperShape, expr: str, inferred: str) -> str:"""``T x = expr;`` for an output the span declared (*inferred* when itstype is unknown), ``x = expr;`` for one declared before it."""- out = _out(s)+ out = _single_out(s)if out is None:return expr + ";"if s.out_declared:@@ -289,7 +342,7 @@ def _declared_call(s: HelperShape, expr: str, inferred: str) -> str:def _cpp_sig(s: HelperShape) -> str:- out = _out(s)+ out = _single_out(s)if s.is_async:ret = TYPE_PLACEHOLDER # the coroutine's own type (a note says so)elif out:@@ -347,7 +400,7 @@ def _rust_sig(s: HelperShape) -> str:]if _method(s):params.insert(0, _rust_self(s))- out = _out(s)+ out = _single_out(s)ret = f" -> {_type(out, 'rust')}" if out else ""return f"{'async ' if s.is_async else ''}fn {_name(s)}({', '.join(params)}){ret} {{"@@ -356,7 +409,7 @@ def _rust_call(s: HelperShape) -> str:target = "self." if _method(s) else ""args = ", ".join(f"&{p.name}" if _rust_borrowed(s, p) else p.name for p in s.params)expr = f"{target}{_name(s)}({args}){'.await' if s.is_async else ''}"- out = _out(s)+ out = _single_out(s)if out is None:return expr + ";"if s.out_declared:@@ -375,8 +428,53 @@ _RENDERERS = {}+# -- a staged plan's parameter object ------------------------------------------+++class ContextText(NamedTuple):+ """The parameter object's declaration (None where the language needs+ none), the statement building it before the first stage, and notes."""++ declaration: str | None+ construct: str+ notes: tuple[str, ...]+++def context_name(language: str | None, host: str) -> str:+ """``_PersistContext`` for host ``persist`` in Python, ``PersistContext``+ in TS / JS: a type name, private where the language spells it."""+ words = [*split_words(host.rsplit(".", 1)[-1]), "context"]+ return private_name(language, "".join(w.capitalize() for w in words)) or "Context"+++def render_context(+ language: str, name: str, var: str, fields: tuple[Slot, ...]+) -> ContextText | None:+ """The object carrying *fields* to every stage, or None for a language+ without a staged renderer."""+ family = _FAMILY.get(language)+ if family == "python":+ lines = [f" {f.name}: {f.type or 'Any'}" for f in fields]+ notes = ["Import dataclass from dataclasses."]+ if any(f.type is None for f in fields):+ notes.append("Import Any from typing, or write the fields' real types.")+ construct = f"{var} = {name}({', '.join(f'{f.name}={f.name}' for f in fields)})"+ head = ["@dataclass(frozen=True)", f"class {name}:"]+ return ContextText("\n".join([*head, *lines]), construct, tuple(notes))+ if family not in ("ts", "js"):+ return None+ names = ", ".join(f.name for f in fields)+ if family == "js":+ return ContextText(None, f"const {var} = {{ {names} }};", ())+ lines = [f" {f.name}: {f.type or TYPE_PLACEHOLDER};" for f in fields]+ declaration = "\n".join([f"interface {name} {{", *lines, "}"])+ return ContextText(declaration, f"const {var}: {name} = {{ {names} }};", ())++#: What the renderer adds to a stored plan, served on plan detail only.-_DETAIL_SYMBOL_KEYS = ("params", "returns", "signature_text", "notes")+_DETAIL_SYMBOL_KEYS = ("params", "returns", "signature_text", "return_text", "notes")+#: A staged plan's stages, parameter object and residual sit on detail too.+_DETAIL_PLAN_KEYS = ("call_site", "stages", "parameter_object", "orchestrator")def list_plan(plan: dict) -> dict:@@ -384,11 +482,11 @@ def list_plan(plan: dict) -> dict:list serves every plan, and an agent reads the texts on one plan'sdetail."""symbol = plan.get("new_symbol")- if "call_site" not in plan and not (+ if not any(k in plan for k in _DETAIL_PLAN_KEYS) and not (isinstance(symbol, dict) and any(k in symbol for k in _DETAIL_SYMBOL_KEYS)):return plan- out = {k: v for k, v in plan.items() if k != "call_site"}+ out = {k: v for k, v in plan.items() if k not in _DETAIL_PLAN_KEYS}if isinstance(symbol, dict):out["new_symbol"] = {k: v for k, v in symbol.items() if k not in _DETAIL_SYMBOL_KEYS}return out@@ -408,13 +506,17 @@ __all__ = ["NAME_PLACEHOLDER","PARAM_MODES","TYPE_PLACEHOLDER",+ "ContextText","HelperShape","ParamMode","Rendered","Slot","brief",+ "context_name","list_plan","private_name","render",+ "render_context",+ "staged_outputs","symbol_params",]diff --git a/packages/types/src/refactoring.ts b/packages/types/src/refactoring.tsindex 449f1ebab..accfde774 100644--- a/packages/types/src/refactoring.ts+++ b/packages/types/src/refactoring.ts@@ -201,6 +201,9 @@ export interface RecipeStep {params: string[];returns: string[];signature_text: string | null;+ /** The helper's last line handing its outputs back (`return a, b`);+ * null without outputs or on a plan stored before it. */+ return_text?: string | null;notes: string[];};call_site?: ExtractCallSite;diff --git a/packages/ui/__tests__/refactoring/staged-extract-detail.test.tsx b/packages/ui/__tests__/refactoring/staged-extract-detail.test.tsxnew file mode 100644index 000000000..822ddb415--- /dev/null+++ b/packages/ui/__tests__/refactoring/staged-extract-detail.test.tsx@@ -0,0 +1,134 @@+import { render, screen } from "@testing-library/react";+import { describe, expect, it } from "vitest";+import type { RefactoringPlan } from "@repowise-dev/types/refactoring";++import { PlanDetail } from "../../src/refactoring/plan-detail";+import { extractMethodStages } from "../../src/refactoring/types";++function stage(start: number, end: number, name: string | null, out: string[]) {+ return {+ span: { start, end },+ params: ["ctx"],+ returns: out,+ suggested_name: name,+ ccn: 6,+ nloc: 20,+ context_params: ["session"],+ new_symbol: {+ kind: "function",+ async: true,+ signature_text: `async def ${name ?? "<name>"}(ctx: _PersistContext):`,+ return_text: out.length ? `return ${out.join(", ")}` : null,+ notes: ["Read session in the helper as ctx.session."],+ },+ call_site: {+ replace_span: { start, end },+ new_text: `${out.length ? `${out.join(", ")} = ` : ""}await ${name ?? "<name>"}(ctx)`,+ },+ };+}++const first = stage(10, 30, "_persist_pages", ["pages"]);+const second = stage(34, 60, null, []);++const plan = {+ id: "plan-staged",+ refactoring_type: "extract_method",+ file_path: "pkg/persist.py",+ target_symbol: "persist",+ line_start: 5,+ line_end: 90,+ plan: {+ ...first,+ stages: [first, second],+ parameter_object: {+ name: "_PersistContext",+ var: "ctx",+ fields: [{ name: "session", type: null }],+ declaration_text: "@dataclass(frozen=True)\nclass _PersistContext:\n session: Any",+ construct_text: "ctx = _PersistContext(session=session)",+ construct_before: 10,+ notes: [],+ },+ orchestrator: { ccn_before: 40, ccn_after: 12 },+ },+ evidence: { slice_nloc: 40, ccn_removed: 28 },+ impact_delta: 0.7,+ effort_bucket: "L",+ blast_radius: { scope: "local" },+ confidence: "medium",+ source_biomarker: "brain_method",+ rank_score: 5,+} satisfies RefactoringPlan;++describe("PlanDetail for a staged Extract Method plan", () => {+ it("lists every stage in order, not only the first", () => {+ render(<PlanDetail plan={plan} />);+ expect(screen.getByText(/into 2 helpers it calls in order/)).toBeTruthy();+ expect(screen.getByText(/from 40 to about 12/)).toBeTruthy();+ const items = screen.getAllByRole("listitem");+ expect(items).toHaveLength(2);+ expect(items[0]!.textContent).toContain("_persist_pages");+ expect(items[0]!.textContent).toContain("lines 10–30");+ expect(items[1]!.textContent).toContain("Stage 2");+ expect(items[1]!.textContent).toContain("lines 34–60");+ });++ it("shows the shared object once and each stage's texts", () => {+ render(<PlanDetail plan={plan} />);+ expect(screen.getAllByText(/class _PersistContext/)).toHaveLength(1);+ expect(screen.getByText("ctx = _PersistContext(session=session)")).toBeTruthy();+ expect(screen.getByText("return pages")).toBeTruthy();+ expect(screen.getByText("pages = await _persist_pages(ctx)")).toBeTruthy();+ expect(screen.getByText("await <name>(ctx)")).toBeTruthy();+ });++ it("opens the first stage and folds the rest", () => {+ const { container } = render(<PlanDetail plan={plan} />);+ const folds = container.querySelectorAll("details");+ expect(folds).toHaveLength(2);+ expect(folds[0]!.open).toBe(true);+ expect(folds[1]!.open).toBe(false);+ });+});++describe("extractMethodStages bounds", () => {+ const withBounds = (start: unknown, end: unknown) =>+ ({+ ...plan,+ plan: { ...plan.plan, stages: [{ ...first, span: { start, end } }, second] },+ }) as unknown as RefactoringPlan;++ it.each([+ ["a numeric string", "10", 30],+ ["a boolean", true, 30],+ ["a float", 10.5, 30],+ ["zero", 0, 30],+ ["an end that is a string", 10, "30"],+ ])("drops a stage whose bound is %s", (_label, start, end) => {+ const stages = extractMethodStages(withBounds(start, end));+ expect(stages.map((s) => s.span)).toEqual([{ start: 34, end: 60 }]);+ });++ it("keeps whole positive line numbers", () => {+ expect(extractMethodStages(withBounds(10, 30)).map((s) => s.span.start)).toEqual([10, 34]);+ });+});++describe("PlanDetail with fewer than two valid stages", () => {+ it("renders the single-span view for one stage", () => {+ const single = { ...plan, plan: { ...plan.plan, stages: [first] } } satisfies RefactoringPlan;+ render(<PlanDetail plan={single} />);+ expect(screen.queryByText(/helpers it calls in order/)).toBeNull();+ expect(screen.getByText("Extract span")).toBeTruthy();+ });++ it("renders the single-span view when invalid bounds leave one stage", () => {+ const broken = {+ ...plan,+ plan: { ...plan.plan, stages: [{ ...first, span: { start: "10", end: 30 } }, second] },+ } as unknown as RefactoringPlan;+ render(<PlanDetail plan={broken} />);+ expect(screen.queryByText(/helpers it calls in order/)).toBeNull();+ });+});diff --git a/packages/ui/src/health/ai-prompts/refactoring-plan-steps.ts b/packages/ui/src/health/ai-prompts/refactoring-plan-steps.tsindex 9475314f8..bede557ad 100644--- a/packages/ui/src/health/ai-prompts/refactoring-plan-steps.ts+++ b/packages/ui/src/health/ai-prompts/refactoring-plan-steps.ts@@ -70,6 +70,7 @@ function extractMethodSteps(plan: RefactoringPlan): string {const name = em.suggested_name ?? HELPER_NAME_PLACEHOLDER;const rendered = [...(em.signature_text ? [`- **New helper:** \`${em.signature_text}\``] : []),+ ...(em.return_text ? [`- **End the helper with:** \`${em.return_text}\``] : []),...(em.call_site? [`- **Replace lines ${em.span.start}–${em.span.end} with:** \`${em.call_site.new_text}\``]: []),diff --git a/packages/ui/src/refactoring/plan-detail.tsx b/packages/ui/src/refactoring/plan-detail.tsxindex 7188a1f9d..a5035d5c9 100644--- a/packages/ui/src/refactoring/plan-detail.tsx+++ b/packages/ui/src/refactoring/plan-detail.tsx@@ -14,6 +14,9 @@ import {extractHelperOccurrences,extractMethodPlan,extractMethodSignature,+ extractMethodStages,+ extractOrchestrator,+ extractParameterObject,helperSite,moveTarget,performancePlanDetail,@@ -23,6 +26,7 @@ import {splitResidual,splitShimRequired,} from "./types";+import type { ExtractStage } from "./types";import type { RefactoringPlan } from "@repowise-dev/types/refactoring";export interface PlanDetailProps {@@ -107,6 +111,113 @@ export function CodeBlock({ code, startLine }: { code: string; startLine: number);}+/** A staged Extract Method plan: the shared object once, then each helper the+ * function will call, in order. Each stage folds to one line; the first is+ * open. Every text has the code block's own copy button. */+function StagedExtract({+ plan,+ fileHref,+ hideIntro,+ stages,+}: {+ plan: RefactoringPlan;+ fileHref: PlanDetailProps["fileHref"];+ hideIntro: boolean;+ stages: ExtractStage[];+}) {+ const language = getLanguageFromPath(plan.file_path);+ const shared = extractParameterObject(plan);+ const ccn = extractOrchestrator(plan);+ return (+ <div className="space-y-3">+ {hideIntro ? null : (+ <p className="text-xs text-[var(--color-text-tertiary)]">+ Split <span className="font-mono">{plan.target_symbol}</span> into {stages.length} helpers+ it calls in order+ {ccn ? `, taking its complexity from ${ccn.before} to about ${ccn.after}` : ""}.+ </p>+ )}+ {shared ? (+ <div className="rounded-xl border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] p-3.5">+ {shared.declaration_text ? (+ <HighlightedCodeBlock+ code={shared.declaration_text}+ language={language}+ label={`Shared values: ${shared.name}`}+ compact+ className="my-0"+ />+ ) : null}+ <HighlightedCodeBlock+ code={shared.construct_text}+ language={language}+ label={shared.construct_before ? `Build it above line ${shared.construct_before}` : "Build it"}+ compact+ className="mb-0 mt-2"+ />+ </div>+ ) : null}+ <ol className="space-y-2">+ {stages.map((stage, i) => (+ <li+ key={stage.span.start}+ className="rounded-xl border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] p-3.5"+ >+ <details open={i === 0} className="group">+ <summary className="flex cursor-pointer items-center gap-2 text-xs">+ <Scissors className="h-4 w-4 shrink-0" style={{ color: ACCENT }} aria-hidden />+ <span className="font-mono text-[var(--color-text-primary)]">+ {stage.name ?? `Stage ${i + 1}`}+ </span>+ <FileRef path={plan.file_path} line={stage.span.start} fileHref={fileHref} />+ <span className="ml-auto shrink-0 font-mono text-[var(--color-text-secondary)]">+ lines {stage.span.start}–{stage.span.end}+ {stage.ccn ? ` · CCN ${stage.ccn}` : ""}+ </span>+ </summary>+ <div className="mt-2">+ {stage.signature_text ? (+ <HighlightedCodeBlock+ code={stage.signature_text}+ language={language}+ label="New helper"+ compact+ className="my-0"+ />+ ) : null}+ {stage.return_text ? (+ <HighlightedCodeBlock+ code={stage.return_text}+ language={language}+ label="Ends with"+ compact+ className="mb-0 mt-2"+ />+ ) : null}+ {stage.call_text ? (+ <HighlightedCodeBlock+ code={stage.call_text}+ language={language}+ label={`Replaces lines ${stage.span.start}–${stage.span.end}`}+ compact+ className="mb-0 mt-2"+ />+ ) : null}+ <PlaceholderHint texts={[stage.signature_text ?? "", stage.call_text ?? ""]} />+ {stage.notes.map((note) => (+ <p key={note} className="mt-2 text-2xs text-[var(--color-text-tertiary)]">+ {note}+ </p>+ ))}+ </div>+ </details>+ </li>+ ))}+ </ol>+ </div>+ );+}+/*** The concrete, type-specific body of a refactoring plan: split groups as a* tree, the move as an arrow, clone occurrences as a list, the cycle as cut@@ -430,6 +541,11 @@ export function PlanDetail({ plan, fileHref, hideIntro = false }: PlanDetailProp}if (plan.refactoring_type === "extract_method") {+ const stages = extractMethodStages(plan);+ // Two or more valid stages, as Fix first counts them; else the single span.+ if (stages.length >= 2) {+ return <StagedExtract plan={plan} fileHref={fileHref} hideIntro={hideIntro} stages={stages} />;+ }const em = extractMethodPlan(plan);const lines = em.span ? em.span.end - em.span.start + 1 : 0;const ccn = Number(plan.evidence?.ccn_removed ?? 0);diff --git a/packages/ui/src/refactoring/types.ts b/packages/ui/src/refactoring/types.tsindex e3c993e03..2a9f485aa 100644--- a/packages/ui/src/refactoring/types.ts+++ b/packages/ui/src/refactoring/types.ts@@ -181,6 +181,9 @@ export interface ExtractMethodPlan {* the span. Null when the helper's form is unknown or the plan predates it.* `<name>` / `<type>` are placeholders to fill. */signature_text: string | null;+ /** The helper's last line handing its outputs back; null without outputs+ * or on a plan stored before it. */+ return_text: string | null;call_site: ExtractCallSite | null;/** What the texts cannot say (a value that may move, a call the host* cannot await). */@@ -211,6 +214,7 @@ export function extractMethodPlan(plan: RefactoringPlan): ExtractMethodPlan {typed_params: Array.isArray(sym.params) ? (sym.params as ExtractSlot[]) : [],typed_returns: Array.isArray(sym.returns) ? (sym.returns as ExtractSlot[]) : [],signature_text: typeof sym.signature_text === "string" ? sym.signature_text : null,+ return_text: typeof sym.return_text === "string" ? sym.return_text : null,call_site: callSite(p.call_site),notes: Array.isArray(sym.notes) ? (sym.notes as string[]) : [],};@@ -233,6 +237,82 @@ export function slotLabel(slot: ExtractSlot): string {return slot.type ? `${slot.name}: ${slot.type}` : slot.name;}+/** One helper of a staged Extract Method plan, in the order the function+ * calls them. `name` is null when nothing in the code anchors one. */+export interface ExtractStage {+ name: string | null;+ span: { start: number; end: number };+ ccn: number | null;+ signature_text: string | null;+ call_text: string | null;+ return_text: string | null;+ notes: string[];+}++/** The object carrying the values the stages share, declared once. */+export interface ExtractParameterObject {+ name: string;+ declaration_text: string | null;+ construct_text: string;+ construct_before: number | null;+}++/** A positive whole line number: not a numeric string, a boolean or a float. */+function isLine(v: unknown): v is number {+ return typeof v === "number" && Number.isInteger(v) && v > 0;+}++/** A staged plan's helpers (`plan.stages`) with valid line bounds; empty for+ * a single-span plan. */+export function extractMethodStages(plan: RefactoringPlan): ExtractStage[] {+ const raw = ((plan.plan ?? {}) as Record<string, unknown>).stages;+ if (!Array.isArray(raw)) return [];+ return raw.flatMap((entry): ExtractStage[] => {+ const s = (entry ?? {}) as Record<string, unknown>;+ const span = (s.span ?? {}) as Record<string, unknown>;+ const start = span.start;+ const end = span.end;+ if (!isLine(start) || !isLine(end)) return [];+ const sym = (s.new_symbol ?? {}) as Record<string, unknown>;+ const site = callSite(s.call_site);+ return [+ {+ name: typeof s.suggested_name === "string" ? s.suggested_name : null,+ span: { start, end },+ ccn: typeof s.ccn === "number" ? s.ccn : null,+ signature_text: typeof sym.signature_text === "string" ? sym.signature_text : null,+ call_text: site ? site.new_text : null,+ return_text: typeof sym.return_text === "string" ? sym.return_text : null,+ notes: Array.isArray(sym.notes) ? (sym.notes as string[]) : [],+ },+ ];+ });+}++/** A staged plan's shared parameter object, or null without one. */+export function extractParameterObject(plan: RefactoringPlan): ExtractParameterObject | null {+ const raw = ((plan.plan ?? {}) as Record<string, unknown>).parameter_object as+ | Record<string, unknown>+ | null+ | undefined;+ if (!raw || typeof raw !== "object" || typeof raw.construct_text !== "string") return null;+ return {+ name: typeof raw.name === "string" ? raw.name : HELPER_NAME_PLACEHOLDER,+ declaration_text: typeof raw.declaration_text === "string" ? raw.declaration_text : null,+ construct_text: raw.construct_text,+ construct_before: typeof raw.construct_before === "number" ? raw.construct_before : null,+ };+}++/** The function's cyclomatic complexity before and after a staged split. */+export function extractOrchestrator(plan: RefactoringPlan): { before: number; after: number } | null {+ const raw = ((plan.plan ?? {}) as Record<string, unknown>).orchestrator as+ | Record<string, unknown>+ | undefined;+ if (!raw || typeof raw.ccn_before !== "number" || typeof raw.ccn_after !== "number") return null;+ return { before: raw.ccn_before, after: raw.ccn_after };+}+/** The helper an extraction proposes, as one line: `async name(a, b) -> c`.* For a plan stored before the server rendered `signature_text`. */export function extractMethodSignature(em: ExtractMethodPlan): string {diff --git a/tests/unit/health/test_extract_method_receiver.py b/tests/unit/health/test_extract_method_receiver.pyindex e986597e0..9e37fc209 100644--- a/tests/unit/health/test_extract_method_receiver.py+++ b/tests/unit/health/test_extract_method_receiver.py@@ -123,7 +123,7 @@ def test_python_plan_carries_new_symbol():sym = {k: vfor k, v in plan.plan["new_symbol"].items()- if k not in ("params", "returns", "signature_text")+ if k not in ("params", "returns", "signature_text", "return_text")}if plan.plan["span"]["start"] >= 12:assert sym == {diff --git a/tests/unit/health/test_extract_method_render.py b/tests/unit/health/test_extract_method_render.pyindex 2ffb577d0..b48735fdf 100644--- a/tests/unit/health/test_extract_method_render.py+++ b/tests/unit/health/test_extract_method_render.py@@ -217,7 +217,7 @@ def test_rust_borrows_a_value_the_host_reads_after_the_call():),returns=(),)- sig, call, notes = render(shape)+ sig, call, notes, _returns = render(shape)assert sig == "fn loadTotals(rows: &Vec<Row>, n: usize, cfg: <type>, tmp: String) {"assert call == "loadTotals(&rows, n, cfg, tmp);"assert notes == (@@ -337,6 +337,28 @@ def test_param_modes_match_the_wire_type():assert set(re.findall(r'"([a-z_]+)"', match.group(1))) == set(PARAM_MODES)+def test_recipe_step_symbol_keys_match_the_wire_type():+ """``RecipeStep.new_symbol`` in the TS types names every key the recipe+ writes for an Extract Method step, ``return_text`` included."""+ from repowise.core.analysis.health.refactoring.recipe import recipe_steps++ src = (pathlib.Path(__file__).resolve().parents[3] / "packages/types/src/refactoring.ts").read_text(+ encoding="utf-8"+ )+ block = re.search(r"export interface RecipeStep \{.*?new_symbol\?: \{(.*?)\};", src, re.DOTALL)+ assert block+ ts_keys = set(re.findall(r"^\s*([a-z_]+)\??:", block.group(1), re.MULTILINE))+ (step,) = recipe_steps(+ {+ "refactoring_type": "extract_method",+ "file_path": "m.py",+ "target_symbol": "f",+ "plan": {"span": {"start": 2, "end": 5}, "params": [], "returns": ["x"]},+ }+ )+ assert ts_keys == set(step["new_symbol"])++def test_list_rows_leave_the_texts_to_plan_detail():"""A list serves every plan, so its rows stay as they were before thetexts existed; one plan's detail carries them."""diff --git a/tests/unit/health/test_extract_method_stages.py b/tests/unit/health/test_extract_method_stages.pynew file mode 100644index 000000000..884ae256e--- /dev/null+++ b/tests/unit/health/test_extract_method_stages.py@@ -0,0 +1,624 @@+"""Staged Extract Method: a brain method split into helpers called in order.++One helper cannot take a CCN 30+ function under the bar, so the plan cuts its+effective body (under a dominant ``try`` / ``with`` wrapper) into stages, each+a helper with CCN <= 10 and NLOC <= 60, and credits the summed drop. The+fixture mirrors ``update_cmd/persistence.py::_persist_full_update_async``: an+``async with`` session inside a ``try``, sections each wrapped in+``try / except: _skip(...); if strict: raise``, a list that sections extend.+"""++from __future__ import annotations++import textwrap+from dataclasses import dataclass++import pytest++from repowise.core.analysis.health.complexity.languages import get_language_map+from repowise.core.analysis.health.dataflow import Extraction, analyze_file+from repowise.core.analysis.health.dataflow.stages import (+ STAGE_MAX_CCN,+ STAGE_MAX_NLOC,+ _composes,+ find_stages,+)+from repowise.core.analysis.health.refactoring.extract_method import ExtractMethodDetector+from repowise.core.analysis.health.refactoring.models import RefactoringContext+from repowise.core.analysis.health.refactoring.recipe import build_recipe+from repowise.core.analysis.health.refactoring.render import list_plan+++@dataclass+class _Finding:+ biomarker_type: str+ function_name: str+ line_start: int+ health_impact: float+++def _functions(src: str, language: str = "python", ext: str = "py"):+ from repowise.core.ingestion.parser import _get_language++ if _get_language(language) is None:+ pytest.skip(f"tree-sitter language pack missing for {language}")+ res = analyze_file(f"m.{ext}", language, textwrap.dedent(src).encode(), flagged_only=False)+ if res.stats.functions_seen == 0:+ pytest.skip(f"tree-sitter language pack missing for {language}")+ return res.functions+++def _plans(src: str, language: str = "python", ext: str = "py"):+ fns = _functions(src, language, ext)+ ctx = RefactoringContext(+ file_path=f"m.{ext}",+ language=language,+ nloc=300,+ findings=[_Finding("complex_method", f.name, f.start_line, 2.0) for f in fns],+ function_analyses=fns,+ )+ return {p.target_symbol: p for p in ExtractMethodDetector().detect(ctx)}+++def _section(n: int, *, extend: bool = False) -> str:+ """One persist step: a banner, a timed block and the degrade handler."""+ write = (+ f"pages += await step_{n}(session, repo_id, a, b, c, d, e)"+ if extend+ else f"await step_{n}(session, repo_id, a, b, c, d, e)"+ )+ return f"""+ # Persist part {n}+ try:+ with timed(timings, "persist.part_{n}"):+ if flag_{n}:+ {write}+ elif other_{n}:+ await other_step_{n}(session, repo_id)+ except Exception as exc:+ _skip("part {n}", exc)+ if strict:+ raise+"""+++def _persist(sections: int = 8, *, extend: tuple[int, ...] = (2, 5)) -> str:+ flags = ", ".join(f"flag_{n}, other_{n}" for n in range(sections))+ body = "".join(_section(n, extend=n in extend) for n in range(sections))+ return f"""+async def persist(repo_path, a, b, c, d, e, timings, strict, {flags}):+ from store import other_step_1, step_1++ degraded = []++ def _skip(step, exc):+ degraded.append(f"{{step}}: {{exc}}")++ pages: list[str] = []+ engine = create_engine(repo_path)+ try:+ async with get_session(engine) as session:+ repo_id = await upsert_repository(session, repo_path)+{textwrap.indent(textwrap.dedent(body), " " * 12)}+ return pages, degraded+ finally:+ await engine.dispose()+"""+++def test_persistence_shape_yields_a_staged_plan():+ plan = _plans(_persist())["persist"]+ stages = plan.plan["stages"]+ assert len(stages) >= 2+ # The top-level keys are stage 1, so a single-span reader reads step one.+ assert plan.plan["span"] == stages[0]["span"]+ assert plan.plan["call_site"] == stages[0]["call_site"]+ for stage in stages:+ assert stage["ccn"] <= STAGE_MAX_CCN and stage["nloc"] <= STAGE_MAX_NLOC+ assert stage["needs_async"] and stage["new_symbol"]["async"]+ assert stage["new_symbol"]["signature_text"].startswith("async def ")+ assert "await " in stage["call_site"]["new_text"]+ removed = sum(s["ccn"] - 1 for s in stages)+ assert plan.evidence["ccn_removed"] == removed+ residual = plan.plan["orchestrator"]+ assert residual["ccn_after"] == residual["ccn_before"] - removed+ # Credited the summed drop, not one span's share.+ assert plan.impact_delta == pytest.approx(2.0 * removed / residual["ccn_before"], abs=1e-3)+ # Stages carry the raise their sections hold (it propagates unchanged).+ lines = textwrap.dedent(_persist()).splitlines()+ assert any(+ "raise" in lines[ln - 1]+ for s in stages+ for ln in range(s["span"]["start"], s["span"]["end"] + 1)+ )+++def test_stage_names_come_from_timed_labels_and_banners():+ stages = _plans(_persist(sections=8, extend=()))["persist"].plan["stages"]+ # A stage covering one section takes its label; one spanning two has none.+ for stage in stages:+ name = stage["suggested_name"]+ assert name is None or name.startswith("_persist_part")+++def test_shared_values_travel_on_a_parameter_object():+ plan = _plans(_persist()).get("persist").plan+ obj = plan["parameter_object"]+ assert obj is not None+ names = {f["name"] for f in obj["fields"]}+ assert {"session", "repo_id", "timings", "strict", "_skip", "a"} <= names+ assert obj["declaration_text"].startswith("@dataclass(frozen=True)\nclass _PersistContext:")+ assert obj["construct_text"].startswith("ctx = _PersistContext(")+ first = plan["stages"][0]+ assert first["params"][0] == "ctx"+ assert first["new_symbol"]["params"][0] == {+ "name": "ctx",+ "type": "_PersistContext",+ "mode": "in",+ }+ assert set(first["context_params"]) <= names+ assert any("ctx.session" in n for n in first["new_symbol"]["notes"])+++def test_few_shared_values_stay_plain_parameters():+ src = _persist().replace(+ "session, repo_id, a, b, c, d, e)", "session, repo_id)"+ ).replace('_skip("part', 'log("part').replace("if strict:\n", "if flag_0:\n")+ plan = _plans(src)["persist"].plan+ assert plan["stages"]+ assert plan["parameter_object"] is None+ assert all(s["context_params"] == [] for s in plan["stages"])+++def test_a_list_extended_in_a_branch_is_passed_in_and_handed_back():+ stages = _plans(_persist())["persist"].plan["stages"]+ carrying = [s for s in stages if "pages" in s["returns"]]+ assert carrying+ for stage in carrying:+ # Written on one path only, so the stage takes the list and returns it.+ modes = {p["name"]: p["mode"] for p in stage["new_symbol"]["params"]}+ assert modes["pages"] == "inout"+ assert stage["call_site"]["new_text"].startswith(+ ", ".join(stage["returns"]) + " = await "+ )+++def test_a_return_inside_a_section_never_lands_in_a_stage():+ src = _persist().replace(+ " if strict:\n raise\n",+ " if strict:\n return pages, degraded\n",+ 1,+ )+ fn = _functions(src)[0]+ plan = find_stages(fn, get_language_map("python"))+ returns = [+ i + 1+ for i, line in enumerate(textwrap.dedent(src).splitlines())+ if line.strip().startswith("return pages") and i + 1 < fn.end_line - 3+ ]+ assert returns+ for stage in plan.stages:+ assert not any(stage.start_line <= ln <= stage.end_line for ln in returns)+++def test_composition_refuses_a_value_no_stage_hands_on():+ src = """+ def run(rows, limit):+ total = 0+ for r in rows:+ if r > limit:+ total += r+ seen = total * 2+ for r in rows:+ if r < seen:+ print(r)+ return seen+ """+ fn = _functions(src)[0]+ first = Extraction(3, 6, ("limit", "rows"), ("total",), 4, 2)+ second = Extraction(7, 10, ("rows", "total"), ("seen",), 4, 2)+ assert _composes(fn, (first, second), ()) == (((), ()), frozenset())+ # The first stage keeps ``total`` to itself: the second would read nothing.+ keeps = Extraction(3, 6, ("limit", "rows"), (), 4, 2)+ assert _composes(fn, (keeps, second), ()) is None+ # The second stage was not given ``total``.+ assert _composes(fn, (first, Extraction(7, 10, ("rows",), ("seen",), 4, 2)), ()) is None+ # Nor hands ``seen`` back to the ``return`` after it.+ assert _composes(fn, (first, Extraction(7, 10, ("rows", "total"), (), 4, 2)), ()) is None+++def test_a_sync_host_gets_sync_stages():+ src = _persist().replace("async def persist", "def persist").replace("await ", "")+ src = src.replace("async with", "with")+ stages = _plans(src)["persist"].plan["stages"]+ assert stages+ for stage in stages:+ assert not stage["needs_async"]+ assert stage["new_symbol"]["signature_text"].startswith("def ")+ assert "await" not in stage["call_site"]["new_text"]+++def test_a_function_one_helper_can_fix_is_never_staged():+ src = _persist(sections=4, extend=())+ assert _functions(src)[0].ccn <= 2 * STAGE_MAX_CCN+ plan = _plans(src).get("persist")+ assert plan is None or "stages" not in plan.plan+++def test_stages_are_detail_only_and_recipe_steps():+ suggestion = _plans(_persist())["persist"]+ plan = suggestion.plan+ listed = list_plan(plan)+ assert not {"stages", "parameter_object", "orchestrator", "call_site"} & listed.keys()+ recipe = build_recipe(+ {+ "id": "x",+ "refactoring_type": "extract_method",+ "file_path": "m.py",+ "target_symbol": "persist",+ "plan": plan,+ }+ )+ steps = recipe["steps"]+ assert steps[0]["action"] == "add_helper"+ extracts = [s for s in steps if s["action"] == "extract"]+ assert len(extracts) == len(plan["stages"])+ assert extracts[0]["span"] == plan["stages"][0]["span"]+ assert extracts[0]["text"].startswith(f"Stage 1 of {len(plan['stages'])}: ")+ assert recipe["summary"].startswith(f"Split `persist` into {len(plan['stages'])} helpers")+++def test_python_helper_hands_back_a_tuple():+ from repowise.core.analysis.health.refactoring import render++ shape = render.HelperShape(+ language="python",+ name="_split",+ kind="function",+ is_async=True,+ params=(render.Slot("rows"),),+ returns=(render.Slot("kept", "list[str]"), render.Slot("dropped", "list[str]")),+ )+ texts = render.render(shape)+ assert texts.signature == "async def _split(rows) -> tuple[list[str], list[str]]:"+ assert texts.call == "kept, dropped = await _split(rows)"+++def test_typescript_parameter_object():+ from repowise.core.analysis.health.refactoring import render++ fields = (render.Slot("session", "Session"), render.Slot("repoId"))+ text = render.render_context("typescript", "PersistContext", "ctx", fields)+ assert text.declaration == "interface PersistContext {\n session: Session;\n repoId: <type>;\n}"+ assert text.construct == "const ctx: PersistContext = { session, repoId };"+ assert render.context_name("typescript", "persistAll") == "PersistAllContext"+ assert render.context_name("python", "persist_all") == "_PersistAllContext"+++def test_a_stage_is_told_to_import_what_the_function_imports_locally():+ stages = _plans(_persist())["persist"].plan["stages"]+ told = [+ n+ for s in stages+ for n in s["new_symbol"].get("notes", [])+ if n.startswith("Import ") and "step_1" in n+ ]+ assert told == ["Import other_step_1, step_1 in the helper: the function imports them inside its body."]+++def _loop_section(n: int) -> str:+ """A section whose loop breaks and continues: both stay in the loop."""+ return f"""+ # Scan part {n}+ for row in rows_{n}:+ if not row:+ continue+ if row == "stop":+ break+ seen_{n}.append(row)+"""+++def test_break_and_continue_inside_a_stage_are_allowed():+ sections = "".join(_loop_section(n) for n in range(8))+ seen = ", ".join(f"seen_{n}" for n in range(8))+ rows = ", ".join(f"rows_{n}" for n in range(8))+ src = f"""+def scan({rows}, {seen}):+ total = 0+{textwrap.indent(textwrap.dedent(sections), " " * 4)}+ return total+"""+ stages = _plans(src)["scan"].plan["stages"]+ lines = textwrap.dedent(src).splitlines()+ held = [+ lines[ln - 1].strip()+ for s in stages+ for ln in range(s["span"]["start"], s["span"]["end"] + 1)+ ]+ assert "break" in held and "continue" in held+++def test_the_receiver_never_rides_the_parameter_object():+ method = textwrap.indent(_persist().replace("async def persist(", "async def persist(self, "), " ")+ method = method.replace("session, repo_id, a, b", "self.store, session, repo_id, a, b")+ src = "class Store:\n" + method+ plan = _plans(src)["persist"].plan+ obj = plan["parameter_object"]+ assert obj is not None and "self" not in {f["name"] for f in obj["fields"]}+ for stage in plan["stages"]:+ assert "self" not in stage["context_params"]+ assert stage["new_symbol"]["kind"] == "method"+ assert stage["new_symbol"]["signature_text"].startswith("async def ")+ assert "(self, ctx" in stage["new_symbol"]["signature_text"]+ assert stage["call_site"]["new_text"].count("self.") == 1+++def test_a_module_global_named_ctx_is_not_shadowed():+ src = _persist().replace(" degraded = []\n", " degraded = [ctx]\n", 1)+ obj = _plans(src)["persist"].plan["parameter_object"]+ assert obj["var"] == "context"+ assert obj["construct_text"].startswith("context = _PersistContext(")+++def test_an_async_stage_hands_back_a_tuple():+ src = _persist(extend=(2, 3)).replace(+ "pages += await step_3(", "more += await step_3("+ ).replace(" pages: list[str] = []\n", " pages: list[str] = []\n more: list[str] = []\n")+ src = src.replace("return pages, degraded", "return pages, more, degraded")+ stages = _plans(src)["persist"].plan["stages"]+ pair = [s for s in stages if len(s["returns"]) == 2]+ assert pair+ stage = pair[0]+ assert stage["new_symbol"]["signature_text"].endswith(+ "-> tuple[list[str], list[str]]:"+ )+ assert stage["call_site"]["new_text"].startswith(+ f"{', '.join(stage['returns'])} = await "+ )+++def test_a_timer_is_never_split_by_a_stage_edge():+ src = _persist().replace(+ " # Persist part 4\n",+ ' if timings is not None:\n timings.start("persist.four")\n'+ " # Persist part 4\n",+ ).replace(+ ' _skip("part 4", exc)\n if strict:\n raise\n',+ ' _skip("part 4", exc)\n if strict:\n raise\n'+ ' finally:\n if timings is not None:\n'+ ' timings.stop("persist.four")\n',+ )+ assert 'timings.stop("persist.four")' in src+ lines = textwrap.dedent(src).splitlines()+ start = next(i for i, ln in enumerate(lines, 1) if 'start("persist.four")' in ln)+ stop = next(i for i, ln in enumerate(lines, 1) if 'stop("persist.four")' in ln)+ for s in _plans(src)["persist"].plan["stages"]:+ inside = [s["span"]["start"] <= ln <= s["span"]["end"] for ln in (start, stop)]+ assert inside[0] == inside[1]+++def test_a_typed_host_gets_typed_void_helpers():+ src = _persist().replace("strict, flag_0", "strict: bool, flag_0", 1)+ src = src.replace("other_7):", "other_7) -> tuple:", 1)+ stages = _plans(src)["persist"].plan["stages"]+ void = [s for s in stages if not s["returns"]]+ assert void+ assert all(s["new_symbol"]["signature_text"].endswith(") -> None:") for s in void)+ untyped = _plans(_persist())["persist"].plan["stages"]+ assert not any("-> None" in s["new_symbol"]["signature_text"] for s in untyped)+++def test_a_staged_id_names_the_whole_split():+ from repowise.core.analysis.health.refactoring.identity import refactoring_public_id++ plan = _plans(_persist())["persist"]+ single = dict(plan.plan)+ single.pop("stages")+ fewer = dict(plan.plan, stages=plan.plan["stages"][:-1])+ ids = {+ refactoring_public_id(plan),+ refactoring_public_id(type(plan)(**{**plan.__dict__, "plan": single})),+ refactoring_public_id(type(plan)(**{**plan.__dict__, "plan": fewer})),+ }+ assert len(ids) == 3+++def test_an_else_arm_opening_on_a_comment_is_in_the_flow_graph():+ # hermes ``run_doctor``: the stage read ``should_fix`` and bumped+ # ``fixed_count`` inside such an arm, and the plan passed neither.+ src = """+ def f(p, fix):+ n = 0+ if p:+ g()+ else:+ # fall back+ if fix:+ n += 1+ return n+ """+ fn = _functions(src)[0]+ lines = {st.start_line for b in fn.cfg.blocks for st in b.statements}+ assert {8, 9} <= lines+ reads = {u.name for b in fn.def_use.blocks.values() for u in b.uses}+ assert {"fix", "n"} <= reads+++def test_an_input_bound_on_one_path_only_is_never_passed():+ # ours ``tool_symbol.py::get_symbol``: ``members`` was bound only under+ # ``if outline is not None:`` and the stage took it, raising on the other path.+ sections = "".join(_section(n) for n in range(8))+ src = f"""+async def persist(repo_path, a, b, c, d, e, timings, strict, outline, {", ".join(f"flag_{n}, other_{n}" for n in range(8))}):+ def _skip(step, exc):+ pass++ session = open_session(repo_path)+ repo_id = 1+ if outline is not None:+ members = outline.members+{textwrap.indent(textwrap.dedent(sections), " " * 4)}+ if outline is not None:+ report(members)+"""+ src = src.replace("await step_3(session, repo_id, a, b, c, d, e)", "await step_3(session, repo_id, members if outline is not None else None)")+ fn = _functions(src)[0]+ plan = find_stages(fn, get_language_map("python"))+ assert plan.stages+ assert all("members" not in x.params for x in plan.stages)+++_TS_GUARD = """+async function run(opts, a, b, c, d, e) {+ const token = opts.token ?? a.token;+ if (!token) {+ throw new Error("token missing");+ }+ // part one+ try {+ if (a) { await one(token, a); } else if (b) { await two(token, b); }+ } catch (err) {+ if (c) { log(err); }+ }+ // part two+ try {+ if (d) { await three(token, d); } else if (e) { await four(token, e); }+ } catch (err) {+ if (c) { log(err); }+ }+ // part three+ for (const item of a.items) {+ if (item.ok) { await five(token, item); } else if (item.skip) { continue; }+ }+ // part four+ try {+ if (a && b) { await six(token); } else if (d || e) { await seven(token); }+ } catch (err) {+ if (c) { log(err); }+ }+ return send(token);+}+"""+++def test_a_narrowing_guard_stays_in_the_function():+ fn = _functions(_TS_GUARD, "typescript", "ts")[0]+ plan = find_stages(fn, get_language_map("typescript"), max_returns=1)+ assert plan.stages+ guard = next(i for i, ln in enumerate(textwrap.dedent(_TS_GUARD).splitlines(), 1) if "if (!token)" in ln)+ assert all(not x.start_line <= guard <= x.end_line for x in plan.stages)+++def test_a_loop_variable_a_stage_declares_is_never_handed_back():+ # openclaw ``template.js``: ``entry = helper(entries, entry, labelMap)``+ # for a ``for (const entry of ...)`` binder that ends with its loop.+ src = """+ function render(entries, extra) {+ const byId = new Map();+ for (const entry of entries) {+ if (entry.a && entry.id) {+ byId.set(entry.id, entry);+ } else if (entry.b || extra) {+ skip(entry);+ } else if (entry.c && entry.d) {+ keep(entry);+ }+ }+ const labels = new Map();+ for (const entry of entries) {+ if (entry.type === "label" && entry.target && entry.label) {+ labels.set(entry.target, entry.label);+ } else if (entry.type === "a") {+ labels.set(entry.id, "a");+ } else if (entry.type === "b") {+ labels.set(entry.id, "b");+ } else if (entry.type === "c") {+ labels.set(entry.id, "c");+ } else if (entry.type === "d") {+ labels.set(entry.id, "d");+ }+ }+ function tree() {+ for (const entry of entries) { if (entry.id && labels.has(entry.id)) { draw(entry); } }+ }+ return tree();+ }+ """+ fn = _functions(src, "javascript", "js")[0]+ plan = find_stages(fn, get_language_map("javascript"), max_returns=1)+ assert len(plan.stages) >= 2+ for x in plan.stages:+ assert "entry" not in x.returns and "entry" not in x.params+++def test_typescript_texts_hand_back_and_type_what_they_can():+ from repowise.core.analysis.health.refactoring import render++ # The author's declared type is kept; the note says the narrower one is safe.+ widened = render.render(+ render.HelperShape(+ language="typescript",+ name="settle",+ kind="function",+ is_async=False,+ returns=(render.Slot("outcome", "Outcome | undefined"),),+ )+ )+ assert widened.signature.endswith(": Outcome | undefined {")+ assert widened.notes == (+ "outcome is declared `Outcome | undefined`, but every path through these lines "+ "writes it, so the helper may return `Outcome`.",+ )+ inout = render.render(+ render.HelperShape(+ language="typescript",+ name="settle",+ kind="function",+ is_async=False,+ params=(render.Slot("outcome", "Outcome | undefined"),),+ returns=(render.Slot("outcome", "Outcome | undefined"),),+ )+ )+ assert inout.notes == ()+ shape = render.HelperShape(+ language="typescript",+ name="settle",+ kind="function",+ is_async=True,+ params=(render.Slot("reply"), render.Slot("limit", "number")),+ returns=(render.Slot("outcome", "Outcome"),),+ )+ texts = render.render(shape)+ assert texts.returns == "return outcome;"+ assert texts.notes == ("Write the types of reply: the code declares none for them.",)+ py = render.render(render.HelperShape("python", "_f", "function", False, returns=(render.Slot("a"), render.Slot("b"))))+ assert py.returns == "return a, b"+++def test_every_output_stage_says_how_it_hands_back():+ for stage in _plans(_persist())["persist"].plan["stages"]:+ text = stage["new_symbol"]["return_text"]+ assert text == (f"return {', '.join(stage['returns'])}" if stage["returns"] else None)+++def test_an_import_only_a_stage_reads_leaves_the_function():+ stages = _plans(_persist())["persist"].plan["stages"]+ notes = [n for s in stages for n in s["new_symbol"].get("notes", []) if n.startswith("Remove ")]+ assert notes and all("step_1" in n or "other_step_1" in n for n in notes)+++def test_code_no_path_reaches_has_no_bound_inputs():+ from repowise.core.analysis.health.dataflow.assigned import DefiniteAssignment++ fn = _functions(+ """+ def f(x):+ y = x + 1+ return y+ z = y+ """+ )[0]+ assigned = DefiniteAssignment(fn)+ assert {"x", "y"} <= assigned.before(4, 4)+ assert assigned.before(5, 5) is Nonediff --git a/tests/unit/health/test_refactoring_extract_method.py b/tests/unit/health/test_refactoring_extract_method.pyindex e166c94a8..c4cadf501 100644--- a/tests/unit/health/test_refactoring_extract_method.py+++ b/tests/unit/health/test_refactoring_extract_method.py@@ -640,6 +640,7 @@ def test_detector_emits_suggestion_for_flagged_function():"params": s.plan["new_symbol"]["params"],"returns": s.plan["new_symbol"]["returns"],"signature_text": s.plan["new_symbol"]["signature_text"],+ "return_text": "return average",}assert s.plan["call_site"]["replace_span"] == s.plan["span"]assert set(s.plan["span"]) == {"start", "end"}@@ -989,7 +990,7 @@ def test_a_best_span_below_the_floor_yields_to_the_next_one(monkeypatch):trivial = Extraction(10, 17, ("a",), (), slice_nloc=8, ccn_removed=1)worth = Extraction(20, 27, ("b",), (), slice_nloc=8, ccn_removed=3)- monkeypatch.setattr(extract_method, "find_extractions", lambda _a, _l, _r=None: [trivial, worth])+ monkeypatch.setattr(extract_method, "find_extractions", lambda _a, _l, _r=None, _p=None: [trivial, worth])fn = _Shape(12, 40)analysis = type("A", (), {"name": "f", "start_line": 1, "end_line": 50, "ccn": 12, "nloc": 40,@@ -1202,7 +1203,7 @@ def test_a_refused_span_yields_only_to_a_disjoint_one(monkeypatch):shrunk = Extraction(2, 55, ("a",), (), slice_nloc=40, ccn_removed=8) # overlaps itdisjoint = Extraction(85, 95, ("b",), (), slice_nloc=10, ccn_removed=3)monkeypatch.setattr(- extract_method, "find_extractions", lambda _a, _l, _r=None: [whole, shrunk, disjoint]+ extract_method, "find_extractions", lambda _a, _l, _r=None, _p=None: [whole, shrunk, disjoint])analysis = type("A", (), {"name": "f", "start_line": 1, "end_line": 100, "ccn": 30, "nloc": 90,