Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(refactoring): read-only guards for flat builders, never run out of helper names (#3427)
Raghav Chamadiya29d25ec85681
diff --git a/packages/core/src/repowise/core/analysis/health/dataflow/effects.py b/packages/core/src/repowise/core/analysis/health/dataflow/effects.pyindex e2523417e..63dc12585 100644--- a/packages/core/src/repowise/core/analysis/health/dataflow/effects.py+++ b/packages/core/src/repowise/core/analysis/health/dataflow/effects.py@@ -348,14 +348,15 @@ def declared_names(return frozenset(names)-def imported_names(root: Node) -> frozenset[str]:- """Names a file's top-level imports bring in, plus built-in namespaces.+def imported_names(root: Node, *, namespaces: bool = True) -> frozenset[str]:+ """Names a file's top-level imports bring in, plus built-in namespaces+ unless *namespaces* is False.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)+ names = set(_BUILTIN_NAMESPACES) if namespaces else set()for node in root.named_children:if "import" not in node.type and node.type != "use_declaration":continuediff --git a/packages/core/src/repowise/core/analysis/health/refactoring/declarative.py b/packages/core/src/repowise/core/analysis/health/refactoring/declarative.pyindex 7859a79d0..4c2c21d6e 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/declarative.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/declarative.py@@ -9,23 +9,25 @@ of the list without making either half simpler to read.The shape, read off the tree in any language the slicer serves: everystatement writes the same one name (``x.f = v`` / ``x[k] = v``, ``delete x.f``,or a call on a parameter or local, ``rows.append(...)``) or binds a local once,-and the only control flow is a guard around such statements (an ``if`` chain,-a ``try``, a loop over rows) or a guard that returns. A second written name, a-call on a module or imported name (``print``, ``logger.info``, ``res.send``-on no local), a loop in a loop, a callback (whose body is logic the statement-only registers), a ``break`` / ``continue`` or a ``switch`` is logic, and the-function is not flat.+and the only control flow is a guard around such statements (an ``if`` chain+whose conditions only read, a ``try``, a loop over rows) or a guard that+returns. A second written name, a call on a module or imported name+(``print``, ``logger.info``, ``res.send`` on no local), a condition that calls+or writes (``if prepare():``), a loop in a loop, a callback (whose body is+logic the statement only registers), a ``break`` / ``continue`` or a+``switch`` is logic, and the function is not flat."""from __future__ import annotationsfrom dataclasses import dataclass, field-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Anyfrom ..complexity.ast_utils import _find_function_entry_namefrom ..complexity.nloc import is_string_stmt-from ..dataflow.effects import binding_target, bound_names+from ..dataflow.effects import binding_target, bound_names, imported_namesfrom ..dataflow.span import is_comment+from .helper_naming import defined_namesif TYPE_CHECKING:from collections.abc import Collection@@ -43,6 +45,33 @@ _ACCESS_FIELDS = ("object", "value", "operand", "argument", "array", "function")_CALLEE_FIELDS = ("function", "object")_CALL_KINDS = frozenset({"call", "call_expression", "method_invocation"})_NAME_TARGETS = frozenset({"identifier", "pattern_list", "tuple_pattern"})+# Calls a guard may make, only where nothing in the file rebinds the name:+# the language's own read-only builtins, and read-only methods of its global+# namespaces. A method on any other receiver is unresolved, so it is a step.+_BUILTIN_CALLS: dict[str, frozenset[str]] = {+ "python": frozenset({"len", "isinstance", "issubclass"}),+ **dict.fromkeys(("typescript", "tsx", "javascript", "jsx"), frozenset({"isFinite", "isNaN"})),+}+_NAMESPACE_CALLS = frozenset(+ {("Number", "isFinite"), ("Number", "isInteger"), ("Number", "isNaN"), ("Array", "isArray")}+)+# Read-only methods of a string or list literal: ``["a", "b"].includes(x)``.+_LITERAL_METHODS = frozenset({"includes", "startsWith", "endsWith", "startswith", "endswith"})+# Read-only methods by a parameter's declared type (``result: dict[str, Any]``,+# ``opts: { selector?: string }``): the one receiver whose type is written down.+_STR_READS = frozenset(+ {"strip", "lower", "upper", "isdigit", "trim", "toLowerCase", "toUpperCase"} | _LITERAL_METHODS+)+_TYPED_READS: dict[str, frozenset[str]] = {+ "str": _STR_READS,+ "string": _STR_READS,+ **dict.fromkeys(("dict", "Dict", "Mapping"), frozenset({"get", "keys", "values", "items"})),+}+# A write or a wait inside a condition: ``if (x := f())``, ``if (n++)``.+_WRITE_KINDS = frozenset(+ {"named_expression", "assignment_expression", "augmented_assignment_expression"}+ | {"update_expression", "await", "await_expression", "assignment"}+)# Fewer writes than this is a short function with a few guards, not a builder._MIN_WRITES = 3@@ -50,6 +79,11 @@ _MIN_WRITES = 3@dataclass(slots=True)class _Census:lmap: LanguageNodeMap+ language: str = ""+ params: frozenset[str] = frozenset()+ fn_node: Any = None+ file_names: frozenset[str] | set[str] | None = None+ param_types: dict[str, Any] | None = Noneroots: set[str] = field(default_factory=set)call_roots: set[str] = field(default_factory=set)writes: int = 0@@ -65,24 +99,34 @@ class _Census:def declarative_flat(- fn_node: Node | None, lmap: LanguageNodeMap, params: Collection[str] = ()+ fn_node: Node | None,+ lmap: LanguageNodeMap,+ params: Collection[str] = (),+ language: str | None = None,) -> bool:"""True when *fn_node*'s body is a flat record builder (module docstring).- *params* are its parameter names, the receivers a call may write through."""+ *params* are its parameter names, the receivers a call may write through;+ *language* names the builtins a guard may call."""body = fn_node.child_by_field_name("body") if fn_node is not None else Noneif body is None or body.type not in lmap.block_kinds:return False- census = _Census(lmap)+ census = _Census(lmap, language or "", frozenset(params), fn_node)stmts = _statements(body)if stmts and stmts[-1].type in lmap.return_kinds:stmts = stmts[:-1]if not all(_flat(s, census, top=True) for s in stmts):return Falsewrites = census.writes- owned = census.call_roots <= census.bound | set(params)+ owned = census.call_roots <= census.bound | census.paramsreturn owned and len(census.roots) == 1 and writes >= max(_MIN_WRITES, len(census.bound) + 1)+def _file_root(node: Node) -> Node:+ while node.parent is not None:+ node = node.parent+ return node++def _statements(block: Node) -> list[Node]:"""*block*'s statements, comments and a leading docstring left out."""out = [c for c in block.named_children if not is_comment(c)]@@ -142,12 +186,123 @@ def _flat_decl(stmt: Node, census: _Census) -> bool:def _flat_branches(stmt: Node, census: _Census) -> bool:- """Every arm of an ``if`` chain is flat, or only returns."""+ """Every arm of an ``if`` chain is flat, or only returns, behind a pure guard."""condition = stmt.child_by_field_name("condition")+ if condition is not None and not _pure_guard(condition, census):+ return Falsearms = [c for c in stmt.named_children if c != condition and not is_comment(c)]return all(_guard_exit(arm, census.lmap) or _flat(arm, census) for arm in arms)+def _pure_guard(condition: Node, census: _Census) -> bool:+ """Whether *condition* only reads: comparisons and truthiness of names,+ fields and keys, no write, and no call but a builtin read (``_BUILTIN_CALLS``+ and the rest). ``if prepare_record():``, ``if logger.enabled():`` and an+ ``obj.get()`` nobody can resolve are steps, not guards."""+ lmap = census.lmap+ stack = [condition]+ while stack:+ node = stack.pop()+ if node.type in _WRITE_KINDS or node.type in lmap.lambda_kinds:+ return False+ if node.type in lmap.call_kinds and not _builtin_read(node, census):+ return False+ stack.extend(node.named_children)+ return True+++def _builtin_read(call: Node, census: _Census) -> bool:+ if call.type == "method_invocation":+ # Java: the method is ``name``, ``object`` the receiver; none is resolved.+ return False+ callee = _field(call, _CALLEE_FIELDS)+ if callee is None:+ return False+ if callee.type == "identifier":+ name = _text(callee)+ return name in _BUILTIN_CALLS.get(census.language, ()) and not _rebound(name, census)+ receiver = _field(callee, ("object", "value", "operand"))+ method = _field(callee, ("attribute", "property", "field"))+ if receiver is None or method is None:+ return False+ if "string" in receiver.type or receiver.type in ("array", "list"):+ return _text(method) in _LITERAL_METHODS+ pair = (_text(receiver), _text(method))+ if pair in _NAMESPACE_CALLS and not _rebound(pair[0], census):+ return True+ return _text(method) in _TYPED_READS.get(_declared_type(receiver, census), ())+++def _declared_type(receiver: Node, census: _Census) -> str:+ """The declared type of a parameter (``result``) or of a field of a+ parameter's inline object type (``opts.selector``), as its head word."""+ if census.param_types is None:+ census.param_types = _param_types(census.fn_node)+ if receiver.type == "identifier":+ return _type_head(census.param_types.get(_text(receiver)))+ owner = _field(receiver, ("object",))+ prop = _field(receiver, ("property",))+ if owner is None or prop is None or owner.type != "identifier":+ return ""+ shape = _type_node(census.param_types.get(_text(owner)))+ if shape is None or shape.type != "object_type":+ return ""+ member = next(+ (+ c+ for c in shape.named_children+ if c.type == "property_signature" and _text(_field(c, ("name",))) == _text(prop)+ ),+ None,+ )+ return _type_head(member.child_by_field_name("type")) if member is not None else ""+++def _param_types(fn_node: Node) -> dict[str, Any]:+ params = fn_node.child_by_field_name("parameters")+ out: dict[str, Any] = {}+ for param in params.named_children if params is not None else ():+ name = _field(param, ("pattern", "name")) or next(+ (c for c in param.named_children if c.type == "identifier"), None+ )+ kind = param.child_by_field_name("type")+ if name is not None and kind is not None and name.type == "identifier":+ out[_text(name)] = kind+ return out+++def _type_node(kind: Node | None) -> Node | None:+ """A written type without its ``: `` / ``type`` wrapper."""+ while kind is not None and kind.type in ("type_annotation", "type") and kind.named_children:+ kind = kind.named_children[0]+ return kind+++def _type_head(kind: Node | None) -> str:+ """``dict`` for ``dict[str, Any]``, ``string`` for ``string``."""+ kind = _type_node(kind)+ if kind is not None and kind.type == "generic_type" and kind.named_children:+ kind = kind.named_children[0]+ return _text(kind) if kind is not None and not kind.named_children else ""+++def _rebound(name: str, census: _Census) -> bool:+ """Whether the function or its file binds *name* itself (a parameter, a+ local, an import or a top-level definition), hiding the builtin."""+ if name in census.params or name in census.bound:+ return True+ if census.file_names is None:+ root = _file_root(census.fn_node)+ # The file's own imports only: an imported ``Number`` is not the global.+ imports = imported_names(root, namespaces=False)+ census.file_names = imports | defined_names(root, census.lmap)+ return name in census.file_names+++def _text(node: Node | None) -> str:+ return (node.text or b"").decode("utf-8", "replace") if node is not None else ""++def _guard_exit(arm: Node, lmap: LanguageNodeMap) -> bool:exits = lmap.return_kinds | lmap.raise_kindsif arm.type in exits:diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.py b/packages/core/src/repowise/core/analysis/health/refactoring/extract_method.pyindex b414d7d7f..8144fcdd2 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@@ -189,7 +189,7 @@ class ExtractMethodDetector(RefactoringDetector):if jsx_plumbing_dominates(analysis.fn_node, lmap):continueif analysis.fn_node is not None and declarative_flat(- analysis.fn_node, lmap, {p.name for p in analysis.def_use.params}+ analysis.fn_node, lmap, {p.name for p in analysis.def_use.params}, ctx.language):_mark_refused(matched, "declarative_flat")continuediff --git a/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.py b/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.pyindex bab5ce294..f45e87ce3 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/helper_naming.py@@ -13,6 +13,7 @@ edit rather than a blank.from __future__ import annotations+import itertoolsfrom collections.abc import Iterable, Iteratorfrom typing import TYPE_CHECKING, Any@@ -148,8 +149,11 @@ def helper_names(rest = subject[_overlap(host, subject) :]if rest:yield join_identifier([*host, *rest], _convention(language))- # A span with no subject (it only logs, say) is still a block of the host.+ # A span with no subject (it only logs, say) is still a block of the host;+ # numbered when that is taken too, so every plan ends with a free name.yield join_identifier([*host, "block"], _convention(language))+ for n in itertools.count(2):+ yield join_identifier([*host, "block", str(n)], _convention(language))def _overlap(host: list[str], subject: list[str]) -> int:@@ -256,11 +260,11 @@ class ScopeNames:def claim_first(self, analysis: FunctionAnalysis, names: Iterable[str]) -> str | None:"""The first of *names* free in the helper's scope, claimed; ``None``- when every one is taken."""+ when every one is taken (:func:`helper_names` never runs out)."""return next((name for name in names if self.claim(analysis, name)), None)def _scope_names(self, scope: Any) -> set[str]:- names = {_key(n) for n in _defined_names(scope, self._lmap)}+ 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@@ -280,7 +284,7 @@ def _enclosing_scope(fn_node: Any, lmap: LanguageNodeMap) -> Any:return node if node is not None else fn_node-def _defined_names(scope: Any, lmap: LanguageNodeMap) -> set[str]:+def defined_names(scope: Any, lmap: LanguageNodeMap) -> set[str]:"""Functions defined and names assigned directly in *scope* (not in nestedfunctions or classes)."""fn_kinds = lmap.function_kinds | lmap.lambda_kindsdiff --git a/tests/unit/health/test_refactoring_declarative.py b/tests/unit/health/test_refactoring_declarative.pyindex 4736e0229..4fb089440 100644--- a/tests/unit/health/test_refactoring_declarative.py+++ b/tests/unit/health/test_refactoring_declarative.py@@ -39,12 +39,13 @@ def _functions(language: str, ext: str, src: str):def _flat(src: str, language: str = "python", ext: str = "py") -> bool:(fn,) = [f for f in _functions(language, ext, src) if f.name == "build"]- return declarative_flat(fn.fn_node, get_language_map(language))+ params = {p.name for p in fn.def_use.params}+ return declarative_flat(fn.fn_node, get_language_map(language), params, language)# The configuration-summary shape: rows added behind one guard each._SUMMARY = """-def build(result, patterns, allow_fast, generate_docs=True):+def build(result: dict[str, Any], patterns, allow_fast, generate_docs=True):\"\"\"The summary rows.\"\"\"summary = []@@ -78,7 +79,9 @@ def build(result, patterns, allow_fast, generate_docs=True):# Query parameters set when given, then one request._QUERY_TS = """-export async function build(opts: Opts): Promise<Result> {+export async function build(+ opts: { format?: string; limit?: number; selector?: string; labels?: boolean },+): Promise<Result> {const q = new URLSearchParams();if (opts.format) {q.set("format", opts.format);@@ -152,6 +155,50 @@ def test_logic_beside_the_writes_is_not_declarative(change):assert not _flat(_SUMMARY.replace(old, new, 1))+ "condition",+ [+ "prepare_record(result)", # a call made for what it does+ "logger.enabled()", # a call on an imported name+ '(cap := result.get("x"))', # a write in the condition+ ],+)+def test_a_guard_that_calls_or_writes_is_not_flat(condition):+ old = " if allow_fast:\n"+ assert old in _SUMMARY+ assert not _flat(_SUMMARY.replace(old, f" if {condition}:\n", 1))+++ ("prefix", "condition"),+ [+ # ``get`` on a receiver with no declared type may do anything.+ ("", 'patterns.get("x")'),+ # A builtin the file rebinds is the file's own function.+ ("from helpers import len\n", "len(patterns)"),+ ("def isinstance(x, y):\n return True\n", "isinstance(result, dict)"),+ ],+)+def test_an_unresolved_or_rebound_call_is_not_a_guard(prefix, condition):+ src = prefix + _SUMMARY.replace(" if allow_fast:\n", f" if {condition}:\n", 1)+ assert not _flat(src)+++def test_a_namespace_read_is_a_guard_and_a_java_method_call_is_not():+ ts = _QUERY_TS.replace("opts.labels === true", "Number.isFinite(opts.limit)")+ assert _flat(ts, "typescript", "ts")+ # A file's own ``Number`` is not the global one.+ assert not _flat('import { Number } from "./num";\n' + ts, "typescript", "ts")+ java = _JAVA.replace("cfg.name != null", "cfg.name.isEmpty()")+ assert not _flat(java, "java", "java")+++def test_a_guard_reading_keys_lengths_and_types_stays_flat():+ # ``result.get``, ``len`` and ``isinstance`` only read.+ new = " if isinstance(result, dict) and len(patterns) > 1:\n"+ assert _flat(_SUMMARY.replace(" if allow_fast:\n", new, 1))++# Statement-level calls on module or imported names are steps, not fields:# a function that logs or responds as it goes decomposes._LOGGING = """diff --git a/tests/unit/health/test_refactoring_extract_method_naming.py b/tests/unit/health/test_refactoring_extract_method_naming.pyindex 99564c0dd..188c33c39 100644--- a/tests/unit/health/test_refactoring_extract_method_naming.py+++ b/tests/unit/health/test_refactoring_extract_method_naming.py@@ -626,7 +626,13 @@ def _span_names(language, ext, src, start, end, returns=()):(fn,) = _functions(language, ext, src)first = fn.start_line - 1extraction = Extraction(first + start, first + end, (), tuple(returns), 8, 2, False)- return list(helper_names(fn, extraction, get_language_map(language), language))+ names = []+ # The candidates never run out; read through the first unnumbered block name.+ for name in helper_names(fn, extraction, get_language_map(language), language):+ names.append(name)+ if name.lower().endswith("block"):+ return names+ return namesdef test_a_branch_body_is_named_for_the_branch_it_handles():@@ -700,3 +706,30 @@ def test_a_span_with_no_subject_is_a_block_of_its_host():"""# An unnamed function expression has no host name to qualify.assert _span_names("typescript", "ts", anonymous, 2, 3) == ["handleBlock"]+++def test_a_numbered_block_name_follows_when_every_candidate_is_taken():+ from repowise.core.analysis.health.refactoring.helper_naming import ScopeNames++ src = """+ def report(job):+ logger.info("start")+ logger.info("done")+++ def report_block():+ return 0+ """+ fns = _functions("python", "py", src)+ (fn,) = [f for f in fns if f.name == "report"]+ lmap = get_language_map("python")+ first = fn.start_line - 1+ extraction = Extraction(first + 2, first + 3, (), (), 8, 2, False)+ names = ScopeNames(lmap)+ assert names.claim_first(fn, helper_names(fn, extraction, lmap, "python")) == (+ "report_block_2"+ )+ # The next plan in the same scope takes the next number.+ assert names.claim_first(fn, helper_names(fn, extraction, lmap, "python")) == (+ "report_block_3"+ )