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.

feat(health): Fix first applies the baseline precision levers and says why in plain words (#2839)

Raghav Chamadiyae07c79f151ee
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index a87cb9478..ebefbd48d 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -1010,12 +1010,13 @@ CLAUDE.md render the same object. The block carries `lead` (equal to
`title`, `target`, `why`, `gain`, `effort`, `confidence`, `next_call`),
`totals` (`candidates`, `eligible`, `shown`, and `excluded` counted by reason:
`test`, `tooling`, `unknown`, `generated`, `expected`, `no_strategy`, `no_plan`,
-`below_min_worth`, `history_only`; a performance cause enters only from the
-performance default queue, whose reasons `unknown`, `expected` and `no_strategy`
-are), `by_improves`, `model_version`, `basis`, and `detail_call`,
+`below_min_worth`, `history_only`, `vendored`, `docs_example`, `deprecated`,
+`inherent_dispatch`, `small_function`, `no_concrete_step`, `low_value_kind`; a
+performance cause enters only from the performance default queue, whose reasons
+`unknown`, `expected` and `no_strategy` are), `by_improves`, `model_version`, `basis`, and `detail_call`,
the `get_health(fix_id=...)` call that returns the lead in full. `tier` is
`now` (worth doing, and the plan is safe to start), `next` (worth doing, needs
-judgment) or `later`. Items are ordered by value first, the larger of the recoverable health and the size of the problem (CCN, lines and nesting past their bars, a critical or brain-method finding, a hot file), then by tier, so a function far past every bar leads as "Break up ..." ahead of tidy work that is safer to start. `kind` is `refactor` (one file's composed refactoring),
+judgment) or `later`. Items are ordered by value first, the larger of the recoverable health and the size of the problem (CCN, lines and nesting past their bars, a critical or brain-method finding, a hot file), then by tier, so a function far past every bar leads as "Break up ..." ahead of tidy work that is safer to start. A performance fix's value is its cost: a production, entry-reachable database or network call in a loop that grows with the data shares the top band with the largest functions, and a loop of unknown size that no entry point reaches drops one step. A cause whose marker has not cleared the bar for leading is listed, never first. `kind` is `refactor` (one file's composed refactoring),
`perf_fix` (one intervention, its sinks listed under it) or `finding` (a file's
strongest code-shape finding with no plan). Always the production population,
whatever `scope` says. `limit` caps the items, never which one leads.
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py b/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py
index f1f245c16..e5c8a7bb5 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py
@@ -247,6 +247,7 @@ def _subtree_contains_complex(arm_node: Node, complex_types: frozenset[str]) ->
def _walk_function_body(
body_node: Node,
lmap: LanguageNodeMap,
+ deepest: list[int] | None = None,
) -> tuple[int, int, int, int, list[ConditionComplexity]]:
"""Recursive AST walk. Returns (ccn, max_nesting, cognitive, bumps,
complex_conditions).
@@ -262,6 +263,13 @@ def _walk_function_body(
``complex_conditions`` is an additive side-channel — collected for
every branch/loop/case construct encountered. The CCN / cognitive
accumulation logic is unchanged.
+
+ ``deepest``, when given, is filled with the 1-indexed ``[start, end]``
+ lines of the first block that reaches the function's deepest nesting,
+ widened to the nearest enclosing control-flow block of at least
+ :data:`MIN_BLOCK_LINES` lines: where a reader starts flattening it. A
+ one-line branch is too small to name as the place to start. Also a
+ side-channel only.
"""
ccn = 1
@@ -273,9 +281,11 @@ def _walk_function_body(
# Track match_expression nodes identified as "flat" so their arms
# are not individually counted as branch points.
flat_match_ids: set[int] = set()
+ deepest_depth = 0
+ deepest_node: list[Node] = []
def _recurse(node: Node, depth: int) -> None:
- nonlocal ccn, max_nesting, cognitive
+ nonlocal ccn, max_nesting, cognitive, deepest_depth
# Don't descend into nested function bodies — they're walked
# separately at the top level. Lambdas / arrow functions DO
@@ -363,6 +373,9 @@ def _walk_function_body(
if new_depth > max_nesting:
max_nesting = new_depth
+ if deepest is not None and nesting_increment and new_depth > deepest_depth:
+ deepest_depth = new_depth
+ deepest_node[:] = [node]
for child in node.children:
_recurse(child, new_depth)
@@ -378,4 +391,30 @@ def _walk_function_body(
if child_peak >= 2:
bumps += 1
+ if deepest is not None and deepest_node:
+ block = _widened_block(deepest_node[0], body_node, lmap)
+ deepest[:] = [block.start_point[0] + 1, block.end_point[0] + 1]
return ccn, max_nesting, cognitive, bumps, conditions
+
+
+#: The smallest block named as the place to start flattening a function.
+MIN_BLOCK_LINES = 4
+
+
+def _widened_block(node: Node, body_node: Node, lmap: LanguageNodeMap) -> Node:
+ """*node*, or its nearest enclosing control-flow block spanning at least
+ :data:`MIN_BLOCK_LINES` lines, never past the function body."""
+ kinds = (
+ lmap.branch_kinds
+ | lmap.loop_kinds
+ | lmap.case_kinds
+ | lmap.catch_kinds
+ | lmap.try_kinds
+ | lmap.switch_kinds
+ )
+ cur: Node | None = node
+ while cur is not None and cur != body_node:
+ if cur.type in kinds and cur.end_point[0] - cur.start_point[0] + 1 >= MIN_BLOCK_LINES:
+ return cur
+ cur = cur.parent
+ return node
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/models.py b/packages/core/src/repowise/core/analysis/health/complexity/models.py
index 42a10e4b5..df5a8bb5f 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/models.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/models.py
@@ -108,6 +108,10 @@ class FunctionComplexity:
# True when the declaration is marked deprecated or the body's top level
# issues a deprecation warning. ``complexity/deprecation.py``.
deprecated: bool = False
+ # 1-indexed (start, end) lines of the first block that reaches
+ # ``max_nesting``, when the function nests at all: the concrete place to
+ # start flattening it. ``cyclomatic._walk_function_body``.
+ deepest_block: tuple[int, int] | None = None
def __post_init__(self) -> None:
if self.complex_conditions is None:
@@ -282,10 +286,16 @@ class PerfHit:
promoted: bool = False
# What the innermost enclosing loop proves (same-function hits only).
loop: LoopFacts | None = None
+ # 1-indexed header line of the innermost data-dependent loop the hit runs
+ # in (for a cross-function hit, the loop around the call site); 0 when none.
+ loop_line: int = 0
def loop_facts(self) -> dict[str, Any]:
"""Loop facts for ``details``; absent when unset so old findings are unchanged."""
- return self.loop.as_details() if self.loop is not None else {}
+ facts = self.loop.as_details() if self.loop is not None else {}
+ if self.loop_line:
+ facts["loop_line"] = self.loop_line
+ return facts
@dataclass(frozen=True)
@@ -334,6 +344,8 @@ class PerfFnFacts:
# ``(call_line, facts)`` for loop-nested calls whose loop settles a fact, so a
# cross-function hit reports the trip count and chunking of the loop that pays it.
loop_call_facts: tuple[tuple[int, LoopFacts], ...] = ()
+ # ``(call_line, loop header line)`` for the same loop-nested calls.
+ loop_call_lines: tuple[tuple[int, int], ...] = ()
@dataclass
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/perf_walk.py b/packages/core/src/repowise/core/analysis/health/complexity/perf_walk.py
index c4d1c6e8c..f64ef36cf 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/perf_walk.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/perf_walk.py
@@ -320,6 +320,8 @@ def _collect_perf_hits(
] = {}
# func_start -> {call_line: facts} for the loop-call targets above.
call_facts: dict[int, dict[int, LoopFacts]] = {}
+ # func_start -> {call_line: loop header line} for the same targets.
+ call_loop_lines: dict[int, dict[int, int]] = {}
# ``(first_line, last_line, name)`` of each lambda with no named function
# around it, so a hit inside one is named for it rather than left blank.
lambda_spans: list[tuple[int, int, str]] = []
@@ -333,14 +335,18 @@ def _collect_perf_hits(
fn_acc[func_start] = entry
return entry[1], entry[2], entry[3], entry[4]
- # (node, loop_depth, in_async, func_name, func_start, lock_depth, outer_iter)
- # ``outer_iter`` is whether the OUTERMOST enclosing loop iterates a collection
- # (vs a ``while``/cursor) — the precision gate for ``nested_loop_with_io``.
- stack: list[tuple[Node, int, bool, str | None, int, int, bool]] = [
- (root, 0, False, None, 0, 0, True)
+ # (node, loop_depth, in_async, func_name, func_start, lock_depth, outer_iter,
+ # loop_line). ``outer_iter`` is whether the OUTERMOST enclosing loop iterates
+ # a collection (vs a ``while``/cursor) — the precision gate for
+ # ``nested_loop_with_io``. ``loop_line`` is the innermost data-dependent
+ # loop's header line (0 outside one), so a reader can show the iteration.
+ stack: list[tuple[Node, int, bool, str | None, int, int, bool, int]] = [
+ (root, 0, False, None, 0, 0, True, 0)
]
while stack:
- node, loop_depth, in_async, func_name, func_start, lock_depth, outer_iter = stack.pop()
+ (
+ node, loop_depth, in_async, func_name, func_start, lock_depth, outer_iter, loop_line
+ ) = stack.pop()
t = node.type
# ``node.is_named`` guards grammars (Ruby) whose keyword tokens share
@@ -380,6 +386,7 @@ def _collect_perf_hits(
)
next_loop_depth = loop_depth if (body_scope or not entering_fn) else 0
next_lock_depth = lock_depth if (body_scope or not entering_fn) else 0
+ next_loop_line = loop_line if (body_scope or not entering_fn) else 0
next_func = func_name
next_start = func_start
if t in fn_kinds:
@@ -421,6 +428,9 @@ def _collect_perf_hits(
hits.append(
PerfHit(icm, node.start_point[0] + 1, next_func, "", func_start=next_start)
)
+ # Hits from here on sit in the loop the stack names; the iterable marker
+ # above is on the loop's own header line.
+ stamp_from = len(hits)
call_node: Node | None = None
if t in call_kinds:
@@ -532,6 +542,8 @@ def _collect_perf_hits(
targets = _acc(next_start, next_func)[0]
if method not in targets:
targets[method] = line
+ if loop_line:
+ call_loop_lines.setdefault(next_start, {})[line] = loop_line
facts = loop_facts(call_node, sink=False)
if facts is not None:
call_facts.setdefault(next_start, {})[line] = facts
@@ -589,6 +601,9 @@ def _collect_perf_hits(
)
)
+ if loop_line and len(hits) > stamp_from:
+ hits[stamp_from:] = [replace(h, loop_line=loop_line) for h in hits[stamp_from:]]
+
# A block-scoped lock (``lock``/``synchronized``) opens a held region.
# Only its BLOCK body runs with the lock held — a sink in the lock-object
# expression (``synchronized(repo.find(id)){…}``) runs before the lock is
@@ -605,13 +620,23 @@ def _collect_perf_hits(
body = block_loop_body
if body is None:
body = dialect.loop_body(node)
+ header = node.start_point[0] + 1
if body is not None:
# NB: tree-sitter Node wrappers are not singletons, so compare
# with ``==`` (identity by tree + byte range), never ``is``.
for c in node.children:
- cd = next_loop_depth + 1 if c == body else next_loop_depth
+ inside = c == body
stack.append(
- (c, cd, next_async, next_func, next_start, next_lock_depth, next_outer_iter)
+ (
+ c,
+ next_loop_depth + 1 if inside else next_loop_depth,
+ next_async,
+ next_func,
+ next_start,
+ next_lock_depth,
+ next_outer_iter,
+ header if inside else next_loop_line,
+ )
)
else:
for c in node.children:
@@ -624,6 +649,7 @@ def _collect_perf_hits(
next_start,
next_lock_depth,
next_outer_iter,
+ header,
)
)
elif entering_lock:
@@ -631,7 +657,16 @@ def _collect_perf_hits(
for c in node.children:
cl = next_lock_depth + 1 if c.type in _LOCK_BODY_KINDS else next_lock_depth
stack.append(
- (c, next_loop_depth, next_async, next_func, next_start, cl, outer_iter)
+ (
+ c,
+ next_loop_depth,
+ next_async,
+ next_func,
+ next_start,
+ cl,
+ outer_iter,
+ next_loop_line,
+ )
)
else:
for c in node.children:
@@ -644,6 +679,7 @@ def _collect_perf_hits(
next_start,
next_lock_depth,
outer_iter,
+ next_loop_line,
)
)
@@ -671,6 +707,7 @@ def _collect_perf_hits(
blocking_sink_kind=misc[1],
blocking_sink_line=misc[2],
loop_call_facts=tuple(sorted(call_facts.get(start, {}).items())),
+ loop_call_lines=tuple(sorted(call_loop_lines.get(start, {}).items())),
)
for start, (name, loop_targets, lock_targets, sink, misc) in fn_acc.items()
if (loop_targets or lock_targets or sink[0] is not None or misc[0] or misc[1] is not None)
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/walker.py b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
index 79e1f139a..4f71754f6 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -164,7 +164,8 @@ def walk_file(
asserts = _assert_dialect(language, extra_assert_names)
for fn_node in _collect_function_nodes(tree.root_node, lmap):
body = fn_node.child_by_field_name("body") or fn_node
- ccn, max_nest, cognitive, bumps, conditions = _walk_function_body(body, lmap)
+ deepest: list[int] = []
+ ccn, max_nest, cognitive, bumps, conditions = _walk_function_body(body, lmap, deepest)
(
assertion_blocks,
assertion_count,
@@ -195,6 +196,7 @@ def walk_file(
bare_called_names=bare_called,
dispatch_share=dispatch_share(dispatch_points(body, lmap), ccn),
deprecated=is_deprecated(fn_node, body, name, lmap, source),
+ deepest_block=(deepest[0], deepest[1]) if deepest else None,
)
functions.append(fc)
fc_by_node_id[fn_node.id] = fc
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 84a91a6fb..b6b5902dd 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -129,6 +129,10 @@ log = structlog.get_logger(__name__)
# line (``details["symbol_line"]``) and its public id is anchored on the symbol
# plus the offset into it, hashing no metric values, so every stored finding id
# moves once.
+# v37 (also): the walker records each function's deepest nested block and each
+# performance hit's loop header line; size findings carry ``deepest_block`` and
+# performance findings ``loop_line`` in their details, both outside the id
+# kernel. A cached v37 walk without them reads the defaults (absent).
# v37 (also): a perf hit inside a lambda with no named function around it is
# named for that lambda (``build``, ``it callback``), so its stored
# ``function_name`` and public id change; top-level script code still carries
@@ -389,6 +393,34 @@ def _mark_deprecated(
finding.details["deprecated"] = True
+#: Function-size findings whose fix starts at the deepest nested block.
+_DEEPEST_BLOCK_MARKERS = frozenset(
+ {"complex_method", "nested_complexity", "brain_method", "large_method", "bumpy_road"}
+)
+
+
+def _mark_deepest_block(
+ findings: list[HealthFindingData], functions: list[FunctionComplexity]
+) -> None:
+ """Copy the function's deepest nested block onto its size findings as
+ ``deepest_block: {start, end}``, so a fix list can name where to start
+ without re-walking the file. Absent when the function does not nest."""
+ blocks = {
+ (fc.name, fc.start_line): fc.deepest_block
+ for fc in functions
+ if fc.deepest_block
+ }
+ if not blocks:
+ return
+ for finding in findings:
+ if finding.biomarker_type not in _DEEPEST_BLOCK_MARKERS:
+ continue
+ block = blocks.get((finding.function_name, finding.line_start))
+ if block:
+ # A mapping, not a pair: surfaces count every nested list as a collection.
+ finding.details["deepest_block"] = {"start": block[0], "end": block[1]}
+
+
def walked_functions(
fc_list: list[FunctionComplexity], language: str
) -> tuple[FunctionComplexity, ...]:
@@ -1535,6 +1567,7 @@ class HealthAnalyzer:
f.file_path = file_path
_mark_deprecated(findings, fc_list)
_stamp_symbol_lines(findings, fcx)
+ _mark_deepest_block(findings, fc_list)
# The overall surfaced score stays == the defect dimension (no blend
# yet); the per-dimension scores ride alongside it, additively.
diff --git a/packages/core/src/repowise/core/analysis/health/finding_identity.py b/packages/core/src/repowise/core/analysis/health/finding_identity.py
index eb24e660f..8d777d4d6 100644
--- a/packages/core/src/repowise/core/analysis/health/finding_identity.py
+++ b/packages/core/src/repowise/core/analysis/health/finding_identity.py
@@ -72,7 +72,14 @@ are made relative to the symbol, so neither moves with an unrelated edit.
"""
_DERIVED_DETAIL_KEYS = frozenset(
- {"opportunity_id", "reliable_entry_reachability", "dispatch_share", "deprecated"}
+ {
+ "opportunity_id",
+ "reliable_entry_reachability",
+ "dispatch_share",
+ "deprecated",
+ "loop_line",
+ "deepest_block",
+ }
)
"""Keys version 1 left out of its hash; only :func:`legacy_finding_public_id` reads it."""
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/build.py b/packages/core/src/repowise/core/analysis/health/fix_first/build.py
index ee2c00824..6fb7a11b2 100644
--- a/packages/core/src/repowise/core/analysis/health/fix_first/build.py
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/build.py
@@ -10,15 +10,17 @@ caller may pass unfiltered rows.
Row shapes (field names are the SQL columns):
``metrics``
- ``file_path``, ``score``, ``nloc``, ``is_test``, ``analyzed_commit``,
- ``updated_at``, plus ``commit_count_90d`` (git) and ``dependents`` (graph
- in-degree).
+ ``file_path``, ``score``, ``nloc``, ``is_test``, ``code_origin``,
+ ``line_coverage_pct``, ``analyzed_commit``, ``updated_at``, plus
+ ``commit_count_90d`` and ``contributor_count`` (git) and ``dependents``
+ (graph in-degree).
``findings``
- ``file_path``, ``biomarker_type``, ``severity``, ``function_name``,
+ Hidden types are never items. ``file_path``, ``biomarker_type``,
+ ``severity``, ``function_name``,
``line_start``, ``line_end``, ``reason``, ``health_impact``, ``public_id``,
``dimension``, ``status`` (absent = open), and ``details`` /
``details_json`` (``ccn``, ``nloc``, ``max_nesting``) for the numbers a
- sentence quotes.
+ sentence quotes, and ``deprecated`` for a function on its way out.
``refactoring``
The ``refactoring_opportunities`` columns, ``details`` (or
``details_json``) carrying ``steps``, ``validation_profiles``,
@@ -31,8 +33,12 @@ Row shapes (field names are the SQL columns):
``plans``
Plan rows named by a refactoring step: ``public_id``, ``evidence`` /
``evidence_json`` and ``plan`` / ``plan_json`` (an extract-method ``span``,
- ``params``, ``returns``, ``suggested_name``). A step whose plan is absent
- is kept, with less to say.
+ ``params``, ``returns``, ``suggested_name``; a move's destination; a
+ split's named groups; a helper's ``occurrences``). A plan row that also
+ carries ``refactoring_type`` ``extract_method``, ``file_path`` and
+ ``target_symbol`` can give a finding with no plan of its own its first
+ concrete step. Every Extract Helper plan's occurrences say where verified
+ duplicates sit.
"""
from __future__ import annotations
@@ -120,6 +126,33 @@ MAX_CONTEXT = 3
HEAD = 5
HEAD_PER_KIND = 3
DEFAULT_LIMIT = 10
+#: Findings that measure one function's size; a unit led by one of them, or by
+#: an Extract Method step, is a function-level complexity unit.
+SIZE_MARKERS = frozenset(
+ {"complex_method", "nested_complexity", "brain_method", "large_method", "bumpy_road"}
+)
+#: A function whose largest dispatch on one value holds this share of its
+#: decision points is usually fine as it is. Fitted on the dev labels only:
+#: share >= 0.6 held 9 labelled complexity rows, 8 of them rejected.
+DISPATCH_SHARE = 0.6
+#: A function-level complexity unit needs this many code lines or this CCN.
+#: Picked on the dev labels (67 complexity rows): 30 / 15 drops 13 rejected
+#: small functions and 4 accepted ones; no cut that keeps every accepted row
+#: drops more than 4 rejected.
+SMALL_NLOC = 30
+SMALL_CCN = 15
+#: Class-level findings: a fix names member groups, which only a plan holds.
+CLASS_MARKERS = frozenset({"low_cohesion", "god_class"})
+#: Kinds the baseline raters found not worth doing: a refactoring led by one
+#: of these steps, or a plan-less finding led by one of these markers, is no
+#: candidate (it stays in the refactoring tab). Worth over rater labels, dev
+#: repos first, then all 17 baseline repos.
+LOW_VALUE_KINDS: dict[str, str] = {
+ "extract_class": "dev 0/6, all 0/14",
+ "move_method": "dev 0/14, all 0/34",
+ "low_cohesion": "dev 0/26, all 0/46",
+ "large_method": "dev 0/4, all 0/10",
+}
@dataclass(frozen=True, slots=True)
@@ -139,9 +172,20 @@ class _Unit:
effort: str
improves: str
write: Callable[[int], FixItem]
+ #: False for a performance cause whose marker has not cleared the bar for
+ #: leading (``opportunity_rank.may_lead``): listed, never first.
+ may_lead: bool = True
_VENDORED = frozenset({"vendor", "third_party", "thirdparty", "node_modules"})
+#: Stored code origins that do not ship, by the exclusion each counts as.
+_ORIGIN_EXCLUSION = {
+ "test": "test",
+ "vendored": "vendored",
+ "docs_example": "docs_example",
+ "generated": "generated",
+ "tooling": "tooling",
+}
def _open(row: Any) -> bool:
@@ -157,19 +201,27 @@ def _num(value: Any) -> float:
_code_context = functools.lru_cache(maxsize=65536)(code_context)
-def _path_exclusion(path: str, is_test: bool | None, context: str | None = None) -> str | None:
+def _path_exclusion(
+ path: str, is_test: bool | None, context: str | None = None, origin: str | None = None
+) -> str | None:
"""Why a file is out of the queue, or ``None`` when it ships.
- Code-shape work reads :func:`code_context`, where a CLI ships. A
- performance fix passes ``production``: its stored execution context is
- judged by the performance default queue, so only the path rules apply.
- The stored ``is_test`` flag also marks a test.
+ The stored ``code_origin`` decides first: it read the file's head, so it
+ knows a vendored library or a docs tutorial the path alone does not.
+ Then the path rules. Code-shape work reads :func:`code_context`, where a
+ CLI ships. A performance fix passes ``production``: its stored execution
+ context is judged by the performance default queue, so only the path
+ rules apply. The stored ``is_test`` flag also marks a test.
"""
+ if origin in _ORIGIN_EXCLUSION:
+ return _ORIGIN_EXCLUSION[origin]
ctx = context or _code_context(path)
if is_test or ctx == "test":
return "test"
parts = set(path.lower().split("/")[:-1])
- if _is_generated_path(path) or parts & _VENDORED:
+ if parts & _VENDORED:
+ return "vendored"
+ if _is_generated_path(path):
return "generated"
# ``unknown`` under a directory is docs, examples or demos: code that does
# not ship. A root-level file stays eligible.
@@ -254,9 +306,13 @@ class _Files:
history: Mapping[str, list[Any]],
functions: Mapping[tuple[str, str], list[Any]],
cuts: tuple[float, float] | None,
+ clones: Mapping[str, list[tuple[int, int]]] | None = None,
+ extractions: Mapping[tuple[str, str], list[Any]] | None = None,
) -> None:
self.by_path = {field(m, "file_path"): m for m in metrics}
self.functions = functions
+ self.clones = clones or {}
+ self.extractions = extractions or {}
if cuts is None:
production = [m for m in self.by_path.values() if not field(m, "is_test")]
cuts = (
@@ -270,9 +326,17 @@ class _Files:
"""The stored flag; ``None`` when the file has no metric row or flag."""
return field(self.by_path.get(path), "is_test")
+ def origin(self, path: str) -> str | None:
+ """The stored code origin; ``None`` before it was recorded."""
+ return field(self.by_path.get(path), "code_origin")
+
def commits(self, path: str) -> int:
return int(field(self.by_path.get(path), "commit_count_90d") or 0)
+ def coverage(self, path: str) -> float | None:
+ """Measured line coverage in percent; ``None`` when no report has it."""
+ return field(self.by_path.get(path), "line_coverage_pct")
+
def dependents(self, path: str) -> int | None:
return field(self.by_path.get(path), "dependents")
@@ -299,6 +363,78 @@ class _Files:
)
return _measure(found)
+ def cloned(self, path: str, shape: Mapping[str, int]) -> bool:
+ """Whether a stored duplicate overlaps the function ``shape`` spans."""
+ start, end = shape.get("start"), shape.get("end")
+ if not start or not end:
+ return False
+ return any(a <= end and b >= start for a, b in self.clones.get(path, ()))
+
+ def first_step(self, finding: Any) -> FixStep | None:
+ """The concrete first edit for a finding with no plan of its own.
+
+ A function-size finding starts at the best stored Extract Method span
+ inside the function, else at its deepest nested block. Any other
+ finding names its own line or function. ``None`` when there is no
+ such edit to name: a class-level finding with no member groups, or a
+ size finding with neither fact stored.
+ """
+ path = field(finding, "file_path")
+ marker = field(finding, "biomarker_type") or ""
+ function = field(finding, "function_name")
+ line = field(finding, "line_start")
+ if marker in CLASS_MARKERS:
+ return None
+ if marker not in SIZE_MARKERS:
+ if line or function:
+ summary = text.first_sentence(suggestion_for(marker))
+ return FixStep(1, summary, path, line, False)
+ return None
+ tail = (function or "").rsplit(".", 1)[-1]
+ plans = self.extractions.get((path, tail)) or ()
+ best = max(plans, key=_extraction_worth, default=None)
+ if best is not None:
+ start, end = _span(best)
+ body = _plan_body(best)
+ into = text.signature(
+ body.get("suggested_name"),
+ list(body.get("params") or []),
+ list(body.get("returns") or []),
+ )
+ return FixStep(1, f"Extract lines {start}-{end} of {tail} into {into}", path, start)
+ shape = self.shape(path, function)
+ start, end = shape.get("deep_start"), shape.get("deep_end")
+ if start and end:
+ depth = shape.get("max_nesting")
+ where = f"where it nests {depth} deep" if depth else "where it nests deepest"
+ lines = f"line {start}" if start == end else f"lines {start}-{end}"
+ return FixStep(
+ 1,
+ f"Start with {lines}, {where}: return early or move it into a helper",
+ path,
+ start,
+ )
+ return None
+
+ def unit_exclusion(self, path: str, symbol: str | None, complexity: bool) -> str | None:
+ """Why a unit on ``symbol`` is not a candidate, or ``None``.
+
+ A deprecated function is on its way out. A complexity unit on a
+ function that is mostly one dispatch on one value is usually fine as
+ it is, unless a duplicate also sits in it; one on a small function is
+ not worth an item.
+ """
+ shape = self.shape(path, symbol)
+ if shape.get("deprecated"):
+ return "deprecated"
+ if not complexity:
+ return None
+ if shape.get("dispatch_pct", 0) >= DISPATCH_SHARE * 100 and not self.cloned(path, shape):
+ return "inherent_dispatch"
+ if _small(shape):
+ return "small_function"
+ return None
+
def why(
self,
path: str,
@@ -306,25 +442,31 @@ class _Files:
measured: str | None,
fallback: str,
dependents: int | None = None,
+ cloned: bool = False,
) -> str:
- """One sentence: the measured problem, then who depends on the file."""
+ """One sentence: the problem, then why it matters here (who imports
+ the file, how often it changes, how much of it tests run)."""
deps = dependents if dependents is not None else self.dependents(path)
head = measured or fallback.rstrip(". ")
- return f"{head}{text.exposure(deps, self.commits(path))}."
+ if cloned:
+ head += f", {text.CLONED}"
+ return f"{head}{text.exposure(deps, self.commits(path), self.coverage(path))}."
def context(self, path: str) -> tuple[FixContext, ...]:
"""History is context: shown beside the item, never ranked on."""
out: list[FixContext] = []
commits = self.commits(path)
if commits:
- out.append(FixContext("changes in 90 days", str(commits)))
+ people = field(self.by_path.get(path), "contributor_count")
+ out.append(FixContext("recent changes", text.changes(commits, people)))
if self.is_test(path):
out.append(FixContext("file kind", "test"))
ranked = sorted(self.history.get(path, ()), key=lambda f: -_num(field(f, "health_impact")))
for f in ranked:
- out.append(
- FixContext(text.humanize(field(f, "biomarker_type") or ""), field(f, "reason") or "")
- )
+ marker = field(f, "biomarker_type") or ""
+ sentence = text.history_fact(marker, detail_map(f), field(f, "function_name"))
+ if sentence:
+ out.append(FixContext(text.HISTORY_LABEL.get(marker, "history"), sentence))
return tuple(out[:MAX_CONTEXT])
def common_facts(self, path: str, dependents: int | None = None) -> list[FixFact]:
@@ -358,6 +500,7 @@ def _finish(
improves: str,
rank_inputs: Callable[[], list[FixRankFact]],
fields: Callable[[], dict[str, Any]],
+ may_lead: bool = True,
) -> _Unit:
confidence = confidence if confidence in LEVEL_RANK else "low"
effort = effort if effort in FIX_EFFORTS else "M"
@@ -379,7 +522,7 @@ def _finish(
**fields(),
)
- return _Unit(item_id, kind, tier, value, score, confidence, effort, improves, write)
+ return _Unit(item_id, kind, tier, value, score, confidence, effort, improves, write, may_lead)
# --- refactoring ----------------------------------------------------------------
@@ -423,19 +566,97 @@ def _refactor_step(order: int, step: Mapping[str, Any], plan: Any) -> FixStep:
elif kind == "extract_helper":
line_text = f"Replace the duplicate in {sym} with a call to one shared helper"
elif kind == "extract_class":
- line_text = f"Move a cohesive group of {sym}'s methods into a new class"
+ groups = [g for g in _plan_body(plan).get("groups") or [] if g.get("methods")]
+ members = sorted(groups, key=lambda g: len(g["methods"]))[0]["methods"] if groups else []
+ line_text = (
+ f"Move {', '.join(members[:4])}"
+ + (f" and {len(members) - 4} more" if len(members) > 4 else "")
+ + f" out of {sym} into a new class"
+ if members
+ else f"Move a cohesive group of {sym}'s methods into a new class"
+ )
elif kind == "split_file":
- line_text = f"Split {text.basename(path)} along its independent groups"
+ names = [g.get("name") for g in _plan_body(plan).get("groups") or [] if g.get("name")]
+ line_text = (
+ f"Split {text.basename(path)} into {', '.join(names[:4])}"
+ + (f" and {len(names) - 4} more" if len(names) > 4 else "")
+ if names
+ else f"Split {text.basename(path)} along its independent groups"
+ )
elif kind == "break_cycle":
- line_text = f"Break the import cycle at {text.basename(path)}"
+ edge = _cut_edge(plan)
+ line_text = (
+ f"Cut the import of {text.basename(edge['to'])} in "
+ f"{text.basename(edge['from'])} (line {edge['line']})"
+ if edge
+ else f"Break the import cycle at {text.basename(path)}"
+ )
elif kind == "move_method":
- line_text = f"Move {sym} to the class it uses most"
+ dest = _plan_body(plan).get("to_class") or text.basename(
+ _plan_body(plan).get("to_file") or ""
+ )
+ line_text = (
+ f"Move {sym} to {dest}" if dest else f"Move {sym} to the class it uses most"
+ )
else:
line_text = f"Apply the {text.humanize(kind)} step to {sym}"
mechanical = (step.get("applicability") or {}).get("classification") == "mechanical"
return FixStep(order, line_text, path, start or step.get("line_start"), mechanical)
+def _cut_edge(plan: Any) -> dict[str, Any] | None:
+ """The first cut edge whose import line is stored."""
+ for edge in _plan_body(plan).get("cut_edges") or ():
+ if isinstance(edge, dict) and edge.get("line") and edge.get("from") and edge.get("to"):
+ return edge
+ return None
+
+
+def _concrete(step: Mapping[str, Any], plan: Any) -> bool:
+ """Whether a refactoring step names an edit someone can make: lines to
+ lift, a destination, the import to cut, or named groups."""
+ kind = step.get("refactoring_type") or ""
+ body = _plan_body(plan)
+ if kind == "extract_method":
+ start, end = _span(plan)
+ return bool(start and end)
+ if kind == "extract_helper":
+ return any(
+ isinstance(o, dict) and o.get("line_start") for o in body.get("occurrences") or ()
+ )
+ if kind == "move_method":
+ return bool(body.get("to_class") or body.get("to_file"))
+ if kind == "break_cycle":
+ return _cut_edge(plan) is not None
+ if kind in ("split_file", "extract_class"):
+ members = "symbols" if kind == "split_file" else "methods"
+ return any(
+ isinstance(g, dict) and g.get(members) and (g.get("name") or kind == "extract_class")
+ for g in body.get("groups") or ()
+ )
+ return bool(step.get("line_start"))
+
+
+def _extraction_worth(plan: Any) -> tuple[int, int]:
+ evidence = _evidence(plan)
+ return int(evidence.get("ccn_removed") or 0), int(evidence.get("slice_nloc") or 0)
+
+
+def _extractions(plans: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:
+ """Extract Method plans with a span, by (file, function name)."""
+ out: dict[tuple[str, str], list[Any]] = defaultdict(list)
+ for plan in plans:
+ symbol = field(plan, "target_symbol")
+ if field(plan, "refactoring_type") != "extract_method" or not symbol:
+ continue
+ start, end = _span(plan)
+ if start and end:
+ out[(field(plan, "file_path"), text.short_symbol(symbol).rsplit(".", 1)[-1])].append(
+ plan
+ )
+ return dict(out)
+
+
def _refactor_unit(
row: Any,
details: Mapping[str, Any],
@@ -460,6 +681,7 @@ def _refactor_unit(
dimension = biomarker_dimension(marker) if marker else "maintainability"
shape = files.shape(path, lead.get("target_symbol"))
size = _size_value(shape, hot)
+ cloned = lead_type == "extract_method" and files.cloned(path, shape)
def fields() -> dict[str, Any]:
lead_plan = plans.get(lead.get("plan_id"))
@@ -501,8 +723,10 @@ def _refactor_unit(
fix_steps = tuple(
_refactor_step(i + 1, s, plans.get(s.get("plan_id"))) for i, s in enumerate(steps)
)
+ size_text = text.size_line(shape)
facts = [
FixFact("health recoverable", f"+{gain:.1f}", "inferred"),
+ *([FixFact("size", size_text)] if size_text else []),
FixFact("steps", f"{len(steps)} ({mechanical_n} mechanical)"),
*files.common_facts(path, dependents),
]
@@ -527,6 +751,7 @@ def _refactor_unit(
measured=_refactor_measure(lead_type, sym, path, lead, lead_plan, files),
fallback=text.problem(marker, sym),
dependents=dependents,
+ cloned=cloned,
),
"facts": tuple(facts[:MAX_FACTS]),
"action": FixAction(
@@ -562,7 +787,7 @@ def _refactor_unit(
return _finish(
kind="refactor",
source_id=field(row, "opportunity_id"),
- value=max(_gain_value(gain, hot), size),
+ value=_lifted(max(_gain_value(gain, hot), size), cloned),
ready=mechanical or confidence == "high",
score=_num(field(row, "rank_score")),
confidence=confidence if confidence in LEVEL_RANK else "medium",
@@ -572,11 +797,18 @@ def _refactor_unit(
FixRankFact("health gain", f"{gain:.2f}"),
FixRankFact("problem size", str(size)),
FixRankFact("hot file", "yes" if hot else "no"),
+ FixRankFact("duplicate inside", "yes" if cloned else "no"),
],
fields=fields,
)
+def _lifted(value: int, cloned: bool) -> int:
+ """A complexity unit with a duplicate in the same function is one step
+ more worth doing: raters accepted that shape almost every time."""
+ return min(VALUE_MAX, value + 1) if cloned else value
+
+
def _refactor_measure(
kind: str, sym: str, path: str, step: Mapping[str, Any], plan: Any, files: _Files
) -> str | None:
@@ -610,7 +842,27 @@ def _has_plan(row: Any) -> bool:
return field(row, "plan_state") == "available" and bool(field(row, "fix_strategy"))
+#: Causes whose cost is real only in shipped code over a loop that grows: a
+#: string built in a bounded loop, or in a script, costs nothing a user sees.
+GROWS_ONLY_MARKERS = frozenset({"string_concat_in_loop"})
+
+
+def _perf_worth(row: Any) -> bool:
+ """Whether a planned cause is worth an item at all."""
+ if field(row, "biomarker_type") not in GROWS_ONLY_MARKERS:
+ return True
+ facets = detail_map(row).get("facets") or {}
+ return (
+ field(row, "execution_context") == "production"
+ and facets.get("loop_magnitude") == "grows_with_data"
+ )
+
+
def _perf_value(row: Any, facets: Mapping[str, Any]) -> int:
+ """0 to :data:`VALUE_MAX`. A production, entry-reachable database or
+ network call in a loop that grows with the data is the costliest kind of
+ work Fix first holds, so it shares the top band with the largest
+ functions; capped below it, it never reached a top ten that size fills."""
production = field(row, "execution_context") == "production"
grows = facets.get("loop_magnitude") == "grows_with_data"
unknown = facets.get("loop_magnitude") in (None, "unknown")
@@ -620,10 +872,13 @@ def _perf_value(row: Any, facets: Mapping[str, Any]) -> int:
and grows
and field(row, "boundary_kind") in ("db", "network")
):
- return 3
- if production and (grows or unknown):
- return 2
- return 1
+ return VALUE_MAX
+ value = 2 if production and (grows or unknown) else 1
+ # No traffic data: a loop of unknown size that no entry point reaches is
+ # most often an admin or maintenance path, where an N+1 is cheap.
+ if unknown and facets.get("exposure") != "entry_reachable":
+ value -= 1
+ return value
def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
@@ -648,10 +903,11 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
# A cause with no intervention symbol is named by the function its plan edits.
first = plan_steps[0] if plan_steps else {}
name = (
- text.short_symbol(symbol)
- or text.short_symbol(first.get("symbol"))
+ text.scope_name(symbol, path)
+ or text.scope_name(first.get("symbol"), path)
or text.basename(path)
)
+ module = name.startswith("module scope of ")
noun = text.BOUNDARY_NOUN.get(field(lead, "boundary_kind") or "")
call_sites = int(field(lead, "affected_call_sites_total") or 0)
files_n = int(field(lead, "affected_files_total") or 1)
@@ -660,7 +916,7 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
if shaped:
title = shaped[0].format(name=name)
elif noun and call_sites > 1:
- title = f"Batch the {noun} calls loops make through {name}"
+ title = f"Batch the {noun} calls loops make {'in' if module else 'through'} {name}"
elif noun:
title = f"Move the {noun} call in {name} out of its loop"
else:
@@ -700,7 +956,7 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
FixStep(
int(s.get("order") or i + 1),
s.get("action", "")
- + (f" ({text.short_symbol(s.get('symbol'))})" if s.get("symbol") else ""),
+ + (f" ({text.scope_name(s.get('symbol'), path)})" if s.get("symbol") else ""),
s.get("file_path") or path,
s.get("line"),
s.get("applicability") == "mechanical",
@@ -711,7 +967,9 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
return {
"title": text.clip(title),
"target": FixTarget(
- path, name if symbol or first.get("symbol") else None, first.get("line")
+ path,
+ name if (symbol or first.get("symbol")) and not module else None,
+ first.get("line"),
),
"why": f"{what}; {', '.join(reach) or 'the loop size is unknown'}.",
"facts": tuple(facts[:MAX_FACTS]),
@@ -744,6 +1002,7 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
confidence = confidence if confidence in LEVEL_RANK else "low"
return _finish(
kind="perf_fix",
+ may_lead=details.get("may_lead") is not False,
source_id=f"{path}::{symbol or path}",
value=_perf_value(lead, facets),
ready=ready or mechanical,
@@ -753,8 +1012,8 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
improves="performance",
rank_inputs=lambda: [
FixRankFact("runs in", field(lead, "execution_context") or "unknown"),
- FixRankFact("entry reachable", exposure or "unknown"),
- FixRankFact("loop size", magnitude or "unknown"),
+ FixRankFact("entry reachable", text.humanize(exposure or "unknown")),
+ FixRankFact("loop size", text.humanize(magnitude or "unknown")),
FixRankFact("boundary", field(lead, "boundary_kind") or "none"),
],
fields=fields,
@@ -764,7 +1023,7 @@ def _perf_unit(rows: list[Any], files: _Files) -> _Unit:
# --- findings with no plan ----------------------------------------------------------
-def _finding_unit(lead: Any, files: _Files) -> _Unit:
+def _finding_unit(lead: Any, files: _Files, first: FixStep) -> _Unit:
path = field(lead, "file_path")
marker = field(lead, "biomarker_type") or ""
function = field(lead, "function_name")
@@ -774,12 +1033,13 @@ def _finding_unit(lead: Any, files: _Files) -> _Unit:
dimension = biomarker_dimension(marker)
shape = files.shape(path, function)
size = _size_value(shape, hot)
+ cloned = marker in SIZE_MARKERS and files.cloned(path, shape)
def fields() -> dict[str, Any]:
where = function or text.basename(path)
summary = text.first_sentence(suggestion_for(marker))
line = field(lead, "line_start")
- if _magnitude(shape) >= SIZE_BREAK_UP and function:
+ if _magnitude(shape) >= SIZE_BREAK_UP and function and marker in SIZE_MARKERS:
title = f"Break up {where} ({text.size_brief(shape)})"
else:
title = text.FINDING_TITLE.get(marker, "Address the finding in {where}").format(
@@ -790,17 +1050,19 @@ def _finding_unit(lead: Any, files: _Files) -> _Unit:
"target": FixTarget(path, function, line, field(lead, "line_end")),
"why": files.why(
path,
- measured=text.measured(where, files.shape(path, function)),
- fallback=field(lead, "reason") or text.problem(marker, where),
+ measured=text.measured(where, shape),
+ fallback=text.problem(marker, where),
+ cloned=cloned,
),
"facts": tuple(
[
- FixFact("finding", marker),
+ FixFact("finding", text.marker_label(marker)),
+ *([FixFact("size", size_text)] if (size_text := text.size_line(shape)) else []),
FixFact("severity", field(lead, "severity") or "unknown"),
*files.common_facts(path),
][:MAX_FACTS]
),
- "action": FixAction(summary, (FixStep(1, summary, path, line, False),), 1, False),
+ "action": FixAction(summary, (first,), 1, False),
"gain": FixGain(
"health_points", round(impact, 3), text.health_gain(impact, ceiling=True)
),
@@ -820,7 +1082,7 @@ def _finding_unit(lead: Any, files: _Files) -> _Unit:
return _finish(
kind="finding",
source_id=public_id or f"{path}::{marker}::{function or ''}",
- value=max(_gain_value(impact, hot), size),
+ value=_lifted(max(_gain_value(impact, hot), size), cloned),
ready=False,
score=impact,
confidence="medium",
@@ -830,11 +1092,52 @@ def _finding_unit(lead: Any, files: _Files) -> _Unit:
FixRankFact("health gain", f"{impact:.2f}"),
FixRankFact("problem size", str(size)),
FixRankFact("hot file", "yes" if hot else "no"),
+ FixRankFact("duplicate inside", "yes" if cloned else "no"),
],
fields=fields,
)
+def _small(shape: Mapping[str, int]) -> bool:
+ """Under both size floors. A function whose size findings carry no line
+ count is measured by its span, which bounds its code lines from above; one
+ with neither is not judged small."""
+ nloc = shape.get("nloc")
+ if not nloc and shape.get("start") and shape.get("end"):
+ nloc = shape["end"] - shape["start"] + 1
+ if not nloc:
+ return False
+ return nloc < SMALL_NLOC and shape.get("ccn", 0) < SMALL_CCN
+
+
+def _finding_exclusion(finding: Any, files: _Files) -> str | None:
+ if field(finding, "biomarker_type") in LOW_VALUE_KINDS:
+ return "low_value_kind"
+ reason = files.unit_exclusion(
+ field(finding, "file_path"),
+ field(finding, "function_name"),
+ complexity=field(finding, "biomarker_type") in SIZE_MARKERS,
+ )
+ if reason is None and files.first_step(finding) is None:
+ return "no_concrete_step"
+ return reason
+
+
+def _clone_spans(plans: Iterable[Any]) -> dict[str, list[tuple[int, int]]]:
+ """Where verified duplicates sit, by file: the occurrences an Extract
+ Helper plan names. Those come from clone pairs the detector verified
+ token by token and by shared identifier names, with test, generated and
+ short spans already dropped. ``dry_violation`` is not read: it also
+ pairs import blocks and data literals, which is why it is hidden.
+ """
+ out: dict[str, list[tuple[int, int]]] = defaultdict(list)
+ for plan in plans:
+ for occ in _plan_body(plan).get("occurrences") or ():
+ if isinstance(occ, dict) and occ.get("line_start") and occ.get("line_end"):
+ out[occ.get("file") or ""].append((occ["line_start"], occ["line_end"]))
+ return dict(out)
+
+
# --- order ------------------------------------------------------------------------
@@ -868,7 +1171,12 @@ def _order(units: list[_Unit]) -> list[_Unit]:
ranked.remove(pick)
head.append(pick)
taken[pick.kind] += 1
- return head + ranked
+ out = head + ranked
+ # A cause that may not lead stays in the list, behind the first that may.
+ first = next((i for i, u in enumerate(out) if u.may_lead), 0)
+ if first:
+ out.insert(0, out.pop(first))
+ return out
def _by_function(findings: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:
@@ -883,13 +1191,31 @@ def _by_function(findings: Iterable[Any]) -> dict[tuple[str, str], list[Any]]:
def _measure(findings: Iterable[Any]) -> dict[str, int]:
"""A function's largest measured CCN, size and nesting across its findings.
- ``severe`` is set when any of them is critical or a brain method.
+ ``severe`` is set when any of them is critical or a brain method,
+ ``deprecated`` when any sits in a function marked deprecated,
+ ``dispatch_pct`` is the largest stored dispatch share in percent,
+ ``start`` / ``end`` span the function as its size findings place it, and
+ ``deep_start`` / ``deep_end`` are its deepest nested block's lines.
"""
shape: dict[str, int] = {}
for f in findings:
if field(f, "severity") == "critical" or field(f, "biomarker_type") == "brain_method":
shape["severe"] = 1
details = detail_map(f)
+ if details.get("deprecated"):
+ shape["deprecated"] = 1
+ deepest = details.get("deepest_block")
+ if isinstance(deepest, dict) and deepest.get("start") and "deep_start" not in shape:
+ shape["deep_start"] = int(deepest["start"])
+ shape["deep_end"] = int(deepest.get("end") or deepest["start"])
+ share = details.get("dispatch_share")
+ if isinstance(share, (int, float)):
+ shape["dispatch_pct"] = max(shape.get("dispatch_pct", 0), round(share * 100))
+ if field(f, "biomarker_type") in SIZE_MARKERS:
+ start, end = field(f, "line_start"), field(f, "line_end")
+ if start and end:
+ shape["start"] = min(shape.get("start", start), start)
+ shape["end"] = max(shape.get("end", end), end)
for k in ("ccn", "nloc", "max_nesting", "lcom4", "method_count"):
v = details.get(k)
if isinstance(v, (int, float)) and v > shape.get(k, 0):
@@ -932,6 +1258,7 @@ def build_fix_first(
:func:`hot_cut` for the rule.
"""
metrics = list(metrics)
+ findings = list(findings)
keep_tests = scope == "all"
excluded = dict.fromkeys(FIX_EXCLUSIONS, 0)
hidden = excluded_types()
@@ -946,15 +1273,18 @@ def build_fix_first(
):
by_file[field(f, "file_path")].append(f)
split = {path: split_by_origin(rows) for path, rows in by_file.items()}
+ plans = list(plans)
files = _Files(
metrics,
{p: hist for p, (_shape, hist) in split.items() if hist},
_by_function(f for shape, _hist in split.values() for f in shape),
hot_cuts,
+ _clone_spans(plans),
+ _extractions(plans),
)
def out_of_scope(path: str, context: str | None = None) -> bool:
- reason = _path_exclusion(path, files.is_test(path), context)
+ reason = _path_exclusion(path, files.is_test(path), context, files.origin(path))
if reason is None or (reason == "test" and keep_tests):
return False
excluded[reason] += 1
@@ -979,6 +1309,20 @@ def build_fix_first(
if not steps:
excluded["below_min_worth"] += 1
continue
+ reason = (
+ "low_value_kind"
+ if steps[0].get("refactoring_type") in LOW_VALUE_KINDS
+ else files.unit_exclusion(
+ path,
+ steps[0].get("target_symbol"),
+ complexity=steps[0].get("refactoring_type") == "extract_method",
+ )
+ )
+ if reason is None and not _concrete(steps[0], plan_rows.get(steps[0].get("plan_id"))):
+ reason = "no_concrete_step"
+ if reason is not None:
+ excluded[reason] += 1
+ continue
units.append(_refactor_unit(row, details, steps, gain, plan_rows, files))
# Only a plan that became an item speaks for the file's findings; an
# excluded one leaves them to compete on their own.
@@ -1005,7 +1349,11 @@ def build_fix_first(
if not ready:
excluded["no_plan" if queued else reasons[0] or "no_plan"] += 1
continue
- units.append(_perf_unit(ready, files))
+ worth = [r for r in ready if _perf_worth(r)]
+ if not worth:
+ excluded["below_min_worth"] += 1
+ continue
+ units.append(_perf_unit(worth, files))
for path, (shape, history) in split.items():
if path in planned_files:
@@ -1018,7 +1366,14 @@ def build_fix_first(
if lead is None:
excluded["history_only"] += 1
continue
- units.append(_finding_unit(lead, files))
+ # A finding that is no candidate leaves the file's others to compete;
+ # the file is counted under its own lead's reason when none is left.
+ reasons = {id(f): _finding_exclusion(f, files) for f in shape}
+ eligible = primary_finding([f for f in shape if reasons[id(f)] is None])
+ if eligible is None:
+ excluded[reasons[id(lead)] or next(r for r in reasons.values() if r)] += 1
+ continue
+ units.append(_finding_unit(eligible, files, files.first_step(eligible)))
ordered = _order(units)
if item_id is not None:
@@ -1041,11 +1396,18 @@ def build_fix_first(
__all__ = [
+ "CLASS_MARKERS",
"DEFAULT_LIMIT",
+ "DISPATCH_SHARE",
"GAIN_CUTS",
+ "GROWS_ONLY_MARKERS",
"HEAD",
"HEAD_PER_KIND",
+ "LOW_VALUE_KINDS",
"MIN_WORTH",
+ "SIZE_MARKERS",
+ "SMALL_CCN",
+ "SMALL_NLOC",
"build_fix_first",
"hot_cut",
"hot_cut_offset",
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/model.py b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
index 1605d4fc3..783604db0 100644
--- a/packages/core/src/repowise/core/analysis/health/fix_first/model.py
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/model.py
@@ -46,6 +46,13 @@ FixExclusion = Literal[
"no_plan",
"below_min_worth",
"history_only",
+ "vendored",
+ "docs_example",
+ "deprecated",
+ "inherent_dispatch",
+ "small_function",
+ "no_concrete_step",
+ "low_value_kind",
]
FIX_EXCLUSIONS: tuple[str, ...] = get_args(FixExclusion)
diff --git a/packages/core/src/repowise/core/analysis/health/fix_first/text.py b/packages/core/src/repowise/core/analysis/health/fix_first/text.py
index b7f11eeac..2eb158a5d 100644
--- a/packages/core/src/repowise/core/analysis/health/fix_first/text.py
+++ b/packages/core/src/repowise/core/analysis/health/fix_first/text.py
@@ -1,8 +1,10 @@
-"""Plain-language copy for Fix-first items: titles, problems, gains.
+"""Plain-language copy for Fix-first items: titles, problems, gains, context.
-Biomarker ids and internal units (CCN, LCOM, deficit points) never reach a
-title, a why sentence or a gain; they may appear in ``facts``, which renderers
-label through their own glossary.
+Biomarker ids never reach any text field: a fact names a finding by its plain
+label. A title may carry a function's size; the why sentence never repeats it,
+and says why the problem matters here instead (who imports the file, how
+often it changes, how much of it tests run). History context is a short plain
+sentence, never a percentile.
"""
from __future__ import annotations
@@ -62,6 +64,9 @@ REFACTOR_TITLE: dict[str, str] = {
"move_method": "Move {sym} next to the code it uses",
}
+#: Appended to a why when a duplicate sits in the function being split.
+CLONED = "and part of it is duplicated, so splitting it also removes a copy"
+
BOUNDARY_NOUN = {
"db": "database",
"filesystem": "file system",
@@ -165,12 +170,20 @@ def health_gain(value: float, *, ceiling: bool) -> str:
def measured(subject: str, shape: dict[str, int]) -> str | None:
- """``walk_file: CCN 12, 60 lines, nests 4 deep`` from stored findings, or ``None``."""
+ """``Store: 12 methods in 3 groups that share little state``, or ``None``.
+
+ A function's size is a fact and may lead the title, so it is not here.
+ """
if shape.get("lcom4") and shape.get("method_count"):
return (
f"{subject}: {plural(shape['method_count'], 'method')} in "
f"{shape['lcom4']} groups that share little state"
)
+ return None
+
+
+def size_line(shape: dict[str, int]) -> str | None:
+ """``CCN 12, 60 lines, nests 4 deep`` from stored findings, or ``None``."""
parts = []
if shape.get("ccn"):
parts.append(f"CCN {shape['ccn']}")
@@ -178,7 +191,7 @@ def measured(subject: str, shape: dict[str, int]) -> str | None:
parts.append(plural(shape["nloc"], "line"))
if (shape.get("max_nesting") or 0) >= 3:
parts.append(f"nests {shape['max_nesting']} deep")
- return f"{subject}: {', '.join(parts)}" if parts else None
+ return ", ".join(parts) or None
def size_brief(shape: dict[str, int]) -> str:
@@ -193,16 +206,111 @@ def size_brief(shape: dict[str, int]) -> str:
return ", ".join(parts) or "large"
-def exposure(dependents: int | None, commits: int) -> str:
- """``; 7 files import it, changed 15 times in 90 days``, or nothing."""
+def exposure(dependents: int | None, commits: int, coverage: float | None = None) -> str:
+ """``; 7 files import it, changed 15 times in 90 days, tests run 40% of
+ its lines``, or nothing. Coverage only when a report measured the file."""
parts = []
if dependents:
parts.append(f"{plural(dependents, 'file')} import{'s' if dependents == 1 else ''} it")
if commits:
parts.append(f"changed {plural(commits, 'time')} in 90 days")
+ if coverage is not None:
+ parts.append(
+ "no test runs it" if coverage < 0.5 else f"tests run {round(coverage)}% of its lines"
+ )
return "; " + ", ".join(parts) if parts else ""
+def marker_label(marker: str) -> str:
+ """``complex_method`` reads ``Complex method``: the plain label, not the id."""
+ return humanize(marker).capitalize()
+
+
+def scope_name(symbol: str | None, path: str) -> str | None:
+ """A symbol as a reader says it; a file's top level is its module scope."""
+ short = short_symbol(symbol)
+ if short and short.rsplit(".", 1)[-1] == "__module__":
+ return f"module scope of {basename(path)}"
+ return short
+
+
+def changes(commits: int, people: int | None) -> str:
+ """``changed 13 times in 90 days; 3 people have worked on it``."""
+ out = f"changed {plural(commits, 'time')} in 90 days"
+ if people and people > 1:
+ out += f"; {people} people have worked on it"
+ return out
+
+
+#: Plain labels for history context, by marker.
+HISTORY_LABEL: dict[str, str] = {
+ "change_entropy": "scattered changes",
+ "ungoverned_hotspot": "no decision",
+ "co_change_scatter": "ripple",
+ "hidden_coupling": "hidden coupling",
+ "churn_risk": "churn",
+ "ownership_risk": "ownership",
+ "knowledge_loss": "knowledge loss",
+ "developer_congestion": "many hands",
+ "prior_defect": "past bugs",
+ "function_hotspot": "keeps changing",
+ "code_age_volatility": "old and changing",
+ "stale_governance": "stale decision",
+ "contradictory_decision": "conflicting decisions",
+}
+
+
+def _num(details: dict, key: str) -> float:
+ value = details.get(key)
+ return float(value) if isinstance(value, (int, float)) else 0.0
+
+
+def history_fact(marker: str, details: dict, function: str | None = None) -> str | None:
+ """One short plain sentence for a history marker, from its stored numbers;
+ ``None`` when the numbers it needs are absent."""
+ d = details or {}
+ if marker == "change_entropy":
+ return "its changes are spread across many unrelated commits"
+ if marker == "ungoverned_hotspot":
+ return "it changes often and no recorded decision covers it"
+ if marker == "co_change_scatter" and d.get("scatter"):
+ return f"it changes together with {int(_num(d, 'scatter'))} other files"
+ if marker == "hidden_coupling" and d.get("partner") and d.get("co_change_count"):
+ return (
+ f"it changes with {basename(str(d['partner']))} in "
+ f"{int(_num(d, 'co_change_count'))} of {int(_num(d, 'self_commits'))} commits, "
+ "with no import between them"
+ )
+ if marker == "churn_risk" and d.get("relative_churn"):
+ lines = int(_num(d, "lines_added_90d") + _num(d, "lines_deleted_90d"))
+ ratio = _num(d, "relative_churn")
+ return f"{plural(lines, 'line')} changed in 90 days, {ratio:.1f} times its size"
+ if marker == "ownership_risk" and d.get("contributor_count"):
+ share = round(_num(d, "top_owner_share") * 100)
+ return (
+ f"{int(_num(d, 'contributor_count'))} people have changed it; "
+ f"one wrote {share}% of its commits"
+ )
+ if marker == "knowledge_loss":
+ return "the person who wrote most of it is no longer the one changing it"
+ if marker == "developer_congestion" and d.get("contributor_count"):
+ return f"{int(_num(d, 'contributor_count'))} people change it, with no clear owner"
+ if marker == "prior_defect" and d.get("prior_defect_count"):
+ months = max(1, round(_num(d, "window_days") / 30)) if d.get("window_days") else 6
+ fixes = int(_num(d, "prior_defect_count"))
+ return f"{fixes} bug fix{'' if fixes == 1 else 'es'} touched it in the last {months} months"
+ if marker == "function_hotspot" and d.get("modification_count"):
+ who = function or "one function"
+ return f"{who} changed in {int(_num(d, 'modification_count'))} commits"
+ if marker == "code_age_volatility":
+ return "old code that still changes often"
+ if marker == "stale_governance":
+ return "a decision that covers it is out of date"
+ if marker == "contradictory_decision":
+ return "decisions that cover it disagree"
+ return None
+
+
def signature(name: str | None, params: list[str], returns: list[str]) -> str:
"""``compute_x(a, b) -> c``; a long parameter list is cut with its count."""
shown = ", ".join(params[:4]) + (f", +{len(params) - 4} more" if len(params) > 4 else "")
@@ -217,22 +325,29 @@ def first_sentence(text: str) -> str:
__all__ = [
"BOUNDARY_NOUN",
+ "CLONED",
"FINDING_TITLE",
"FIX_STRATEGY",
+ "HISTORY_LABEL",
"PERF_SHAPE",
"PROBLEM",
"REFACTOR_TITLE",
"TITLE_MAX",
"basename",
+ "changes",
"clip",
"exposure",
"first_sentence",
"health_gain",
+ "history_fact",
"humanize",
+ "marker_label",
"measured",
"plural",
"problem",
+ "scope_name",
"short_symbol",
"signature",
"size_brief",
+ "size_line",
]
diff --git a/packages/core/src/repowise/core/analysis/health/perf/sink_reach.py b/packages/core/src/repowise/core/analysis/health/perf/sink_reach.py
index 8be4dc37e..f6ed156c5 100644
--- a/packages/core/src/repowise/core/analysis/health/perf/sink_reach.py
+++ b/packages/core/src/repowise/core/analysis/health/perf/sink_reach.py
@@ -151,6 +151,7 @@ def _hits_for_function(
extra: dict[str, Any] = {"func_start": fact.func_start} if carry_func_start else {}
loop_facts = dict(fact.loop_call_facts) if carry_loop else {}
+ loop_lines = dict(fact.loop_call_lines) if carry_loop else {}
hits: list[PerfHit] = []
seen: set[str] = set()
for target_name, call_line in entries(fact):
@@ -177,6 +178,7 @@ def _hits_for_function(
path=(a_sid, *chain),
resolution_basis=basis,
loop=loop_facts.get(call_line),
+ loop_line=loop_lines.get(call_line, 0),
**extra,
)
)
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py b/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py
index b86c5421f..f8a687c8c 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/fix_first.py
@@ -69,7 +69,10 @@ async def _metrics(session: AsyncSession, repo_id: str, paths: set[str]) -> list
HealthFileMetric.file_path,
HealthFileMetric.nloc,
HealthFileMetric.is_test,
+ HealthFileMetric.code_origin,
+ HealthFileMetric.line_coverage_pct,
GitMetadata.commit_count_90d,
+ GitMetadata.contributor_count,
GraphMetric.in_degree.label("dependents"),
)
.outerjoin(
@@ -208,10 +211,8 @@ async def _findings(
f.public_id,
f.dimension,
f.status,
- # Only a code-shape finding's numbers are quoted.
- case((f.biomarker_type.in_(history), None), else_=f.details_json).label(
- "details_json"
- ),
+ # History numbers become plain context sentences.
+ f.details_json,
).where(
_eligible_findings(repo_id),
or_(
@@ -305,21 +306,36 @@ def _steps(refactoring: list[Any]) -> list[dict[str, Any]]:
return [s for r in refactoring if r.details for s in r.details.get("steps") or []]
-async def _plans(session: AsyncSession, repo_id: str, steps: list[dict[str, Any]]) -> list[Any]:
- """The plans those steps name: span, signature, evidence."""
+async def _plans(
+ session: AsyncSession, repo_id: str, steps: list[dict[str, Any]], files: set[str]
+) -> list[Any]:
+ """The plans those steps name (span, signature, evidence), the open
+ Extract Method plans in ``files``, where a finding with no plan of its own
+ takes its first concrete step from, and every open Extract Helper plan,
+ whose occurrences say where verified duplicates sit (a plan is stored at
+ one anchor file and names every site, so it is not filtered by file)."""
ids = {s.get("plan_id") for s in steps if s.get("plan_id")}
- if not ids:
+ s = RefactoringSuggestion
+ named = s.public_id.in_(ids) if ids else None
+ extractions = (
+ and_(s.refactoring_type == "extract_method", s.status == "open", s.file_path.in_(files))
+ if files
+ else None
+ )
+ helpers = and_(s.refactoring_type == "extract_helper", s.status == "open")
+ wanted = [c for c in (named, extractions, helpers) if c is not None]
+ if not wanted:
return []
return _plain(
await session.execute(
select(
- RefactoringSuggestion.public_id,
- RefactoringSuggestion.evidence_json,
- RefactoringSuggestion.plan_json,
- ).where(
- RefactoringSuggestion.repository_id == repo_id,
- RefactoringSuggestion.public_id.in_(ids),
- )
+ s.public_id,
+ s.refactoring_type,
+ s.file_path,
+ s.target_symbol,
+ s.evidence_json,
+ s.plan_json,
+ ).where(s.repository_id == repo_id, or_(*wanted))
)
)
@@ -412,7 +428,7 @@ async def _build(
findings=[*findings, *(r for r in history_only if r.file_path not in full | planned)],
refactoring=refactoring,
performance=performance,
- plans=await _plans(session, repository_id, steps),
+ plans=await _plans(session, repository_id, steps, full),
limit=limit,
scope=scope,
item_id=item_id,
diff --git a/packages/types/src/fix-first.ts b/packages/types/src/fix-first.ts
index a23e9bf42..b36348c31 100644
--- a/packages/types/src/fix-first.ts
+++ b/packages/types/src/fix-first.ts
@@ -31,7 +31,14 @@ export type FixExclusion =
| "no_strategy"
| "no_plan"
| "below_min_worth"
- | "history_only";
+ | "history_only"
+ | "vendored"
+ | "docs_example"
+ | "deprecated"
+ | "inherent_dispatch"
+ | "small_function"
+ | "no_concrete_step"
+ | "low_value_kind";
/** `all` keeps test files, labelled in `context`. */
export type FixScope = "production" | "all";
diff --git a/packages/ui/__tests__/health/fix-first.test.tsx b/packages/ui/__tests__/health/fix-first.test.tsx
index 37aaba012..268c10d66 100644
--- a/packages/ui/__tests__/health/fix-first.test.tsx
+++ b/packages/ui/__tests__/health/fix-first.test.tsx
@@ -31,7 +31,7 @@ function renderList(overrides: Partial<React.ComponentProps<typeof FixFirstList>
describe("Fix first header", () => {
it("states shown of eligible and every nonzero exclusion with its count", () => {
expect(fixFirstScopeSentence(FIX_FIRST_QUEUE)).toBe(
- "3 of 423 eligible items. Excluded: 612 in tests, 91 tooling, 5 generated or vendored, " +
+ "3 of 423 eligible items. Excluded: 612 in tests, 91 tooling, 5 generated, " +
"158 expected repetition, 12 with no safe fix, 505 below the worth floor, 167 history only.",
);
});
diff --git a/packages/ui/__tests__/health/fixtures/fix-first.ts b/packages/ui/__tests__/health/fixtures/fix-first.ts
index e6d352a5d..86351fac0 100644
--- a/packages/ui/__tests__/health/fixtures/fix-first.ts
+++ b/packages/ui/__tests__/health/fixtures/fix-first.ts
@@ -600,7 +600,14 @@ export const FIX_FIRST_QUEUE: FixFirstQueue = {
"no_strategy": 0,
"no_plan": 12,
"below_min_worth": 505,
- "history_only": 167
+ "history_only": 167,
+ "vendored": 0,
+ "docs_example": 0,
+ "deprecated": 0,
+ "inherent_dispatch": 0,
+ "small_function": 0,
+ "no_concrete_step": 0,
+ "low_value_kind": 0
}
},
"by_improves": {
diff --git a/packages/ui/src/health/fix-first/scope.ts b/packages/ui/src/health/fix-first/scope.ts
index 7300edb76..de97e8af5 100644
--- a/packages/ui/src/health/fix-first/scope.ts
+++ b/packages/ui/src/health/fix-first/scope.ts
@@ -33,25 +33,39 @@ export function tierReason(item: Pick<FixItem, "why_ranked">): string | null {
export const EXCLUSION_LABEL: Record<FixExclusion, string> = {
test: "in tests",
tooling: "tooling",
- generated: "generated or vendored",
+ generated: "generated",
+ vendored: "vendored",
+ docs_example: "docs and examples",
expected: "expected repetition",
unknown: "where the code's context is unknown",
no_strategy: "with no fix strategy",
no_plan: "with no safe fix",
below_min_worth: "below the worth floor",
history_only: "history only",
+ deprecated: "deprecated",
+ inherent_dispatch: "one long dispatch on a value",
+ small_function: "small functions",
+ no_concrete_step: "with no concrete first edit",
+ low_value_kind: "of a kind rarely worth doing",
};
const EXCLUSION_ORDER: FixExclusion[] = [
"test",
"tooling",
"generated",
+ "vendored",
+ "docs_example",
"expected",
"unknown",
"no_strategy",
"no_plan",
"below_min_worth",
"history_only",
+ "deprecated",
+ "inherent_dispatch",
+ "small_function",
+ "no_concrete_step",
+ "low_value_kind",
];
/**
diff --git a/packages/web/src/components/code-health/fix-first-section.test.tsx b/packages/web/src/components/code-health/fix-first-section.test.tsx
index c355ae071..2acbd404b 100644
--- a/packages/web/src/components/code-health/fix-first-section.test.tsx
+++ b/packages/web/src/components/code-health/fix-first-section.test.tsx
@@ -57,6 +57,13 @@ function queue(items: FixItem[]): FixFirstQueue {
no_plan: 0,
below_min_worth: 3,
history_only: 0,
+ vendored: 0,
+ docs_example: 0,
+ deprecated: 0,
+ inherent_dispatch: 0,
+ small_function: 0,
+ no_concrete_step: 0,
+ low_value_kind: 0,
},
},
by_improves: { defect: 4, maintainability: 0, performance: 0 },
diff --git a/tests/unit/analysis/test_actions_rules.py b/tests/unit/analysis/test_actions_rules.py
index 2d224067a..0f2da235b 100644
--- a/tests/unit/analysis/test_actions_rules.py
+++ b/tests/unit/analysis/test_actions_rules.py
@@ -269,15 +269,16 @@ def _fix_items():
def test_fix_first_emits_now_and_next_and_leaves_later() -> None:
items = _fix_items()
- assert [i.tier for i in items] == ["now", "next", "later"]
+ # The growing, reachable database loop leads; it needs judgment.
+ assert [i.tier for i in items] == ["next", "now", "later"]
actions = _run(code.fix_first, _facts(fix_first=items)).actions
assert [(a.tier, a.title) for a in actions] == [
- ("act_now", items[0].title),
- ("plan", items[1].title),
+ ("plan", items[0].title),
+ ("act_now", items[1].title),
]
- assert actions[0].horizons == ("week", "quarter") and actions[1].horizons == ("quarter",)
- assert actions[1].surface == "performance"
- assert actions[0].commands[0].mcp == f'get_health(fix_id="{items[0].id}")'
+ assert actions[1].horizons == ("week", "quarter") and actions[0].horizons == ("quarter",)
+ assert actions[0].surface == "performance"
+ assert actions[1].commands[0].mcp == f'get_health(fix_id="{items[1].id}")'
assert len({a.action_id for a in actions}) == 2
diff --git a/tests/unit/cli/test_health_cmd_controls.py b/tests/unit/cli/test_health_cmd_controls.py
index ea70ddadb..92793818a 100644
--- a/tests/unit/cli/test_health_cmd_controls.py
+++ b/tests/unit/cli/test_health_cmd_controls.py
@@ -127,6 +127,8 @@ def test_the_report_leads_with_fix_first() -> None:
_render_fix_first(None)
out = console.file.getvalue()
assert out.startswith("\nFix first (3 of 3 eligible")
- assert " 1. Extract lines 20-35 of run into sum_rows (+1 more step) " in out
+ # The growing, reachable database loop leads; the refactor follows.
+ assert " 1. Batch the database calls loops make through load_all " in out
+ assert " 2. Extract lines 20-35 of run into sum_rows (+1 more step) " in out
assert "src/core.py:20" in out
assert "verify: pytest tests/test_core_0.py" in out
diff --git a/tests/unit/generation/test_editor_file_fetcher.py b/tests/unit/generation/test_editor_file_fetcher.py
index fb07ec48a..8cfa86593 100644
--- a/tests/unit/generation/test_editor_file_fetcher.py
+++ b/tests/unit/generation/test_editor_file_fetcher.py
@@ -627,8 +627,8 @@ async def test_code_health_names_production_files_only(session, repo, tmp_path):
"severity": "high",
"function_name": "f",
"line_start": 1,
- "line_end": 9,
- "details": {},
+ "line_end": 130,
+ "details": {"ccn": 30, "nloc": 120, "max_nesting": 4, "deepest_block": {"start": 40, "end": 52}},
"health_impact": 2.0,
"reason": "brain method",
}
diff --git a/tests/unit/health/fix_first_rows.py b/tests/unit/health/fix_first_rows.py
index 73a7e5d2f..b8a96e824 100644
--- a/tests/unit/health/fix_first_rows.py
+++ b/tests/unit/health/fix_first_rows.py
@@ -29,10 +29,12 @@ FINDINGS = [
{"file_path": "src/core.py", "biomarker_type": "complex_method", "severity": "high",
"function_name": "run", "line_start": 10, "line_end": 60, "health_impact": 1.0,
"reason": "run has cyclomatic complexity 14", "public_id": "finding_c1",
- "dimension": "defect", "details": {"ccn": 14, "nloc": 50, "max_nesting": 4}},
+ "dimension": "defect",
+ "details": {"ccn": 14, "nloc": 50, "max_nesting": 4, "deepest_block": {"start": 30, "end": 44}}},
{"file_path": "src/plain.py", "biomarker_type": "nested_complexity", "severity": "medium",
"function_name": "walk", "line_start": 5, "line_end": 40, "health_impact": 0.6,
- "reason": "walk nests 5 levels deep", "public_id": "finding_n1", "dimension": "defect"},
+ "reason": "walk nests 5 levels deep", "public_id": "finding_n1", "dimension": "defect",
+ "details": {"max_nesting": 5, "deepest_block": {"start": 18, "end": 26}}},
# Only history: context, never an item.
{"file_path": "src/hist.py", "biomarker_type": "co_change_scatter", "severity": "high",
"health_impact": 1.2, "reason": "co-changes with 20 files", "public_id": "finding_h2",
@@ -90,6 +92,8 @@ PLANS = [
"suggested_name": "sum_rows"}},
{"public_id": "refac2_tiny", "refactoring_type": "extract_method",
"evidence": {"slice_nloc": 2, "ccn_removed": 1}, "plan": {"span": {"start": 40, "end": 41}}},
+ {"public_id": "refac2_t", "refactoring_type": "extract_method",
+ "evidence": {"slice_nloc": 9, "ccn_removed": 2}, "plan": {"span": {"start": 30, "end": 45}}},
]
diff --git a/tests/unit/health/test_deepest_block.py b/tests/unit/health/test_deepest_block.py
new file mode 100644
index 000000000..b47020e1e
--- /dev/null
+++ b/tests/unit/health/test_deepest_block.py
@@ -0,0 +1,115 @@
+"""Each function's deepest nested block, stored where a fix can start.
+
+A "break up this function" item needs a first concrete step. When no
+extraction plan covers the function, the deepest nested block is that step,
+so the walker records its lines and size findings carry them as
+``deepest_block``. No CCN, nesting or score moves, and the finding id does not.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.analysis.health.complexity import walk_file
+from repowise.core.analysis.health.duplication import DuplicationReport
+from repowise.core.analysis.health.engine import HealthAnalyzer
+from repowise.core.analysis.health.finding_identity import finding_public_id
+from repowise.core.analysis.health.models import HealthFindingData, Severity
+
+_DEEP = """
+def deep(rows, flag):
+ total = 0
+ for row in rows:
+ if row.a:
+ total += 1
+ if row.b:
+ for item in row.items:
+ if item.ok:
+ while item.more:
+ if flag:
+ total += 2
+ item = item.next
+ return total
+
+def flat(x):
+ return x + 1
+"""
+
+
+def _functions() -> dict:
+ fcx = walk_file("/tmp/deep.py", "python", _DEEP.encode())
+ if not fcx.functions:
+ pytest.skip("python grammar unavailable")
+ return {fc.name: fc for fc in fcx.functions}
+
+
+def test_a_small_deepest_block_widens_to_its_nearest_four_line_block() -> None:
+ deep = _functions()["deep"]
+ assert deep.max_nesting == 6
+ # The 6-deep ``if flag`` spans 3 lines; the ``while`` around it spans 4.
+ assert deep.deepest_block == (10, 13)
+
+
+def test_a_deepest_block_of_four_lines_is_kept() -> None:
+ src = (
+ "def wide(rows):\n"
+ " for row in rows:\n"
+ " if row.ok:\n"
+ " a = 1\n"
+ " b = 2\n"
+ " c = 3\n"
+ )
+ fcx = walk_file("/tmp/wide.py", "python", src.encode())
+ if not fcx.functions:
+ pytest.skip("python grammar unavailable")
+ assert fcx.functions[0].deepest_block == (3, 6)
+
+
+def test_a_flat_function_records_none() -> None:
+ assert _functions()["flat"].deepest_block is None
+
+
+def test_size_findings_carry_it_and_keep_their_id() -> None:
+ fcx = walk_file("/tmp/deep.py", "python", _DEEP.encode())
+ pf = SimpleNamespace(
+ file_info=SimpleNamespace(
+ path="src/deep.py", language="python", abs_path="/tmp/deep.py", is_test=False
+ ),
+ symbols=[],
+ )
+ _, findings, _ = HealthAnalyzer(graph=None)._evaluate_file(
+ pf,
+ fcx,
+ paired_tests=set(),
+ package_roots=set(),
+ disabled=[],
+ dup_report=DuplicationReport(),
+ )
+ nested = next(f for f in findings if f.biomarker_type == "nested_complexity")
+ assert nested.details["deepest_block"] == {"start": 10, "end": 13}
+ without = HealthFindingData(
+ **{
+ **nested.__dict__,
+ "details": {k: v for k, v in nested.details.items() if k != "deepest_block"},
+ }
+ )
+ assert finding_public_id(nested) == finding_public_id(without)
+
+
+def test_other_findings_do_not_carry_it() -> None:
+ finding = HealthFindingData(
+ biomarker_type="error_handling",
+ severity=Severity.MEDIUM,
+ file_path="src/a.py",
+ function_name="deep",
+ line_start=2,
+ line_end=2,
+ details={},
+ health_impact=0.5,
+ )
+ from repowise.core.analysis.health.engine import _mark_deepest_block
+
+ _mark_deepest_block([finding], list(_functions().values()))
+ assert "deepest_block" not in finding.details
diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.py
index 3e6f0d5bb..51002113f 100644
--- a/tests/unit/health/test_fix_first_build.py
+++ b/tests/unit/health/test_fix_first_build.py
@@ -48,6 +48,13 @@ def test_each_exclusion_is_counted_by_reason() -> None:
"no_plan": 0,
"below_min_worth": 1,
"history_only": 1,
+ "vendored": 0,
+ "docs_example": 0,
+ "deprecated": 0,
+ "inherent_dispatch": 0,
+ "small_function": 0,
+ "no_concrete_step": 0,
+ "low_value_kind": 0,
}
assert queue.totals.eligible == 3
assert queue.totals.candidates == 3 + 7
@@ -56,23 +63,33 @@ def test_each_exclusion_is_counted_by_reason() -> None:
def test_history_never_leads_and_rides_along_as_context() -> None:
queue = _build()
+ # The production, entry-reachable, growing database loop shares the top
+ # band with the refactor and leads it on score.
assert [i.target.file_path for i in queue.items] == [
- "src/core.py",
"src/repo.py",
+ "src/core.py",
"src/plain.py",
]
- core = queue.lead
+ core = queue.items[1]
assert core.kind == "refactor"
assert "change" not in core.title.lower() and "entropy" not in core.why
- assert [c.label for c in core.context] == ["changes in 90 days", "change entropy"]
+ assert [(c.label, c.value) for c in core.context] == [
+ ("recent changes", "changed 12 times in 90 days"),
+ ("scattered changes", "its changes are spread across many unrelated commits"),
+ ]
# The history-only file is no item at all.
assert all(i.target.file_path != "src/hist.py" for i in queue.items)
def test_text_quotes_the_stored_numbers() -> None:
- core = _build().lead
+ core = next(i for i in _build().items if i.kind == "refactor")
assert core.title == "Extract lines 20-35 of run into sum_rows (+1 more step)"
- assert core.why == "run: CCN 14, 50 lines, nests 4 deep; 9 files import it, changed 12 times in 90 days."
+ # The size is a fact; the why says why it matters here.
+ assert core.why == (
+ "run has many independent paths through it; 9 files import it, "
+ "changed 12 times in 90 days."
+ )
+ assert ("size", "CCN 14, 50 lines, nests 4 deep") in [(f.label, f.value) for f in core.facts]
assert core.action.steps[0].text == "Extract lines 20-35 of run into sum_rows(rows, limit) -> total"
assert core.action.steps[1].text == "Extract lines 40-41 of run into a helper"
# The model's credit is the gain, with one decimal; the builder does not re-judge it.
@@ -126,9 +143,13 @@ def test_no_kind_takes_more_than_three_of_the_first_five() -> None:
row["file_path"] = f"src/core{n}.py"
row["details"]["steps"] = row["details"]["steps"][:1]
refactors.append(row)
- # Same value as the refactors (production, loop size unknown), lower tier.
+ # Same value as the refactors (production, loop size unknown, reachable),
+ # lower tier.
perf = _perf("perf2_a", "s")
- perf["details"] = {**perf["details"], "facets": {"loop_magnitude": "unknown"}}
+ perf["details"] = {
+ **perf["details"],
+ "facets": {"loop_magnitude": "unknown", "exposure": "entry_reachable"},
+ }
queue = _build(refactoring=refactors, performance=[perf], findings=[])
# The fourth place goes to the perf fix; the fifth back to a refactor,
# since no other kind has anything left at value 2 or above.
@@ -173,14 +194,14 @@ def test_value_leads_tier_and_a_huge_function_says_so() -> None:
"""A function far past every bar outranks tidy work that is safer to start."""
huge = {**FINDINGS[1], "file_path": "src/plain.py", "function_name": "walk",
"public_id": "finding_huge", "details": {"ccn": 249, "nloc": 1280, "max_nesting": 5}}
- queue = _build(findings=[*FINDINGS, huge])
+ queue = _build(findings=[*FINDINGS, huge], performance=[])
lead = queue.lead
assert (lead.kind, lead.tier, lead.target.file_path) == ("finding", "next", "src/plain.py")
assert lead.title == "Break up walk (CCN 249, 1,280 lines)"
assert ("problem size", "4") in [(f.factor, f.value) for f in lead.why_ranked]
# With a plan, the title names the problem and the first concrete step.
big = {**FINDINGS[1], "details": {"ccn": 120, "nloc": 900, "max_nesting": 6}}
- planned = _build(findings=[big]).lead
+ planned = _build(findings=[big], performance=[]).lead
assert planned.title == (
"Start breaking up run (CCN 120, 900 lines): first lift lines 20-35 into sum_rows"
)
diff --git a/tests/unit/health/test_fix_first_precision.py b/tests/unit/health/test_fix_first_precision.py
new file mode 100644
index 000000000..afcd33e4e
--- /dev/null
+++ b/tests/unit/health/test_fix_first_precision.py
@@ -0,0 +1,505 @@
+"""Fix first's precision levers over plain rows (SPEC_W7 F1-F8 and the lift).
+
+Each lever narrows what may be an item or moves its value; none touches a
+score. Each test builds the smallest rows that show the lever firing and the
+nearest case where it must not.
+"""
+
+from __future__ import annotations
+
+from repowise.core.analysis.health.fix_first import build_fix_first
+from tests.unit.health.fix_first_rows import FINDINGS, METRICS
+
+_COMPLEX = FINDINGS[1] # run in src/core.py: CCN 14, 50 lines, nests 4 deep
+
+
+def _finding(path: str = "src/core.py", **details) -> dict:
+ return {
+ **_COMPLEX,
+ "file_path": path,
+ "public_id": f"finding_{path}",
+ "details": {"ccn": 14, "nloc": 50, "max_nesting": 4, "deepest_block": {"start": 20, "end": 30},
+ **details},
+ }
+
+
+def _metric(path: str = "src/core.py", **over) -> dict:
+ return {**METRICS[0], "file_path": path, **over}
+
+
+def _queue(findings, metrics=None, **over):
+ return build_fix_first(
+ metrics=metrics if metrics is not None else [_metric(f["file_path"]) for f in findings],
+ findings=findings,
+ **over,
+ )
+
+
+# --- F1: code that does not ship -------------------------------------------------
+
+
+def test_stored_origin_excludes_vendored_docs_generated_and_tooling() -> None:
+ origins = ("vendored", "docs_example", "generated", "tooling")
+ findings = [_finding(f"src/{o}.py") for o in origins]
+ metrics = [_metric(f"src/{o}.py", code_origin=o) for o in origins]
+ queue = _queue(findings, metrics)
+ assert queue.items == ()
+ assert {o: queue.totals.excluded[o] for o in origins} == dict.fromkeys(origins, 1)
+
+
+def test_production_origin_and_an_unrecorded_one_stay_eligible() -> None:
+ findings = [_finding("src/a.py"), _finding("src/b.py")]
+ metrics = [_metric("src/a.py", code_origin="production"), _metric("src/b.py")]
+ assert len(_queue(findings, metrics).items) == 2
+
+
+def test_test_origin_is_kept_under_scope_all() -> None:
+ findings = [_finding("src/check.py")]
+ metrics = [_metric("src/check.py", code_origin="test")]
+ assert _queue(findings, metrics).totals.excluded["test"] == 1
+ assert len(_queue(findings, metrics, scope="all").items) == 1
+
+
+def test_a_vendored_directory_counts_as_vendored() -> None:
+ queue = _queue([_finding("lib/vendor/x.py")])
+ assert queue.totals.excluded["vendored"] == 1
+
+
+def test_a_deprecated_function_is_no_item() -> None:
+ queue = _queue([_finding(deprecated=True)])
+ assert queue.items == () and queue.totals.excluded["deprecated"] == 1
+ assert len(_queue([_finding()]).items) == 1
+
+
+# --- F2: one long dispatch on one value -------------------------------------------
+
+
+def _helper(path: str = "src/core.py", start: int = 25, end: int = 40) -> dict:
+ """A verified duplicate: an Extract Helper plan stored at another file."""
+ return {"public_id": f"refac3_h{start}", "refactoring_type": "extract_helper",
+ "file_path": "src/other.py", "target_symbol": "other",
+ "plan": {"occurrences": [
+ {"file": "src/other.py", "line_start": 5, "line_end": 20},
+ {"file": path, "line_start": start, "line_end": end}]}}
+
+
+def _dry(path: str = "src/core.py", start: int = 25, end: int = 40) -> dict:
+ return {"file_path": path, "biomarker_type": "dry_violation", "severity": "medium",
+ "line_start": start, "line_end": end, "health_impact": 0.4,
+ "public_id": f"finding_dry_{start}", "dimension": "maintainability",
+ "details": {"clone_pair_count": 1}}
+
+
+def test_a_dispatch_function_is_no_candidate() -> None:
+ queue = _queue([_finding(dispatch_share=0.8)])
+ assert queue.items == () and queue.totals.excluded["inherent_dispatch"] == 1
+
+
+def test_a_lower_dispatch_share_stays() -> None:
+ assert len(_queue([_finding(dispatch_share=0.5)]).items) == 1
+
+
+def test_a_duplicate_inside_the_dispatch_function_keeps_it() -> None:
+ queue = _queue([_finding(dispatch_share=0.8)], plans=[_helper()])
+ assert [i.target.symbol for i in queue.items] == ["run"]
+ # A duplicate elsewhere in the file does not.
+ away = _queue([_finding(dispatch_share=0.8)], plans=[_helper(start=200, end=220)])
+ assert away.items == () and away.totals.excluded["inherent_dispatch"] == 1
+
+
+def test_an_unverified_clone_finding_rescues_nothing() -> None:
+ """``dry_violation`` also pairs import blocks and data literals."""
+ queue = _queue([_finding(dispatch_share=0.8), _dry()])
+ assert queue.items == () and queue.totals.excluded["inherent_dispatch"] == 1
+
+
+def test_the_files_other_findings_still_compete() -> None:
+ handler = {**_COMPLEX, "biomarker_type": "error_handling", "function_name": "load",
+ "public_id": "finding_eh", "line_start": 70, "line_end": 70,
+ "health_impact": 0.5, "details": {}}
+ queue = _queue([_finding(dispatch_share=0.9), handler])
+ assert [i.target.symbol for i in queue.items] == ["load"]
+ assert queue.totals.excluded["inherent_dispatch"] == 0
+
+
+def test_a_dispatch_function_plan_is_no_candidate() -> None:
+ from tests.unit.health.fix_first_rows import PLANS, REFACTORING
+
+ queue = build_fix_first(
+ metrics=[_metric()], findings=[_finding(dispatch_share=0.7)],
+ refactoring=REFACTORING[:1], plans=PLANS,
+ )
+ # The plan and then the finding it leaves behind: both on the dispatch.
+ assert queue.items == () and queue.totals.excluded["inherent_dispatch"] == 2
+
+
+# --- F3: small functions --------------------------------------------------------
+
+
+def test_a_small_simple_function_is_no_candidate() -> None:
+ queue = _queue([_finding(ccn=12, nloc=22)])
+ assert queue.items == () and queue.totals.excluded["small_function"] == 1
+
+
+def test_either_floor_keeps_a_function() -> None:
+ assert len(_queue([_finding(ccn=12, nloc=30)]).items) == 1
+ assert len(_queue([_finding(ccn=15, nloc=12)]).items) == 1
+
+
+def test_a_finding_with_no_line_count_is_measured_by_its_span() -> None:
+ short = {**_finding(ccn=6), "line_start": 10, "line_end": 25}
+ del short["details"]["nloc"]
+ assert _queue([short]).totals.excluded["small_function"] == 1
+ long = {**short, "line_end": 70}
+ assert len(_queue([long]).items) == 1
+
+
+def test_a_small_function_outside_the_size_markers_is_judged_by_its_own_rule() -> None:
+ condition = {**_finding(ccn=6, nloc=10), "biomarker_type": "complex_conditional"}
+ assert _queue([condition]).totals.excluded["small_function"] == 0
+
+
+# --- F4: every item names a concrete edit ----------------------------------------
+
+
+def _extraction(start: int = 22, end: int = 34, ccn_removed: int = 3) -> dict:
+ return {"public_id": f"refac2_x{start}", "refactoring_type": "extract_method",
+ "file_path": "src/core.py", "target_symbol": "run",
+ "evidence": {"slice_nloc": end - start, "ccn_removed": ccn_removed},
+ "plan": {"span": {"start": start, "end": end}, "params": ["rows"],
+ "suggested_name": "total_rows"}}
+
+
+def test_a_size_finding_starts_at_the_best_stored_extraction() -> None:
+ plans = [_extraction(22, 34, 3), _extraction(40, 44, 1)]
+ item = _queue([_finding()], plans=plans).lead
+ assert item.action.steps[0].text == "Extract lines 22-34 of run into total_rows(rows)"
+ assert item.action.steps[0].line == 22
+
+
+def test_without_an_extraction_it_starts_at_the_deepest_block() -> None:
+ item = _queue([_finding()]).lead
+ assert item.action.steps[0].text == (
+ "Start with lines 20-30, where it nests 4 deep: return early or move it into a helper"
+ )
+ assert (item.action.steps[0].file_path, item.action.steps[0].line) == ("src/core.py", 20)
+
+
+def test_a_size_finding_with_no_concrete_step_is_no_candidate() -> None:
+ bare = _finding()
+ bare["details"] = {k: v for k, v in bare["details"].items() if k != "deepest_block"}
+ queue = _queue([bare])
+ assert queue.items == () and queue.totals.excluded["no_concrete_step"] == 1
+
+
+def test_a_class_finding_without_a_plan_is_no_candidate() -> None:
+ god = {**_finding(), "biomarker_type": "god_class", "function_name": "Store"}
+ assert _queue([god]).totals.excluded["no_concrete_step"] == 1
+
+
+def test_a_line_finding_names_its_line() -> None:
+ handler = {**_finding(), "biomarker_type": "error_handling", "line_start": 77}
+ step = _queue([handler]).lead.action.steps[0]
+ assert (step.line, step.file_path) == (77, "src/core.py")
+
+
+def _opportunity(kind: str, plan: dict | None) -> tuple[dict, list[dict]]:
+ from tests.unit.health.fix_first_rows import REFACTORING
+
+ row = {**REFACTORING[0], "lead_refactoring_type": kind, "lead_biomarker": None,
+ "details": {**REFACTORING[0]["details"], "steps": [
+ {**REFACTORING[0]["details"]["steps"][0], "refactoring_type": kind,
+ "plan_id": "refac2_k", "target_symbol": "Store.save"}]}}
+ plans = [{"public_id": "refac2_k", "refactoring_type": kind, "plan": plan}] if plan else []
+ return row, plans
+
+
+def _refactor_queue(kind: str, plan: dict | None):
+ row, plans = _opportunity(kind, plan)
+ return build_fix_first(metrics=[_metric()], refactoring=[row], plans=plans)
+
+
+def _step_text(kind: str, plan: dict) -> str:
+ """A step's text as an opportunity lists it, led by any step."""
+ from repowise.core.analysis.health.fix_first.build import _refactor_step
+
+ row, _plans = _opportunity(kind, plan)
+ return _refactor_step(1, row["details"]["steps"][0], {"plan": plan}).text
+
+
+def test_a_move_step_names_its_destination() -> None:
+ assert _step_text("move_method", {"to_class": "Ledger"}) == "Move Store.save to Ledger"
+
+
+def test_break_cycle_needs_the_import_line() -> None:
+ edges = [{"from": "src/a.py", "to": "src/b.py"}]
+ assert _refactor_queue("break_cycle", {"cut_edges": edges}).totals.excluded[
+ "no_concrete_step"] == 1
+ lined = _refactor_queue("break_cycle", {"cut_edges": [{**edges[0], "line": 7}]})
+ assert lined.lead.action.steps[0].text == "Cut the import of b.py in a.py (line 7)"
+
+
+def test_split_file_needs_named_groups() -> None:
+ unnamed = {"groups": [{"symbols": ["a", "b"]}]}
+ assert _refactor_queue("split_file", unnamed).totals.excluded["no_concrete_step"] == 1
+ named = {"groups": [{"name": "io", "symbols": ["read"]}, {"name": "ui", "symbols": ["draw"]}]}
+ assert _refactor_queue("split_file", named).lead.action.steps[0].text == (
+ "Split core.py into io, ui"
+ )
+
+
+def test_an_extract_method_step_without_a_span_is_no_candidate() -> None:
+ assert _refactor_queue("extract_method", {"params": []}).totals.excluded[
+ "no_concrete_step"] == 1
+
+
+# --- F7: string building in a bounded loop -------------------------------------
+
+
+def _concat(**facets) -> dict:
+ from tests.unit.health.fix_first_rows import _perf
+
+ row = _perf("perf3_concat", "", biomarker_type="string_concat_in_loop", boundary_kind=None,
+ fix_strategy="buffer_string_accumulation")
+ row["details"] = {**row["details"], "facets": {**row["details"]["facets"], **facets}}
+ return row
+
+
+def _perf_queue(*rows):
+ return build_fix_first(metrics=[_metric("src/repo.py")], performance=list(rows))
+
+
+def test_string_concat_needs_a_loop_that_grows() -> None:
+ assert len(_perf_queue(_concat()).items) == 1
+ for magnitude in ("bounded", "unknown"):
+ queue = _perf_queue(_concat(loop_magnitude=magnitude))
+ assert queue.items == () and queue.totals.excluded["below_min_worth"] == 1
+
+
+def test_other_causes_keep_an_unknown_loop() -> None:
+ from tests.unit.health.fix_first_rows import _perf
+
+ row = _perf("perf3_db", "src/db.py::fetch")
+ row["details"] = {**row["details"], "facets": {"loop_magnitude": "unknown"}}
+ assert len(_perf_queue(row).items) == 1
+
+
+# --- F8: unknown loops no entry point reaches -----------------------------------
+
+
+def _value(**facets) -> str:
+ from tests.unit.health.fix_first_rows import _perf
+
+ row = _perf("perf3_v", "src/db.py::fetch")
+ row["details"] = {**row["details"], "facets": facets}
+ item = _perf_queue(row).lead
+ return next(f.value for f in item.why_ranked if f.factor == "value")
+
+
+def test_an_unknown_loop_no_entry_reaches_drops_a_step() -> None:
+ assert _value(loop_magnitude="unknown", exposure="not_entry_reachable") == "1"
+ assert _value(loop_magnitude="unknown") == "1"
+
+
+def test_reach_or_a_known_loop_keeps_the_step() -> None:
+ assert _value(loop_magnitude="unknown", exposure="entry_reachable") == "2"
+ assert _value(loop_magnitude="grows_with_data", exposure="not_entry_reachable") == "2"
+
+
+# --- lift: a duplicate inside the function ---------------------------------------
+
+
+def _ranked(item, factor: str) -> str:
+ return next(f.value for f in item.why_ranked if f.factor == factor)
+
+
+def test_a_duplicate_inside_lifts_a_complexity_unit_one_step() -> None:
+ plain = _queue([_finding()]).lead
+ lifted = _queue([_finding()], plans=[_helper()]).lead
+ assert int(_ranked(lifted, "value")) == int(_ranked(plain, "value")) + 1
+ assert _ranked(lifted, "duplicate inside") == "yes"
+ assert "duplicated" in lifted.why and "duplicated" not in plain.why
+
+
+def test_a_duplicate_elsewhere_in_the_file_does_not_lift() -> None:
+ item = _queue([_finding()], plans=[_helper(start=200, end=220)]).lead
+ assert _ranked(item, "duplicate inside") == "no"
+
+
+def test_an_unverified_clone_finding_does_not_lift() -> None:
+ item = _queue([_finding(), _dry()]).lead
+ assert _ranked(item, "duplicate inside") == "no"
+
+
+def test_a_duplicate_does_not_lift_a_line_finding() -> None:
+ handler = {**_finding(), "biomarker_type": "error_handling", "line_start": 30}
+ item = _queue([handler], plans=[_helper()]).lead
+ assert _ranked(item, "duplicate inside") == "no"
+
+
+# --- may_lead: a cause that has not cleared the bar never leads ----------------
+
+
+def _lazy(may_lead: bool) -> dict:
+ from tests.unit.health.fix_first_rows import _perf
+
+ row = _perf("perf3_lazy", "src/db.py::fetch", biomarker_type="lazy_load_in_loop")
+ row["details"] = {**row["details"], "may_lead": may_lead}
+ return row
+
+
+def test_a_cause_that_may_not_lead_is_listed_second() -> None:
+ small = _finding("src/core.py", ccn=16, nloc=40)
+ queue = build_fix_first(
+ metrics=[_metric(), _metric("src/repo.py")], findings=[small],
+ performance=[_lazy(False)],
+ )
+ assert [i.kind for i in queue.items] == ["finding", "perf_fix"]
+ assert next(f.value for f in queue.items[1].why_ranked if f.factor == "value") == "4"
+
+
+def test_a_cause_that_may_lead_still_leads() -> None:
+ small = _finding("src/core.py", ccn=16, nloc=40)
+ queue = build_fix_first(
+ metrics=[_metric(), _metric("src/repo.py")], findings=[small],
+ performance=[_lazy(True)],
+ )
+ assert [i.kind for i in queue.items] == ["perf_fix", "finding"]
+
+
+def test_a_lone_cause_that_may_not_lead_is_still_shown() -> None:
+ queue = build_fix_first(metrics=[_metric("src/repo.py")], performance=[_lazy(False)])
+ assert [i.kind for i in queue.items] == ["perf_fix"]
+
+
+# --- wording: why, context, labels ----------------------------------------------
+
+
+def test_why_says_why_it_matters_not_the_titles_size() -> None:
+ huge = _finding(ccn=249, nloc=1280, max_nesting=7)
+ item = _queue([huge]).lead
+ assert item.title == "Break up run (CCN 249, 1,280 lines)"
+ assert "249" not in item.why and "1,280" not in item.why and "CCN" not in item.why
+ assert item.why == (
+ "run has many independent paths through it; 9 files import it, "
+ "changed 12 times in 90 days."
+ )
+
+
+def test_why_names_coverage_when_a_report_measured_it() -> None:
+ covered = _queue([_finding()], [_metric(line_coverage_pct=41.6)]).lead
+ assert covered.why.endswith("tests run 42% of its lines.")
+ bare = _queue([_finding()], [_metric(line_coverage_pct=0.0)]).lead
+ assert bare.why.endswith("no test runs it.")
+ assert "test" not in _queue([_finding()]).lead.why
+
+
+def test_context_is_short_plain_sentences() -> None:
+ scatter = {"file_path": "src/core.py", "biomarker_type": "co_change_scatter",
+ "severity": "high", "health_impact": 2.0, "public_id": "finding_s",
+ "dimension": "defect", "reason": "co-changes with 35 distinct files (top 3.7%)",
+ "details": {"scatter": 35, "co_change_scatter_pct": 96.3}}
+ hotspot = {**scatter, "biomarker_type": "function_hotspot", "function_name": "run",
+ "health_impact": 1.0, "public_id": "finding_fh",
+ "reason": "run has been modified across 3 commits (repo p80=2)",
+ "details": {"modification_count": 3, "repo_p80": 2, "ccn": 14}}
+ item = _queue([_finding(), scatter, hotspot], [_metric(contributor_count=3)]).lead
+ assert [(c.label, c.value) for c in item.context] == [
+ ("recent changes", "changed 12 times in 90 days; 3 people have worked on it"),
+ ("ripple", "it changes together with 35 other files"),
+ ("keeps changing", "run changed in 3 commits"),
+ ]
+ for c in item.context:
+ assert "%" not in c.value and "p80" not in c.value and "top " not in c.value
+
+
+def test_no_text_field_carries_a_marker_id() -> None:
+ from repowise.core.analysis.health.scoring import _BIOMARKER_CATEGORY
+
+ queue = _queue([_finding(), {**_finding("src/b.py"), "biomarker_type": "error_handling",
+ "line_start": 9}])
+ for item in queue.items:
+ texts = [item.title, item.why, item.gain.text, item.action.summary,
+ *(s.text for s in item.action.steps), *(f.value for f in item.facts),
+ *(c.value for c in item.context), *(r.value for r in item.why_ranked)]
+ for value in texts:
+ assert not any(m in value for m in _BIOMARKER_CATEGORY if "_" in m), value
+ assert ("finding", "Complex method") in [(f.label, f.value) for f in queue.items[0].facts]
+
+
+def test_a_module_scope_cause_reads_module_scope_of_its_file() -> None:
+ from tests.unit.health.fix_first_rows import _perf
+
+ row = _perf("perf3_mod", "src/db.py::fetch", intervention_symbol="src/repo.py::__module__")
+ row["details"]["plan"]["steps"][0]["symbol"] = "src/repo.py::__module__"
+ item = _perf_queue(row).lead
+ assert item.title == "Batch the database calls loops make in module scope of repo.py"
+ assert "__module__" not in item.why and "__module__" not in item.action.steps[0].text
+ assert item.target.symbol is None
+
+
+# --- the strongest performance fixes share the top value band ---------------------
+
+
+def test_a_production_reachable_growing_db_loop_is_in_the_top_band() -> None:
+ from repowise.core.analysis.health.fix_first.build import VALUE_MAX
+
+ assert _value(loop_magnitude="grows_with_data", exposure="entry_reachable") == str(VALUE_MAX)
+
+
+def test_it_outranks_a_large_function_that_needs_judgment_on_score() -> None:
+ from tests.unit.health.fix_first_rows import _perf
+
+ huge = _finding(ccn=249, nloc=1280, max_nesting=7)
+ queue = build_fix_first(
+ metrics=[_metric(), _metric("src/repo.py")], findings=[huge],
+ performance=[_perf("perf3_top", "src/db.py::fetch")],
+ )
+ # Both sit in the top band; the perf fix is listed beside the large function.
+ assert {i.kind for i in queue.items[:2]} == {"finding", "perf_fix"}
+
+
+def test_without_reach_it_stays_below_the_top_band() -> None:
+ assert _value(loop_magnitude="grows_with_data", exposure="not_entry_reachable") == "2"
+
+
+# --- titles and steps name what they mean -----------------------------------------
+
+
+def test_an_extract_class_step_names_the_members_it_moves() -> None:
+ plan = {"groups": [{"methods": ["load", "save", "flush"], "fields": ["db"]},
+ {"methods": ["render"], "fields": ["tpl"]}]}
+ assert _step_text("extract_class", plan) == "Move render out of Store.save into a new class"
+
+
+def test_only_a_size_finding_is_titled_break_up() -> None:
+ wide = {**_finding(ccn=12, nloc=40, max_nesting=8), "biomarker_type": "primitive_obsession"}
+ item = _queue([wide]).lead
+ assert item.title == "Group the parameters of run"
+
+
+def test_a_one_line_block_reads_as_one_line() -> None:
+ item = _queue([_finding(deepest_block={"start": 42, "end": 42})]).lead
+ assert item.action.steps[0].text.startswith("Start with line 42, where it nests 4 deep")
+
+
+# --- kinds the baseline raters found not worth doing -------------------------------
+
+
+def test_extract_class_and_move_method_plans_are_low_value() -> None:
+ plan = {"groups": [{"methods": ["load", "save"], "fields": ["db"]}]}
+ assert _refactor_queue("extract_class", plan).totals.excluded["low_value_kind"] == 1
+ moved = _refactor_queue("move_method", {"to_class": "Ledger"})
+ assert moved.items == () and moved.totals.excluded["low_value_kind"] == 1
+
+
+def test_large_method_and_low_cohesion_findings_are_low_value() -> None:
+ for marker in ("large_method", "low_cohesion"):
+ queue = _queue([{**_finding(), "biomarker_type": marker}])
+ assert queue.items == () and queue.totals.excluded["low_value_kind"] == 1
+
+
+def test_a_split_file_plan_and_a_complex_method_stay() -> None:
+ named = {"groups": [{"name": "io", "symbols": ["read"]}]}
+ assert len(_refactor_queue("split_file", named).items) == 1
+ assert len(_queue([_finding()]).items) == 1
diff --git a/tests/unit/health/test_perf_loop_line.py b/tests/unit/health/test_perf_loop_line.py
new file mode 100644
index 000000000..ab59e3bf2
--- /dev/null
+++ b/tests/unit/health/test_perf_loop_line.py
@@ -0,0 +1,85 @@
+"""Performance findings say where their loop starts (``loop_line``).
+
+A reader showing the cost needs the loop header beside the call: the call can
+sit many lines below it. The walker knows the loop node, so it stores the
+header line; the finding id does not move with it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.analysis.health.complexity import walk_file
+from repowise.core.analysis.health.finding_identity import finding_public_id
+from repowise.core.analysis.health.perf import collect_crossfn_io_in_loop
+from tests.unit.health.test_perf_crossfn import _SCHEDULER, _build
+
+_FAR = (
+ "from sqlalchemy import select\n"
+ "def sync(session, repos):\n"
+ " for repo in repos:\n"
+ + "".join(f" x{i} = repo.v{i}\n" for i in range(20))
+ + " session.execute(select(repo))\n"
+)
+
+
+def _hits(source: str):
+ return walk_file("t.py", "python", source.encode()).perf_hits
+
+
+def test_a_hit_far_below_its_loop_stores_the_header_line() -> None:
+ hit = next(h for h in _hits(_FAR) if h.kind == "io_in_loop")
+ assert hit.line == 24
+ assert hit.loop_line == 3
+ assert hit.loop_facts()["loop_line"] == 3
+
+
+def test_the_innermost_loop_is_the_one_stored() -> None:
+ src = (
+ "from sqlalchemy import select\n"
+ "def sync(session, groups):\n"
+ " for group in groups:\n"
+ " for repo in group:\n"
+ " session.execute(select(repo))\n"
+ )
+ hit = next(h for h in _hits(src) if h.kind == "io_in_loop")
+ assert hit.loop_line == 4
+
+
+def test_a_closure_defined_in_a_loop_does_not_inherit_the_outer_loop() -> None:
+ src = (
+ "from sqlalchemy import select\n"
+ "def sync(session, groups):\n"
+ " for group in groups:\n"
+ " def inner(repos):\n"
+ " for repo in repos:\n"
+ " session.execute(select(repo))\n"
+ )
+ hit = next(h for h in _hits(src) if h.kind == "io_in_loop")
+ assert hit.loop_line == 5
+
+
+def test_a_hit_outside_any_loop_has_no_loop_line() -> None:
+ src = "import time\nasync def f():\n time.sleep(1)\n"
+ hits = _hits(src)
+ assert hits and all(h.loop_line == 0 and "loop_line" not in h.loop_facts() for h in hits)
+
+
+def test_a_cross_function_hit_stores_the_loop_around_its_call_site(tmp_path: Path) -> None:
+ walked, graph = _build(tmp_path, {"scheduler.py": _SCHEDULER})
+ hit = next(h for hs in collect_crossfn_io_in_loop(walked, graph).values() for h in hs)
+ assert hit.line == 15
+ assert hit.loop_line == 14
+
+
+def test_loop_line_does_not_move_the_finding_id() -> None:
+ row = {
+ "file_path": "a.py",
+ "biomarker_type": "io_in_loop",
+ "function_name": "sync",
+ "line_start": 24,
+ "dimension": "performance",
+ "details": {"boundary_kind": "db"},
+ }
+ with_line = {**row, "details": {"boundary_kind": "db", "loop_line": 3}}
+ assert finding_public_id(row) == finding_public_id(with_line)
diff --git a/tests/unit/persistence/test_actions_build.py b/tests/unit/persistence/test_actions_build.py
index 6f15602d5..5c846124f 100644
--- a/tests/unit/persistence/test_actions_build.py
+++ b/tests/unit/persistence/test_actions_build.py
@@ -14,7 +14,7 @@ from sqlalchemy import select
from repowise.core.analysis.actions.build import ABSENT, build_repo_facts
from repowise.core.persistence.crud.analysis.actions import load_repo_facts
from repowise.core.persistence.models import DeadCodeFinding
-from tests.unit.persistence.test_actions_loader import ANCHOR, _seed
+from tests.unit.persistence.test_actions_loader import ANCHOR, DEEP, _seed
# SQLite hands datetimes back naive; the rows match it, and the column defaults.
_T = ANCHOR.replace(tzinfo=None)
@@ -50,9 +50,11 @@ HEALTH_FINDINGS = [
{"file_path": "src/core.py", "biomarker_type": "change_entropy", "severity": "high",
"health_impact": 3.0},
{"file_path": "src/core.py", "biomarker_type": "complex_method", "severity": "high",
- "function_name": "run", "health_impact": 1.0},
+ "function_name": "run", "health_impact": 1.0, "line_start": 10, "line_end": 60,
+ "details_json": DEEP},
{"file_path": "src/new.py", "biomarker_type": "complex_method", "severity": "high",
- "function_name": "build", "health_impact": 1.0},
+ "function_name": "build", "health_impact": 1.0, "line_start": 10, "line_end": 60,
+ "details_json": DEEP},
{"file_path": "src/touched.py", "biomarker_type": "long_method", "severity": "high",
"function_name": "x", "health_impact": 1.0},
]
diff --git a/tests/unit/persistence/test_actions_loader.py b/tests/unit/persistence/test_actions_loader.py
index 7d5b11883..41142a9c2 100644
--- a/tests/unit/persistence/test_actions_loader.py
+++ b/tests/unit/persistence/test_actions_loader.py
@@ -34,6 +34,8 @@ from repowise.core.persistence.models import (
from tests.unit.persistence.helpers import insert_repo
ANCHOR = datetime(2026, 9, 28, 12, 0, tzinfo=UTC)
+#: A size finding's deepest nested block: Fix first's first concrete step.
+DEEP = json.dumps({"deepest_block": {"start": 20, "end": 30}, "max_nesting": 4})
NOW = ANCHOR + timedelta(days=1)
@@ -66,7 +68,8 @@ async def _seed(session) -> str:
HealthFinding(repository_id=rid, file_path="src/core.py", biomarker_type="change_entropy",
severity="high", health_impact=3.0),
HealthFinding(repository_id=rid, file_path="src/core.py", biomarker_type="complex_method",
- severity="high", function_name="run", health_impact=1.0),
+ severity="high", function_name="run", health_impact=1.0,
+ line_start=10, line_end=60, details_json=DEEP),
]
)
add(
@@ -97,7 +100,8 @@ async def _seed(session) -> str:
file_path="src/hist.py", symbol=None,
attribution_basis="added_lines"),
HealthFinding(repository_id=rid, file_path="src/new.py", biomarker_type="complex_method",
- severity="high", function_name="build", health_impact=1.0),
+ severity="high", function_name="build", health_impact=1.0,
+ line_start=10, line_end=60, details_json=DEEP),
HealthFinding(repository_id=rid, file_path="src/touched.py", biomarker_type="long_method",
severity="high", function_name="x", health_impact=1.0),
]
diff --git a/tests/unit/persistence/test_fix_first_loader.py b/tests/unit/persistence/test_fix_first_loader.py
index d5fba798f..e2e9291dd 100644
--- a/tests/unit/persistence/test_fix_first_loader.py
+++ b/tests/unit/persistence/test_fix_first_loader.py
@@ -33,6 +33,7 @@ async def seed_fix_first(session, rid: str | None = None) -> str:
repository_id=rid,
**{k: m[k] for k in ("file_path", "score", "nloc", "is_test",
"analyzed_commit", "updated_at")},
+ code_origin=m.get("code_origin"),
)
)
session.add(GitMetadata(repository_id=rid, file_path=m["file_path"],
@@ -100,3 +101,116 @@ async def test_the_queue_is_cached_until_a_store_changes(async_session) -> None:
rebuilt = await load_fix_first(async_session, rid)
assert rebuilt is not first
assert all(i.target.file_path != "src/plain.py" for i in rebuilt.items)
+
+
+async def test_loader_reads_the_stored_code_origin(async_session) -> None:
+ from sqlalchemy import update
+
+ rid = await seed_fix_first(async_session)
+ await async_session.execute(
+ update(HealthFileMetric)
+ .where(HealthFileMetric.file_path == "src/plain.py")
+ .values(code_origin="docs_example")
+ )
+ await async_session.flush()
+ loaded = await load_fix_first(async_session, rid)
+ metrics = [
+ {**m, "code_origin": "docs_example"} if m["file_path"] == "src/plain.py" else m
+ for m in METRICS
+ ]
+ built = build_fix_first(
+ metrics=metrics,
+ findings=FINDINGS,
+ refactoring=REFACTORING,
+ performance=PERFORMANCE,
+ plans=PLANS,
+ )
+ assert loaded.totals.excluded["docs_example"] == 1
+ # The update moved the metric's ``updated_at``, so only the basis differs.
+ assert (loaded.items, loaded.totals) == (built.items, built.totals)
+
+
+async def test_loader_reads_verified_duplicates_as_a_fact(async_session) -> None:
+ """A dispatch-heavy function stays a candidate when a verified duplicate
+ sits in it: an Extract Helper plan stored at another file names it."""
+ from sqlalchemy import select
+
+ rid = await seed_fix_first(async_session)
+ row = (
+ await async_session.execute(
+ select(HealthFinding).where(HealthFinding.public_id == "finding_c1")
+ )
+ ).scalar_one()
+ dispatch = {**json.loads(row.details_json), "dispatch_share": 0.9}
+ row.details_json = json.dumps(dispatch)
+ helper = {
+ "public_id": "refac3_helper", "refactoring_type": "extract_helper",
+ "file_path": "src/other.py", "target_symbol": "other",
+ "evidence": {"duplicated_lines": 15},
+ "plan": {"occurrences": [
+ {"file": "src/other.py", "line_start": 5, "line_end": 20},
+ {"file": "src/core.py", "line_start": 30, "line_end": 44},
+ ]},
+ }
+ async_session.add(
+ RefactoringSuggestion(
+ repository_id=rid,
+ public_id=helper["public_id"],
+ refactoring_type="extract_helper",
+ file_path="src/other.py",
+ target_symbol="other",
+ status="open",
+ evidence_json=json.dumps(helper["evidence"]),
+ plan_json=json.dumps(helper["plan"]),
+ )
+ )
+ await async_session.flush()
+ findings = [
+ {**f, "details": dispatch} if f["public_id"] == "finding_c1" else f for f in FINDINGS
+ ]
+ built = build_fix_first(
+ metrics=METRICS,
+ findings=findings,
+ refactoring=REFACTORING,
+ performance=PERFORMANCE,
+ plans=[*PLANS, helper],
+ )
+ loaded = await load_fix_first(async_session, rid)
+ assert "src/core.py" in {i.target.file_path for i in loaded.items}
+ assert (loaded.items, loaded.totals) == (built.items, built.totals)
+
+
+async def test_loader_reads_extractions_for_a_finding_without_a_plan(async_session) -> None:
+ """A size finding takes its first step from an Extract Method plan stored
+ for its function, though no opportunity carries that plan."""
+ rid = await seed_fix_first(async_session)
+ extraction = {
+ "public_id": "refac2_walk", "refactoring_type": "extract_method",
+ "file_path": "src/plain.py", "target_symbol": "walk",
+ "evidence": {"slice_nloc": 8, "ccn_removed": 2},
+ "plan": {"span": {"start": 12, "end": 20}, "suggested_name": "step"},
+ }
+ async_session.add(
+ RefactoringSuggestion(
+ repository_id=rid,
+ public_id=extraction["public_id"],
+ refactoring_type="extract_method",
+ file_path="src/plain.py",
+ target_symbol="walk",
+ status="open",
+ evidence_json=json.dumps(extraction["evidence"]),
+ plan_json=json.dumps(extraction["plan"]),
+ )
+ )
+ await async_session.flush()
+ loaded = await load_fix_first(async_session, rid)
+ walk = next(i for i in loaded.items if i.target.file_path == "src/plain.py")
+ assert walk.action.steps[0].text == "Extract lines 12-20 of walk into step()"
+ built = build_fix_first(
+ metrics=METRICS,
+ findings=FINDINGS,
+ refactoring=REFACTORING,
+ performance=PERFORMANCE,
+ plans=[*PLANS, extraction],
+ )
+ assert (loaded.items, loaded.totals) == (built.items, built.totals)
diff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.py
index 6b6eb3429..b4a659eaa 100644
--- a/tests/unit/server/mcp/conftest.py
+++ b/tests/unit/server/mcp/conftest.py
@@ -639,7 +639,7 @@ async def health_data(session: AsyncSession, populated_db: str) -> str:
"function_name": "authenticate",
"line_start": 10,
"line_end": 80,
- "details": {"ccn": 15, "cognitive": 30, "nloc": 70},
+ "details": {"ccn": 15, "cognitive": 30, "nloc": 70, "deepest_block": {"start": 40, "end": 52}},
"health_impact": 1.2,
"reason": "authenticate has cyclomatic complexity 15",
},
diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.py
index 0f0586d12..2449c3ade 100644
--- a/tests/unit/server/test_refactoring_opportunities.py
+++ b/tests/unit/server/test_refactoring_opportunities.py
@@ -44,7 +44,11 @@ def _plan(path: str, symbol: str, **over: Any) -> dict[str, Any]:
"target_symbol": symbol,
"line_start": 10,
"line_end": 30,
- "plan": {"extracted_name": f"_{symbol}_part", "local_scope": True},
+ "plan": {
+ "extracted_name": f"_{symbol}_part",
+ "local_scope": True,
+ "span": {"start": 12, "end": 28},
+ },
"evidence": {"ccn_removed": 6, "slice_nloc": 20},
"impact_delta": 1.0,
"effort_bucket": "S",
@@ -66,7 +70,8 @@ def _finding(
"function_name": function_name,
"line_start": 10,
"line_end": 30,
- "details": {},
+ # Past Fix first's size floor, so the composed plan is a candidate.
+ "details": {"ccn": 16},
"health_impact": impact,
"reason": "seeded",
"dimension": "defect",