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): say what a Break up split buys in its reason (#3581)
Raghav Chamadiyafb8d423e3d8d
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.mdindex 1d1c256ac..bd5869e8d 100644--- a/docs/layers/CODE_HEALTH.md+++ b/docs/layers/CODE_HEALTH.md@@ -91,7 +91,9 @@ finding in a file with no plan. It gives what to change and where, why, the firsedit, the expected gain, the effort and the tests to run.Among items of the same value, a function that many commits have changed comesbefore an equally complex one that rarely changes, and its reason says how many-commits changed it.+commits changed it. A "Break up X" item's reason names the function's shape and what+splitting it buys: smaller parts that are easier to read and change, and less+duplicated code when part of it is a copy.Left out, and counted with a reason: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 6466fcceb..797d02c22 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@@ -16,16 +16,21 @@ from ..refactoring.render import briefTITLE_MAX = 90+#: What splitting a large function or class buys. Readability and the cost+#: of the next change, not defects: that is the claim a split can keep.+SPLIT_GAIN = "easier to read and change once split"+#: What the finding says about the code, completing "<subject> ...". The#: fallback when no measured fact is stored; each phrase must hold for every#: finding of its kind, so none claims coverage or callers it was not given.+#: A shape a split fixes ends on what the split buys.PROBLEM: dict[str, str] = {- "brain_method": "is long, branchy and widely depended on",- "complex_method": "has many independent paths through it",- "nested_complexity": "nests its control flow deeply",- "bumpy_road": "repeats nested blocks side by side, a sign it does several jobs",- "large_method": "is long",- "god_class": "holds too much of its subsystem in one class",+ "brain_method": f"is long and branchy; {SPLIT_GAIN}",+ "complex_method": f"has many paths; {SPLIT_GAIN}",+ "nested_complexity": f"nests deeply; {SPLIT_GAIN}",+ "bumpy_road": f"does several jobs side by side; {SPLIT_GAIN}",+ "large_method": f"is long; {SPLIT_GAIN}",+ "god_class": f"holds much of its subsystem; {SPLIT_GAIN}","low_cohesion": "holds groups of methods that share little state","complex_conditional": "packs several boolean operators into one condition","primitive_obsession": "takes a long list of parameters",@@ -68,7 +73,7 @@ REFACTOR_TITLE: dict[str, str] = {}#: 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"+CLONED = "which also removes a duplicate"#: Performance causes whose cost is not a boundary call: (title, problem, gain).PERF_SHAPE: dict[str, tuple[str, str, str]] = {diff --git a/tests/unit/health/test_fix_first_build.py b/tests/unit/health/test_fix_first_build.pyindex efb3499d6..552200fd9 100644--- a/tests/unit/health/test_fix_first_build.py+++ b/tests/unit/health/test_fix_first_build.py@@ -98,8 +98,8 @@ def test_text_quotes_the_stored_numbers() -> None:)# 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."+ "run has many paths; easier to read and change once split; "+ "9 files import it, changed 12 times in 90 days.")assert ("size", "CCN 44, 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"diff --git a/tests/unit/health/test_fix_first_precision.py b/tests/unit/health/test_fix_first_precision.pyindex 99ef05538..cce880f8d 100644--- a/tests/unit/health/test_fix_first_precision.py+++ b/tests/unit/health/test_fix_first_precision.py@@ -7,7 +7,10 @@ nearest case where it must not.from __future__ import annotations-from repowise.core.analysis.health.fix_first import build_fix_first+import re++from repowise.core.analysis.health.fix_first import build_fix_first, text+from repowise.core.analysis.health.worth import SIZE_MARKERSfrom tests.unit.health.fix_first_rows import FINDINGS, METRICS_COMPLEX = FINDINGS[1] # run in src/core.py: CCN 14, 50 lines, nests 4 deep@@ -359,7 +362,7 @@ def test_a_duplicate_inside_lifts_a_complexity_unit_one_step() -> None:value = "value within later"assert int(_ranked(lifted, value)) == int(_ranked(plain, value)) + 1assert _ranked(lifted, "duplicate inside") == "yes"- assert "duplicated" in lifted.why and "duplicated" not in plain.why+ assert text.CLONED in lifted.why and text.CLONED not in plain.whydef test_a_duplicate_elsewhere_in_the_file_does_not_lift() -> None:@@ -422,11 +425,24 @@ def test_why_says_why_it_matters_not_the_titles_size() -> None: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.whyassert item.why == (- "run has many independent paths through it; 9 files import it, "- "changed 12 times in 90 days."+ "run has many paths; easier to read and change once split; "+ "9 files import it, changed 12 times in 90 days.")+def test_break_up_why_says_what_the_split_buys_not_defects() -> None:+ """A split is a readability and change-cost claim: every phrase a Break up+ why can carry says what improves and names no defect."""+ defect = re.compile(r"bug|defect|fail|error|risk", re.IGNORECASE)+ phrases = [text.PROBLEM[m] for m in sorted(SIZE_MARKERS)] + [text.PROBLEM["god_class"]]+ for phrase in [*phrases, text.CLONED]:+ assert not defect.search(phrase), phrase+ assert all(phrase.endswith(text.SPLIT_GAIN) for phrase in phrases)+ item = _queue([_finding(ccn=249, nloc=1280, max_nesting=7)]).lead+ assert item.title.startswith("Break up run")+ assert not defect.search(f"{item.title} {item.why}")++def test_why_names_coverage_when_a_report_measured_it() -> None:covered = _queue([_finding()], [_metric(line_coverage_pct=41.6)]).leadassert covered.why.endswith("tests run 42% of its lines.")