Skip to content

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

feat(health): 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.md
index 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 firs
edit, the expected gain, the effort and the tests to run.
Among items of the same value, a function that many commits have changed comes
before 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.py
index 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 brief
TITLE_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.py
index 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.py
index 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_MARKERS
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
@@ -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)) + 1
assert _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.why
def 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.why
assert 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)]).lead
assert covered.why.endswith("tests run 42% of its lines.")