Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(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.mdindex 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; forExtract Method that is `ccn_removed / ccn`, `slice_nloc / nloc`, or the larger ofthe 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 stablekernel. Bumping the version re-mints ids; a held id from an older version reportsdiff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.mdindex 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 nothingin the code anchors one. A Split File or Extract Class plan with an unnamed groupis held as `needs_design`, like a cycle: it is not a step and never reaches Fixfirst. 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 meanthe code needs no attention: check the findings in@@ -180,8 +183,8 @@ Most plans answer a health finding, so per-path marker rules ingenerated 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 theoriginal finding into the helper. A component whose branching is mostly in itsmarkup 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.pynew file mode 100644index 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.pyindex 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_childrenn = 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.pynew file mode 100644index 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.typediff --git a/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.py b/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.pyindex 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 callis awaited. An awaiting plan also carries ``async_host``: False when theenclosing function is not declared async, which makes the step a judgment@@ -79,8 +80,8 @@ from ..dataflow import find_extractionsfrom ..effort import effort_bucketfrom ..perf.dialects import PERF_DIALECTSfrom ..scoring import severity_deduction+from .helper_naming import ScopeNames, helper_name, out_value_namefrom .models import RefactoringContext, RefactoringSuggestion-from .naming import join_identifier, split_wordsfrom .registry import RefactoringDetector, registerif TYPE_CHECKING:@@ -88,30 +89,6 @@ if TYPE_CHECKING:from ..dataflow import Extraction, FunctionAnalysisfrom ..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)@staticmethoddef _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.pynew file mode 100644index 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 namesdiff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.pyindex 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 andcomplexity (code lines, decision points) the residual method sheds.- ``blast_radius`` = ``{"scope": "local"}`` — the one type whose blast radius isdiff --git a/packages/core/src/repowise/core/analysis/health/refactoring/naming.py b/packages/core/src/repowise/core/analysis/health/refactoring/naming.pyindex 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 wecannot 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 ishow 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 = wordsreturn 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.pyindex 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_childrenn = len(stmts)is_body = block.id == body_container.iddiff --git a/tests/unit/health/test_refactoring_extract_method_naming.py b/tests/unit/health/test_refactoring_extract_method_naming.pynew file mode 100644index 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 actsdiff --git a/tests/unit/health/test_refactoring_naming.py b/tests/unit/health/test_refactoring_naming.pyindex 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 annotationsfrom 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") == []