Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(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.md
index 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 move
with the first edit); if that text repeats in the file, it says to stay inside the
function.
+- 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.md
index 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 in
code declares them; `<type>` marks a type for you to fill in. It flags an
awaiting 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 reason
code: `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.py
index 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.py
index 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, Mapping
from dataclasses import dataclass
from typing import Any
+from repowise.core.analysis.health.refactoring.recipe import _strs
from repowise.core.analysis.health.rows import field
from 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 None
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/model.py b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
index 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.py
index 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 LowPriority
from repowise.core.ci.markdown import code as md_code
from . import text
-from ._parts import _helper_code, _open
+from ._parts import _helper_code, _open, object_code, shared_object
from .model import FixStep
@@ -134,6 +134,14 @@ def _extract_text(sym: str, body: Mapping[str, Any], start: Any, end: Any) -> st
return 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):
continue
start, 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.py
index 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_scope
from .declarative import declarative_flat
from .helper_naming import ScopeNames, placeholder_names
from .models import RefactoringContext, RefactoringSuggestion
-from .narrowing import narrowed, narrowings
+from .narrowing import narrowed, narrowings, property_narrowings, span_guards
from .registry import RefactoringDetector, register
if 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 None
plan = 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 None
if 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 None
and 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"] = notes
span = {"start": extraction.start_line, "end": extraction.end_line}
call = texts.call if texts else None
return {
@@ -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.py
index 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 no
arms: the plan says the parameter needs the narrowed type instead of writing
one.
+
+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 re
from dataclasses import dataclass
from 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 None
while 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_sibling
while sib is not None:
- _add_guard(sib, lmap, end, names, def_lines, out)
+ out.append(sib)
sib = sib.prev_named_sibling
node = node.parent
return 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.py
index 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.py
index 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.py
index 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"