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): brain_method becomes advisory (#4115)

Raghav Chamadiya516d9e53707e
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index e44905407..e5c982c3a 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -323,7 +323,7 @@ golden guarantee (§6).
| Category | Cap | Markers |
|------------------------|------|------------|
| Organizational | −3.5‡ | developer_congestion, knowledge_loss, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter, prior_defect, ungoverned_hotspot†, stale_governance†, contradictory_decision† |
-| Structural complexity | −2.5 | brain_method, low_cohesion, god_class, nested_complexity, bumpy_road, complex_conditional |
+| Structural complexity | −2.5 | low_cohesion, god_class, nested_complexity, bumpy_road, complex_conditional |
| Test coverage | −2.0 | untested_hotspot, coverage_gap |
| Test coverage gradient | −2.0 | coverage_gradient |
| Size & complexity | −1.5 | complex_method, large_method, primitive_obsession |
@@ -346,6 +346,11 @@ nothing. On its own it ranks defect-prone files near chance (AUC about 0.55), an
a pre-registered test on 12 repositories no earlier health study used found the
score without it non-inferior at predicting defects.
+`brain_method` is advisory too. It fires only on a function that `complex_method`
+and `large_method` already charge, so scoring it charged one function twice, and
+dropping it left defect AUC unchanged on the 66-repo corpus. It is still listed
+under structural complexity.
+
The maintainability dimension has its own independent tables
(`_MAINTAINABILITY_CATEGORY`, caps: structural_complexity 4.0,
size_and_complexity 2.0, duplication 2.0, error_handling 2.0, sql 2.0), and the
@@ -572,7 +577,7 @@ full calibration, with confidence intervals, is published in the
| 1.1–1.33 | remaining structural complexity / size markers | Moderate calibrated lift. |
| 1.3 / 1.2 / 1.1 | `untested_hotspot` / `churn_risk` / `code_age_volatility` | Coverage-dependent and rarely-firing; keep prior weights the corpus could not fairly measure. |
| 1.0 | `prior_defect` | Neutral by design: largely redundant with the other process signals, kept for its explanatory value. |
-| 0.5 (floored) | `developer_congestion`, `dry_violation`, `low_cohesion`, `brain_method`, `primitive_obsession`, `bumpy_road` | Fire widely but proved weak under leakage-free scoring; kept as maintainability and parity signals, not disabled. |
+| 0.5 (floored) | `developer_congestion`, `dry_violation`, `low_cohesion`, `primitive_obsession`, `bumpy_road` | Fire widely but proved weak under leakage-free scoring; kept as maintainability and parity signals, not disabled. |
| 0.4 (de-rated) | `knowledge_loss` | Weakest of the floored set. |
| 0.5 (not fitted) | `error_handling` | Excluded from calibration (AUC-neutral); floored and capped at 0.5 per file. |
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index 71416b9d7..908d6f1b2 100644
--- a/docs/layers/CODE_HEALTH.md
+++ b/docs/layers/CODE_HEALTH.md
@@ -47,8 +47,8 @@ are never blended into one number.
| Maintainability | How hard the code is to read and change | Set by hand; never fitted to bugs |
| Performance risk | Where the structure wastes work | Per-marker precision weights; see [PERFORMANCE.md](PERFORMANCE.md) |
-Smells that fire often but predict bugs weakly (low cohesion, brain methods,
-duplicated code, broad error handling) are down-weighted in code health and
+Smells that fire often but predict bugs weakly (low cohesion, duplicated code,
+broad error handling) are down-weighted in code health and
counted in full in maintainability.
## Reading the score
@@ -195,7 +195,7 @@ dominating a file.
| Family | Detectors | Cap | Catches |
|---|---:|---|---|
-| Structural complexity | 6 | 2.5 | Deep nesting, brain methods, god classes, low cohesion, bumpy roads, complex conditions |
+| Structural complexity | 6 | 2.5 | Deep nesting, brain methods (listed, not scored), god classes, low cohesion, bumpy roads, complex conditions |
| Size and complexity | 3 | 1.5 | Long or high-CCN functions, primitive obsession |
| Duplication | 1 | 1.0 | Cloned blocks |
| Error handling | 1 | 0.5 | Swallowed or catch-all handlers, `unwrap`/panic, discarded Go errors |
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index a84422163..576842520 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -98,9 +98,10 @@ log = structlog.get_logger(__name__)
# Not a licence to move a calibrated scoring weight — those are frozen
# independently of this stamp.
#
-# Current stamp (v41): parameter counts exclude every comment kind and discover
-# C/C++ declarators and Kotlin lists. Cached walks must refresh the total,
-# typed and scalar counts, enabling primitive_obsession in those languages.
+# v41: ``brain_method`` is advisory, so every stored score that carried one
+# moves. Parameter counts exclude every comment kind and discover C/C++
+# declarators and Kotlin lists; cached walks refresh the total, typed and scalar
+# counts, enabling primitive_obsession in those languages.
#
# v40: an Extract Method plan names its helper with a placeholder
# (``extracted_helper``, numbered when taken in scope) and asks the agent applying
@@ -388,7 +389,7 @@ log = structlog.get_logger(__name__)
# forms. Files that were counted untested and are not become tested, which
# moves untested-hotspot findings and the scores that carry them, on every
# language with a prefix or spec convention rather than Ruby alone.
-HEALTH_ANALYZER_VERSION = 40
+HEALTH_ANALYZER_VERSION = 41
def _log_duplication_diagnostics(report: DuplicationReport) -> None:
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index c9be51d9c..a3f69479c 100644
--- a/packages/core/src/repowise/core/analysis/health/scoring.py
+++ b/packages/core/src/repowise/core/analysis/health/scoring.py
@@ -169,7 +169,6 @@ _BIOMARKER_WEIGHT_MULTIPLIER: dict[str, float] = {
# --- floored: fired widely but weak / non-predictive at T0 ---
"developer_congestion": 0.5, # was 1.5 - the HEAD-leakage hero; weak under T0
"low_cohesion": 0.5,
- "brain_method": 0.5,
"bumpy_road": 0.5,
"primitive_obsession": 0.5,
"dry_violation": 0.5,
@@ -273,7 +272,6 @@ ZERO_IMPACT_DIMENSIONS: frozenset[str] = frozenset({"performance", ADVISORY_DIME
_BIOMARKER_DIMENSIONS: dict[str, set[str]] = {
# Floored-in-defect maintainability smells -> full weight in maintainability.
"low_cohesion": {"defect", "maintainability"},
- "brain_method": {"defect", "maintainability"},
"primitive_obsession": {"defect", "maintainability"},
"dry_violation": {"defect", "maintainability"},
"error_handling": {"defect", "maintainability"},
@@ -332,6 +330,9 @@ _BIOMARKER_DIMENSIONS: dict[str, set[str]] = {
# Near-chance defect AUC alone, and dropping it was non-inferior on a fresh
# 12-repo pre-registered test (docs/architecture/code-health.md).
"hidden_coupling": {ADVISORY_DIMENSION},
+ # Fires only beside complex_method and large_method on the same function, so
+ # scoring it charged that function twice; dropping it moved no defect AUC.
+ "brain_method": {ADVISORY_DIMENSION},
}
# Maintainability per-biomarker weight multipliers. Expert-set by definition -
@@ -341,7 +342,6 @@ _BIOMARKER_DIMENSIONS: dict[str, set[str]] = {
# below, never against the defect corpus. Unknown biomarkers fall back to 1.0.
_MAINTAINABILITY_WEIGHT_MULTIPLIER: dict[str, float] = {
"low_cohesion": 1.0,
- "brain_method": 1.0,
"primitive_obsession": 1.0,
"dry_violation": 1.0,
"error_handling": 1.0,
@@ -361,7 +361,6 @@ _MAINTAINABILITY_WEIGHT_MULTIPLIER: dict[str, float] = {
# Maintainability category per biomarker - an OWN table, independent of the
# defect category map, so the two dimensions can be retuned separately.
_MAINTAINABILITY_CATEGORY: dict[str, str] = {
- "brain_method": "structural_complexity",
"low_cohesion": "structural_complexity",
"god_class": "structural_complexity",
"nested_complexity": "structural_complexity",
@@ -398,7 +397,6 @@ _MAINTAINABILITY_CATEGORY_CAPS: dict[str, float] = {
_MAINTAINABILITY_HOME: frozenset[str] = frozenset(
{
"low_cohesion",
- "brain_method",
"primitive_obsession",
"dry_violation",
"error_handling",
@@ -556,7 +554,7 @@ _PERFORMANCE_HOME: frozenset[str] = frozenset(
# The display half of the pairing above; ``test_advisory_dimension.py`` locks
# the two together for every registered biomarker.
_ADVISORY_HOME: frozenset[str] = frozenset(
- {"assertion_free_test", "mock_saturated_test", "hidden_coupling"}
+ {"assertion_free_test", "mock_saturated_test", "hidden_coupling", "brain_method"}
)
diff --git a/packages/ui/src/health/biomarker-glossary.ts b/packages/ui/src/health/biomarker-glossary.ts
index bfb803ed7..ba73b146e 100644
--- a/packages/ui/src/health/biomarker-glossary.ts
+++ b/packages/ui/src/health/biomarker-glossary.ts
@@ -66,7 +66,7 @@ export const BIOMARKER_GLOSSARY: Record<string, BiomarkerInfo> = {
label: BIOMARKER_LABELS.brain_method,
category: "structural_complexity",
description:
- "A function that knows too much — high cyclomatic complexity, many parameters, and deep nesting all at once. Hard to test, easy to break.",
+ "A function that knows too much — high cyclomatic complexity, many parameters, and deep nesting all at once. Hard to test, easy to break. Advisory: its complexity and size findings already cost this file points, so it costs none of its own.",
},
nested_complexity: {
label: BIOMARKER_LABELS.nested_complexity,
@@ -395,6 +395,7 @@ export const ADVISORY_HOME_BIOMARKERS: ReadonlySet<string> = new Set([
"assertion_free_test",
"mock_saturated_test",
"hidden_coupling",
+ "brain_method",
]);
/**
@@ -411,7 +412,6 @@ export const ADVISORY_HOME_BIOMARKERS: ReadonlySet<string> = new Set([
*/
export const MAINTAINABILITY_HOME_BIOMARKERS: ReadonlySet<string> = new Set([
"low_cohesion",
- "brain_method",
"primitive_obsession",
"dry_violation",
"error_handling",
diff --git a/tests/unit/generation/test_editor_file_fetcher.py b/tests/unit/generation/test_editor_file_fetcher.py
index 8cfa86593..51d4c8723 100644
--- a/tests/unit/generation/test_editor_file_fetcher.py
+++ b/tests/unit/generation/test_editor_file_fetcher.py
@@ -623,14 +623,14 @@ async def test_code_health_names_production_files_only(session, repo, tmp_path):
[
{
"file_path": path,
- "biomarker_type": "brain_method",
+ "biomarker_type": "complex_method",
"severity": "high",
"function_name": "f",
"line_start": 1,
"line_end": 130,
"details": {"ccn": 30, "nloc": 120, "max_nesting": 4, "deepest_block": {"start": 40, "end": 52}},
"health_impact": 2.0,
- "reason": "brain method",
+ "reason": "complex method",
}
for path in ("tests/test_a.py", "src/a.py")
],
@@ -640,4 +640,4 @@ async def test_code_health_names_production_files_only(session, repo, tmp_path):
assert data.code_health.worst_path == "src/a.py"
assert [f["where"] for f in data.code_health.fix_first] == ["src/a.py:1"]
- assert data.code_health.fix_first[0]["title"] == "Split f into smaller functions"
+ assert data.code_health.fix_first[0]["title"] == "Reduce the branching in f"
diff --git a/tests/unit/health/test_advisory_dimension.py b/tests/unit/health/test_advisory_dimension.py
index d860d9384..7007ecf34 100644
--- a/tests/unit/health/test_advisory_dimension.py
+++ b/tests/unit/health/test_advisory_dimension.py
@@ -91,10 +91,20 @@ def test_hidden_coupling_is_advisory():
assert deductions[1] == 0.0
+def test_brain_method_is_advisory():
+ """It restates complex_method plus large_method on the same function; still detected."""
+ assert is_advisory("brain_method")
+ shape = [_result("complex_method"), _result("large_method")]
+ alone, _ = score_file(shape)
+ with_brain, deductions = score_file([*shape, _result("brain_method", Severity.CRITICAL)])
+ assert with_brain == alone
+ assert deductions[2] == 0.0
+
+
def test_advisory_findings_do_not_dilute_a_real_deduction():
"""Adding an advisory finding to a scored one leaves the score alone."""
- scored_only, _ = score_file([_result("brain_method")])
- with_advisory, _ = score_file([_result("brain_method"), _result("mock_saturated_test")])
+ scored_only, _ = score_file([_result("low_cohesion")])
+ with_advisory, _ = score_file([_result("low_cohesion"), _result("mock_saturated_test")])
assert scored_only == with_advisory
assert with_advisory["defect"] < 10.0
@@ -185,7 +195,7 @@ def test_an_advisory_finding_is_never_a_files_dominant_cause():
advisory = _finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION)
assert primary_finding([advisory]) is None
- scored = _finding("brain_method", 0.5, "defect")
+ scored = _finding("low_cohesion", 0.5, "defect")
assert primary_finding([advisory, scored]) is scored
@@ -209,7 +219,7 @@ def test_severity_breakdown_excludes_advisory():
counts = severity_breakdown(
[
_finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION),
- _finding("brain_method", 0.5, "defect"),
+ _finding("low_cohesion", 0.5, "defect"),
]
)
assert counts["medium"] == 1
@@ -236,7 +246,7 @@ def test_advisory_is_absent_from_every_change_delta_counter():
from repowise.core.analysis.change_health.matcher import FindingMatcher
advisory = _finding("mock_saturated_test", 0.0, ADVISORY_DIMENSION)
- scored = _finding("brain_method", 0.5, "defect")
+ scored = _finding("low_cohesion", 0.5, "defect")
keep = [f for f in (advisory, scored) if not is_advisory(f.biomarker_type)]
both_sides = FindingMatcher({}).match([advisory, scored], [advisory, scored])
diff --git a/tests/unit/health/test_model_version_coupling.py b/tests/unit/health/test_model_version_coupling.py
index 179faf29b..b94d793dc 100644
--- a/tests/unit/health/test_model_version_coupling.py
+++ b/tests/unit/health/test_model_version_coupling.py
@@ -22,7 +22,7 @@ from repowise.core.analysis.health.refactoring.identity import (
# The three stamps as they stand together. Moving either identity model means
# moving the analyzer with it, and updating this tuple in the same commit.
-_STAMPS = (40, 3, 4)
+_STAMPS = (41, 3, 4)
def test_the_identity_models_and_the_analyzer_stamp_are_pinned_together() -> None:
diff --git a/tests/unit/health/test_primary_and_magnitude.py b/tests/unit/health/test_primary_and_magnitude.py
index 8921d46c3..bca632b74 100644
--- a/tests/unit/health/test_primary_and_magnitude.py
+++ b/tests/unit/health/test_primary_and_magnitude.py
@@ -121,7 +121,7 @@ def test_primary_finding_lets_a_function_worth_breaking_up_lead() -> None:
return row
condition = sized("complex_conditional", "run", 0.98, operator_count=7)
- brain = sized("brain_method", "run", 0.37, ccn=279, nloc=1354, max_nesting=5)
+ brain = sized("large_method", "run", 0.37, ccn=279, nloc=1354, max_nesting=5)
medium = sized("complex_method", "helper", 0.5, ccn=45, nloc=120, max_nesting=3)
small = sized("complex_method", "tiny", 0.2, ccn=12, nloc=20)
assert primary_finding([condition, small, medium, brain]) is brain
@@ -132,5 +132,5 @@ def test_primary_finding_lets_a_function_worth_breaking_up_lead() -> None:
dispatch = sized("complex_method", "route", 0.3, ccn=45, nloc=120, dispatch_share=0.9)
assert primary_finding([condition, dispatch]) is condition
# Nor does a function a constant-false flag switches off.
- gated = sized("brain_method", "off", 0.3, ccn=279, nloc=1354, gated_off=True)
+ gated = sized("large_method", "off", 0.3, ccn=279, nloc=1354, gated_off=True)
assert primary_finding([condition, gated]) is condition
diff --git a/tests/unit/health/test_scoring_dimensions.py b/tests/unit/health/test_scoring_dimensions.py
index e945b1b3b..12f0408c2 100644
--- a/tests/unit/health/test_scoring_dimensions.py
+++ b/tests/unit/health/test_scoring_dimensions.py
@@ -164,9 +164,9 @@ def _r(name: str, severity: Severity, *, deduction: float | None = None) -> Biom
_FIXTURES: list[list[BiomarkerResult]] = [
[],
[_r("complex_method", Severity.CRITICAL) for _ in range(20)],
- [_r("brain_method", Severity.CRITICAL), _r("nested_complexity", Severity.CRITICAL)],
+ [_r("low_cohesion", Severity.CRITICAL), _r("nested_complexity", Severity.CRITICAL)],
[
- _r("brain_method", Severity.CRITICAL),
+ _r("low_cohesion", Severity.CRITICAL),
_r("nested_complexity", Severity.HIGH),
_r("complex_method", Severity.MEDIUM),
_r("untested_hotspot", Severity.HIGH),
@@ -231,7 +231,7 @@ def test_defect_deductions_unchanged():
def test_score_file_returns_all_dimensions():
- scores, _ = score_file([_r("brain_method", Severity.HIGH)])
+ scores, _ = score_file([_r("low_cohesion", Severity.HIGH)])
assert set(scores) == set(DIMENSIONS)
@@ -374,7 +374,7 @@ def test_maintainability_accumulates_across_findings():
"""Two structural maintainability smells accumulate (under the 4.0 cap)."""
findings = [
_r("low_cohesion", Severity.HIGH), # 1.2 * 1.0
- _r("brain_method", Severity.HIGH), # 1.2 * 1.0
+ _r("low_cohesion", Severity.HIGH), # 1.2 * 1.0
]
scores, _ = score_file(findings)
# structural_complexity maintainability: 1.2 + 1.2 = 2.4 (< 4.0 cap) -> 7.6
@@ -383,7 +383,7 @@ def test_maintainability_accumulates_across_findings():
def test_maintainability_structural_cap_bounds_stream():
"""Many critical structural smells saturate the 4.0 maintainability cap."""
- findings = [_r("brain_method", Severity.CRITICAL) for _ in range(10)]
+ findings = [_r("low_cohesion", Severity.CRITICAL) for _ in range(10)]
scores, _ = score_file(findings)
# 10 * 2.0 = 20 raw -> clamped to the 4.0 structural cap -> 6.0
assert scores["maintainability"] == 6.0
@@ -392,9 +392,9 @@ def test_maintainability_structural_cap_bounds_stream():
def test_maintainability_categories_capped_independently():
"""Each maintainability category is bounded on its own budget."""
findings = [
- _r("brain_method", Severity.CRITICAL), # structural, capped at 4.0
- _r("brain_method", Severity.CRITICAL),
- _r("brain_method", Severity.CRITICAL),
+ _r("low_cohesion", Severity.CRITICAL), # structural, capped at 4.0
+ _r("low_cohesion", Severity.CRITICAL),
+ _r("low_cohesion", Severity.CRITICAL),
_r("dry_violation", Severity.CRITICAL), # duplication, capped at 2.0
_r("dry_violation", Severity.CRITICAL),
_r("error_handling", Severity.CRITICAL), # error_handling, capped at 2.0
diff --git a/tests/unit/health/test_scoring_snapshot.py b/tests/unit/health/test_scoring_snapshot.py
index 44681fe5c..c54261b7b 100644
--- a/tests/unit/health/test_scoring_snapshot.py
+++ b/tests/unit/health/test_scoring_snapshot.py
@@ -70,7 +70,6 @@ _EXPECTED_BIOMARKER_WEIGHT_MULTIPLIER = {
# floored - fired widely but weak/non-predictive at T0
"developer_congestion": 0.5,
"low_cohesion": 0.5,
- "brain_method": 0.5,
"bumpy_road": 0.5,
"primitive_obsession": 0.5,
"dry_violation": 0.5,
@@ -154,7 +153,7 @@ def _result(biomarker: str, severity: Severity) -> BiomarkerResult:
def test_known_fixture_score_is_stable():
"""A handcrafted finding set should produce a known, fixed score."""
findings = [
- _result("brain_method", Severity.CRITICAL),
+ _result("low_cohesion", Severity.CRITICAL),
_result("nested_complexity", Severity.HIGH),
_result("complex_method", Severity.MEDIUM),
_result("untested_hotspot", Severity.HIGH),
@@ -162,7 +161,7 @@ def test_known_fixture_score_is_stable():
]
scores, _ = score_file(findings)
# Math (defect-calibrated weights):
- # structural = brain(2.0*0.5) + nested(1.2*1.34) = 1.0 + 1.608 = 2.608 -> capped at 2.5
+ # structural = cohesion(2.0*0.5) + nested(1.2*1.34) = 1.0 + 1.608 = 2.608 -> capped at 2.5
# size_and_cx = complex_method 0.7 * 1.21 = 0.847 (under 1.5 cap)
# coverage = untested_hotspot 1.2 * 1.3 = 1.56 (under 2.0 cap)
# organizational = knowledge_loss 0.3 * 0.4 = 0.12 (under 3.5 cap)
@@ -172,7 +171,7 @@ def test_known_fixture_score_is_stable():
def test_category_cap_clamps_score():
"""Many critical structural findings should not exceed the -2.5 cap."""
- findings = [_result("brain_method", Severity.CRITICAL) for _ in range(10)]
+ findings = [_result("low_cohesion", Severity.CRITICAL) for _ in range(10)]
scores, _ = score_file(findings)
# Cap at -2.5, so floor on this category alone is 7.5.
assert scores["defect"] == 7.5
@@ -241,8 +240,8 @@ def test_organizational_cap_bounds_stream():
def test_history_cap_follows_structure():
"""Each point of code-shape deduction lets history deduct one more, to 3.5."""
history = [_result("prior_defect", Severity.CRITICAL) for _ in range(3)] # 6.0 raw
- # structure 2.5 (brain_method x 3 -> structural cap) -> history cap 3.5
- shaped = [*history, *(_result("brain_method", Severity.CRITICAL) for _ in range(3))]
+ # structure 2.5 (low_cohesion x 3 -> structural cap) -> history cap 3.5
+ shaped = [*history, *(_result("low_cohesion", Severity.CRITICAL) for _ in range(3))]
scores, _ = score_file(shaped)
assert round(scores["defect"], 6) == round(10.0 - 2.5 - 3.5, 6)
# structure 0.847 (one MEDIUM complex_method) -> history cap 1.847
diff --git a/tests/unit/server/golden/overview_summary.json b/tests/unit/server/golden/overview_summary.json
index ec6535058..072e376da 100644
--- a/tests/unit/server/golden/overview_summary.json
+++ b/tests/unit/server/golden/overview_summary.json
@@ -55,7 +55,7 @@
"worst_performance_score": 9.5,
"severity_breakdown": {
"critical": 0,
- "high": 5,
+ "high": 4,
"medium": 0,
"low": 0
},