Skip to content

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

fix(refactoring): 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.py
index 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":
continue
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/declarative.py b/packages/core/src/repowise/core/analysis/health/refactoring/declarative.py
index 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: every
statement 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 annotations
from dataclasses import dataclass, field
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from ..complexity.ast_utils import _find_function_entry_name
from ..complexity.nloc import is_string_stmt
-from ..dataflow.effects import binding_target, bound_names
+from ..dataflow.effects import binding_target, bound_names, imported_names
from ..dataflow.span import is_comment
+from .helper_naming import defined_names
if 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 = None
roots: 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 None
if 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 False
writes = census.writes
- owned = census.call_roots <= census.bound | set(params)
+ owned = census.call_roots <= census.bound | census.params
return 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 False
arms = [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_kinds
if 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.py
index 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):
continue
if 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")
continue
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
index 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 itertools
from collections.abc import Iterable, Iterator
from 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 nested
functions or classes)."""
fn_kinds = lmap.function_kinds | lmap.lambda_kinds
diff --git a/tests/unit/health/test_refactoring_declarative.py b/tests/unit/health/test_refactoring_declarative.py
index 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.py
index 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 - 1
extraction = 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 names
def 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"
+ )