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
fix(refactoring): Extract Method plans that would not compile are completed or refused (#4378)
Raghav Chamadiya4c06fddd954a
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 57842e4d4..07088ca11 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -489,6 +489,10 @@ runs it over growing data).- An Extract Method step finds its lines by their start and end text (line numbers movewith the first edit); if that text repeats in the file, it says to stay inside thefunction.+- An Extract Method step carries the plan's `notes`. A stage that takes the shared parameter+ object shows the object's declaration above its helper and the line building it above+ its call. A plan missing either is not offered as a Fix first step, since its call would+ name a variable that does not exist.### 6.4 Performance opportunities (`perf/`)diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.mdindex da0e2ff22..0312e0b17 100644--- a/docs/layers/REFACTORING.md+++ b/docs/layers/REFACTORING.md@@ -258,6 +258,16 @@ Most plans answer a health finding, so per-path marker rules incode declares them; `<type>` marks a type for you to fill in. It flags anawaiting span with `needs_async: true` and a receiver-bound helper under`new_symbol`.+- A TypeScript span is not offered when a test above or around it narrows a+ value no helper parameter can carry: a property the span reads+ (`if (!tc.result) continue;` before `tc.result.id`), a property compared with+ a literal, or a module-level name (`assert(cursor !== undefined)`). Nor is a+ span holding an `assert` the code after it relies on, or one that assigns a+ name declared outside it without taking or returning it.+ One such stage refuses the whole staged split; the finding records+ `narrowing_lost` or `outer_declaration` in `details.extract_method_stage_refused`.+ A guard or `if` narrowing a parameter gets a note to type it as narrowed, and+ an output declared before the span a note to declare it in the helper.- A step Repowise cannot express mechanically is a judgment call with a reasoncode: `async_helper_unexpressible`, `receiver_unbound` or`receiver_copy_written`.diff --git a/packages/core/src/repowise/core/agent_prompts/fix_first.py b/packages/core/src/repowise/core/agent_prompts/fix_first.pyindex ab35b10ff..995be6cbd 100644--- a/packages/core/src/repowise/core/agent_prompts/fix_first.py+++ b/packages/core/src/repowise/core/agent_prompts/fix_first.py@@ -61,11 +61,22 @@ def _step(s: Mapping[str, Any]) -> str:loc = f"{s['file_path']}{f':{line}' if line else ''}"tag = " [mechanical]" if s.get("mechanical") else " [judgment]"extra = [- f" {label}: `{s[key]}`"+ _code_line(label, s[key])for key, label in (("signature", "Helper"), ("call", "Call"), ("command", "Check"))if s.get(key)]- return "\n".join([f"{s['order']}. {s['text']} (`{loc}`){tag}", *extra])+ notes = [f" Note: {' '.join(n.split())}" for n in s.get("notes") or ()]+ return "\n".join([f"{s['order']}. {s['text']} (`{loc}`){tag}", *extra, *notes])+++def _code_line(label: str, code: str) -> str:+ """One labelled piece of a step's code: inline, or fenced when it spans+ lines (a parameter object's declaration above its helper)."""+ if "\n" not in code:+ return f" {label}: `{code}`"+ body = "\n".join(f" {line}" if line else "" for line in code.splitlines())+ fence = "````" if "```" in code else "```"+ return f" {label}:\n {fence}\n{body}\n {fence}"def render_fix_item(item: Mapping[str, Any], flavor: str = "generic", repo_name: str | None = None) -> str:diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/_parts.py b/packages/core/src/repowise/core/analysis/health/fix_first/_parts.pyindex 71394e86b..26885f4d9 100644--- a/packages/core/src/repowise/core/analysis/health/fix_first/_parts.py+++ b/packages/core/src/repowise/core/analysis/health/fix_first/_parts.py@@ -8,6 +8,7 @@ from collections.abc import Callable, Iterable, Mappingfrom dataclasses import dataclassfrom typing import Any+from repowise.core.analysis.health.refactoring.recipe import _strsfrom repowise.core.analysis.health.rows import fieldfrom repowise.core.analysis.health.worth import WORTH_MAGNITUDE@@ -154,11 +155,48 @@ def _step_command(check: Mapping[str, Any] | None, item_command: str | None) ->return commands[0] if commands and commands[0] != item_command else None-def _helper_code(body: Mapping[str, Any]) -> dict[str, str | None]:- """An Extract Method plan's rendered helper header and call, when it wrote them."""- symbol = body.get("new_symbol") or {}- site = body.get("call_site") or {}- return {- "signature": symbol.get("signature_text") if isinstance(symbol, dict) else None,- "call": site.get("new_text") if isinstance(site, dict) else None,- }+def shared_object(body: Mapping[str, Any]) -> Mapping[str, Any] | None:+ """The parameter object a staged plan's first stage takes, None when its+ helper takes plain values only."""+ obj = body.get("parameter_object")+ params = body.get("params")+ if not isinstance(obj, dict) or not isinstance(params, list):+ return None+ var = obj.get("var")+ return obj if isinstance(var, str) and var in params else None+++def object_code(obj: Mapping[str, Any]) -> tuple[str, str] | None:+ """The object's declaration and the line building it, None when the plan+ lacks either."""+ declaration, construct = _text(obj.get("declaration_text")), _text(obj.get("construct_text"))+ return (declaration, construct) if declaration and construct else None+++def _helper_code(body: Mapping[str, Any]) -> dict[str, Any]:+ """An Extract Method plan's rendered helper header and call, when it wrote+ them, and the plan's notes on what that code cannot say (a type a guard+ narrows, an import to repeat). A helper taking the shared parameter object+ comes after the object's declaration, and its call after the line+ building it: the call names that variable."""+ symbol = body.get("new_symbol")+ symbol = symbol if isinstance(symbol, dict) else {}+ site = body.get("call_site")+ signature = _text(symbol.get("signature_text"))+ call = _text(site.get("new_text")) if isinstance(site, dict) else None+ notes = _strs(symbol.get("notes"))+ obj = shared_object(body)+ code = object_code(obj) if obj is not None else None+ if obj is not None and code is not None:+ signature = "\n\n".join(t for t in (code[0], signature) if t)+ call = "\n".join(t for t in (code[1], call) if t)+ first = (+ f"Add the {obj.get('name')} declaration above the helper, and the line building "+ f"{obj.get('var')} just before the call, as shown."+ )+ notes = [first, *_strs(obj.get("notes")), *notes]+ return {"signature": signature, "call": call, "notes": tuple(dict.fromkeys(notes))}+++def _text(value: Any) -> str | None:+ return value if isinstance(value, str) and value else Nonediff --git a/packages/core/src/repowise/core/analysis/health/fix_first/model.py b/packages/core/src/repowise/core/analysis/health/fix_first/model.pyindex e9e06bf40..15d3a935b 100644--- a/packages/core/src/repowise/core/analysis/health/fix_first/model.py+++ b/packages/core/src/repowise/core/analysis/health/fix_first/model.py@@ -122,6 +122,9 @@ class FixStep:call: str | None = None#: The command that checks this step, when it differs from the item's.command: str | None = None+ #: What the helper's code cannot say, in the plan's words: a type a guard+ #: narrows, a parameter object to declare, the values read off it.+ notes: tuple[str, ...] = ()@dataclass(frozen=True, slots=True)diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.py b/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.pyindex fd40510d0..0d2858f34 100644--- a/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.py+++ b/packages/core/src/repowise/core/analysis/health/fix_first/plan_steps.py@@ -12,7 +12,7 @@ from repowise.core.analysis.health.worth import LowPriorityfrom repowise.core.ci.markdown import code as md_codefrom . import text-from ._parts import _helper_code, _open+from ._parts import _helper_code, _open, object_code, shared_objectfrom .model import FixStep@@ -134,6 +134,14 @@ def _extract_text(sym: str, body: Mapping[str, Any], start: Any, end: Any) -> streturn line_text+def _extract_ready(body: Mapping[str, Any]) -> bool:+ """Whether the step can be written as it reads: a helper taking the shared+ parameter object needs the object's declaration and the line building it,+ or its call names a variable and a type that do not exist."""+ obj = shared_object(body)+ return obj is None or object_code(obj) is not None++#: A refactoring step's sentence, by plan type, from (symbol, path, plan, plan body)._STEP_TEXT: dict[str, Callable[[str, str, Any, Mapping[str, Any]], str]] = {"extract_method": lambda sym, path, plan, body: _extract_text(sym, body, *_span(plan)),@@ -218,7 +226,7 @@ def _concrete(step: Mapping[str, Any], plan: Any) -> bool:body = _plan_body(plan)if kind == "extract_method":start, end = _span(plan)- return bool(start and end)+ return bool(start and end) and _extract_ready(body)if kind == "extract_helper":return any(isinstance(o, dict) and o.get("line_start") for o in body.get("occurrences") or ()@@ -250,7 +258,7 @@ def _extractions(plans: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:if field(plan, "refactoring_type") != "extract_method" or not symbol or not _open(plan):continuestart, end = _span(plan)- if start and end:+ if start and end and _extract_ready(_plan_body(plan)):out[(field(plan, "file_path"), text.short_symbol(symbol).rsplit(".", 1)[-1])].append(plan)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 e79ccc0a1..4ec86ca51 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@@ -124,7 +124,7 @@ from .anchors import Scope, anchor_plan, file_source, function_scopefrom .declarative import declarative_flatfrom .helper_naming import ScopeNames, placeholder_namesfrom .models import RefactoringContext, RefactoringSuggestion-from .narrowing import narrowed, narrowings+from .narrowing import narrowed, narrowings, property_narrowings, span_guardsfrom .registry import RefactoringDetector, registerif TYPE_CHECKING:@@ -235,6 +235,7 @@ class ExtractMethodDetector(RefactoringDetector):prefixes: dict[int, Any] = {}refused: set[str] = set()candidates = find_extractions(analysis, lmap, receiver, prefixes, refused)+ candidates = _writable_spans(analysis, candidates, ctx.language, refused)_mark_stage_refused(matched, frozenset(refused))best = _choose(analysis, candidates, markers)staged = _staged(analysis, best, lmap, receiver, ctx.language, matched, prefixes)@@ -468,7 +469,12 @@ def _staged(if max_returns is None or analysis.ccn < _STAGE_MIN_CCN:return Noneplan = find_stages(analysis, lmap, receiver, max_returns=max_returns, prefixes=prefixes)- _mark_stage_refused(findings, plan.refused)+ refused = set(plan.refused)+ # One stage no helper can be written for refuses the split: the others compose with it.+ kept = _writable_spans(analysis, plan.stages, language, refused)+ if len(kept) < len(plan.stages):+ plan = replace(plan, stages=())+ _mark_stage_refused(findings, frozenset(refused))if not plan.stages or (best is not None and plan.ccn_removed < 2 * best.ccn_removed):return Noneif not all(_worth_extracting(analysis, x, markers) for x in plan.stages):@@ -700,11 +706,7 @@ def _render_fields(out_rebound=rebound,typed_host=fn_node is not Noneand fn_node.child_by_field_name("return_type") is not None,- throws_clause=(- next((child.text.decode() for child in fn_node.named_children if child.type == "throws"), None)- if language == "java" and fn_node is not None- else None- ),+ throws_clause=_throws_clause(fn_node, language),))rendered = {@@ -714,8 +716,9 @@ def _render_fields("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)+ notes = [*(texts.notes if texts else ()), *_undeclared_outputs_note(analysis, extraction)]+ if notes:+ rendered["notes"] = notesspan = {"start": extraction.start_line, "end": extraction.end_line}call = texts.call if texts else Nonereturn {@@ -725,6 +728,35 @@ def _render_fields(}+def _throws_clause(fn_node: Any, language: str | None) -> str | None:+ """A Java method's ``throws`` clause, for the helper to repeat."""+ if language != "java" or fn_node is None:+ return None+ return next((c.text.decode() for c in fn_node.named_children if c.type == "throws"), None)+++def _undeclared_outputs_note(analysis: FunctionAnalysis, extraction: Extraction) -> list[str]:+ """A note for the outputs the function declares before the span (``let+ x: T;``) and the span only assigns: the helper needs its own declaration+ or its first assignment names nothing."""+ if not extraction.returns:+ return []+ inside = range(extraction.start_line, extraction.end_line + 1)+ declared = [(d.var, d.line in inside) for d in analysis.def_use.definitions if d.declared_at is not None]+ names = [+ r+ for r in extraction.returns+ if r not in extraction.params and (r, False) in declared and (r, True) not in declared+ ]+ if not names:+ return []+ what = "it" if len(names) == 1 else "them"+ return [+ f"Declare {', '.join(names)} at the top of the helper, as the function does: "+ f"the lines assign {what} without declaring {what}."+ ]++def _declared_types(analysis: FunctionAnalysis, extraction: Extraction, dialect: BaseDefUseDialect | None) -> dict[str, str]:@@ -755,6 +787,87 @@ def _declared_types(return found+#: Why a span was refused: a test the span runs under narrows a value it reads+#: in a way no helper parameter keeps (a property path, a name the function+#: does not bind), so the lifted lines stop type-checking.+NARROWING_LOST = "narrowing_lost"+#: Why a span was refused: it assigns a name declared outside it that it+#: neither takes nor returns, so the helper's assignment names nothing.+OUTER_DECLARATION = "outer_declaration"+++def _writable_spans(+ analysis: FunctionAnalysis,+ spans: list[Extraction] | tuple[Extraction, ...],+ language: str | None,+ refused: set[str],+) -> list[Extraction]:+ """*spans* without those whose helper cannot be written as planned; each+ drop adds its reason to *refused*. Without a tree no span was cut from one."""+ if analysis.fn_node is None:+ return list(spans)+ def_lines = _def_lines(analysis)+ kept = []+ for x in spans:+ reason = _unwritable(analysis, x, language, def_lines)+ if reason is None:+ kept.append(x)+ else:+ refused.add(reason)+ return kept+++def _unwritable(+ analysis: FunctionAnalysis,+ x: Extraction,+ language: str | None,+ def_lines: dict[str, list[int]],+) -> str | None:+ """Why *x*'s helper cannot be written as planned, None when it can."""+ if _assigns_outer_declaration(analysis, x):+ return OUTER_DECLARATION+ if language in _NARROWING_LANGUAGES and _loses_narrowing(analysis, x, language, def_lines):+ return NARROWING_LOST+ return None+++def _assigns_outer_declaration(analysis: FunctionAnalysis, x: Extraction) -> bool:+ """Whether *x* assigns a name declared outside it that it neither takes nor+ returns. A name the span declares itself is its own binding (a second+ ``for (int i``)."""+ inside = range(x.start_line, x.end_line + 1)+ defs = analysis.def_use.definitions+ declared = [(d.var, d.line in inside) for d in defs if d.declared_at is not None]+ outside = {v for v, held in declared if not held} - {v for v, held in declared if held}+ outside -= set(x.params) | set(x.returns)+ return any(d.line in inside and d.declared_at is None and d.var in outside for d in defs)+++def _loses_narrowing(+ analysis: FunctionAnalysis, x: Extraction, language: str, def_lines: dict[str, list[int]]+) -> bool:+ """Whether a TypeScript narrowing the lines rely on stays behind in the+ function, or one the code after them relies on leaves with them+ (``narrowing``)."""+ inside = range(x.start_line, x.end_line + 1)+ args = (analysis.fn_node, get_language_map(language), x.start_line, x.end_line)+ uses = [u for bdu in analysis.def_use.blocks.values() for u in bdu.uses if not u.echo]+ # Names the function never binds (a module's): the helper reads them unnarrowed.+ free = {u.name for u in uses if u.line in inside} - set(def_lines)+ if property_narrowings(*args, set(x.params) | free, def_lines):+ return True+ if free and narrowings(*args, free, def_lines):+ return True+ return bool(span_guards(*args) & {u.name for u in uses if u.line > x.end_line})+++def _def_lines(analysis: FunctionAnalysis) -> dict[str, list[int]]:+ out: dict[str, list[int]] = {}+ for d in analysis.def_use.definitions:+ out.setdefault(d.var, []).append(d.line)+ return out++def _narrow(analysis: FunctionAnalysis, extraction: Extraction, language: str | None, types: dict[str, str]) -> dict[str, int]:@@ -764,9 +877,7 @@ def _narrow(guard's line, for the plan's note."""if language not in _NARROWING_LANGUAGES or not extraction.params:return {}- def_lines: dict[str, list[int]] = {}- for d in analysis.def_use.definitions:- def_lines.setdefault(d.var, []).append(d.line)+ def_lines = _def_lines(analysis)found = narrowings(analysis.fn_node,get_language_map(language),diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/narrowing.py b/packages/core/src/repowise/core/analysis/health/refactoring/narrowing.pyindex a56de1e50..f56e65395 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/narrowing.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/narrowing.py@@ -14,10 +14,18 @@ alone or joined by ``||``. ``typeof``, ``instanceof`` and ``Array.isArray``narrow to a type the declaration does not name, so those are reported with noarms: the plan says the parameter needs the narrowed type instead of writingone.++A test of a property (``if (!tc.result) continue;``, or an ``if`` / ``while``+/ ``switch`` holding the span) narrows the path ``tc.result``, not ``tc``: no+parameter type a caller's ``tc`` satisfies keeps it. :func:`property_narrowings`+names the span's inputs whose narrowed path the span reads, and any input a+literal comparison may discriminate (``tc.kind === "done"``), for the planner+to refuse. An ordering or arithmetic test (``xs.length > 0``) narrows nothing."""from __future__ import annotations+import refrom dataclasses import dataclassfrom typing import TYPE_CHECKING@@ -32,6 +40,10 @@ if TYPE_CHECKING:_FALSY = frozenset({"undefined", "null", "false"})_NULLISH = frozenset({"undefined", "null"})_EQUALITY = {"==": _NULLISH, "===": None}+_MEMBER_KINDS = frozenset({"member_expression", "subscript_expression"})+_EQUALITY_OPS = frozenset({"==", "===", "!=", "!=="})+# A unit type a union may be discriminated by; ``null`` / ``undefined`` narrow the path.+_LITERALS = frozenset({"string", "number", "true", "false", "template_string"})_EXITS = frozenset({"return_statement", "throw_statement", "continue_statement", "break_statement"})@@ -53,15 +65,138 @@ def narrowings(def_lines: dict[str, list[int]],) -> dict[str, Narrowing]:"""Per name in *names*, the nearest guard narrowing it over lines- *start*..*end* (module docstring)."""- stmts = span_statements(fn_node, start, end, lmap)+ *start*..*end* (module docstring). An ``assert(x)`` above them or an+ ``if`` / ``while`` / ``switch`` holding them narrows too, to a type the+ declaration does not name."""out: dict[str, Narrowing] = {}+ for sib in _statements_above(fn_node, lmap, start, end):+ _add_guard(sib, lmap, end, names, def_lines, out)+ for st, condition in _tests(fn_node, lmap, start, end, exiting=False):+ for name in _tested_names(condition):+ if name in names and name not in out and not _rebound(st, name, end, def_lines):+ out[name] = Narrowing(st.start_point[0] + 1, None)+ return out+++def property_narrowings(+ fn_node: Node | None,+ lmap: LanguageNodeMap,+ start: int,+ end: int,+ names: set[str],+ def_lines: dict[str, list[int]],+) -> dict[str, int]:+ """Per name in *names*, the line of the nearest test narrowing one of its+ properties for lines *start*..*end* (module docstring): an exiting guard+ above them, or a statement holding them. Nothing may rebind the name+ between the test and *end*."""+ read = "\n".join(_text(st) for st in span_statements(fn_node, start, end, lmap))+ out: dict[str, int] = {}+ for st, condition in _tests(fn_node, lmap, start, end, exiting=True):+ for name, path in _property_tests(condition):+ if name not in names or name in out or (path and not _reads_path(read, path)):+ continue+ if not _rebound(st, name, end, def_lines):+ out[name] = st.start_point[0] + 1+ return out+++def span_guards(fn_node: Node | None, lmap: LanguageNodeMap, start: int, end: int) -> set[str]:+ """The names an ``assert(...)`` or a throwing guard among lines+ *start*..*end* tests, plain or by a property: lifted into a helper, the+ narrowing it gives the code after the lines is gone."""+ out: set[str] = set()+ for st in span_statements(fn_node, start, end, lmap):+ condition = _asserted(st) or exiting_guard(st, lmap, lmap.raise_kinds)+ if condition is not None:+ out |= _tested_names(condition) | {root for root, _ in _property_tests(condition)}+ return out+++def _tests(+ fn_node: Node | None, lmap: LanguageNodeMap, start: int, end: int, *, exiting: bool+) -> list[tuple[Node, Node]]:+ """``(statement, condition)`` per test the span runs under, nearest first:+ an ``assert(...)`` above it, a statement holding it, and with *exiting* an+ exiting guard above it."""+ out = []+ for sib in _statements_above(fn_node, lmap, start, end):+ condition = _asserted(sib) or (exiting_guard(sib, lmap, _EXITS) if exiting else None)+ if condition is not None:+ out.append((sib, condition))+ stmts = span_statements(fn_node, start, end, lmap)+ out += [(h, c) for h in _holders(fn_node, stmts) if (c := _condition(h)) is not None]+ return sorted(out, key=lambda t: -t[0].start_point[0])+++def _asserted(st: Node) -> Node | None:+ """The condition of an ``assert(cond)`` / ``console.assert(cond)`` statement."""+ call = st.named_children[0] if st.type == "expression_statement" and st.named_children else None+ if call is None or call.type != "call_expression":+ return None+ if not _text(call.child_by_field_name("function")).split(".")[-1].startswith("assert"):+ return None+ args = call.child_by_field_name("arguments")+ return args.named_children[0] if args is not None and args.named_children else None+++def _rebound(st: Node, name: str, end: int, def_lines: dict[str, list[int]]) -> bool:+ return any(st.end_point[0] + 1 < ln <= end for ln in def_lines.get(name, ()))+++def _tested_names(expr: Node) -> set[str]:+ """The plain names *expr* tests (``x`` in ``x !== undefined``, ``isRec(x)``):+ not a property's object, a callee, an ordering or arithmetic operand."""+ out: set[str] = set()+ stack = [expr]+ while stack:+ node = stack.pop()+ stack.extend(node.named_children)+ parent = node.parent+ if node.type != "identifier" or (parent is not None and parent.type in _MEMBER_KINDS):+ continue+ if _operand_role(node) != "none":+ out.add(_text(node))+ return out+++def _holders(fn_node: Node | None, stmts: list[Node]) -> list[Node]:+ """The statements between *fn_node* and the span that hold it."""+ out = []+ node = stmts[0].parent if stmts else None+ while node is not None and node is not fn_node:+ if _condition(node) is not None:+ out.append(node)+ node = node.parent+ return out+++def _condition(node: Node) -> Node | None:+ """An ``if`` / ``while`` / ``do`` test or a ``switch`` subject; None for anything else."""+ if node.type in ("if_statement", "while_statement", "do_statement"):+ return node.child_by_field_name("condition")+ return node.child_by_field_name("value") if node.type == "switch_statement" else None+++def _reads_path(text: str, path: str) -> bool:+ """Whether *text* reads *path* (``tc.result``, ``tc?.result``) itself, not a+ longer name it prefixes."""+ plain = re.escape(path)+ return re.search(rf"(?<![\w$.]){plain}(?![\w$])", text.replace("?.", ".")) is not None+++def _statements_above(+ fn_node: Node | None, lmap: LanguageNodeMap, start: int, end: int+) -> list[Node]:+ """The statements before the span in each block holding it, nearest first."""+ stmts = span_statements(fn_node, start, end, lmap)+ out: list[Node] = []node = stmts[0] if stmts else Nonewhile node is not None and node.parent is not None and node is not fn_node:if node.parent.type in lmap.block_kinds:sib = node.prev_named_siblingwhile sib is not None:- _add_guard(sib, lmap, end, names, def_lines, out)+ out.append(sib)sib = sib.prev_named_siblingnode = node.parentreturn out@@ -171,6 +306,51 @@ def _typed_names(expr: Node) -> list[str]:return out+def _property_tests(expr: Node) -> list[tuple[str, str | None]]:+ """``(root, path)`` per property *expr* tests (``("tc", "tc.result")`` for+ ``!tc.result``); path None when a literal comparison may narrow the whole+ root (a discriminant). A callee, an ordering or an arithmetic operand is+ not a test of it."""+ out: list[tuple[str, str | None]] = []+ stack = [expr]+ while stack:+ node = stack.pop()+ if node.type not in _MEMBER_KINDS:+ stack.extend(node.named_children)+ continue+ root = node+ while root.type in _MEMBER_KINDS and root.child_by_field_name("object") is not None:+ root = _peel(root.child_by_field_name("object"))+ role = _operand_role(node)+ if root.type == "identifier" and role != "none":+ out.append((_text(root), None if role == "discriminant" else _text(node).replace("?.", ".")))+ return out+++def _operand_role(node: Node) -> str:+ """How a property path's test uses it: ``none`` (a callee, an ordering or+ arithmetic operand), ``discriminant`` (compared with a literal), else ``path``."""+ parent = node.parent+ while parent is not None and parent.type == "parenthesized_expression":+ node, parent = parent, parent.parent+ if parent is None:+ return "path"+ if parent.type == "switch_statement":+ return "discriminant"+ if parent.type == "call_expression" and parent.child_by_field_name("function") == node:+ return "none"+ return _binary_role(node, parent) if parent.type == "binary_expression" else "path"+++def _binary_role(node: Node, parent: Node) -> str:+ """:func:`_operand_role` for an operand of binary *parent*."""+ op = _operator(parent)+ if op in _EQUALITY_OPS:+ other = parent.child_by_field_name("right" if parent.child_by_field_name("left") == node else "left")+ return "discriminant" if other is not None and _peel(other).type in _LITERALS else "path"+ return "path" if op in ("&&", "||", "??", "instanceof", "in") else "none"++def _peel(node: Node) -> Node:while node.type == "parenthesized_expression" and node.named_children:node = node.named_children[0]@@ -186,4 +366,4 @@ def _text(node: Node | None) -> str:return (node.text or b"").decode("utf-8", "replace") if node is not None else ""-__all__ = ["Narrowing", "narrowed", "narrowings"]+__all__ = ["Narrowing", "narrowed", "narrowings", "property_narrowings", "span_guards"]diff --git a/packages/types/src/fix-first.ts b/packages/types/src/fix-first.tsindex 538315e56..2a9a29845 100644--- a/packages/types/src/fix-first.ts+++ b/packages/types/src/fix-first.ts@@ -80,6 +80,8 @@ export interface FixStep {call?: string | null;/** The command that checks this step, when it differs from the item's. */command?: string | null;+ /** What the helper's code cannot say: a type a guard narrows, a parameter object to declare. */+ notes?: string[];}/** A due item's first edit, inline in the compact projection. */diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 33c864209..850b87e79 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -2211,6 +2211,7 @@ export interface FixStep {signature?: string | null;call?: string | null;command?: string | null;+ notes?: string[];}export interface FixTarget {diff --git a/packages/ui/__tests__/health/fix-first.test.tsx b/packages/ui/__tests__/health/fix-first.test.tsxindex 8fd84b5ee..c79a28e8c 100644--- a/packages/ui/__tests__/health/fix-first.test.tsx+++ b/packages/ui/__tests__/health/fix-first.test.tsx@@ -156,6 +156,7 @@ describe("Fix first items", () => {signature: "def _<name>(repo_path):",call: "info = _<name>(repo_path)",command: "pytest tests/unit/cli/test_repo_scanner.py",+ notes: ["Type tc as the guard on line 50 narrows it: a wider type undoes that narrowing."],};const item: FixItem = {...REFACTOR,@@ -171,6 +172,7 @@ describe("Fix first items", () => {expect(screen.getByText("info = _<name>(repo_path)")).toBeTruthy();expect(screen.getByText(/with a name for what the lines do/)).toBeTruthy();expect(screen.getByText(step.command)).toBeTruthy();+ expect(screen.getByText(step.notes[0]!)).toBeTruthy();expect(screen.getByText(first)).toBeTruthy();});diff --git a/packages/ui/src/health/fix-first/fix-first-item.tsx b/packages/ui/src/health/fix-first/fix-first-item.tsxindex f27c45494..e43ebd40a 100644--- a/packages/ui/src/health/fix-first/fix-first-item.tsx+++ b/packages/ui/src/health/fix-first/fix-first-item.tsx@@ -250,8 +250,9 @@ function Steps({);}-/** What a step writes (a helper's header, the call that replaces the span)- * and the command that checks it when it differs from the item's. */+/** What a step writes (a helper's header, the call that replaces the span),+ * the plan's notes on what that code cannot say, and the command that checks+ * it when it differs from the item's. */function StepCode({ step }: { step: FixStep }) {const language = getLanguageFromPath(step.file_path);return (@@ -275,6 +276,15 @@ function StepCode({ step }: { step: FixStep }) {/>) : null}<PlaceholderHint texts={[step.signature ?? "", step.call ?? ""]} />+ {step.notes?.length ? (+ <ul className="mt-1.5 flex list-disc flex-col gap-0.5 pl-4 text-xs text-[var(--color-text-secondary)]">+ {step.notes.map((note, i) => (+ <li key={`${i}:${note}`} className="[overflow-wrap:anywhere]">+ {note}+ </li>+ ))}+ </ul>+ ) : null}{step.command ? <CommandLine command={step.command} /> : null}</>);diff --git a/tests/unit/agent_prompts/test_golden.py b/tests/unit/agent_prompts/test_golden.pyindex bebc7d779..965cacfc6 100644--- a/tests/unit/agent_prompts/test_golden.py+++ b/tests/unit/agent_prompts/test_golden.py@@ -117,3 +117,19 @@ def test_refactoring_plan_spec_matches_golden(case: dict) -> None:def test_refactoring_opportunity_matches_golden(case: dict, flavor: str) -> None:text = render_opportunity(case["detail"], flavor, case.get("repo_name"))assert text == _GOLDEN["refactoring_opportunity"][case["name"]][flavor]+++def test_a_step_fences_code_that_spans_lines_and_lists_its_notes() -> None:+ from repowise.core.agent_prompts.fix_first import _step++ step = {+ "order": 1, "text": "Extract it", "file_path": "a.py", "line": 9, "mechanical": False,+ "signature": "class _Ctx:\n a: int\n\ndef f(ctx: _Ctx):",+ "call": "f(ctx)", "notes": ["Read a in the helper as ctx.a."],+ }+ assert _step(step) == (+ "1. Extract it (`a.py:9`) [judgment]\n"+ " Helper:\n ```\n class _Ctx:\n a: int\n\n def f(ctx: _Ctx):\n ```\n"+ " Call: `f(ctx)`\n"+ " Note: Read a in the helper as ctx.a."+ )diff --git a/tests/unit/health/test_extract_method_narrowing.py b/tests/unit/health/test_extract_method_narrowing.pyindex 43125454a..942f29dec 100644--- a/tests/unit/health/test_extract_method_narrowing.py+++ b/tests/unit/health/test_extract_method_narrowing.py@@ -98,3 +98,275 @@ def test_a_name_tested_twice_in_one_guard_loses_both_arms():"a": frozenset({"null", "undefined"})}assert _merged({"a": frozenset({"null"})}, {"a": None, "b": None}) == {"a": None, "b": None}++++_LOOP_SRC = """+function collect(calls: Call[], seen: Set<string>, name: string) {+ for (const tc of calls) {+ if (tc.status !== "done" || !tc.result) continue;+ if (!seen.has(name)) continue;+ const result = tc.result;+ seen.add(result.id);+ seen.add(tc.name);+ }+}+"""+++def test_a_guard_on_a_property_is_named_for_the_object_holding_it():+ # ``chat/source-citations.tsx``: ``!tc.result`` narrows the path, not ``tc``,+ # so a helper typed with any type a caller's ``tc`` has stops compiling.+ from repowise.core.analysis.health.complexity.languages import get_language_map+ from repowise.core.analysis.health.refactoring.extract_method import _def_lines+ from repowise.core.analysis.health.refactoring.narrowing import property_narrowings+ from repowise.core.ingestion.parser import _get_language++ if _get_language("typescript") is None:+ pytest.skip("tree-sitter language pack missing for typescript")+ src = textwrap.dedent(_LOOP_SRC)+ res = analyze_file("m.ts", "typescript", src.encode(), flagged_only=False)+ if not res.functions:+ pytest.skip("tree-sitter language pack missing for typescript")+ fn = res.functions[0]+ lines = src.splitlines()+ start = next(i for i, ln in enumerate(lines, 1) if "const result" in ln)+ guard = next(i for i, ln in enumerate(lines, 1) if "!tc.result" in ln)+ found = property_narrowings(+ fn.fn_node, get_language_map("typescript"), start, start + 2, {"seen", "tc"}, _def_lines(fn)+ )+ # ``seen.has`` is a callee, not a property the guard tests.+ assert found == {"tc": guard}+++_PLANNED_SRC = """+function scan(calls: Call[], out: string[], strict: boolean) {+ for (const tc of calls) {+ if (!GUARD) continue;+ const result = tc.result;+ if (result.a) {+ out.push(result.a);+ } else if (result.b) {+ out.push(result.b);+ }+ if (result.c && strict) {+ out.push(result.c);+ }+ out.push(String(out.length));+ out.push(String(out.length + 1));+ }+ if (strict) {+ out.push("strict");+ }+ return out;+}+"""++[email protected](("guard", "planned"), [("tc.result", False), ("strict", True)])+def test_a_span_reading_a_property_a_guard_narrowed_is_refused(guard, planned):+ from dataclasses import dataclass++ from repowise.core.analysis.health.refactoring.extract_method import (+ NARROWING_LOST,+ STAGE_REFUSED_DETAIL,+ ExtractMethodDetector,+ )+ from repowise.core.analysis.health.refactoring.models import RefactoringContext+ from repowise.core.ingestion.parser import _get_language++ if _get_language("typescript") is None:+ pytest.skip("tree-sitter language pack missing for typescript")+ src = textwrap.dedent(_PLANNED_SRC).replace("GUARD", guard)+ res = analyze_file("m.ts", "typescript", src.encode(), flagged_only=False)+ if not res.functions:+ pytest.skip("tree-sitter language pack missing for typescript")++ @dataclass+ class _Finding:+ biomarker_type: str+ function_name: str+ line_start: int+ health_impact: float+ details: dict++ finding = _Finding("complex_method", "scan", res.functions[0].start_line, 2.0, {})+ ctx = RefactoringContext(+ file_path="m.ts", language="typescript", nloc=40, findings=[finding],+ function_analyses=res.functions,+ )+ plans = ExtractMethodDetector().detect(ctx)+ assert any("tc" in p.plan["params"] for p in plans) is planned+ assert (NARROWING_LOST in finding.details.get(STAGE_REFUSED_DETAIL, ())) is not planned+++_GUARDED_SRC = """+function f(calls: Call[], xs: number[], seen: Set<string>) {+ for (let tc of calls) {+ GUARD+ REBIND+ seen.add(BODY);+ }+}+"""+++ ("guard", "body", "rebind", "refused"),+ [+ ("if (!tc.result) continue;", "tc.result.id", "", True),+ ("if (tc.result == null) continue;", "tc?.result.id", "", True),+ # The span never reads the narrowed path: nothing to lose.+ ("if (!tc.result) continue;", "tc.name", "", False),+ # A literal comparison may discriminate the whole union.+ ("if (tc.kind !== 'done') continue;", "tc.name", "", True),+ # An ordering test narrows nothing.+ ("if (xs.length > 0) continue;", "String(xs[0])", "", False),+ # A rebinding after the guard ends its narrowing.+ ("if (!tc.result) continue;", "tc.result.id", "tc = calls[0];", False),+ ],+)+def test_which_property_tests_narrow_a_span_input(guard, body, rebind, refused):+ from repowise.core.analysis.health.complexity.languages import get_language_map+ from repowise.core.analysis.health.refactoring.extract_method import _def_lines+ from repowise.core.analysis.health.refactoring.narrowing import property_narrowings+ from repowise.core.ingestion.parser import _get_language++ if _get_language("typescript") is None:+ pytest.skip("tree-sitter language pack missing for typescript")+ src = textwrap.dedent(_GUARDED_SRC).replace("GUARD", guard).replace("BODY", body)+ src = src.replace("REBIND", rebind)+ res = analyze_file("m.ts", "typescript", src.encode(), flagged_only=False)+ if not res.functions:+ pytest.skip("tree-sitter language pack missing for typescript")+ fn = res.functions[0]+ line = next(i for i, ln in enumerate(src.splitlines(), 1) if "seen.add" in ln)+ found = property_narrowings(+ fn.fn_node, get_language_map("typescript"), line, line, {"tc", "xs", "seen"}, _def_lines(fn)+ )+ assert bool(found) is refused+++def _ts_function(src: str):+ from repowise.core.ingestion.parser import _get_language++ if _get_language("typescript") is None:+ pytest.skip("tree-sitter language pack missing for typescript")+ src = textwrap.dedent(src)+ res = analyze_file("m.ts", "typescript", src.encode(), flagged_only=False)+ if not res.functions:+ pytest.skip("tree-sitter language pack missing for typescript")+ return res.functions[0], src.splitlines()+++def test_an_if_or_assert_the_span_runs_under_narrows_a_plain_name():+ # zulip ``composebox_typeahead.ts``: ``if (sub !== undefined) { ... }`` around+ # the span; ``activity_ui.ts``: ``assert(user_cursor !== undefined)`` above it.+ fn, lines = _ts_function("""+ function f(sub: Sub | undefined, n: number, out: string[]) {+ assert(out !== undefined);+ if (sub !== undefined && n > 0) {+ out.push(sub.name);+ }+ }+ """)+ line = next(i for i, ln in enumerate(lines, 1) if "out.push" in ln)+ types = {"sub": "Sub | undefined", "out": "string[]", "n": "number"}+ notes = _narrow(fn, Extraction(line, line, ("sub", "n", "out"), (), 0, 0), "typescript", types)+ holder = next(i for i, ln in enumerate(lines, 1) if "sub !== undefined" in ln)+ asserted = next(i for i, ln in enumerate(lines, 1) if "assert(" in ln)+ # An ordering test (``n > 0``) narrows nothing.+ assert notes == {"sub": holder, "out": asserted} and types == {"n": "number"}+++ ("src", "reason"),+ [+ # A module-level name the host asserts on: no parameter carries it.+ ("""+ function f(out: string[]) {+ assert(cursor !== undefined);+ for (const x of out) {+ if (x) {+ cursor.next();+ } else if (x === "a") {+ cursor.prev();+ }+ cursor.mark(x);+ }+ }+ """, "narrowing_lost"),+ # ``let line: T;`` outside, assigned inside: the helper's write names nothing.+ ("""+ function f(out: string[], k: string) {+ let line: string;+ for (const x of out) {+ if (x === k) {+ line = x;+ out.push(line);+ } else if (x) {+ line = k;+ out.push(line);+ }+ }+ }+ """, "outer_declaration"),+ ],+)+def test_a_span_whose_helper_cannot_be_written_is_refused(src, reason):+ from repowise.core.analysis.health.refactoring.extract_method import _writable_spans++ fn, lines = _ts_function(src)+ start = next(i for i, ln in enumerate(lines, 1) if "for (const x" in ln)+ end = next(i for i in range(len(lines), 0, -1) if lines[i - 1].strip() == "}") - 1+ refused: set[str] = set()+ span = Extraction(start, end, ("out",) if reason == "narrowing_lost" else ("k", "out"), (), 0, 0)+ assert _writable_spans(fn, [span], "typescript", refused) == []+ assert refused == {reason}+++def test_a_span_holding_an_assert_the_code_after_it_needs_is_refused():+ # zulip ``copy_messages.ts``: the span opened with ``assert(message !== undefined)``+ # and the loop read ``message.sender_full_name`` after it.+ from repowise.core.analysis.health.refactoring.extract_method import _writable_spans++ fn, lines = _ts_function("""+ function f(rows: Row[], out: string[]) {+ for (const row of rows) {+ const message = find(row);+ assert(message !== undefined);+ if (message.a) {+ out.push(message.a);+ }+ out.push(message.name);+ }+ }+ """)+ start = next(i for i, ln in enumerate(lines, 1) if "assert(" in ln)+ span = Extraction(start, start + 3, ("message", "out"), (), 0, 0)+ refused: set[str] = set()+ assert _writable_spans(fn, [span], "typescript", refused) == []+ assert refused == {"narrowing_lost"}+++def test_an_output_declared_before_the_span_is_declared_again_in_the_helper():+ # ``blast-radius-header.tsx``: ``let gapClause: string;`` above, assigned in the span.+ from repowise.core.analysis.health.refactoring.extract_method import _undeclared_outputs_note++ fn, lines = _ts_function("""+ function f(n: number): string {+ let clause: string;+ if (n > 1) {+ clause = "many";+ } else {+ clause = "one";+ }+ return clause;+ }+ """)+ start = next(i for i, ln in enumerate(lines, 1) if "if (n > 1)" in ln)+ span = Extraction(start, start + 4, ("n",), ("clause",), 0, 0)+ assert _undeclared_outputs_note(fn, span) == [+ "Declare clause at the top of the helper, as the function does: the lines assign it "+ "without declaring it."+ ]diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.pyindex 06e608e3a..8ad4ec0b3 100644--- a/tests/unit/health/test_fix_first_build.py+++ b/tests/unit/health/test_fix_first_build.py@@ -612,6 +612,54 @@ def test_a_finding_whose_plan_is_below_the_worth_floor_leads_with_that_plan() ->)+def _object_plans(**obj_over) -> list:+ """A staged plan whose first stage reads three values off ``ctx``."""+ plans = _staged_plans()+ body = plans[0]["plan"]+ body["params"] = ["ctx", "rows"]+ body["new_symbol"] = {+ "signature_text": "def sum_rows(ctx: _RunContext, rows):",+ "notes": ["Read a, b, limit in the helper as ctx.a, ctx.b, ctx.limit."],+ }+ body["call_site"] = {"new_text": "total = sum_rows(ctx, rows)"}+ body["parameter_object"] = {+ "name": "_RunContext", "var": "ctx",+ "declaration_text": "@dataclass(frozen=True)\nclass _RunContext:\n a: int",+ "construct_text": "ctx = _RunContext(a=a, b=b, limit=limit)",+ "notes": ["Import dataclass from dataclasses."],+ **obj_over,+ }+ return plans+++def test_a_step_reading_the_parameter_object_declares_and_builds_it() -> None:+ # Without them the call names a variable and a type that do not exist.+ core = next(i for i in _build(plans=_object_plans()).items if i.kind == "refactor")+ step = core.action.steps[0]+ assert step.signature == (+ "@dataclass(frozen=True)\nclass _RunContext:\n a: int\n\n"+ "def sum_rows(ctx: _RunContext, rows):"+ )+ assert step.call == "ctx = _RunContext(a=a, b=b, limit=limit)\ntotal = sum_rows(ctx, rows)"+ assert step.notes == (+ "Add the _RunContext declaration above the helper, and the line building ctx just before "+ "the call, as shown.",+ "Import dataclass from dataclasses.",+ "Read a, b, limit in the helper as ctx.a, ctx.b, ctx.limit.",+ )+ # The compact row stays the edit only.+ assert set(core.compact()["first_step"]) == {"action", "line"}+++def test_a_step_whose_parameter_object_cannot_be_written_is_not_offered() -> None:+ queue = _build(plans=_object_plans(declaration_text=None))+ assert "refac2_big" not in {p for i in queue.items for p in i.source.plan_ids}+ plans = _object_plans(construct_text="")+ plans[0].update(file_path="src/core.py", target_symbol="src/core.py::run")+ lone = _build(plans=plans, refactoring=[], performance=[]).lead+ assert lone.action.steps[0].call is None++def test_a_staged_plan_leading_a_finding_names_its_helpers() -> None:run = _run(*_hidden_plan(_staged_plans()))assert run.title == "Split run into 3 helpers"