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): brain_method becomes advisory (#4115)
Raghav Chamadiya516d9e53707e
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 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), ana pre-registered test on 12 repositories no earlier health study used found thescore 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.mdindex 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 andcounted 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.pyindex 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 = 41def _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.pyindex 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.tsindex 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.pyindex 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.pyindex 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_advisoryassert 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 FindingMatcheradvisory = _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.pyindex 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.pyindex 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 rowcondition = 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 conditiondiff --git a/tests/unit/health/test_scoring_dimensions.py b/tests/unit/health/test_scoring_dimensions.pyindex 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.0assert 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.0diff --git a/tests/unit/health/test_scoring_snapshot.py b/tests/unit/health/test_scoring_snapshot.pyindex 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.847diff --git a/tests/unit/server/golden/overview_summary.json b/tests/unit/server/golden/overview_summary.jsonindex 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},