Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.mdindex 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'sstrongest 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.pyindex 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 forevery branch/loop/case construct encountered. The CCN / cognitiveaccumulation 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 nodediff --git a/packages/core/src/repowise/core/analysis/health/complexity/models.py b/packages/core/src/repowise/core/analysis/health/complexity/models.pyindex 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 = Nonedef __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 = 0def 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], ...] = ()@dataclassdiff --git a/packages/core/src/repowise/core/analysis/health/complexity/perf_walk.py b/packages/core/src/repowise/core/analysis/health/complexity/perf_walk.pyindex 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] = entryreturn 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 0next_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 0next_func = func_namenext_start = func_startif 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 = Noneif 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_linefacts = 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_bodyif body is None:body = dialect.loop_body(node)+ header = node.start_point[0] + 1if 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 == bodystack.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_depthstack.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.pyindex 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] = fcdiff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex 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.pyindex 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.pyindex 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 = 3HEAD = 5HEAD_PER_KIND = 3DEFAULT_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: strimproves: strwrite: 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 growsand 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 valuedef _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 outdef _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"] = 1details = 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 Falseexcluded[reason] += 1@@ -979,6 +1309,20 @@ def build_fix_first(if not steps:excluded["below_min_worth"] += 1continue+ 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+ continueunits.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"] += 1continue- 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"] += 1continue- 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.pyindex 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.pyindex 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 Nonedef 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.pyindex 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.pyindex 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]) -> listHealthFileMetric.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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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.pyindex 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)).actionsassert [(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}) == 2diff --git a/tests/unit/cli/test_health_cmd_controls.py b/tests/unit/cli/test_health_cmd_controls.pyindex 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 outassert "src/core.py:20" in outassert "verify: pytest tests/test_core_0.py" in outdiff --git a/tests/unit/generation/test_editor_file_fetcher.py b/tests/unit/generation/test_editor_file_fetcher.pyindex 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.pyindex 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.pynew file mode 100644index 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.detailsdiff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.pyindex 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 == 3assert 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.leadassert (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=[]).leadassert 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.pynew file mode 100644index 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) == 1diff --git a/tests/unit/health/test_perf_loop_line.py b/tests/unit/health/test_perf_loop_line.pynew file mode 100644index 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.pyindex 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 selectfrom repowise.core.analysis.actions.build import ABSENT, build_repo_factsfrom repowise.core.persistence.crud.analysis.actions import load_repo_factsfrom 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.pyindex 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_repoANCHOR = 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.pyindex 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 firstassert 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.pyindex 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.pyindex 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",