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): lead Fix first with work that pays (#3422)
Raghav Chamadiyaf3d1b3ba5e5f
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 62557de8e..7f3ae5566 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -683,10 +683,13 @@ reason. These reasons and the performance default queue's are decided in one pla| `no_concrete_step` | No first edit with a file and line or a named group || `low_value_kind` | Low cohesion (0 of 46 accepted), long method (0 of 10), long parameter lists (0 of 2) || `kind_unaudited` | Plans led by Extract Class (0 of 14 accepted) or Move Method (0 of 34), kept to the full list until each passes a per-language audit |+| `terminal_flow` | A quarter or more of the function's calls print or prompt (`complexity/terminal.py`): a status report, checklist or setup wizard |+| `moderate_quiet` | Under CCN 80 and 200 lines, in a file outside the top fifth by churn (or changed once), with no `prior_defect` in the file and no `function_hotspot` on the function |Order: value first (the larger of health recovered and size: CCN 20/40/80/150,lines 100/200/400/800, nesting 5/6/8, a critical or brain-method finding, one step-more on a hot file); a performance fix's value is its cost, with production,+more on a hot file, where a function under 5% of its file's lines is credited that+share of the file's importers); a performance fix's value is its cost, with production,entry-reachable, data-growing DB or network calls in the top band. Then tier`now` / `next` / `later`, with at most `HEAD_PER_KIND` (3) of the first `HEAD` (5)places per kind. `worth.py` decides `later` for every default list: a functiondiff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.mdindex caba9c62e..c762daf82 100644--- a/docs/layers/CODE_HEALTH.md+++ b/docs/layers/CODE_HEALTH.md@@ -99,6 +99,10 @@ Left out, and counted with a reason:- kinds that reviewers found not worth doing- code a sure dead-code finding covers (the fix is to delete it)- dormant functions, which a constant flag switches off+- print and prompt flows (status reports, checklists, setup wizards), whose+ branches choose what to show+- functions under CCN 80 and 200 lines whose file rarely changes and has no bug+ fixes; they stay in the refactoring listA function is dormant when its body opens with `if not FLAG: return ...` (or is one`if FLAG:` block) and `FLAG` is a module-level `False`, `0` or `None` (`const FLAG =@@ -110,7 +114,8 @@ outside with `setattr` or a test's monkeypatch, still reads as off.Items rank by value first (how far the code sits past size and complexity bars,one step more in a widely imported file), then by tier. Within a value, thecomplexity a fix removes times how widely the file is imported decides, so a-4,000-line loop outranks a long print routine. A performance fix ranks by what runs+4,000-line loop outranks a long print routine. A function under a twentieth of a+very large file counts only its share of that file's importers. A performance fix ranks by what runsit: a request or message handler, then a scheduled job, then code with no roleevidence. No kind takes more than 3 of the first 5 places while another has workworth doing.@@ -142,6 +147,8 @@ snoozing a row takes effect at once.A fragile file asks for tests only when no measured coverage and no test in thecode graph reaches it; otherwise the row asks you to simplify its lead function.+A folder where bug fixes concentrate names its first step, the most fixed file's,+or is left out.An index with fewer than five commits leaves out the rows ranked by history.```bashdiff --git a/packages/core/src/repowise/core/analysis/actions/rules/code.py b/packages/core/src/repowise/core/analysis/actions/rules/code.pyindex f294fd1d2..357fdd159 100644--- a/packages/core/src/repowise/core/analysis/actions/rules/code.py+++ b/packages/core/src/repowise/core/analysis/actions/rules/code.py@@ -387,7 +387,10 @@ def fix_concentration(facts: RepoFacts, ctx: RepoContext) -> RuleOutcome:Told as an area of work rather than a list of files, because that is how alead plans it. The deepest folder that still clears the share wins, so the- answer is `update_cmd/`, not `packages/`.+ answer is `update_cmd/`, not `packages/`. The title names where to start:+ the first step of its most fixed fragile file. A folder with no such step+ is left out and counted in the outcome's reason, and its files keep their+ own rows."""rule = "fix_concentration"if "files" in facts.unavailable:@@ -438,72 +441,110 @@ def fix_concentration(facts: RepoFacts, ctx: RepoContext) -> RuleOutcome:continuechosen.append(folder)actions = []+ no_step = 0for folder in chosen[:CONCENTRATION_MAX_ACTIONS]:n = len(shas_per_folder[folder])- share = round(100 * n / total)members = sorted(fixed_files[folder], key=lambda p: -production[p].fix_commits_90d)includes = tuple(p for p in members if is_fragile(production[p], ctx) and p not in named)+ first = _first_step(includes, production)+ if first is None:+ no_step += 1+ continueactions.append(- Action(- rule=rule,- tier="plan",- horizons=("quarter",),- severity="high",- title=(- f"Stabilise {code(folder + '/')}: {share}% of the bug fixes land in "- f"its {plural(files_per_folder[folder], 'file')}"- ),- impact=(- f"{n} of the {total} bug-fix commits in the last 90 days touched "- f"this folder, which holds {files_per_folder[folder] / n_prod:.1%} "- "of the production files."- ),- why=(- WhyFact("share of bug-fix commits", f"{share}%"),- WhyFact("files with repeated fixes", str(len(members))),- WhyFact("most fixed", posixpath.basename(members[0])),- ),- target_kind="folder",- target_path=folder,- surface="findings",- effort="L",- confidence="medium",- done_when="Its share of bug-fix commits falls over the next 90 days.",- weight=float(n),- evidence_total=len(members),+ _folder_action(+ folder,+ first=first,+ fixes=(n, total),+ files=(files_per_folder[folder], n_prod),+ members=[(p, production[p]) for p in members],includes=includes,- fingerprint=fingerprint(share // 5),- details=tuple(- ActionDetail(- path=p,- reason=(- f"{production[p].fix_commits_90d} bug-fix commits, "- f"{production[p].commits_90d} commits in 90 days"- ),- )- for p in members- ),- commands=(- ActionCommand.call(- "Bug-fix history and co-change partners for the most fixed files",- "get_risk",- {"targets": members[:5]},- cli="repowise risk " + " ".join(f"-t {p}" for p in members[:5]),- ),- ActionCommand.call(- "Why the folder is shaped this way",- "get_why",- {"targets": [f"{folder}/"]},- cli=f"repowise why {folder}/",- ),- ),))- return RuleOutcome(rule, "evaluated", "", tuple(actions))+ reason = (+ f"{plural(no_step, 'folder')} left out: no file in it names a first step."+ if no_step+ else ""+ )+ return RuleOutcome(rule, "evaluated", reason, tuple(actions))+++def _folder_action(+ folder: str,+ *,+ first: str,+ fixes: tuple[int, int],+ files: tuple[int, int],+ members: list[tuple[str, FileFacts]],+ includes: tuple[str, ...],+) -> Action:+ """The folder's action: ``fixes`` is (the folder's bug-fix commits, the+ repository's), ``files`` (its production files, the repository's)."""+ n, total = fixes+ share = round(100 * n / total)+ paths = [p for p, _f in members]+ return Action(+ rule="fix_concentration",+ tier="plan",+ horizons=("quarter",),+ severity="high",+ title=f"Stabilise {code(folder + '/')}: first, {first}",+ impact=(+ f"{n} of the {total} bug-fix commits in the last 90 days ({share}%) "+ f"touched this folder's {plural(files[0], 'file')}, "+ f"{files[0] / files[1]:.1%} of the production files."+ ),+ why=(+ WhyFact("share of bug-fix commits", f"{share}%"),+ WhyFact("files with repeated fixes", str(len(members))),+ WhyFact("most fixed", posixpath.basename(paths[0])),+ ),+ target_kind="folder",+ target_path=folder,+ surface="findings",+ effort="L",+ confidence="medium",+ done_when="Its share of bug-fix commits falls over the next 90 days.",+ weight=float(n),+ evidence_total=len(members),+ includes=includes,+ fingerprint=fingerprint(share // 5),+ details=tuple(+ ActionDetail(+ path=p,+ reason=f"{f.fix_commits_90d} bug-fix commits, {f.commits_90d} commits in 90 days",+ )+ for p, f in members+ ),+ commands=(+ ActionCommand.call(+ "Bug-fix history and co-change partners for the most fixed files",+ "get_risk",+ {"targets": paths[:5]},+ cli="repowise risk " + " ".join(f"-t {p}" for p in paths[:5]),+ ),+ ActionCommand.call(+ "Why the folder is shaped this way",+ "get_why",+ {"targets": [f"{folder}/"]},+ cli=f"repowise why {folder}/",+ ),+ ),+ )+++def _first_step(includes: tuple[str, ...], production: dict[str, FileFacts]) -> str | None:+ """The first step of the most fixed file in ``includes`` that has one, as+ a clause: ``simplify `run` in `a.py```."""+ for path in includes:+ step = _fragile_step(production[path])+ if step is not None:+ title = step[0].split(": ", 1)[0]+ return title[0].lower() + title[1:]+ return Nonedef _ancestors(path: str) -> list[str]:diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py b/packages/core/src/repowise/core/analysis/health/biomarkers/base.pyindex 9f571d640..cc88816c6 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/base.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/base.py@@ -165,6 +165,15 @@ class BiomarkerResult:deduction: float | None = None+def shape_details(fn: FunctionComplexity) -> dict[str, Any]:+ """The shape facts every function-size marker stores beside its numbers:+ the dispatch share always, the terminal share only when there is one."""+ out: dict[str, Any] = {"dispatch_share": fn.dispatch_share}+ if fn.terminal_share:+ out["terminal_share"] = fn.terminal_share+ return out++class Biomarker(Protocol):"""Detector contract. Each concrete biomarker is a stateless object."""diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.pyindex bc416e539..53587e32f 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py@@ -29,7 +29,7 @@ from __future__ import annotationsfrom ..complexity.dispatch import judged_ccnfrom ..models import Severity-from .base import BiomarkerResult, FileContext+from .base import BiomarkerResult, FileContext, shape_detailsclass BrainMethodDetector:@@ -87,7 +87,7 @@ class BrainMethodDetector:"max_nesting": fn.max_nesting,"dependents_count": ctx.dependents_count,"centrality_floor": floor,- "dispatch_share": fn.dispatch_share,+ **shape_details(fn),},reason=(f"Brain Method: {fn.name} is {fn.nloc} lines, CCN {fn.ccn}, "diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.pyindex 05253edb3..8d0946d7b 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py@@ -9,7 +9,7 @@ from __future__ import annotationsfrom ..complexity.dispatch import judged_ccnfrom ..models import Severity-from .base import BiomarkerResult, FileContext+from .base import BiomarkerResult, FileContext, shape_detailsclass ComplexMethodDetector:@@ -42,7 +42,7 @@ class ComplexMethodDetector:"ccn": fn.ccn,"cognitive": fn.cognitive,"nloc": fn.nloc,- "dispatch_share": fn.dispatch_share,+ **shape_details(fn),},reason=f"{fn.name} has cyclomatic complexity {fn.ccn}",)diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.pyindex 9f85ccf02..f1ad86607 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/large_method.py@@ -13,7 +13,7 @@ they don't double-count.from __future__ import annotationsfrom ..models import Severity-from .base import BiomarkerResult, FileContext+from .base import BiomarkerResult, FileContext, shape_detailsclass LargeMethodDetector:@@ -64,7 +64,7 @@ class LargeMethodDetector:details={"nloc": fn.nloc,"ccn": fn.ccn,- "dispatch_share": fn.dispatch_share,+ **shape_details(fn),},reason=f"{fn.name} is {fn.nloc} lines long",)diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py b/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.pyindex a28af8506..e8826c0b4 100644--- a/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py@@ -8,7 +8,7 @@ from __future__ import annotationsfrom ..complexity.dispatch import judged_nestingfrom ..models import Severity-from .base import BiomarkerResult, FileContext+from .base import BiomarkerResult, FileContext, shape_detailsclass NestedComplexityDetector:@@ -41,7 +41,7 @@ class NestedComplexityDetector:"max_nesting": fn.max_nesting,"ccn": fn.ccn,"cognitive": fn.cognitive,- "dispatch_share": fn.dispatch_share,+ **shape_details(fn),},reason=f"{fn.name} nests {fn.max_nesting} levels deep",)diff --git a/packages/core/src/repowise/core/analysis/health/complexity/assertions.py b/packages/core/src/repowise/core/analysis/health/complexity/assertions.pyindex 49085c90a..260af465c 100644--- a/packages/core/src/repowise/core/analysis/health/complexity/assertions.py+++ b/packages/core/src/repowise/core/analysis/health/complexity/assertions.py@@ -31,11 +31,12 @@ design (``asserts/lexicon.py`` carries the vocabulary and the evidence):``called_names`` rides along on the same traversal. Alone among these it iscollected **through** nested function bodies, because nothing else ever-collects them.+collects them. ``terminal_share`` (``terminal.py``) counts the same calls."""from __future__ import annotations+from dataclasses import dataclassfrom typing import TYPE_CHECKINGfrom ..asserts.lexicon import NARROW_PREFIXES, STUB_EXCEPTIONS, AssertDialect@@ -46,10 +47,19 @@ from .ast_utils import (_receiver_method_verdict,)from .languages import LanguageNodeMap+from .terminal import is_terminal_call, terminal_shareif TYPE_CHECKING:from tree_sitter import Node+@dataclass(slots=True)+class _CallTally:+ """Calls read in one body, and those on the terminal."""++ calls: int = 0+ terminal: int = 0++_EXPRESSION_STATEMENT = "expression_statement"_AWAIT_WRAPPER_KINDS = ("await_expression", "await", "parenthesized_expression")@@ -343,8 +353,8 @@ def _is_oracle_raise(node: Node) -> bool:def _collect_assertion_facts(body_node: Node, lmap: LanguageNodeMap, dialect: AssertDialect | None = None-) -> tuple[list[tuple[int, int, int]], int, int, int, frozenset[str], frozenset[str]]:- """``(blocks, total, verifications, raises, called, bare)`` for one body.+) -> tuple[list[tuple[int, int, int]], int, int, int, frozenset[str], frozenset[str], float]:+ """``(blocks, total, verifications, raises, called, bare, terminal)`` for one body.*blocks* are runs of ≥2 consecutive **narrow-tier** assertion statements,each recorded as ``(start_line, end_line, count)``. Runs are found per@@ -392,17 +402,30 @@ def _collect_assertion_facts(function body twice. It counts nothing and so cannot move a calibratedmarker. Empty under the early return above, which is fine only because theone reader ships no language that takes it.++ *terminal* is :func:`terminal.terminal_share` over the same calls *called*+ reads, nested bodies included."""if not lmap.assert_kinds and not lmap.assert_call_kinds:- return [], 0, 0, 0, frozenset(), frozenset()+ return [], 0, 0, 0, frozenset(), frozenset(), 0.0blocks: list[tuple[int, int, int]] = []total = 0verifications = 0raises = 0called: set[str] = set()bare: set[str] = set()+ tally = _CallTally()call_kinds = lmap.call_kinds or lmap.assert_call_kinds+ def _record_call(node: Node) -> None:+ names = _callee_names(node)+ if names is not None:+ called.add(names[0])+ if not names[1]:+ bare.add(names[0])+ tally.calls += 1+ tally.terminal += is_terminal_call(names[0], names[1])+def _scan_siblings(parent: Node, *, count_total: bool) -> None:nonlocal total, verificationsrun_start = 0@@ -452,11 +475,7 @@ def _collect_assertion_facts(if node.type in lmap.raise_kinds and not under_lambda and _is_oracle_raise(node):raises += 1if node.type in call_kinds:- names = _callee_names(node)- if names is not None:- called.add(names[0])- if not names[1]:- bare.add(names[0])+ _record_call(node)for child in node.children:child_under_lambda = under_lambda or child.type in lmap.lambda_kindsif child.type in lmap.function_kinds:@@ -470,11 +489,7 @@ def _collect_assertion_facts(def _visit_names_only(node: Node) -> None:if node.type in call_kinds:- names = _callee_names(node)- if names is not None:- called.add(names[0])- if not names[1]:- bare.add(names[0])+ _record_call(node)for child in node.children:_visit_names_only(child)@@ -492,4 +507,12 @@ def _collect_assertion_facts(verifications += 1elif tier != _NOT_ASSERTION:total += 1- return blocks, total, verifications, raises, frozenset(called), frozenset(bare)+ return (+ blocks,+ total,+ verifications,+ raises,+ frozenset(called),+ frozenset(bare),+ terminal_share(tally.terminal, tally.calls),+ )diff --git a/packages/core/src/repowise/core/analysis/health/complexity/models.py b/packages/core/src/repowise/core/analysis/health/complexity/models.pyindex b0da16b3c..e9873a38d 100644--- a/packages/core/src/repowise/core/analysis/health/complexity/models.py+++ b/packages/core/src/repowise/core/analysis/health/complexity/models.py@@ -119,6 +119,9 @@ class FunctionComplexity:# CCN points inside that dispatch's heaviest arm, its own case point not# counted: a switch of one-line cases has 0.dispatch_arm: int = 0+ # Calls on the terminal (print, prompt, console, stdout) over all calls in+ # the body, nested bodies included, to two decimals. ``complexity/terminal.py``.+ terminal_share: float = 0.0# True when the declaration is marked deprecated or the body's top level# issues a deprecation warning. ``complexity/deprecation.py``.deprecated: bool = Falsediff --git a/packages/core/src/repowise/core/analysis/health/complexity/terminal.py b/packages/core/src/repowise/core/analysis/health/complexity/terminal.pynew file mode 100644index 000000000..80817316e--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/complexity/terminal.py@@ -0,0 +1,65 @@+"""How much of a function's work is talking to a terminal.++A status report, a doctor checklist or a setup wizard is long and branchy by+construction: each check prints a line, each step prompts. Its CCN counts+``if configured: print(...) else: print(...)`` pairs, which split into helpers+without making anything safer. ``terminal_share`` lets a reader tell that shape+apart from a function whose branches decide what the program does.++The share is the calls in the function (nested bodies included) that write to+or read from a terminal, over all its calls, read by the callee's name: the+print family in any language, a ``print_*`` / ``prompt_*`` / ``confirm_*``+helper, ``console.log`` and its siblings, and a write to stdout or stderr. A+function with fewer than :data:`MIN_CALLS` calls has no share.+"""++from __future__ import annotations++#: From this share of its calls on the terminal, a function is a print or+#: prompt flow. Chosen in the gap between the status and setup commands+#: (0.27 to 0.50) and the largest share of a function that decides program+#: behaviour (0.15, a CLI init command) in three repositories' Fix first lists.+TERMINAL_SHARE = 0.25+#: Fewer calls than this say nothing about what a function is for.+MIN_CALLS = 4++_PLAIN = frozenset(+ {+ "print",+ "println",+ "printf",+ "eprint",+ "eprintln",+ "puts",+ "echo",+ "secho",+ "pprint",+ "input",+ "getpass",+ "prompt",+ "confirm",+ }+)+# Prefixes with their separator: ``printer_for`` and ``echo_server`` are not output.+_PREFIXES = ("print_", "prompt_", "confirm_")+_CONSOLE_METHODS = frozenset({"log", "info", "warn", "error", "table", "debug"})+_STREAMS = frozenset({"stdout", "stderr"})+++def is_terminal_call(name: str, roots: set[str]) -> bool:+ """Whether a call named *name* (lowercased) on receiver path *roots*+ writes to or reads from a terminal."""+ bare = name.lstrip("_")+ if bare in _PLAIN or bare.startswith(_PREFIXES):+ return True+ if "console" in roots and bare in _CONSOLE_METHODS:+ return True+ return bare == "write" and not _STREAMS.isdisjoint(roots)+++def terminal_share(terminal: int, calls: int) -> float:+ """*terminal* calls over *calls*, to two decimals; 0.0 under :data:`MIN_CALLS`."""+ return round(terminal / calls, 2) if calls >= MIN_CALLS else 0.0+++__all__ = ["MIN_CALLS", "TERMINAL_SHARE", "is_terminal_call", "terminal_share"]diff --git a/packages/core/src/repowise/core/analysis/health/complexity/walker.py b/packages/core/src/repowise/core/analysis/health/complexity/walker.pyindex 2a03e5614..b8b732d6c 100644--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py@@ -30,6 +30,7 @@ The whole-file passes share one descent of the tree (``file_scan``):- ``assertions``: assertion blocks + per-function assertion totals- ``test_case``: whether a walked function is a test case- ``dispatch``: how much of the CCN is one dispatch on one value+- ``terminal``: how much of the function prints or prompts- ``deprecation``: whether a function is marked deprecated- ``gating``: whether a constant-false flag switches a function off- ``mock_walk``: per-function mock-setup counting (test-quality)@@ -190,6 +191,7 @@ def walk_file(raises,called,bare_called,+ terminal,) = _collect_assertion_facts(body, lmap, asserts)name = _find_function_entry_name(fn_node, lmap)typed, scalar = typed_param_counts(_parameter_list(fn_node), lmap)@@ -219,6 +221,7 @@ def walk_file(bare_called_names=bare_called,dispatch_share=dispatch_share(dispatch.points, ccn),dispatch_arm=dispatch.arm,+ terminal_share=terminal,deprecated=is_deprecated(fn_node, body, name, lmap, source),gated_off=body is not fn_node and is_gated_off(body, flags),deepest_block=(deepest[0], deepest[1]) if deepest else None,diff --git a/packages/core/src/repowise/core/analysis/health/finding_identity.py b/packages/core/src/repowise/core/analysis/health/finding_identity.pyindex 8de0f9a2f..77359b302 100644--- a/packages/core/src/repowise/core/analysis/health/finding_identity.py+++ b/packages/core/src/repowise/core/analysis/health/finding_identity.py@@ -78,6 +78,7 @@ _DERIVED_DETAIL_KEYS = frozenset("execution_role","role_owner","dispatch_share",+ "terminal_share","deprecated","gated_off","loop_line",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 4deaec3ae..4fe9cf4ec 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@@ -57,6 +57,8 @@ from dataclasses import dataclassfrom typing import Anyfrom repowise.core.analysis.finding_registry import excluded_types+from repowise.core.analysis.health.biomarkers.function_hotspot import FunctionHotspotDetector+from repowise.core.analysis.health.biomarkers.prior_defect import PriorDefectDetectorfrom repowise.core.analysis.health.complexity.dispatch import DISPATCH_SHAREfrom repowise.core.analysis.health.models import primary_finding, split_by_originfrom repowise.core.analysis.health.queue.counts import COVERED_BY_PLAN, NOT_FILE_LEAD, Judgement@@ -77,6 +79,8 @@ from repowise.core.analysis.health.queue.eligibility import ()from repowise.core.analysis.health.queue.order import LEVEL_RANK, orderfrom repowise.core.analysis.health.queue.value import (+ MIN_CHURN_COMMITS,+ function_reach,perf_confidence,perf_ready,perf_value,@@ -98,6 +102,7 @@ from repowise.core.analysis.health.worth import (low_priority,magnitude,measure,+ measured_nloc,worth_size,)from repowise.core.analysis.next_call import ActionCommand@@ -166,6 +171,11 @@ class _Unit:may_lead: bool = True+def _tail(symbol: str | None) -> str | None:+ """A symbol's own name: ``a.py::Cls.run`` and ``Cls::run`` read ``run``."""+ return re.split(r"::|\.", symbol)[-1] if symbol else None++def _open(row: Any) -> bool:return (field(row, "status") or "open") == "open"@@ -276,6 +286,17 @@ class _Files:)self.churn_cut, self.deps_cut = cutsself.history = history+ # History that shows a function costs something: bug fixes in its+ # file, or the function changing more than most in the repository.+ self.fixed = {+ p for p, rows in history.items()+ if any(field(f, "biomarker_type") == PriorDefectDetector.name for f in rows)+ }+ self.hotspots = {+ p: {_tail(field(f, "function_name")) for f in rows+ if field(f, "biomarker_type") == FunctionHotspotDetector.name}+ for p, rows in history.items()+ }def is_test(self, path: str) -> bool | None:"""The stored flag; ``None`` when the file has no metric row or flag."""@@ -302,7 +323,32 @@ class _Files:return (self.dependents(path) or 0) >= self.deps_cutdef churning(self, path: str) -> bool:- return self.commits(path) >= self.churn_cut+ return self.commits(path) >= max(self.churn_cut, MIN_CHURN_COMMITS)++ def evidence(self, path: str, symbol: str | None) -> bool | None:+ """Whether history shows work on ``symbol`` pays: its file changes+ often or has bug fixes, or the function itself is a hotspot.+ ``None`` when the file's history is unknown: no commit count, or a+ repository whose history does not tell files apart."""+ tail = _tail(symbol)+ if self.churning(path) or path in self.fixed or (tail and tail in self.hotspots.get(path, ())):+ return True+ known = field(self.by_path.get(path), "commit_count_90d") is not None+ return False if known and self.churn_cut >= MIN_CHURN_COMMITS else None++ def reach(+ self, path: str, shape: Mapping[str, int], dependents: int | None, *, sized: bool+ ) -> tuple[int | None, bool]:+ """The importers a unit in ``path`` is credited with, and whether that+ makes it central: a function-size unit's are ``queue.value.function_reach``,+ any other unit's are its file's."""+ deps = self.dependents(path) if dependents is None else dependents+ if not sized:+ return deps, self.central(path)+ credited = function_reach(deps, measured_nloc(shape), self.nloc(path))+ if credited == deps:+ return deps, self.central(path)+ return credited, (credited or 0) >= self.deps_cutdef shape(self, path: str, symbol: str | None) -> dict[str, int]:"""The measured size of ``symbol`` in ``path``, from its findings."""@@ -490,6 +536,9 @@ class _ShapeRank:gain: floatccn_removed: intdependents: int | None+ #: The importers the value counts (``_Files.reach``): ``dependents``, or a+ #: function's share of them in a file far larger than it.+ credited: int | None@propertydef value(self) -> int:@@ -509,7 +558,7 @@ class _ShapeRank:FixRankFact("health gain", f"{self.gain:.2f}"),FixRankFact("complexity removed", str(self.ccn_removed)),FixRankFact("problem size", str(size)),- *_reach_facts(self.dependents, self.central, self.churning),+ *_reach_facts(self.dependents, self.central, self.churning, self.credited),FixRankFact("duplicate inside", "yes" if self.cloned else "no"),]@@ -519,18 +568,24 @@ def _finish_shaped(rank: _ShapeRank, **unit: Any) -> _Unit:return _finish(value=rank.value,cold_value=rank.cold_value,- worth=worth(removed(rank.ccn_removed, rank.gain), rank.dependents, rank.churning),+ worth=worth(removed(rank.ccn_removed, rank.gain), rank.credited, rank.churning),low=rank.low,rank_inputs=rank.facts,**unit,)-def _reach_facts(deps: int | None, central: bool, churning: bool) -> list[FixRankFact]:+def _reach_facts(+ deps: int | None, central: bool, churning: bool, credited: int | None+) -> list[FixRankFact]:"""What reach and history add: importers lift the band when central,- churn only orders inside it."""+ churn only orders inside it. A function credited with only its share of+ its file's importers says so."""+ share = f", {credited} counted for its share of the file" if credited != deps else ""return [- FixRankFact("files that import it", f"{deps or 0}{' (top fifth)' if central else ''}"),+ FixRankFact(+ "files that import it", f"{deps or 0}{' (top fifth)' if central else ''}{share}"+ ),FixRankFact("changes often", "yes" if churning else "no"),]@@ -798,15 +853,19 @@ class _RefactorPlan:lead_type, marker = _lead_kind(row, lead)shape = files.shape(path, lead.get("target_symbol"))deps = details.get("dependents")+ deps = files.dependents(path) if deps is None else deps+ function_size = lead_type == "extract_method"+ credited, central = files.reach(path, shape, deps, sized=function_size)rank = _ShapeRank(shape,- files.central(path),+ central,files.churning(path),- cloned=lead_type == "extract_method" and files.cloned(path, shape),- low=low_priority(marker, shape, function_size=lead_type == "extract_method"),+ cloned=function_size and files.cloned(path, shape),+ low=low_priority(marker, shape, function_size=function_size),gain=gain,ccn_removed=sum(_extraction_worth(plans.get(s.get("plan_id")))[0] for s in steps),- dependents=files.dependents(path) if deps is None else deps,+ dependents=deps,+ credited=credited,)return cls(row,@@ -1246,16 +1305,20 @@ def _finding_rank(finding: Any, files: _Files) -> _ShapeRank:path = field(finding, "file_path")marker = field(finding, "biomarker_type") or ""shape = files.shape(path, field(finding, "function_name"))+ deps = files.dependents(path)+ sized = marker in SIZE_MARKERS+ credited, central = files.reach(path, shape, deps, sized=sized)return _ShapeRank(shape,- files.central(path),+ central,files.churning(path),- cloned=marker in SIZE_MARKERS and files.cloned(path, shape),+ cloned=sized and files.cloned(path, shape),low=low_priority(marker, shape, error_kind=detail_map(finding).get("kind")),gain=_num(field(finding, "health_impact")),# Breaking up the whole function takes out its whole CCN.- ccn_removed=shape.get("ccn", 0) if marker in SIZE_MARKERS else 0,- dependents=files.dependents(path),+ ccn_removed=shape.get("ccn", 0) if sized else 0,+ dependents=deps,+ credited=credited,)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 c9c6ef14b..7054ba2dd 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@@ -43,6 +43,8 @@ FIX_FACT_BASES: tuple[str, ...] = get_args(FixFactBasis)# ``expected`` and ``no_strategy`` come from the performance ladder; ``gated_off``# also keeps out any other unit in a function a constant-false flag switches# off. ``unreachable``: an open dead-code finding covers the target.+# ``terminal_flow``: a print or prompt flow; ``moderate_quiet``: a function+# under the large-size bar with no churn or bug-fix history.FixExclusion = Literal["test","tooling",@@ -64,6 +66,8 @@ FixExclusion = Literal["no_concrete_step","low_value_kind","kind_unaudited",+ "terminal_flow",+ "moderate_quiet",]FIX_EXCLUSIONS: tuple[str, ...] = get_args(FixExclusion)diff --git a/packages/core/src/repowise/core/analysis/health/queue/eligibility.py b/packages/core/src/repowise/core/analysis/health/queue/eligibility.pyindex 0088eecaf..10ed42a0b 100644--- a/packages/core/src/repowise/core/analysis/health/queue/eligibility.py+++ b/packages/core/src/repowise/core/analysis/health/queue/eligibility.py@@ -30,8 +30,11 @@ from ..worth import (dispatch_shaped,dormant,execution_role,+ large_function,lead_reason,+ measured_nloc,perf_facets,+ terminal_shaped,)Reason = Literal[@@ -58,6 +61,8 @@ Reason = Literal["unmeasured_cost","cold_role","background_unproven",+ "terminal_flow",+ "moderate_quiet",]"""Why a unit is out of a default queue. Each surface counts the subset itsladders can produce (``fix_first.model.FIX_EXCLUSIONS``,@@ -270,14 +275,14 @@ class UnitFacts(Protocol):def cloned(self, path: str, shape: Mapping[str, int]) -> bool: ...+ def evidence(self, path: str, symbol: str | None) -> bool | None: ...+def small(shape: Mapping[str, int]) -> bool:"""Under both size floors. A function whose size findings carry no linecount is measured by its span, which bounds its code lines from above; onewith 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+ nloc = measured_nloc(shape)if not nloc:return Falsereturn nloc < SMALL_NLOC and shape.get("ccn", 0) < SMALL_CCN@@ -292,6 +297,10 @@ def unit_verdict(way out, and a dormant one does not run. A complexity unit on a functionthat is mostly one dispatch on one value is usually fine as it is, unlessa duplicate also sits in it; one on a small function is not worth an item.+ A print or prompt flow branches on what to show, so splitting it buys+ little. A function under :func:`worth.large_function` in a file whose+ history is known leads only on evidence that it costs something: it+ changes often or fixes land there. Unknown history keeps it in."""if facts.unreachable(path, symbol, line):return Verdict("unreachable")@@ -306,9 +315,23 @@ def unit_verdict(return Verdict("inherent_dispatch")if small(shape):return Verdict("small_function")+ if terminal_shaped(shape):+ return Verdict("terminal_flow")+ if (+ _measured(shape)+ and not large_function(shape)+ and facts.evidence(path, symbol) is False+ ):+ return Verdict("moderate_quiet")return ELIGIBLE+def _measured(shape: Mapping[str, int]) -> bool:+ """Whether any size was measured: with none, there are no grounds to call+ the function moderate."""+ return bool(shape.get("ccn") or measured_nloc(shape))++def refactor_verdict(gain: float,steps: list[Mapping[str, Any]],diff --git a/packages/core/src/repowise/core/analysis/health/queue/value.py b/packages/core/src/repowise/core/analysis/health/queue/value.pyindex d6f991cd9..e1070179f 100644--- a/packages/core/src/repowise/core/analysis/health/queue/value.py+++ b/packages/core/src/repowise/core/analysis/health/queue/value.py@@ -10,7 +10,7 @@ only re-orders units there.from __future__ import annotationsfrom collections.abc import Mapping-from math import log2+from math import ceil, log2from typing import Anyfrom ...execution_roles import COLD_ROLES, LEADING_ROLES@@ -35,6 +35,9 @@ GAIN_CCN = SIZE_CCN[0]PERF_CCN = SIZE_CCN[1]#: On a file in the top fifth by churn. History re-orders inside a band only.CHURN_WEIGHT = 1.25+#: One change in 90 days is not changing often. Where the top fifth starts+#: below this (a shallow clone, a young repository), history tells nothing.+MIN_CHURN_COMMITS = 2def gain_value(gain: float, central: bool) -> int:@@ -66,6 +69,22 @@ def reach(dependents: int | None) -> float:return 1 + log2(1 + max(dependents or 0, 0))+#: A function under this share of its file's code lines gets that share of+#: the file's importers, not all of them: in a file that holds many modules'+#: worth of code, the importers come for the rest. Chosen after seeing the+#: dogfood lists (no own-repo function in them is under 8% of its file).+HUB_SHARE = 0.05+++def function_reach(dependents: int | None, function_nloc: int, file_nloc: int | None) -> int | None:+ """The importers a function is credited with: its file's, or, under+ :data:`HUB_SHARE` of the file, that share of them, rounded up."""+ if not dependents or not function_nloc or not file_nloc:+ return dependents+ share = function_nloc / file_nloc+ return dependents if share >= HUB_SHARE else ceil(dependents * share)++def worth(removed_ccn: float, dependents: int | None, churning: bool) -> float:"""The order inside a value band: complexity removed times :func:`reach`,:data:`CHURN_WEIGHT` more on a file that changes often. Unbounded on@@ -143,9 +162,12 @@ __all__ = ["CHURN_WEIGHT","GAIN_CCN","GAIN_CUTS",+ "HUB_SHARE",+ "MIN_CHURN_COMMITS","PERF_CCN","SIZE_SEVERE","VALUE_MAX",+ "function_reach","gain_value","perf_confidence","perf_ready",diff --git a/packages/core/src/repowise/core/analysis/health/worth.py b/packages/core/src/repowise/core/analysis/health/worth.pyindex a64a18027..cad621b2c 100644--- a/packages/core/src/repowise/core/analysis/health/worth.py+++ b/packages/core/src/repowise/core/analysis/health/worth.py@@ -17,6 +17,7 @@ from collections.abc import Iterable, Mapping, Sequencefrom typing import Any, Literalfrom .complexity.dispatch import DISPATCH_SHARE+from .complexity.terminal import TERMINAL_SHAREfrom .rows import detail_map, field#: Problem-size cut points. Each is a multiple of the detector's own bar: CCN@@ -120,6 +121,7 @@ def measure(findings: Iterable[Any]) -> dict[str, int]:``deprecated`` when any sits in a function marked deprecated,``gated_off`` when any sits in a :func:`dormant` function,``dispatch_pct`` is the largest stored dispatch share in percent,+ ``terminal_pct`` the largest stored terminal share (``complexity/terminal.py``),``start`` / ``end`` span the function as its size findings place it, and``deep_start`` / ``deep_end`` are its deepest nested block's lines."""@@ -136,9 +138,10 @@ def measure(findings: Iterable[Any]) -> dict[str, int]: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))+ for key, pct in (("dispatch_share", "dispatch_pct"), ("terminal_share", "terminal_pct")):+ share = details.get(key)+ if isinstance(share, (int, float)):+ shape[pct] = max(shape.get(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:@@ -165,6 +168,27 @@ def dispatch_shaped(shape: Mapping[str, int]) -> bool:return shape.get("dispatch_pct", 0) >= DISPATCH_SHARE * 100+def terminal_shaped(shape: Mapping[str, int]) -> bool:+ """The function is a print or prompt flow: a status report, a checklist,+ a setup wizard, whose branches choose what to show."""+ return shape.get("terminal_pct", 0) >= TERMINAL_SHARE * 100+++def measured_nloc(shape: Mapping[str, int]) -> int:+ """The function's code lines; with none stored, its span, which bounds+ them from above; 0 with neither."""+ nloc = shape.get("nloc") or 0+ if not nloc and shape.get("start") and shape.get("end"):+ nloc = shape["end"] - shape["start"] + 1+ return nloc+++def large_function(shape: Mapping[str, int]) -> bool:+ """Big enough to lead on size alone: CCN 80 or 200 lines. Nesting does not+ count here: a deep block in a short function is a small fix."""+ return shape.get("ccn", 0) >= SIZE_CCN[2] or measured_nloc(shape) >= SIZE_NLOC[1]++#: Nesting this share of the CCN or more is one else-if or ternary chain,#: each arm nested in the last: deep by count, flat to read.CHAIN_SHARE = 0.8@@ -178,10 +202,7 @@ def _chained(shape: Mapping[str, int]) -> bool:def worth_size(shape: Mapping[str, int]) -> int:""":func:`magnitude` with nesting under 8 counted only in a function pastthe length bar: moderate depth in a short function is a small fix."""- nloc = shape.get("nloc") or 0- if not nloc and shape.get("start") and shape.get("end"):- nloc = shape["end"] - shape["start"] + 1- if nloc >= SIZE_NLOC[0] or shape.get("max_nesting", 0) >= SIZE_NESTING[2]:+ if measured_nloc(shape) >= SIZE_NLOC[0] or shape.get("max_nesting", 0) >= SIZE_NESTING[2]:return magnitude(shape)return magnitude({**shape, "max_nesting": 0})@@ -344,10 +365,13 @@ __all__ = ["dormant","execution_role","finding_priorities",+ "large_function","lead_reason","low_priority","magnitude","measure",+ "measured_nloc","perf_facets",+ "terminal_shaped","worth_size",]diff --git a/packages/types/src/fix-first.ts b/packages/types/src/fix-first.tsindex d590d536c..e23e7a800 100644--- a/packages/types/src/fix-first.ts+++ b/packages/types/src/fix-first.ts@@ -45,7 +45,9 @@ export type FixExclusion =| "small_function"| "no_concrete_step"| "low_value_kind"- | "kind_unaudited";+ | "kind_unaudited"+ | "terminal_flow"+ | "moderate_quiet";/** `all` keeps test files, labelled in `context`. */export type FixScope = "production" | "all";diff --git a/packages/types/src/queue.ts b/packages/types/src/queue.tsindex 00bfaeeee..033f44c42 100644--- a/packages/types/src/queue.ts+++ b/packages/types/src/queue.ts@@ -33,6 +33,8 @@ export type QueueReason =| "unmeasured_cost"| "cold_role"| "background_unproven"+ | "terminal_flow"+ | "moderate_quiet"| "not_judged"| "covered_by_plan"| "not_file_lead"diff --git a/packages/ui/__tests__/health/fixtures/fix-first.ts b/packages/ui/__tests__/health/fixtures/fix-first.tsindex bd23b97fe..d1c9db983 100644--- a/packages/ui/__tests__/health/fixtures/fix-first.ts+++ b/packages/ui/__tests__/health/fixtures/fix-first.ts@@ -627,7 +627,9 @@ export const FIX_FIRST_QUEUE: FixFirstQueue = {"small_function": 0,"no_concrete_step": 0,"low_value_kind": 0,- "kind_unaudited": 0+ "kind_unaudited": 0,+ "terminal_flow": 0,+ "moderate_quiet": 0},"dormant": 0},diff --git a/packages/ui/src/health/fix-first/scope.ts b/packages/ui/src/health/fix-first/scope.tsindex c63398f3a..9eea160fe 100644--- a/packages/ui/src/health/fix-first/scope.ts+++ b/packages/ui/src/health/fix-first/scope.ts@@ -46,11 +46,13 @@ export const EXCLUSION_LABEL: Record<FixExclusion, string> = {gated_off: "switched off by a constant flag",cold_path: "run once per deploy, boot or incident",unreachable: "in dead code (delete it)",- inherent_dispatch: "one long dispatch on a value",+ inherent_dispatch: "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",kind_unaudited: "of a kind not yet audited for this list",+ terminal_flow: "print and prompt flows",+ moderate_quiet: "moderate functions that rarely change or break",};const EXCLUSION_ORDER: FixExclusion[] = [@@ -74,6 +76,8 @@ const EXCLUSION_ORDER: FixExclusion[] = ["no_concrete_step","low_value_kind","kind_unaudited",+ "terminal_flow",+ "moderate_quiet",];/**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 a60d1185c..159bb90cc 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@@ -78,6 +78,8 @@ function queue(items: FixItem[]): FixFirstQueue {no_concrete_step: 0,low_value_kind: 0,kind_unaudited: 0,+ terminal_flow: 0,+ moderate_quiet: 0,},dormant: 0,},diff --git a/tests/unit/analysis/test_actions_rules.py b/tests/unit/analysis/test_actions_rules.pyindex 2fab87eb4..9eff3f038 100644--- a/tests/unit/analysis/test_actions_rules.py+++ b/tests/unit/analysis/test_actions_rules.py@@ -232,6 +232,29 @@ def test_concentration_picks_the_narrow_high_lift_folder() -> None:assert set(a.includes) == {f"pkg/cli/update/a{i}.py" for i in range(4)}+def test_a_folder_names_its_first_step() -> None:+ (a,) = _run(code.fix_concentration, _concentration_facts()).actions+ # Every file here is untested; the most fixed one comes first.+ assert a.title == (+ "Stabilise `pkg/cli/update/`: first, add tests around `pkg/cli/update/a0.py` "+ "before its next change"+ )+ assert "10 of the 25 bug-fix commits" in a.impact+++def test_a_folder_with_no_first_step_is_left_out_and_counted() -> None:+ facts = _concentration_facts()+ # No coverage report and no test map: no file can name a step.+ unknown = {p: replace(f, tests_reaching=None) for p, f in facts.files.items()}+ out = _run(code.fix_concentration, replace(facts, files=unknown))+ assert out.actions == ()+ assert out.reason == "1 folder left out: no file in it names a first step."+++def test_a_folder_whose_files_fix_first_names_has_no_first_step() -> None:+ assert code._first_step((), {}) is None++def test_engine_drops_fragile_rows_a_folder_absorbed() -> None:facts = _concentration_facts()# Sanity: on their own, the folder's files are fragile.diff --git a/tests/unit/cli/test_refactoring_targets_stored.py b/tests/unit/cli/test_refactoring_targets_stored.pyindex 24d20dc82..812824b60 100644--- a/tests/unit/cli/test_refactoring_targets_stored.py+++ b/tests/unit/cli/test_refactoring_targets_stored.py@@ -49,8 +49,8 @@ def _finding(path: str, symbol: str) -> dict[str, Any]:"function_name": symbol,"line_start": 10,"line_end": 30,- # Past Fix first's size floor, so each opportunity is in the default scope.- "details": {"ccn": 16},+ # Large enough to lead with no history, so each opportunity is in the default scope.+ "details": {"ccn": 85},"health_impact": 3.0,"reason": "seeded","dimension": "defect",diff --git a/tests/unit/health/fix_first_rows.py b/tests/unit/health/fix_first_rows.pyindex 9612510fb..2537d1f70 100644--- a/tests/unit/health/fix_first_rows.py+++ b/tests/unit/health/fix_first_rows.py@@ -9,14 +9,15 @@ AT = datetime(2026, 9, 30, 12, 0)METRICS = [{"file_path": "src/core.py", "score": 4.0, "nloc": 300, "is_test": False,"commit_count_90d": 12, "dependents": 9, "analyzed_commit": "abc", "updated_at": AT},+ # Changes often: a moderate function leads only on churn or fix history.{"file_path": "src/plain.py", "score": 7.0, "nloc": 80, "is_test": False,- "commit_count_90d": 1, "dependents": 1, "analyzed_commit": "abc", "updated_at": AT},+ "commit_count_90d": 12, "dependents": 1, "analyzed_commit": "abc", "updated_at": AT},{"file_path": "src/hist.py", "score": 6.0, "nloc": 50, "is_test": False,"commit_count_90d": 3, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},{"file_path": "src/repo.py", "score": 8.0, "nloc": 90, "is_test": False,"commit_count_90d": 2, "dependents": 2, "analyzed_commit": "abc", "updated_at": AT},{"file_path": "tests/test_core.py", "score": 5.0, "nloc": 90, "is_test": True,- "commit_count_90d": 4, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},+ "commit_count_90d": 12, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},{"file_path": "scripts/tool.py", "score": 5.0, "nloc": 90, "is_test": False,"commit_count_90d": 1, "dependents": 0, "analyzed_commit": "abc", "updated_at": AT},]diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.pyindex 258ae2157..a473fd7cb 100644--- a/tests/unit/health/test_fix_first_build.py+++ b/tests/unit/health/test_fix_first_build.py@@ -61,6 +61,8 @@ def test_each_exclusion_is_counted_by_reason() -> None:"no_concrete_step": 0,"low_value_kind": 0,"kind_unaudited": 0,+ "terminal_flow": 0,+ "moderate_quiet": 0,}assert queue.totals.dormant == 0assert queue.totals.eligible == 3diff --git a/tests/unit/health/test_fix_first_worth.py b/tests/unit/health/test_fix_first_worth.pynew file mode 100644index 000000000..e3a359819--- /dev/null+++ b/tests/unit/health/test_fix_first_worth.py@@ -0,0 +1,175 @@+"""What Fix first leads with: print and prompt flows, moderate functions with no+history, and functions credited with a hub file's importers.++Each test builds the smallest rows that show the rule firing and the nearest+case where it must not.+"""++from __future__ import annotations++from repowise.core.analysis.health.complexity.terminal import is_terminal_call, terminal_share+from repowise.core.analysis.health.complexity.walker import walk_file+from repowise.core.analysis.health.fix_first import build_fix_first+from repowise.core.analysis.health.queue.value import HUB_SHARE, function_reach+from tests.unit.health.fix_first_rows import AT++# Neither churning nor central unless a test says so.+_CUTS = (10.0, 10.0)+++def _metric(path: str, *, commits: int = 1, dependents: int = 0, nloc: int = 900) -> dict:+ return {"file_path": path, "score": 3.0, "nloc": nloc, "is_test": False,+ "commit_count_90d": commits, "dependents": dependents,+ "analyzed_commit": "abc", "updated_at": AT}+++def _size(path: str, function: str, *, line: int = 10, **details) -> dict:+ return {"file_path": path, "biomarker_type": "complex_method", "severity": "high",+ "function_name": function, "line_start": line, "line_end": line + details["nloc"],+ "health_impact": 1.0, "reason": f"{function} is complex",+ "public_id": f"finding_{path}_{function}", "dimension": "defect",+ "details": {**details, "deepest_block": {"start": line + 5, "end": line + 9}}}+++def _history(path: str, marker: str, function: str | None = None) -> dict:+ return {"file_path": path, "biomarker_type": marker, "severity": "medium",+ "function_name": function, "health_impact": 0.5, "reason": marker,+ "public_id": f"finding_{path}_{marker}_{function}", "dimension": "defect"}+++def _queue(metrics: list[dict], findings: list[dict]):+ return build_fix_first(metrics=metrics, findings=findings, hot_cuts=_CUTS, limit=None)+++def _symbols(queue) -> set[str]:+ return {i.target.symbol for i in queue.items}+++# --- print and prompt flows ------------------------------------------------------+++def test_terminal_calls_are_read_by_name_and_receiver() -> None:+ assert is_terminal_call("print", set())+ assert is_terminal_call("print_info", set())+ assert is_terminal_call("_prompt_checklist", set())+ assert is_terminal_call("log", {"console"})+ assert is_terminal_call("write", {"sys", "stdout"})+ assert not is_terminal_call("log", {"logger"})+ assert not is_terminal_call("write", {"handle"})+ assert not is_terminal_call("build_prompt", set())+ for name in ("printer_for", "printable", "confirmed_order", "promptly", "echo_server_handle"):+ assert not is_terminal_call(name, set()), name+++def test_a_function_with_few_calls_has_no_terminal_share() -> None:+ assert terminal_share(2, 3) == 0.0+ assert terminal_share(2, 4) == 0.5+++def test_the_walker_measures_a_status_command_and_not_a_resolver() -> None:+ status = (+ "def show_status(cfg):\n"+ + "".join(+ f" if cfg.get('k{i}'):\n print('k{i} on')\n else:\n"+ f" print('k{i} off')\n"+ for i in range(6)+ )+ + " return load(cfg)\n"+ )+ resolver = "def resolve(cfg):\n a = load(cfg)\n b = merge(a, cfg)\n return check(b)\n"+ fns = {f.name: f for f in walk_file("s.py", "python", (status + resolver).encode()).functions}+ # 12 prints of 19 calls (six `cfg.get` and one `load` are not terminal).+ assert fns["show_status"].terminal_share == 0.63+ assert fns["resolve"].terminal_share == 0.0+++def test_a_print_flow_is_counted_out_and_a_logic_function_beside_it_stays() -> None:+ metrics = [_metric("cli/status.py", commits=40), _metric("core/run.py", commits=40)]+ findings = [+ _size("cli/status.py", "show_status", ccn=153, nloc=478, max_nesting=4,+ terminal_share=0.35),+ _size("core/run.py", "finalize", ccn=131, nloc=408, max_nesting=6, terminal_share=0.1),+ ]+ queue = _queue(metrics, findings)+ assert _symbols(queue) == {"finalize"}+ assert queue.totals.excluded["terminal_flow"] == 1+++# --- moderate functions need history ----------------------------------------------+++_MODERATE = {"ccn": 45, "nloc": 120, "max_nesting": 6}+++def test_a_moderate_function_in_a_known_quiet_file_is_counted_out() -> None:+ queue = _queue([_metric("lib/parse.py")], [_size("lib/parse.py", "parse", **_MODERATE)])+ assert queue.items == ()+ assert queue.totals.excluded["moderate_quiet"] == 1+++def test_a_moderate_function_with_unknown_history_still_leads() -> None:+ finding = _size("lib/parse.py", "parse", **_MODERATE)+ # No commit count: no git, or a file git has not seen.+ no_git = {**_metric("lib/parse.py"), "commit_count_90d": None}+ assert _symbols(_queue([no_git], [finding])) == {"parse"}+ # A shallow clone: every file changed once, so history tells files apart not at all.+ metrics = [_metric("lib/parse.py", commits=1), _metric("lib/other.py", commits=1)]+ shallow = build_fix_first(metrics=metrics, findings=[finding], limit=None)+ assert _symbols(shallow) == {"parse"}+ assert shallow.totals.excluded["moderate_quiet"] == 0+++def test_churn_bug_fixes_or_a_hotspot_on_the_function_let_it_lead() -> None:+ finding = _size("lib/parse.py", "parse", **_MODERATE)+ churning = _queue([_metric("lib/parse.py", commits=40)], [finding])+ fixed = _queue([_metric("lib/parse.py")], [finding, _history("lib/parse.py", "prior_defect")])+ hot = _queue([_metric("lib/parse.py")],+ [finding, _history("lib/parse.py", "function_hotspot", "parse")])+ assert all(_symbols(q) == {"parse"} for q in (churning, fixed, hot))+++def test_a_hotspot_on_another_function_is_no_evidence() -> None:+ queue = _queue([_metric("lib/parse.py")],+ [_size("lib/parse.py", "parse", **_MODERATE),+ _history("lib/parse.py", "function_hotspot", "other")])+ assert queue.totals.excluded["moderate_quiet"] == 1+++def test_a_large_function_leads_without_history() -> None:+ long_ = _size("lib/a.py", "long_one", ccn=45, nloc=230, max_nesting=6)+ branchy = _size("lib/b.py", "branchy", ccn=85, nloc=150, max_nesting=6)+ queue = _queue([_metric("lib/a.py"), _metric("lib/b.py")], [long_, branchy])+ assert _symbols(queue) == {"long_one", "branchy"}+++# --- a hub file's importers -------------------------------------------------------+++def test_function_reach_credits_a_small_share_of_a_hub_file() -> None:+ assert function_reach(287, 265, 21080) == 4+ assert function_reach(18, 423, 1405) == 18+ assert function_reach(None, 265, 21080) is None+ assert function_reach(80, 0, 9000) == 80+ assert function_reach(100, int(HUB_SHARE * 1000), 1000) == 100+++def test_a_function_lost_in_a_hub_file_is_not_central() -> None:+ finding = _size("gateway/run.py", "send_progress", ccn=75, nloc=265, max_nesting=5)+ hub = _queue([_metric("gateway/run.py", commits=40, dependents=287, nloc=21080)], [finding])+ focused = _queue([_metric("gateway/run.py", commits=40, dependents=287, nloc=1000)], [finding])+ (lost,), (kept,) = hub.items, focused.items+ assert (lost.value, kept.value) == (2, 3)+ facts = {f.factor: f.value for f in lost.why_ranked}+ assert facts["files that import it"] == "287, 4 counted for its share of the file"+ assert {f.factor: f.value for f in kept.why_ranked}["files that import it"] == "287 (top fifth)"+ # What the file is, the item still says.+ assert "287" in lost.why+++def test_size_markers_store_a_terminal_share_only_when_there_is_one() -> None:+ from repowise.core.analysis.health.biomarkers.base import shape_details++ src = b"def a():\n print(1)\n run()\n go()\n print(2)\n\ndef b():\n run()\n"+ fns = {f.name: f for f in walk_file("x.py", "python", src).functions}+ assert shape_details(fns["a"]) == {"dispatch_share": 0.0, "terminal_share": 0.5}+ assert shape_details(fns["b"]) == {"dispatch_share": 0.0}diff --git a/tests/unit/health/test_queue_eligibility.py b/tests/unit/health/test_queue_eligibility.pyindex 3bdc19dd1..c3967e8ba 100644--- a/tests/unit/health/test_queue_eligibility.py+++ b/tests/unit/health/test_queue_eligibility.py@@ -24,6 +24,9 @@ class _Facts:def cloned(self, path, shape):return False+ def evidence(self, path, symbol):+ return True+def _cause(**over):row = {diff --git a/tests/unit/health/test_queue_value_order.py b/tests/unit/health/test_queue_value_order.pyindex 432b06830..c596e1721 100644--- a/tests/unit/health/test_queue_value_order.py+++ b/tests/unit/health/test_queue_value_order.py@@ -45,7 +45,8 @@ FINDINGS = [# highest of the large functions, which is what used to rank it first._finding("cli/status.py", "show_status", 0.72, ccn=153, nloc=478, max_nesting=6),_finding("gateway/config.py", "load_gateway_config", 0.52, ccn=151, nloc=341, max_nesting=6),- # Past the bars by less: CCN 45 over 120 lines, in a file nothing imports.+ # Past the bars by less: CCN 45 over 120 lines, in a file nothing imports+ # and nobody changed. It leads only on churn or fix history, so it is out._finding("lib/parse.py", "parse_block", 1.6, ccn=45, nloc=120, max_nesting=6),]@@ -65,7 +66,6 @@ GOLDEN = [("show_status", "4", "the wizard: band 4 on size, CCN 153 x reach of only 7 importers"),("perf_req", "4", "request-run growing db loop: top band, worth a CCN 40 x 3 call sites"),("perf_unknown", "2", "the same loop with no role evidence: band 2, worth 103"),- ("parse_block", "2", "band 2 on size and gain; worth 45 (no importers) is below 103"),]@@ -90,6 +90,17 @@ def test_rank_order_golden() -> None:assert got == [(symbol, band) for symbol, band, _why in GOLDEN]+def test_a_moderate_function_with_no_history_is_counted_out() -> None:+ queue = _queue()+ assert "parse_block" not in {i.target.symbol for i in queue.items}+ assert queue.totals.excluded["moderate_quiet"] == 1+ churned = [{**m, "commit_count_90d": 40} if m["file_path"] == "lib/parse.py" else m+ for m in METRICS]+ again = build_fix_first(metrics=churned, findings=FINDINGS, performance=PERFORMANCE,+ hot_cuts=_CUTS, limit=None)+ assert "parse_block" in {i.target.symbol for i in again.items}++def test_the_giant_outranks_the_wizard_on_complexity_removed_times_reach() -> None:by_symbol = {i.target.symbol: i for i in _queue().items}giant, wizard = by_symbol["run_conversation"], by_symbol["show_status"]diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.pyindex ead131785..b6a1bf25f 100644--- a/tests/unit/server/test_refactoring_opportunities.py+++ b/tests/unit/server/test_refactoring_opportunities.py@@ -71,8 +71,8 @@ def _finding("function_name": function_name,"line_start": 10,"line_end": 30,- # Past Fix first's size floor, so the composed plan is a candidate.- "details": {"ccn": 16},+ # Large enough to lead with no history, so the composed plan is a candidate.+ "details": {"ccn": 85},"health_impact": impact,"reason": "seeded","dimension": "defect",