Skip to content

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

fix(health): name Extract Method helpers from banners and labels, never compute_ for effects (#3287)

Raghav Chamadiyaf0b3a1fe38ef
diff --git a/docs/architecture/refactoring.md b/docs/architecture/refactoring.md
index 1b3ca33cc..de9e003a5 100644
--- a/docs/architecture/refactoring.md
+++ b/docs/architecture/refactoring.md
@@ -32,7 +32,9 @@ feature-envy distance, MFAS for cycles, Newman modularity for decomposition.
`impact_delta` credits the share of the source finding the plan removes; for
Extract Method that is `ccn_removed / ccn`, `slice_nloc / nloc`, or the larger of
the two for `brain_method`, capped at 1. `naming.py` returns `null` when no fact
-anchors a name.
+anchors a name. Extract Method's `helper_naming.py` names a helper from a `timed()`
+label, a banner comment, or `compute_<out>` for an effect-free span, and drops any
+name already taken in scope.
Plan ids come from `identity.py`: a `refac<version>_` prefix over a per-type stable
kernel. Bumping the version re-mints ids; a held id from an older version reports
diff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.md
index 8d54e0d06..e8b4bac41 100644
--- a/docs/layers/REFACTORING.md
+++ b/docs/layers/REFACTORING.md
@@ -103,7 +103,10 @@ Names are never invented. A suggested helper or file name is `null` when nothing
in the code anchors one. A Split File or Extract Class plan with an unnamed group
is held as `needs_design`, like a cycle: it is not a step and never reaches Fix
first. Code only moves within a language family, so Java, Kotlin and Scala are
-separate. A callback is named after the call it is passed to.
+separate. A callback is named after the call it is passed to. An Extract Method
+helper is named from a stage label, a banner comment, or `compute_<value>` when the
+span has no outside effects. A name already taken where the helper lands is
+dropped, so a `null` name means you name the helper.
An empty list means no detector found work that clears its gates. It does not mean
the code needs no attention: check the findings in
@@ -180,8 +183,8 @@ Most plans answer a health finding, so per-path marker rules in
generated code comes back as a diff.
- Extract Method offers a span only when it can show the extraction keeps behavior
(every returned value written on every path, no state carried across loop
- iterations, no local a closure shares crossing the span's edge). Spans it
- cannot prove are dropped, so it under-reports by design.
+ iterations, no local a closure shares across the span's edge). Spans it cannot
+ prove are dropped, so it under-reports by design.
- Extract Method skips spans too small to matter and spans that would carry the
original finding into the helper. A component whose branching is mostly in its
markup gets no extraction.
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/effects.py b/packages/core/src/repowise/core/analysis/health/dataflow/effects.py
new file mode 100644
index 000000000..e2523417e
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/effects.py
@@ -0,0 +1,401 @@
+"""Whether an Extract Method span acts on anything it does not own.
+
+A span that only builds values can be named for the value (``compute_total``);
+one that prints, awaits, mutates an argument or writes through ``self`` is an
+action, and a value name would describe it wrongly. A wrong ``compute_`` name
+costs more than no name, so every doubt here resolves to "acts outside".
+
+What the span owns is what it binds to a fresh value: a literal, a collection
+or comprehension, an operator result, or an empty built-in collection. A name
+bound from a call result or from another name may alias an outside object, so
+calls and writes through it count as outside effects. Aliasing beyond that
+(a fresh list later handed a parameter's object) is not followed.
+
+Calls are judged by position and receiver:
+
+- in statement position (result dropped), any call except a method call on an
+ owned name: it ran for what it does;
+- elsewhere, a method call whose receiver is not owned, unless the receiver is
+ an imported module or a built-in namespace (``os.path.join``,
+ ``Math.max``), or the method is a read that changes nothing on the built-in
+ types it is almost always called on (``_PURE_METHODS``). A free function or a
+ constructor in expression position is not judged: without types there is no
+ telling ``len`` from ``open``, and its result is checked where it is used.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+ from ..complexity.languages import LanguageNodeMap
+ from .defuse import FunctionDefUse
+
+_MEMBER_KINDS = frozenset(
+ {"attribute", "member_expression", "field_expression", "selector_expression", "field_access"}
+)
+# Write targets that reach through a name instead of rebinding it.
+_REACH_KINDS = _MEMBER_KINDS | {
+ "subscript",
+ "subscript_expression",
+ "index_expression",
+ "array_access",
+ "pointer_expression",
+}
+_LIST_KINDS = frozenset({"expression_list", "pattern_list", "tuple_pattern", "list_pattern"})
+# Fields that lead from an access or call to the name it starts from.
+_BASE_FIELDS = ("function", "object", "value", "operand", "argument", "array")
+_RECEIVER_FIELDS = ("object", "operand", "value", "argument")
+_MEMBER_FIELDS = ("property", "attribute", "field")
+# Binding forms outside ``lmap.assignment_kinds`` / ``local_decl_kinds``: the
+# declarator a declaration statement wraps, and module-level constants.
+_DECLARATOR_KINDS = frozenset(
+ {
+ "variable_declarator",
+ "init_declarator",
+ "var_spec",
+ "const_spec",
+ "let_declaration",
+ "short_var_declaration",
+ "const_item",
+ "static_item",
+ }
+)
+_TARGET_FIELDS = ("left", "name", "pattern", "declarator")
+_VALUE_FIELDS = ("right", "value")
+# Statements that act outside the span whatever they hold.
+_EFFECT_STMT_KINDS = frozenset(
+ {"go_statement", "defer_statement", "global_statement", "nonlocal_statement", "send_statement"}
+)
+_UPDATE_KINDS = frozenset({"update_expression", "inc_statement", "dec_statement"})
+# Every grammar the slicer serves names its expression statement this;
+# ``lmap.expr_stmt_kinds`` lists only the grammars that do not.
+_EXPR_STMT = "expression_statement"
+# Values that are new objects or plain values, never an alias.
+_FRESH_KINDS = frozenset(
+ {
+ # Python
+ "list", "dictionary", "set", "tuple", "list_comprehension", "set_comprehension",
+ "dictionary_comprehension", "generator_expression", "string", "concatenated_string",
+ "integer", "float", "true", "false", "none",
+ # TS / JS
+ "array", "object", "template_string", "number", "null", "undefined", "regex",
+ # Go
+ "composite_literal", "interpreted_string_literal", "raw_string_literal", "int_literal",
+ "float_literal", "nil",
+ # Java
+ "array_creation_expression", "string_literal", "decimal_integer_literal", "null_literal",
+ "character_literal",
+ # Rust / C++
+ "array_expression", "tuple_expression", "integer_literal", "boolean_literal", "initializer_list", "number_literal", "nullptr",
+ }
+) # fmt: skip
+_OPERATOR_KINDS = frozenset(
+ {"binary_operator", "binary_expression", "boolean_operator", "comparison_operator",
+ "not_operator", "unary_operator"}
+) # fmt: skip
+# Constructors of an empty or copied built-in collection: the result is new.
+_FRESH_CTORS = frozenset(
+ {
+ "list", "dict", "set", "tuple", "frozenset", "defaultdict", "OrderedDict", "Counter",
+ "deque", "str", "int", "float", "bool", "bytearray",
+ "Map", "Set", "Array", "Object", "WeakMap", "WeakSet",
+ "make", "new",
+ "ArrayList", "HashMap", "HashSet", "LinkedList", "LinkedHashMap", "TreeMap", "ArrayDeque",
+ "StringBuilder",
+ "Vec::new", "Vec::with_capacity", "HashMap::new", "HashSet::new", "BTreeMap::new",
+ "BTreeSet::new", "VecDeque::new", "String::new", "String::from",
+ }
+) # fmt: skip
+_FRESH_MACROS = frozenset({"vec", "format"})
+# Reads that change nothing on the str / list / dict / array / map they are
+# nearly always called on. A name here on a type that does mutate is the
+# ceiling of a type-free check; mutators (append, pop, push, set, sort, update,
+# write, ...) are deliberately absent.
+_PURE_METHODS = frozenset(
+ {
+ # str
+ "strip", "lstrip", "rstrip", "lower", "upper", "casefold", "title", "capitalize",
+ "split", "rsplit", "splitlines", "join", "startswith", "endswith", "replace", "format",
+ "encode", "decode", "find", "rfind", "index", "count", "partition", "rpartition",
+ "removeprefix", "removesuffix", "isdigit", "isalpha", "isalnum", "isspace", "isupper",
+ "islower", "zfill", "ljust", "rjust", "center",
+ # dict / list reads, compiled patterns
+ "items", "keys", "values", "copy", "match", "fullmatch", "search", "findall",
+ "finditer", "sub",
+ # JS / TS strings and arrays (callbacks are walked like the rest of the span)
+ "trim", "trimStart", "trimEnd", "toLowerCase", "toUpperCase", "slice", "substring",
+ "includes", "indexOf", "lastIndexOf", "startsWith", "endsWith", "map", "filter", "some",
+ "every", "findIndex", "findLast", "flatMap", "flat", "concat", "reduce", "at",
+ "charAt", "charCodeAt", "padStart", "padEnd", "repeat", "replaceAll", "test", "toString",
+ "toFixed", "localeCompare", "entries", "has",
+ # Java / Rust reads
+ "equals", "length", "size", "isEmpty", "contains", "containsKey", "getOrDefault",
+ "len", "is_empty", "iter", "clone", "to_string", "as_str", "starts_with", "ends_with",
+ "to_lowercase", "to_uppercase",
+ }
+) # fmt: skip
+# A keyed read (``d.get(k)``); with no argument it is ``q.get()``, which pops.
+_READ_WITH_KEY = frozenset({"get"})
+# Namespaces every file can call without importing them.
+_BUILTIN_NAMESPACES = frozenset(
+ {"Math", "JSON", "Object", "Array", "Number", "String", "Date", "Promise", "Reflect",
+ "Symbol", "BigInt", "Intl", "Integer", "Long", "Double", "Float", "Boolean", "Character"}
+) # fmt: skip
+
+
+@dataclass(frozen=True)
+class Ownership:
+ """What a span may touch without acting outside itself.
+
+ ``owned``: names the span binds, every time, to a fresh value.
+ ``declared``: names its function declares (parameters included); a write
+ to any other name reaches a captured variable. ``None`` for a language
+ where assignment is declaration (Python), whose outer writes need
+ ``global`` / ``nonlocal`` and are caught there.
+ ``modules``: imported names and built-in namespaces.
+ """
+
+ owned: frozenset[str]
+ declared: frozenset[str] | None
+ modules: frozenset[str]
+
+
+def has_outside_effects(stmts: list[Node], own: Ownership, lmap: LanguageNodeMap) -> bool:
+ """Whether running *stmts* acts on anything the span does not own.
+
+ Lambdas and callbacks are walked with the span: most run where they are
+ written (``map``, ``sort(key=...)``). The slicer refuses spans holding a
+ named nested function, so none is walked by mistake.
+ """
+ expr_kinds = lmap.expr_stmt_kinds | {_EXPR_STMT}
+ stack = list(stmts)
+ while stack:
+ node = stack.pop()
+ if _acts_outside(node, own, lmap, expr_kinds):
+ return True
+ stack.extend(node.named_children)
+ return False
+
+
+def _acts_outside(
+ node: Node, own: Ownership, lmap: LanguageNodeMap, expr_kinds: frozenset[str]
+) -> bool:
+ t = node.type
+ if t in lmap.with_kinds or t in _EFFECT_STMT_KINDS:
+ return True
+ if t in expr_kinds:
+ return _drops_a_call(node, own, lmap)
+ if t in lmap.call_kinds:
+ return _impure_call(node, own)
+ if t in lmap.assignment_kinds or t in lmap.augmented_assign_kinds:
+ left = node.child_by_field_name("left")
+ return left is not None and any(_escapes(x, own) for x in _targets(left))
+ if t in _UPDATE_KINDS:
+ target = node.child_by_field_name("argument") or _first(node)
+ return target is not None and _escapes(target, own)
+ if t == "delete_statement":
+ return any(_escapes(x, own) for x in _targets(_first(node)))
+ if t == "unary_expression" and node.children and node.children[0].type == "delete":
+ target = node.child_by_field_name("argument")
+ return target is not None and _escapes(target, own)
+ if t == "reference_expression" and any(c.type == "mutable_specifier" for c in node.children):
+ target = node.child_by_field_name("value")
+ return target is not None and _root(target) not in own.owned
+ return False
+
+
+def _drops_a_call(stmt: Node, own: Ownership, lmap: LanguageNodeMap) -> bool:
+ inner = _first(stmt)
+ while inner is not None and "await" in inner.type and inner.named_children:
+ inner = inner.named_children[0]
+ if inner is None:
+ return False
+ if inner.type.endswith("macro_invocation"):
+ return True
+ if inner.type not in lmap.call_kinds:
+ return False
+ receiver, _method = _call_parts(inner)
+ return receiver is None or _root(receiver) not in own.owned
+
+
+def _impure_call(call: Node, own: Ownership) -> bool:
+ receiver, method = _call_parts(call)
+ if receiver is None or _root(receiver) in own.owned:
+ return False
+ if _module_path(receiver, own.modules) or method in _PURE_METHODS:
+ return False
+ if method in _READ_WITH_KEY:
+ args = call.child_by_field_name("arguments")
+ return args is None or not args.named_children
+ return True
+
+
+def _call_parts(call: Node) -> tuple[Node | None, str | None]:
+ """A method call's receiver and method name; ``(None, None)`` for a call of
+ a plain function or a constructor."""
+ obj, name = call.child_by_field_name("object"), call.child_by_field_name("name")
+ if obj is not None and name is not None: # Java ``method_invocation``
+ return obj, _text(name)
+ fn = call.child_by_field_name("function")
+ if fn is None or fn.type not in _MEMBER_KINDS:
+ return None, None
+ receiver = _field(fn, _RECEIVER_FIELDS)
+ member = _field(fn, _MEMBER_FIELDS)
+ return receiver, _text(member) if member is not None else None
+
+
+def _module_path(receiver: Node, modules: frozenset[str]) -> bool:
+ """True for ``os.path`` / ``Math``: plain member reads from a module name."""
+ node: Node | None = receiver
+ while node is not None and node.type in _MEMBER_KINDS:
+ node = _field(node, _RECEIVER_FIELDS)
+ return node is not None and _is_name(node) and _text(node) in modules
+
+
+def _escapes(target: Node, own: Ownership) -> bool:
+ """Whether writing *target* changes something the span does not own."""
+ if target.type in _REACH_KINDS or _is_deref(target):
+ return _root(target) not in own.owned
+ if _is_name(target) and own.declared is not None:
+ return _text(target) not in own.declared
+ return False
+
+
+def _is_deref(node: Node) -> bool:
+ return node.type == "unary_expression" and bool(node.children) and node.children[0].type == "*"
+
+
+def owned_names(stmts: list[Node], lmap: LanguageNodeMap) -> frozenset[str]:
+ """Names *stmts* bind, at every binding, to a fresh value."""
+ binders = lmap.assignment_kinds | lmap.local_decl_kinds | _DECLARATOR_KINDS
+ fresh: dict[str, bool] = {}
+ stack = list(stmts)
+ while stack:
+ node = stack.pop()
+ stack.extend(node.named_children)
+ target = _field(node, _TARGET_FIELDS) if node.type in binders else None
+ if target is None:
+ continue
+ ok = _fresh(_field(node, _VALUE_FIELDS), lmap)
+ for name in bound_names(target):
+ fresh[name] = fresh.get(name, True) and ok
+ return frozenset(name for name, ok in fresh.items() if ok)
+
+
+def _fresh(value: Node | None, lmap: LanguageNodeMap) -> bool:
+ if value is None:
+ return True # declared, not yet assigned: its later bindings decide
+ while value.type == "parenthesized_expression" and value.named_children:
+ value = value.named_children[0]
+ t = value.type
+ if t in _FRESH_KINDS or t in _OPERATOR_KINDS:
+ return True
+ if t in _LIST_KINDS:
+ return all(_fresh(v, lmap) for v in value.named_children)
+ if t.endswith("macro_invocation"):
+ macro = value.child_by_field_name("macro")
+ return macro is not None and _text(macro) in _FRESH_MACROS
+ if t in lmap.call_kinds or t == "new_expression":
+ callee = _field(value, ("function", "constructor", "type"))
+ return callee is not None and _text(callee).split("<")[0] in _FRESH_CTORS
+ return False
+
+
+def bound_names(target: Node) -> list[str]:
+ """The plain names a binding target binds (not ``a.b`` or ``a[i]``)."""
+ out: list[str] = []
+ stack = [target]
+ while stack:
+ node = stack.pop()
+ if node.type in _REACH_KINDS or _is_deref(node):
+ continue
+ if _is_name(node):
+ out.append(_text(node))
+ continue
+ # A declarator's own target only: its type and initializer bind nothing.
+ inner = _field(node, _TARGET_FIELDS)
+ stack.extend([inner] if inner is not None else node.named_children)
+ return out
+
+
+def binding_target(node: Node, lmap: LanguageNodeMap) -> Node | None:
+ """The target of *node* when it binds names, else ``None``."""
+ binders = lmap.assignment_kinds | lmap.local_decl_kinds | _DECLARATOR_KINDS
+ return _field(node, _TARGET_FIELDS) if node.type in binders else None
+
+
+def declared_names(
+ fn_node: Node, def_use: FunctionDefUse, lmap: LanguageNodeMap
+) -> frozenset[str] | None:
+ """Names *fn_node* declares, parameters and nested scopes included (over-
+ counting only hides a captured write). ``None`` where assignment is
+ declaration."""
+ if not lmap.local_decl_kinds:
+ return None
+ names = {p.name for p in def_use.params} | {d.var for d in def_use.definitions if d.declares}
+ decl = lmap.local_decl_kinds | _DECLARATOR_KINDS
+ stack = [fn_node]
+ while stack:
+ node = stack.pop()
+ stack.extend(node.named_children)
+ target = _field(node, _TARGET_FIELDS) if node.type in decl else None
+ if target is not None:
+ names.update(bound_names(target))
+ return frozenset(names)
+
+
+def imported_names(root: Node) -> frozenset[str]:
+ """Names a file's top-level imports bring in, plus built-in namespaces.
+
+ Every name leaf of an import counts (``os`` and ``path`` of ``os.path``),
+ and a quoted path counts by its last segment (Go ``"net/http"`` is
+ ``http``); an extra name only exempts a module-style call, never a write.
+ """
+ names = set(_BUILTIN_NAMESPACES)
+ for node in root.named_children:
+ if "import" not in node.type and node.type != "use_declaration":
+ continue
+ stack = [node]
+ while stack:
+ leaf = stack.pop()
+ if leaf.named_children:
+ stack.extend(leaf.named_children)
+ continue
+ text = _text(leaf).strip("\"'`")
+ names.add(text.rsplit("/", 1)[-1])
+ return frozenset(names)
+
+
+def _targets(left: Node | None) -> list[Node]:
+ if left is None:
+ return []
+ return list(left.named_children) if left.type in _LIST_KINDS else [left]
+
+
+def _root(node: Node) -> str | None:
+ """The name an access or call chain starts from (``a`` in ``a.b[c].d()``)."""
+ for _ in range(64):
+ if not node.named_children:
+ return _text(node)
+ node = _field(node, _BASE_FIELDS) or node.named_children[0]
+ return None
+
+
+def _field(node: Node, fields: tuple[str, ...]) -> Node | None:
+ return next((c for f in fields if (c := node.child_by_field_name(f)) is not None), None)
+
+
+def _first(node: Node | None) -> Node | None:
+ return node.named_children[0] if node is not None and node.named_children else None
+
+
+def _is_name(node: Node) -> bool:
+ return not node.named_children and "identifier" in node.type
+
+
+def _text(node: Node) -> str:
+ return (node.text or b"").decode("utf-8", "replace")
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/slice.py b/packages/core/src/repowise/core/analysis/health/dataflow/slice.py
index e410145e0..1a9af9cc8 100644
--- a/packages/core/src/repowise/core/analysis/health/dataflow/slice.py
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/slice.py
@@ -144,7 +144,7 @@ def find_extractions(analysis: FunctionAnalysis, lmap: LanguageNodeMap) -> list[
out: list[Extraction] = []
evaluated = 0
- for block, loop in _all_blocks(fn_node, lmap.block_kinds, scope_kinds, lmap.loop_kinds):
+ for block, loop in all_blocks(fn_node, lmap.block_kinds, scope_kinds, lmap.loop_kinds):
stmts = block.named_children
n = len(stmts)
is_body = block.id == body_container.id
@@ -949,7 +949,7 @@ def _unwrap_container(node: Node, block_kinds: frozenset[str]) -> Node:
return cur
-def _all_blocks(
+def all_blocks(
fn_node: Node,
block_kinds: frozenset[str],
scope_kinds: frozenset[str],
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/span.py b/packages/core/src/repowise/core/analysis/health/dataflow/span.py
new file mode 100644
index 000000000..8f1d8f709
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/dataflow/span.py
@@ -0,0 +1,81 @@
+"""Where an Extract Method span sits in its function's tree: its statements, the
+comments that head them, and the ``with`` block it may be the body of.
+
+Read by the helper-naming step only, after a span has been chosen, so the cost
+is one walk of one function per emitted plan. The tree is the one the slicer
+already holds (``FunctionAnalysis.fn_node``); nothing is re-parsed. Whether the
+span acts outside itself is :mod:`effects`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .slice import all_blocks
+
+if TYPE_CHECKING:
+ from tree_sitter import Node
+
+ from ..complexity.languages import LanguageNodeMap
+
+
+def span_statements(
+ fn_node: Node | None, start: int, end: int, lmap: LanguageNodeMap
+) -> list[Node]:
+ """The block statements of *fn_node* spanning lines *start*..*end*, or ``[]``
+ when no block cuts there (the span the slicer produced always does)."""
+ if fn_node is None:
+ return []
+ scope_kinds = lmap.function_kinds | lmap.lambda_kinds
+ for block, _loop in all_blocks(fn_node, lmap.block_kinds, scope_kinds, lmap.loop_kinds):
+ stmts = block.named_children
+ first = next((i for i, s in enumerate(stmts) if s.start_point[0] + 1 == start), None)
+ if first is None:
+ continue
+ for last in range(first, len(stmts)):
+ if stmts[last].end_point[0] + 1 == end:
+ return stmts[first : last + 1]
+ return []
+
+
+def enclosing_with(stmts: list[Node], lmap: LanguageNodeMap) -> Node | None:
+ """The ``with`` statement whose whole body *stmts* is, else ``None``: a span
+ lifted out of ``with timed(...):`` is the block that header labels."""
+ if not stmts:
+ return None
+ block = stmts[0].parent
+ holder = block.parent if block is not None else None
+ if holder is None or holder.type not in lmap.with_kinds:
+ return None
+ code = [c for c in block.named_children if not is_comment(c)]
+ inside = [s for s in stmts if not is_comment(s)]
+ return holder if code and inside and code[0] == inside[0] and code[-1] == inside[-1] else None
+
+
+def section_heads(stmts: list[Node]) -> list[tuple[Node, list[str]]]:
+ """Each code statement of the span with the comment lines directly above it.
+
+ The first one's comment run may open the span or sit just before it; either
+ way a run must touch its statement (no blank line between), since a comment
+ separated by a gap heads something else.
+ """
+ return [(s, _comment_above(s)) for s in stmts if not is_comment(s)]
+
+
+def _comment_above(anchor: Node) -> list[str]:
+ run: list[Node] = []
+ node, top = anchor.prev_named_sibling, anchor.start_point[0]
+ while node is not None and is_comment(node) and node.end_point[0] + 1 == top:
+ before = node.prev_sibling
+ if before is not None and before.end_point[0] == node.start_point[0]:
+ break # a trailing comment on the line above annotates that line
+ run.append(node)
+ node, top = node.prev_named_sibling, node.start_point[0]
+ lines: list[str] = []
+ for comment in reversed(run):
+ lines.extend((comment.text or b"").decode("utf-8", "replace").splitlines())
+ return lines
+
+
+def is_comment(node: Node) -> bool:
+ return "comment" in node.type
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 96d3b8524..42c66a869 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
@@ -46,9 +46,10 @@ Plan shape (open dict, no migration):
- ``plan`` = ``{"span": {"start": int, "end": int}, "params": [str, ...],
"returns": [str, ...], "suggested_name": str | None}`` -- the lines to lift,
the inferred signature, and a deterministic starting name (see
- ``_suggested_name``). ``None`` when the span has no single informative OUT
- value: a name derived from the enclosing function described the context
- rather than the span, and collided with every sibling plan in the file.
+ ``helper_naming``): a ``timed()`` stage label, a banner comment, or
+ ``compute_<out>`` for an effect-free span with one informative OUT value.
+ ``None`` when nothing anchors a name, or when the name is already taken in
+ the scope the helper lands in.
- ``plan.needs_async`` -- the span awaits, so the helper is async and its call
is awaited. An awaiting plan also carries ``async_host``: False when the
enclosing function is not declared async, which makes the step a judgment
@@ -79,8 +80,8 @@ from ..dataflow import find_extractions
from ..effort import effort_bucket
from ..perf.dialects import PERF_DIALECTS
from ..scoring import severity_deduction
+from .helper_naming import ScopeNames, helper_name, out_value_name
from .models import RefactoringContext, RefactoringSuggestion
-from .naming import join_identifier, split_words
from .registry import RefactoringDetector, register
if TYPE_CHECKING:
@@ -88,30 +89,6 @@ if TYPE_CHECKING:
from ..dataflow import Extraction, FunctionAnalysis
from ..models import Severity
-# OUT values whose name describes the variable's role, not the block's
-# product: ``compute_result`` names nothing the reader did not know.
-_UNINFORMATIVE_OUT = frozenset(
- {"out", "result", "results", "value", "values", "ret", "tmp", "temp", "data", "item"}
-)
-
-# How each language that reaches this detector joins the words of a helper
-# name. Only the languages the Extract Method slicer has a dialect for
-# (``dataflow/dialects/__init__.py``) can appear here. C++ is deliberately
-# absent: it has no single convention (the standard library is snake_case,
-# Google style is PascalCase, Qt is camelCase), so it keeps the snake_case
-# default rather than getting one answer that is wrong for most C++ repos.
-_NAME_CONVENTION: dict[str, str] = {
- "go": "camelCase",
- "java": "camelCase",
- "typescript": "camelCase",
- "tsx": "camelCase",
- "javascript": "camelCase",
- "jsx": "camelCase",
- "svelte": "camelCase",
- "vue": "camelCase",
-}
-_SNAKE_CASE = "snake_case"
-
# The function-level structural biomarkers this detector answers. A function is
# only offered an extraction when one of these flagged it, so the suggestion
# list never exceeds (and stays consistent with) what health surfaces.
@@ -156,7 +133,9 @@ class ExtractMethodDetector(RefactoringDetector):
return []
out: list[RefactoringSuggestion] = []
- for analysis in analyses:
+ names = ScopeNames(lmap)
+ # Source order, so the first of two colliding plans keeps the name.
+ for analysis in sorted(analyses, key=lambda a: (a.start_line, a.end_line)):
matched = self._findings_for(analysis, ctx.findings)
if not matched:
# Only suggest where a method biomarker actually fired.
@@ -179,7 +158,12 @@ class ExtractMethodDetector(RefactoringDetector):
"span": {"start": best.start_line, "end": best.end_line},
"params": list(best.params),
"returns": list(best.returns),
- "suggested_name": self._suggested_name(analysis, best, ctx.language),
+ "suggested_name": names.claim(
+ analysis,
+ helper_name(
+ analysis, best, lmap, ctx.language, names.imports(analysis.fn_node)
+ ),
+ ),
**_async_fields(analysis, best, lmap, ctx.language),
},
evidence={
@@ -234,48 +218,8 @@ class ExtractMethodDetector(RefactoringDetector):
def _suggested_name(
analysis: FunctionAnalysis, extraction: Extraction, language: str | None = None
) -> str | None:
- """A deterministic starting name for the lifted helper, in *language*'s
- identifier convention.
-
- Same posture as Extract Helper (see ``naming``): anchor the name to
- something the plan already knows rather than guess what the block does.
- The slice's OUT value is that anchor when there is exactly one -- a span
- whose single product is ``average`` is, by construction, the code that
- computes it, so ``compute_average`` describes it without inferring
- intent. With no single OUT (a void slice, or several) the only certain
- anchor left is the function the span came out of, which at least names
- the helper for its context. Measured over the 854 stored plans on this
- repo's index, 545 (64%) come from the OUT value and 309 from the
- enclosing function.
-
- Convention is per language: Python, Rust and C++ keep ``compute_average``;
- Go, Java and the TypeScript/JavaScript family take ``computeAverage``.
- C++ gets no convention because it has no single one -- the standard
- library is snake_case and Google style is PascalCase, so a fixed answer
- would be wrong for as many repos as it fixed. The out value's own casing
- is kept as word boundaries rather than thrown away, so ``meanValue`` is
- ``computeMeanValue`` in Java, not ``compute_meanvalue``.
-
- **Not unique within a file, by design.** Two functions in one file can
- each produce a value with the same name, and both spans then get the
- same ``compute_*``: 28 of those 854 plans, across 14 files, collide with
- a sibling that way (the fallback branch does not collide, since there is
- one plan per function). Uniqueness would need a per-file suffix, which
- would renumber existing names whenever a new plan appeared and churn
- every persisted row. The name is a starting point every surface frames
- as editable, so the surfaces say to rename on a clash instead.
- """
- if len(extraction.returns) != 1:
- return None
- out_words = split_words(extraction.returns[0])
- if not out_words:
- return None
- # ``_UNINFORMATIVE_OUT`` is keyed on the single-word slug, matching the
- # names it holds (``meanValue`` is a product, ``result`` is a role).
- if "_".join(out_words) in _UNINFORMATIVE_OUT:
- return None
- convention = _NAME_CONVENTION.get(language or "", _SNAKE_CASE)
- return join_identifier(["compute", *out_words], convention)
+ """The OUT-value name alone (:func:`helper_naming.out_value_name`)."""
+ return out_value_name(analysis, extraction, language)
@staticmethod
def _confidence(extraction: Extraction, share: float) -> str:
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.py b/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.py
new file mode 100644
index 000000000..a57626b46
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.py
@@ -0,0 +1,230 @@
+"""The starting name an Extract Method plan gives the helper it asks you to write.
+
+Sources, in order: a ``timed(..., "label")`` stage label on the span, a banner
+comment over it (the author's own name for the block), and the span's single
+OUT value as ``compute_<out>``. An OUT name describes a value, not an action,
+so it is never given to a span that acts outside itself (``dataflow.effects``);
+nor is a banner that opens with a value verb (``_VALUE_VERBS``). Whatever the
+source, a name a symbol in the helper's scope already uses is dropped. ``None``
+is the honest answer when nothing anchors a name, and every surface asks the
+reader to name the helper then.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..complexity.ast_utils import _find_function_entry_name
+from ..dataflow.effects import (
+ Ownership,
+ binding_target,
+ bound_names,
+ declared_names,
+ has_outside_effects,
+ imported_names,
+ owned_names,
+)
+from ..dataflow.span import enclosing_with, section_heads, span_statements
+from .naming import banner_words, join_identifier, label_words, split_words
+
+if TYPE_CHECKING:
+ from ..complexity.languages import LanguageNodeMap
+ from ..dataflow import Extraction, FunctionAnalysis
+
+# OUT values whose name describes the variable's role, not the block's
+# product: ``compute_result`` names nothing the reader did not know.
+_UNINFORMATIVE_OUT = frozenset(
+ {"out", "result", "results", "value", "values", "ret", "tmp", "temp", "data", "item"}
+)
+
+# How each language that reaches this detector joins the words of a helper
+# name. Only the languages the Extract Method slicer has a dialect for
+# (``dataflow/dialects/__init__.py``) can appear here. C++ is deliberately
+# absent: it has no single convention (the standard library is snake_case,
+# Google style is PascalCase, Qt is camelCase), so it keeps the snake_case
+# default rather than getting one answer that is wrong for most C++ repos.
+NAME_CONVENTION: dict[str, str] = {
+ "go": "camelCase",
+ "java": "camelCase",
+ "typescript": "camelCase",
+ "tsx": "camelCase",
+ "javascript": "camelCase",
+ "jsx": "camelCase",
+ "svelte": "camelCase",
+ "vue": "camelCase",
+}
+_SNAKE_CASE = "snake_case"
+
+# Verbs that promise a value. A banner opening with one over a span that acts
+# outside itself names it the way an OUT name would, wrongly.
+_VALUE_VERBS = frozenset({"compute", "calculate", "calc", "derive", "get", "build", "make"})
+
+# How far below a scope a sibling definition can sit: ``export const f = () =>``
+# is four levels under a TS module, a decorated Python method three under its
+# class. Deeper nodes are expressions, which a scan for names need not visit.
+_SIBLING_DEPTH = 4
+
+
+def out_value_name(
+ analysis: FunctionAnalysis, extraction: Extraction, language: str | None = None
+) -> str | None:
+ """``compute_<out>`` for the slice's single informative OUT value, in
+ *language*'s identifier convention; ``None`` without one.
+
+ A span whose single product is ``average`` is, by construction, the code
+ that computes it, so ``compute_average`` describes it without inferring
+ intent. Convention is per language: Python, Rust and C++ keep
+ ``compute_average``; Go, Java and the TypeScript/JavaScript family take
+ ``computeAverage``. The out value's own casing is kept as word boundaries,
+ so ``meanValue`` is ``computeMeanValue`` in Java, not ``compute_meanvalue``.
+ """
+ if len(extraction.returns) != 1:
+ return None
+ out_words = split_words(extraction.returns[0])
+ if not out_words:
+ return None
+ # ``_UNINFORMATIVE_OUT`` is keyed on the single-word slug, matching the
+ # names it holds (``meanValue`` is a product, ``result`` is a role).
+ if "_".join(out_words) in _UNINFORMATIVE_OUT:
+ return None
+ return join_identifier(["compute", *out_words], _convention(language))
+
+
+def helper_name(
+ analysis: FunctionAnalysis,
+ extraction: Extraction,
+ lmap: LanguageNodeMap,
+ language: str | None,
+ modules: frozenset[str] = frozenset(),
+) -> str | None:
+ """A deterministic starting name for the helper, before the collision
+ check, or ``None`` when nothing in the code anchors one. *modules* are the
+ file's imported names (:func:`dataflow.effects.imported_names`)."""
+ stmts = span_statements(analysis.fn_node, extraction.start_line, extraction.end_line, lmap)
+ if not stmts:
+ return None
+ words = _anchored_words(stmts, lmap)
+ own = Ownership(
+ owned=owned_names(stmts, lmap),
+ declared=declared_names(analysis.fn_node, analysis.def_use, lmap),
+ modules=modules,
+ )
+ effects = extraction.needs_async or has_outside_effects(stmts, own, lmap)
+ if words and not (effects and words[0] in _VALUE_VERBS):
+ return join_identifier(words, _convention(language))
+ return None if effects else out_value_name(analysis, extraction, language)
+
+
+def _anchored_words(stmts: list[Any], lmap: LanguageNodeMap) -> list[str]:
+ """The words of the label or banner naming the span, ``[]`` without one.
+
+ The span may be the whole body of ``with timed(...)``; else the label or
+ banner heads its first statement. A label or banner names only its own
+ section, so one heading a later top-level statement means the span runs
+ across sections, and neither names it.
+ """
+ wrapper = enclosing_with(stmts, lmap)
+ if wrapper is not None and (label := _label(wrapper)):
+ return label
+ heads = [_label(stmt) or banner_words(comment) for stmt, comment in section_heads(stmts)]
+ # A later head means a second section starts inside the span.
+ return heads[0] if heads and not any(heads[1:]) else []
+
+
+def _label(stmt: Any) -> list[str]:
+ return label_words((stmt.text or b"").decode("utf-8", "replace"))
+
+
+def _convention(language: str | None) -> str:
+ return NAME_CONVENTION.get(language or "", _SNAKE_CASE)
+
+
+def _key(name: str) -> str:
+ """Names collide regardless of a leading underscore or case: ``_compute_x``
+ takes ``compute_x``, Go's ``ComputeX`` takes ``computeX``."""
+ return name.lstrip("_").casefold()
+
+
+class ScopeNames:
+ """The names already taken where each helper lands, so a suggested name
+ never shadows a sibling or another plan's helper.
+
+ A helper lands where its host function sits: a method's class, a nested
+ function's enclosing function, else the module. Taken there: the functions
+ defined in it, the names it assigns, and at module level its imports; plus
+ the host's own parameters and locals, which the helper's call sits among.
+ A colliding name is dropped rather than suffixed (``compute_total_2`` says
+ nothing the reader can use), and the first plan in source order keeps it.
+ Go's package scope spans files; only this file's names are seen.
+
+ Names come from the tree, not ingestion symbols: ``RefactoringContext``
+ carries no per-file symbol list, and the tree is already parsed.
+ """
+
+ def __init__(self, lmap: LanguageNodeMap) -> None:
+ self._lmap = lmap
+ self._taken: dict[int, set[str]] = {}
+ self._imports: dict[int, frozenset[str]] = {}
+
+ def imports(self, fn_node: Any) -> frozenset[str]:
+ if fn_node is None:
+ return frozenset()
+ root = _root_of(fn_node)
+ if root.id not in self._imports:
+ self._imports[root.id] = imported_names(root)
+ return self._imports[root.id]
+
+ def claim(self, analysis: FunctionAnalysis, name: str | None) -> str | None:
+ fn_node = analysis.fn_node
+ if name is None or fn_node is None:
+ return name
+ scope = _enclosing_scope(fn_node, self._lmap)
+ taken = self._taken.get(scope.id)
+ if taken is None:
+ taken = self._taken[scope.id] = self._scope_names(scope)
+ key = _key(name)
+ if key in taken or key in {_key(d.var) for d in analysis.def_use.definitions}:
+ return None
+ taken.add(key)
+ return name
+
+ def _scope_names(self, scope: Any) -> set[str]:
+ names = {_key(n) for n in _defined_names(scope, self._lmap)}
+ if scope.parent is None:
+ names |= {_key(n) for n in self.imports(scope)}
+ return names
+
+
+def _root_of(node: Any) -> Any:
+ while node.parent is not None:
+ node = node.parent
+ return node
+
+
+def _enclosing_scope(fn_node: Any, lmap: LanguageNodeMap) -> Any:
+ holders = lmap.class_kinds | lmap.function_kinds | lmap.lambda_kinds
+ node = fn_node.parent
+ while node is not None and node.parent is not None and node.type not in holders:
+ node = node.parent
+ return node if node is not None else fn_node
+
+
+def _defined_names(scope: Any, lmap: LanguageNodeMap) -> set[str]:
+ """Functions defined and names assigned directly in *scope* (not in nested
+ functions or classes)."""
+ fn_kinds = lmap.function_kinds | lmap.lambda_kinds
+ stop = fn_kinds | lmap.class_kinds
+ names: set[str] = set()
+ stack = [(child, 1) for child in scope.children]
+ while stack:
+ node, depth = stack.pop()
+ if node.type in fn_kinds:
+ names.add(_find_function_entry_name(node, lmap))
+ continue
+ target = binding_target(node, lmap)
+ if target is not None:
+ names.update(bound_names(target))
+ if node.type in stop or depth >= _SIBLING_DEPTH:
+ continue
+ stack.extend((child, depth + 1) for child in node.children)
+ return names
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
index 575d0f9c0..837155c15 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/models.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
@@ -48,10 +48,11 @@ For Extract Method:
- ``plan`` = ``{"span": {"start": int, "end": int}, "params": [str, ...],
"returns": [str, ...], "suggested_name": str | None, "needs_async": bool}``
— the lines to lift, the inferred signature, a deterministic starting name
- (from the slice's single informative OUT value, else absent; an editable
- starting point, not unique within a file), and whether the span awaits, so
- the helper is async and its call awaited. An awaiting plan adds
- ``"async_host": bool``, False when the enclosing function is not async.
+ (a stage label, a banner comment, or the single OUT value of an effect-free
+ span; never one already taken in the helper's scope; else absent), and
+ whether the span awaits, so the helper is async and its call awaited. An
+ awaiting plan adds ``"async_host": bool``, False when the enclosing function
+ is not async.
- ``evidence`` = ``{"slice_nloc": int, "ccn_removed": int}`` — the size and
complexity (code lines, decision points) the residual method sheds.
- ``blast_radius`` = ``{"scope": "local"}`` — the one type whose blast radius is
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/naming.py b/packages/core/src/repowise/core/analysis/health/refactoring/naming.py
index 900ec5257..9a99942c8 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/naming.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/naming.py
@@ -8,13 +8,38 @@ wrote it, which is the defect this module exists to not repeat.
Precision-first, and the same posture in both detectors: without semantics we
cannot name a block for what it *does*, so a name is anchored to something the
-plan already knows for certain (where the helper lands, or the value it
-produces) and never guesses intent. It is an editable starting point, which is
+plan already knows for certain (where the helper lands, the value it produces,
+or the name its author already wrote over it: a banner comment, a stage label)
+and never guesses intent. It is an editable starting point, which is
how every surface frames it, not a claim about behaviour.
"""
from __future__ import annotations
+import re
+
+# A section banner names its block in a few words; a longer comment is an
+# explanation, and a name built from it is a sentence.
+_MAX_BANNER_WORDS = 5
+_COMMENT_MARK = re.compile(r"^\s*(?:#+|//+|/\*+|\*+)|\*+/\s*$")
+# Rules and separators drawn around a banner: ``# ---- Graph metrics ----``.
+_RULE_CHARS = " \t-=~#*_+.─━═"
+_ENUMERATION = re.compile(r"^(?:\d+[.)]|\[\d+\]|(?:step|pass)\s+\d+\s*[:.)])\s*", re.IGNORECASE)
+_PARENTHETICAL = re.compile(r"\([^)]*\)")
+# Editor folding markers around a section: ``# region Load edges``,
+# ``// #endregion``, ``// <editor-fold desc="Load edges">``.
+_FOLD = re.compile(r'^(?:(?:end)?region\b|</?editor-fold(?:[^>]*desc="([^"]*)")?[^>]*>)\s*', re.I)
+_BANNER_WORD = re.compile(r"[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*")
+# Comments that talk to a tool or a reviewer, not about the code below them.
+_DIRECTIVES = frozenset(
+ {"todo", "fixme", "xxx", "hack", "note", "noqa", "nosec", "pragma"}
+ | {"eslint", "prettier", "istanbul", "c8", "biome", "nolint", "noinspection", "jshint"}
+)
+_ARTICLES = frozenset({"a", "an", "the"})
+# ``with timed(timings, "persist.pages"):`` -- the stage label the timing
+# helper already records for the block it opens.
+_TIMED_LABEL = re.compile(r"\btimed\(\s*[^,()]+,\s*[\"']([A-Za-z_][\w.]*)[\"']")
+
def identifier_slug(label: str | None) -> str:
"""*label* reduced to a lowercase identifier-safe slug, or ``""``.
@@ -89,3 +114,39 @@ def join_identifier(words: list[str], convention: str) -> str:
head, *rest = words
return head + "".join(w.capitalize() for w in rest)
return "_".join(words)
+
+
+def banner_words(comment_lines: list[str]) -> list[str]:
+ """The words of a section banner, or ``[]`` when the comment is not one.
+
+ A banner is one line of short prose, optionally drawn between rules
+ (``# ==== / # Environment / # ====`` or ``# -- Load edges --``), with a
+ leading step number and any editor folding marker (``# region``) dropped. Two to ``_MAX_BANNER_WORDS`` plain words: one
+ word is a heading (``# Decisions``), not a name for what the block does,
+ and anything holding code, paths or punctuation (``# key -> value``) is
+ prose about the code rather than its name.
+ """
+ content = []
+ for line in comment_lines:
+ text = _COMMENT_MARK.sub("", line).strip(_RULE_CHARS)
+ text = _FOLD.sub(lambda m: m.group(1) or "", text).strip(_RULE_CHARS)
+ if text:
+ content.append(text)
+ if len(content) != 1:
+ return []
+ text = _ENUMERATION.sub("", _PARENTHETICAL.sub("", content[0]).strip())
+ tokens = text.strip().rstrip(".:").split()
+ if not 2 <= len(tokens) <= _MAX_BANNER_WORDS:
+ return []
+ if not all(_BANNER_WORD.fullmatch(t) for t in tokens):
+ return []
+ if tokens[0].lower().split("-")[0] in _DIRECTIVES:
+ return []
+ return [w for t in tokens for w in split_words(t) if w not in _ARTICLES]
+
+
+def label_words(statement_text: str) -> list[str]:
+ """The words of a ``timed(..., "label")`` stage label opening a statement."""
+ first_line = statement_text.split("\n", 1)[0]
+ match = _TIMED_LABEL.search(first_line)
+ return split_words(match.group(1)) if match else []
diff --git a/tests/unit/health/test_refactoring_extract_method.py b/tests/unit/health/test_refactoring_extract_method.py
index 0451b0f6c..ab7287425 100644
--- a/tests/unit/health/test_refactoring_extract_method.py
+++ b/tests/unit/health/test_refactoring_extract_method.py
@@ -158,18 +158,18 @@ def _find_extractions_reference(analysis, lmap):
_MIN_SLICE_NLOC,
_MIN_STMTS,
Extraction,
- _all_blocks,
_declared_before_read,
_exit_macros,
_function_lines,
_infer_in_out,
- _loop_carry_free,
- _outs_definitely_assigned,
+ _loop_carry_free,
+ _outs_definitely_assigned,
_sorted,
_span_metrics,
_stmts_nloc,
_unwrap_container,
_var_lines,
+ all_blocks,
)
fn_node = analysis.fn_node
@@ -206,7 +206,7 @@ def _find_extractions_reference(analysis, lmap):
out = []
evaluated = 0
- for block, loop in _all_blocks(fn_node, lmap.block_kinds, scope_kinds, lmap.loop_kinds):
+ for block, loop in all_blocks(fn_node, lmap.block_kinds, scope_kinds, lmap.loop_kinds):
stmts = block.named_children
n = len(stmts)
is_body = block.id == body_container.id
diff --git a/tests/unit/health/test_refactoring_extract_method_naming.py b/tests/unit/health/test_refactoring_extract_method_naming.py
new file mode 100644
index 000000000..23cf577b7
--- /dev/null
+++ b/tests/unit/health/test_refactoring_extract_method_naming.py
@@ -0,0 +1,611 @@
+"""Where an Extract Method helper's ``suggested_name`` comes from, and when it
+has none: a ``timed()`` stage label, a banner comment, or ``compute_<out>`` for
+an effect-free span, never a name a sibling in the helper's scope already uses.
+"""
+
+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.refactoring.extract_method import ExtractMethodDetector
+from repowise.core.analysis.health.refactoring.helper_naming import helper_name
+from repowise.core.analysis.health.refactoring.models import RefactoringContext
+
+
+@dataclass
+class _Finding:
+ biomarker_type: str
+ function_name: str
+ line_start: int
+ health_impact: float
+
+
+def _functions(language: str, ext: str, src: str):
+ 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 _names(src: str, language: str = "python", ext: str = "py") -> list[tuple[str, str | None]]:
+ """``(function, suggested_name)`` per plan, every function flagged."""
+ fns = _functions(language, ext, src)
+ ctx = RefactoringContext(
+ file_path=f"m.{ext}",
+ language=language,
+ nloc=100,
+ findings=[_Finding("complex_method", f.name, f.start_line, 1.5) for f in fns],
+ function_analyses=fns,
+ )
+ plans = sorted(ExtractMethodDetector().detect(ctx), key=lambda s: s.line_start or 0)
+ return [(s.target_symbol, s.plan["suggested_name"]) for s in plans]
+
+
+def _name(src: str, language: str = "python", ext: str = "py") -> str | None:
+ (only,) = _names(src, language, ext)
+ return only[1]
+
+
+# The span the detector lifts is the threshold loop through ``average``; the
+# ``{head}`` and ``{effect}`` slots put a comment above it and a statement in it.
+_PY = """
+def process(records, threshold):
+ results = []
+ errors = 0
+ for r in records:
+ if r is None:
+ errors += 1
+ continue
+ results.append(r)
+{head} total = 0
+ count = 0
+ for v in results:
+ if v > threshold:
+ total += v
+ count += 1
+{effect} else:
+ total -= v
+ average = total / count if count else 0
+ return average, errors
+"""
+
+
+def _py(head: str = "", effect: str = "") -> str:
+ return _PY.format(head=head, effect=effect)
+
+
+# -- sources in order -------------------------------------------------------------
+
+
+def test_without_a_banner_the_single_out_value_names_an_effect_free_span():
+ assert _name(_py()) == "compute_average"
+
+
+def test_a_banner_comment_above_the_span_names_the_helper():
+ assert _name(_py(head=" # Sum values above threshold\n")) == "sum_values_above_threshold"
+
+
+ "head",
+ [
+ " # ---- Sum values ----\n",
+ " # ===========\n # Sum values\n # ===========\n",
+ " # 2. Sum values\n",
+ " # Sum values (above the bar).\n",
+ " # region Sum values\n",
+ ' # <editor-fold desc="Sum values">\n',
+ ],
+)
+def test_rules_numbering_and_asides_around_a_banner_are_dropped(head):
+ assert _name(_py(head=head)) == "sum_values"
+
+
+ "head",
+ [
+ # Prose, not a name: too long, two lines, code in it, a tool directive,
+ # a one-word heading.
+ " # Sum every value that clears the threshold and count them here\n",
+ " # Sum values above\n # the threshold.\n",
+ " # total -> sum of values\n",
+ " # TODO sum values\n",
+ " # Totals\n",
+ " # endregion\n",
+ # Not touching the statement: it heads something else.
+ " # Sum values above threshold\n\n",
+ ],
+)
+def test_a_comment_that_is_not_a_banner_leaves_the_out_value_name(head):
+ assert _name(_py(head=head)) == "compute_average"
+
+
+def test_a_trailing_comment_on_the_line_above_is_not_a_banner():
+ src = _py().replace(" total = 0\n", " errors = errors # Sum values\n total = 0\n")
+ assert _name(src) != "sum_values"
+
+
+def test_a_banner_over_a_nested_statement_neither_names_nor_splits_the_span():
+ src = _py(head=" # Sum values\n").replace(
+ " total += v\n", " # Add it up\n total += v\n"
+ )
+ assert _name(src) == "sum_values"
+ inner_only = _py().replace(
+ " total += v\n", " # Add it up\n total += v\n"
+ )
+ assert _name(inner_only) == "compute_average"
+
+
+def test_a_span_holding_a_second_banner_takes_neither():
+ src = _py(head=" # Sum values\n").replace(
+ " average = total", " # Average them\n average = total"
+ )
+ assert _name(src) == "compute_average"
+
+
+def test_a_timed_stage_label_names_the_helper():
+ src = """
+ def persist(session, pages, timings, flags):
+ written = 0
+ for p in pages:
+ if p is None:
+ continue
+ written += 1
+ with timed(timings, "persist.pages"):
+ for page in pages:
+ if page.stale:
+ session.delete(page)
+ elif page.new:
+ session.add(page)
+ else:
+ session.merge(page)
+ if flags:
+ session.flush()
+ return written
+ """
+ assert _name(src) == "persist_pages"
+
+
+# -- no compute_ for a span with effects ----------------------------------------
+
+
+ "effect",
+ [
+ " print(v)\n", # I/O
+ " records.append(v)\n", # mutates a parameter
+ " threshold.seen = v\n", # writes through a parameter
+ " sink[v] = count\n", # writes into a name the span does not bind
+ # A local bound from a call may be an outside object.
+ " log = get_logger()\n log.info(v)\n",
+ " f = open(v)\n f.write(v)\n",
+ " cur = conn.cursor()\n rows = cur.execute(v)\n",
+ # Mutation in expression position, on a name the span does not own.
+ " last = records.pop()\n",
+ " item = queue.get()\n",
+ " seen = cache.setdefault(v, [])\n",
+ " del records[0]\n",
+ ],
+)
+def test_a_span_with_outside_effects_is_not_named_compute(effect):
+ assert _name(_py(effect=effect)) is None
+
+
+ "effect",
+ [
+ " label = names.get(v)\n", # a keyed read
+ " key = str(v).strip().lower()\n", # string reads
+ " path = os.path.join(v, v)\n", # a module function
+ " local = {}\n local[v] = 1\n del local[v]\n", # its own dict
+ ],
+)
+def test_reads_and_writes_to_what_the_span_owns_keep_the_name(effect):
+ assert _name("import os\n" + _py(effect=effect)) == "compute_average"
+
+
[email protected]("verb", ["Compute", "Build", "Get", "Calculate"])
+def test_a_banner_promising_a_value_does_not_name_a_span_with_effects(verb):
+ src = _py(head=f" # {verb} the totals\n", effect=" print(v)\n")
+ assert _name(src) is None
+
+
+def test_a_banner_still_names_a_span_with_effects():
+ src = _py(head=" # Report the totals\n", effect=" print(v)\n")
+ assert _name(src) == "report_totals"
+
+
+def test_mutating_a_list_the_span_built_is_not_an_effect():
+ src = (
+ _py()
+ .replace(" count = 0\n", " count = 0\n kept = []\n")
+ .replace(" count += 1\n", " count += 1\n kept.append(v)\n")
+ )
+ assert _name(src) == "compute_average"
+
+
+def test_writing_through_self_is_an_effect():
+ src = """
+ class Stats:
+ def process(self, records, threshold):
+ results = []
+ for r in records:
+ if r is None:
+ continue
+ results.append(r)
+ total = 0
+ count = 0
+ for v in results:
+ if v > threshold:
+ total += v
+ self.count = count
+ else:
+ total -= v
+ average = total / count if count else 0
+ return average
+ """
+ assert _name(src) is None
+
+
+# -- collisions with the helper's scope ------------------------------------------
+
+
[email protected]("sibling", ["compute_average", "_compute_average"])
+def test_a_name_a_sibling_function_already_has_is_dropped(sibling):
+ src = _py() + f"\n\ndef {sibling}(values):\n return sum(values) / len(values)\n"
+ assert _names(src) == [("process", None)]
+
+
+def test_two_plans_in_one_scope_do_not_share_a_name():
+ second = textwrap.dedent(_py()).replace("def process(", "def process_again(")
+ assert _names(_py() + "\n" + second) == [
+ ("process", "compute_average"),
+ ("process_again", None),
+ ]
+
+
+def test_a_method_does_not_collide_with_a_module_function():
+ method = textwrap.indent(textwrap.dedent(_py()).replace("(records,", "(self, records,"), " ")
+ src = "def compute_average(values):\n return 0\n\n\nclass Stats:\n" + method
+ assert _names(src) == [("process", "compute_average")]
+
+
+ "prefix",
+ [
+ "compute_average = None\n\n", # a module-level assignment
+ "from stats import compute_average\n\n", # an import
+ "from stats import mean as compute_average\n\n",
+ ],
+)
+def test_module_assignments_and_imports_take_the_name(prefix):
+ assert _names(prefix + _py()) == [("process", None)]
+
+
+def test_the_host_functions_own_parameters_and_locals_take_the_name():
+ src = _py().replace("(records, threshold)", "(records, threshold, compute_average=None)")
+ assert _names(src) == [("process", None)]
+
+
+# -- casing --------------------------------------------------------------------
+
+
+_TS = """
+function process(records: number[], threshold: number): number {
+ const results: number[] = [];
+ let errors = 0;
+ for (const r of records) {
+ if (r < 0) {
+ errors += 1;
+ continue;
+ }
+ results.push(r);
+ }
+ // Sum values above threshold
+ let total = 0;
+ let count = 0;
+ for (const v of results) {
+ if (v > threshold) {
+ total += v;
+ count += 1;
+ } else {
+ total -= v;
+ }
+ }
+ let average = 0;
+ if (count > 0) {
+ average = total / count;
+ }
+ return average + errors;
+}
+"""
+
+
+def test_a_banner_name_follows_the_files_casing():
+ assert _name(_TS, "typescript", "ts") == "sumValuesAboveThreshold"
+
+
+def test_the_out_value_name_keeps_the_files_casing():
+ assert _name(_TS.replace(" // Sum values above threshold\n", ""), "typescript", "ts") == (
+ "computeAverage"
+ )
+
+
+# -- the dogfood shapes ----------------------------------------------------------
+
+
+def _span_name(language, ext, src, start, end, params, returns, *, needs_async=False):
+ (fn,) = _functions(language, ext, src)
+ first = fn.start_line - 1
+ extraction = Extraction(
+ first + start, first + end, tuple(params), tuple(returns), 8, 2, needs_async
+ )
+ return helper_name(fn, extraction, get_language_map(language), language)
+
+
+def test_status_header_span_is_not_compute_deep():
+ # hermes_cli/status.py:133: reads a flag, then prints the header.
+ src = """
+ def show_status(args):
+ deep = getattr(args, 'deep', False)
+ print()
+ print(color("Hermes Agent Status", Colors.CYAN))
+ line = _estop_status_line()
+ if line:
+ print()
+ print(color(line, Colors.YELLOW))
+ if deep and line:
+ print("deep")
+ return deep
+ """
+ assert _span_name("python", "py", src, 2, 10, ["args"], ["deep"]) is None
+
+
+def test_run_main_span_is_not_compute_is_gateway_run_invocation():
+ # openclaw src/cli/run-main.ts:640: marks a trace and asserts the runtime.
+ src = """
+ async function runCli(argv: string[], startupTrace: Trace) {
+ const normalizedArgv = normalize(argv);
+ const isGatewayRunInvocation = isGatewayRunInvocationArgv(normalizedArgv);
+ startupTrace.mark("argv");
+ assertSupportedRuntime();
+ if (isGatewayRunInvocation || shouldLoad()) {
+ loadCliDotEnv({ quiet: true });
+ }
+ return isGatewayRunInvocation;
+ }
+ """
+ params, returns = ["normalizedArgv", "startupTrace"], ["isGatewayRunInvocation"]
+ name = _span_name("typescript", "ts", src, 3, 8, params, returns)
+ assert name is None
+
+
+def test_gateway_child_span_is_not_compute_message():
+ # openclaw extensions/qa-lab/src/gateway-child.ts:1119: closes streams.
+ src = """
+ async function startQaGatewayChild(stdoutLog: Stream, keepTemp: boolean, error: unknown) {
+ await closeWriteStream(stdoutLog);
+ if (!keepTemp) {
+ await cleanupQaGatewayTempRoots({ stdoutLog });
+ }
+ const message = keepTemp ? appendRoot(format(error)) : format(error);
+ return message;
+ }
+ """
+ params = ["stdoutLog", "keepTemp", "error"]
+ name = _span_name("typescript", "ts", src, 2, 6, params, ["message"], needs_async=True)
+ assert name is None
+
+
+def test_order_by_span_keeps_compute_order_by_sql():
+ # hermes hermes_state_search.py:1769: pure, one product.
+ src = """
+ def _search(sort):
+ if isinstance(sort, str):
+ sort_norm = sort.strip().lower()
+ if sort_norm not in ("newest", "oldest"):
+ sort_norm = None
+ else:
+ sort_norm = None
+ if sort_norm == "newest":
+ order_by_sql = "ORDER BY m.timestamp DESC, rank"
+ elif sort_norm == "oldest":
+ order_by_sql = "ORDER BY m.timestamp ASC, rank"
+ else:
+ order_by_sql = "ORDER BY rank"
+ return order_by_sql
+ """
+ assert _span_name("python", "py", src, 2, 13, ["sort"], ["order_by_sql"]) == (
+ "compute_order_by_sql"
+ )
+
+
+# -- other grammars --------------------------------------------------------------
+
+
+_GO = """
+package main
+
+func process(records []int, threshold int) int {
+ errors := 0
+ results := []int{}
+ for _, r := range records {
+ if r < 0 {
+ errors++
+ continue
+ }
+ results = append(results, r)
+ }
+ // Sum values above threshold
+ total := 0
+ count := 0
+ for _, v := range results {
+ if v > threshold {
+ total += v
+ count++
+ } else {
+ total -= v
+ }
+ }
+ average := 0
+ if count > 0 {
+ average = total / count
+ }
+ return average + errors
+}
+"""
+
+_RUST = """
+fn process(records: &[i32], threshold: i32) -> i32 {
+ let mut errors = 0;
+ let mut results: Vec<i32> = Vec::new();
+ for r in records {
+ if *r < 0 {
+ errors += 1;
+ continue;
+ }
+ results.push(*r);
+ }
+ // Sum values above threshold
+ let mut total = 0;
+ let mut count = 0;
+ for v in &results {
+ if *v > threshold {
+ total += v;
+ count += 1;
+ } else {
+ total -= v;
+ }
+ }
+ let mut average = 0;
+ if count > 0 {
+ average = total / count;
+ }
+ average + errors
+}
+"""
+
+
+def test_go_and_rust_banner_names_keep_their_casing():
+ assert _name(_GO, "go", "go") == "sumValuesAboveThreshold"
+ assert _name(_RUST, "rust", "rs") == "sum_values_above_threshold"
+
+
+def test_go_exported_and_unexported_spellings_collide():
+ src = _GO.replace(" // Sum values above threshold\n", "") + (
+ "\nfunc ComputeAverage(xs []int) int {\n return 0\n}\n"
+ )
+ assert _names(src, "go", "go") == [("process", None)]
+
+
+def test_a_one_line_jsdoc_is_a_banner_and_a_block_one_is_not():
+ one_line = _TS.replace("// Sum values above threshold", "/** Sum values above threshold */")
+ assert _name(one_line, "typescript", "ts") == "sumValuesAboveThreshold"
+ block = _TS.replace(
+ " // Sum values above threshold\n",
+ " /**\n * Sum values above threshold\n * @returns the mean\n */\n",
+ )
+ assert _name(block, "typescript", "ts") == "computeAverage"
+
+
+def test_a_ts_region_marker_is_dropped():
+ src = _TS.replace("// Sum values above threshold", "// #region Sum values")
+ assert _name(src, "typescript", "ts") == "sumValues"
+
+
+_TS_EFFECT = """
+let seen = 0;
+function process(values: number[], cache: Record<string, number>): number {
+ const out = [];
+ let total = 0;
+ for (const v of values) {
+ if (v > 0) {
+ total += v;
+ EFFECT
+ }
+ }
+ return total;
+}
+"""
+
+
+ ("effect", "acts"),
+ [
+ ("delete cache.k;", True), # deletes through a parameter
+ ("seen++;", True), # bumps a captured module variable
+ ("--seen;", True),
+ ("out.push(v);", False), # its own array
+ ("total++;", False), # a declared local
+ ],
+)
+def test_ts_deletes_and_captured_updates_are_effects(effect, acts):
+ src = _TS_EFFECT.replace("EFFECT", effect)
+ name = _span_name("typescript", "ts", src, 2, 9, ["values"], ["total"])
+ assert (name is None) is acts
+
+
+_GO_EFFECT = """
+package main
+
+var hits = 0
+
+func process(values []int, ch chan int, out *int) int {
+ total := 0
+ for _, v := range values {
+ if v > 0 {
+ total += v
+ EFFECT
+ }
+ }
+ return total
+}
+"""
+
+
+ ("effect", "acts"),
+ [("ch <- v", True), ("hits++", True), ("*out = v", True), ("total++", False)],
+)
+def test_go_sends_captured_increments_and_pointer_writes_are_effects(effect, acts):
+ src = _GO_EFFECT.replace("EFFECT", effect)
+ name = _span_name("go", "go", src, 2, 8, ["values", "ch", "out"], ["total"])
+ assert (name is None) is acts
+
+
+_RUST_EFFECT = """
+fn process(values: &[i32], out: &mut i32, c: &mut i32) -> i32 {
+ let mut total = 0;
+ let mut own = Vec::new();
+ for v in values {
+ if *v > 0 {
+ total += v;
+ EFFECT
+ }
+ }
+ total
+}
+"""
+
+
+ ("effect", "acts"),
+ [
+ ("*out = *v;", True),
+ ("*c += 1;", True),
+ ("bump(&mut total, c);", True),
+ ("own.push(*v);", False),
+ ],
+)
+def test_rust_deref_writes_and_mut_borrows_are_effects(effect, acts):
+ src = _RUST_EFFECT.replace("EFFECT", effect)
+ name = _span_name("rust", "rs", src, 2, 10, ["values", "out", "c"], ["total"])
+ assert (name is None) is acts
diff --git a/tests/unit/health/test_refactoring_naming.py b/tests/unit/health/test_refactoring_naming.py
index 98ea68bb7..2cb8864b6 100644
--- a/tests/unit/health/test_refactoring_naming.py
+++ b/tests/unit/health/test_refactoring_naming.py
@@ -7,8 +7,10 @@ one thing per detector.
from __future__ import annotations
from repowise.core.analysis.health.refactoring.naming import (
+ banner_words,
identifier_slug,
join_identifier,
+ label_words,
split_words,
)
@@ -103,3 +105,39 @@ def test_join_identifier_uses_the_first_word_as_lowercase_head():
def test_join_identifier_of_no_words_is_empty():
assert join_identifier([], "camelCase") == ""
assert join_identifier([], "snake_case") == ""
+
+
+# -- banner comments and stage labels ---------------------------------------------
+
+
+def test_banner_words_reads_one_short_line_between_rules():
+ assert banner_words(["# Build table"]) == ["build", "table"]
+ assert banner_words(["// Group by consumer repo"]) == ["group", "by", "consumer", "repo"]
+ assert banner_words(["# ---- Graph metrics ----------"]) == ["graph", "metrics"]
+ assert banner_words(["# ── Core runtime state ──"]) == ["core", "runtime", "state"]
+ assert banner_words(["# =====", "# Load edges", "# ====="]) == ["load", "edges"]
+ assert banner_words(["/* Load edges */"]) == ["load", "edges"]
+ # Step numbers, asides and articles are not part of the name.
+ assert banner_words(["# 3. Remove the wrapper script"]) == ["remove", "wrapper", "script"]
+ assert banner_words(["# Step 1: Parse git logs"]) == ["parse", "git", "logs"]
+ assert banner_words(["# Neighboring communities (cap at 5)"]) == ["neighboring", "communities"]
+
+
+def test_banner_words_refuses_prose_code_and_directives():
+ assert banner_words([]) == []
+ assert banner_words(["# Decisions"]) == [] # a heading, not a name
+ assert banner_words(["# Lazy import to avoid circular dependency at load"]) == []
+ assert banner_words(["# Sum values", "# then count them"]) == []
+ assert banner_words(["# Build labels and map indices -> skill names"]) == []
+ assert banner_words(["# Check for image/picture"]) == []
+ assert banner_words(["# [3] get_running_pid()"]) == []
+ assert banner_words(["# Kimi: top-level reasoning effort"]) == []
+ assert banner_words(["// eslint-disable-next-line no-await-in-loop"]) == []
+ assert banner_words(["# TODO tidy this up"]) == []
+
+
+def test_label_words_reads_a_timed_stage_label():
+ assert label_words('with timed(timings, "persist.pages"):') == ["persist", "pages"]
+ assert label_words("with timed(self._t, 'detect_changes'):\n x = 1") == ["detect", "changes"]
+ assert label_words('with span("persist.pages"):') == []
+ assert label_words("x = timed") == []