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.

12.4 KB
Raw Blame
"""Module rollups, breakdowns and category caps, over every record shape.

These folds were held in two copies each — one in the REST router package, one
in the MCP tool — over rows that arrive as ORM objects, analyzer dataclasses or
plain dicts depending on the caller. The copies are gone; this pins what the
one implementation must do, including the cases the copies never agreed on:
floor ties, malformed legacy severity, absent categories, and stored applied
impact taking precedence over anything recomputed.
"""

from __future__ import annotations

from dataclasses import dataclass
from dataclasses import field as dc_field

import pytest

from repowise.core.analysis.health.aggregation import (
    MODULE_ROOT_LABEL,
    biomarker_breakdown,
    finding_base_deduction,
    module_label,
    module_rollups,
    score_breakdown,
    severity_breakdown,
)
from repowise.core.analysis.health.models import Severity
from repowise.core.analysis.health.scoring import (
    CATEGORY_CAPS,
    SCORE_FLOOR,
    SCORE_MAX,
    biomarker_category,
)


@dataclass
class _Finding:
    biomarker_type: str
    severity: str = "high"
    health_impact: float = 0.0
    details: dict = dc_field(default_factory=dict)
    id: str = "f1"
    function_name: str | None = None
    reason: str = ""


class _MetricRow:
    def __init__(self, file_path: str, score: float, nloc: int, module: str | None) -> None:
        self.file_path = file_path
        self.score = score
        self.nloc = nloc
        self.module = module


def _metric_dict(file_path: str, score: float, nloc: int, module: str | None) -> dict:
    return {"file_path": file_path, "score": score, "nloc": nloc, "module": module}


# --------------------------------------------------------------------------- #
# Module label policy
# --------------------------------------------------------------------------- #


@pytest.mark.parametrize(
    "path,expected",
    [
        ("packages/core/src/a.py", "packages"),
        ("packages/a.py", "packages"),
        ("README.md", MODULE_ROOT_LABEL),
        ("", MODULE_ROOT_LABEL),
        (None, MODULE_ROOT_LABEL),
        ("src/", "src"),
    ],
)
def test_module_label_takes_the_first_segment_or_the_root_label(path, expected) -> None:
    assert module_label(path) == expected


# --------------------------------------------------------------------------- #
# Module rollups
# --------------------------------------------------------------------------- #


def test_module_rollups_are_identical_for_dicts_and_attribute_rows() -> None:
    rows = [
        ("api/a.py", 4.0, 100, "api"),
        ("api/b.py", 8.0, 300, "api"),
        ("web/c.py", 6.0, 50, "web"),
    ]
    as_dicts = module_rollups([_metric_dict(*r) for r in rows])
    as_objects = module_rollups([_MetricRow(*r) for r in rows])
    assert as_dicts == as_objects
    assert [r["module"] for r in as_dicts] == ["web", "api"]  # worst average first
    api = as_dicts[1]
    assert api["file_count"] == 2
    assert api["nloc"] == 400
    # NLOC-weighted: (4*100 + 8*300) / 400.
    assert api["average_health"] == 7.0
    assert api["worst_performer_path"] == "api/a.py"
    assert api["worst_performer_score"] == 4.0


def test_rows_without_a_module_are_dropped_not_bucketed_under_none() -> None:
    rollups = module_rollups(
        [_metric_dict("a.py", 3.0, 10, None), _metric_dict("api/b.py", 9.0, 10, "api")]
    )
    assert [r["module"] for r in rollups] == ["api"]


def test_module_rollup_order_is_total_across_equal_averages() -> None:
    rows = [
        _metric_dict("b/x.py", 5.0, 10, "b"),
        _metric_dict("a/x.py", 5.0, 10, "a"),
        _metric_dict("c/x.py", 1.0, 10, "c"),
    ]
    assert [r["module"] for r in module_rollups(rows)] == ["c", "a", "b"]


def test_a_module_worst_performer_uses_depth_when_the_scores_tie() -> None:
    rows = [
        _metric_dict("api/z.py", SCORE_FLOOR, 10, "api"),
        _metric_dict("api/a.py", SCORE_FLOOR, 10, "api"),
    ]
    deepest = module_rollups(rows, {"api/z.py": 12.0, "api/a.py": 3.0})
    assert deepest[0]["worst_performer_path"] == "api/z.py"


def test_without_depth_a_tied_module_worst_performer_falls_to_the_path() -> None:
    rows = [
        _metric_dict("api/z.py", SCORE_FLOOR, 10, "api"),
        _metric_dict("api/a.py", SCORE_FLOOR, 10, "api"),
    ]
    assert module_rollups(rows)[0]["worst_performer_path"] == "api/a.py"


def test_a_zero_score_is_a_score_not_a_missing_measurement() -> None:
    """``or SCORE_MAX`` here would rank the worst possible file as the best."""
    rows = [
        _metric_dict("api/a.py", 0.0, 10, "api"),
        _metric_dict("api/b.py", 10.0, 10, "api"),
    ]
    rollup = module_rollups(rows)[0]
    assert rollup["average_health"] == 5.0
    assert rollup["worst_performer_score"] == 0.0
    assert rollup["worst_performer_path"] == "api/a.py"


def test_a_missing_nloc_weighs_one_rather_than_dividing_by_zero() -> None:
    rows = [
        {"file_path": "api/a.py", "score": 2.0, "module": "api"},
        {"file_path": "api/b.py", "score": 8.0, "module": "api"},
    ]
    rollup = module_rollups(rows)[0]
    assert rollup["nloc"] == 0
    assert rollup["average_health"] == 5.0


# --------------------------------------------------------------------------- #
# Severity + biomarker breakdowns
# --------------------------------------------------------------------------- #


def test_severity_breakdown_always_declares_every_bucket() -> None:
    assert severity_breakdown([]) == {"critical": 0, "high": 0, "medium": 0, "low": 0}


def test_severity_breakdown_reads_enums_strings_and_casing_alike() -> None:
    findings = [
        _Finding("a", severity=Severity.HIGH),
        {"biomarker_type": "b", "severity": "high"},
        _Finding("c", severity="HIGH"),
    ]
    assert severity_breakdown(findings)["high"] == 3


def test_malformed_legacy_severity_is_dropped_not_raised() -> None:
    findings = [_Finding("a", severity="informational"), _Finding("b", severity=None)]
    assert severity_breakdown(findings) == {"critical": 0, "high": 0, "medium": 0, "low": 0}


def test_biomarker_totals_count_a_malformed_severity_the_buckets_cannot() -> None:
    rows = biomarker_breakdown([_Finding("god_class", severity="informational")])
    assert rows == [
        {
            "biomarker_type": "god_class",
            "critical": 0,
            "high": 0,
            "medium": 0,
            "low": 0,
            "total": 1,
        }
    ]


def test_biomarker_breakdown_is_busiest_first_with_a_total_order() -> None:
    findings = [
        _Finding("zeta"),
        _Finding("alpha"),
        _Finding("busy"),
        _Finding("busy"),
    ]
    assert [r["biomarker_type"] for r in biomarker_breakdown(findings)] == [
        "busy",
        "alpha",
        "zeta",
    ]


# --------------------------------------------------------------------------- #
# Score / category breakdown
# --------------------------------------------------------------------------- #


def _category_biomarker(category: str) -> str:
    """A biomarker name the scorer files under *category*."""
    for name in ("god_class", "complex_method", "coverage_gap", "dry_violation", "error_handling"):
        if biomarker_category(name) == category:
            return name
    raise AssertionError(f"no biomarker maps to {category}")


def test_a_continuous_deduction_override_replaces_the_severity_band() -> None:
    finding = _Finding("coverage_gradient", severity="low", details={"deduction": 3.25})
    assert finding_base_deduction(finding) == 3.25


def test_the_override_is_read_from_stored_details_json_too() -> None:
    stored = {
        "biomarker_type": "coverage_gradient",
        "severity": "low",
        "details_json": '{"deduction": 2.5}',
    }
    assert finding_base_deduction(stored) == 2.5


def test_a_malformed_severity_falls_back_instead_of_raising() -> None:
    assert finding_base_deduction(_Finding("god_class", severity="informational")) == 0.5


def test_the_breakdown_reproduces_the_score_from_stored_impact() -> None:
    biomarker = _category_biomarker("structural_complexity")
    findings = [_Finding(biomarker, health_impact=1.5), _Finding(biomarker, health_impact=0.75)]
    out = score_breakdown(findings)
    assert out["total_deduction"] == 2.25
    assert out["score"] == round(SCORE_MAX - 2.25, 2)
    assert out["categories"][0]["applied_deduction"] == 2.25


def test_a_curved_category_reports_its_ceiling_and_is_never_held_at_it() -> None:
    """Code categories saturate toward 3.09 x their cap, so none sits at a ceiling."""
    from repowise.core.analysis.health.shape_curve import ceiling

    biomarker = _category_biomarker("structural_complexity")
    cap = CATEGORY_CAPS["structural_complexity"]
    findings = [_Finding(biomarker, severity="critical", health_impact=cap / 4) for _ in range(4)]
    category = score_breakdown(findings)["categories"][0]
    assert category["applied_deduction"] == pytest.approx(cap)
    assert category["raw_deduction"] > cap
    assert category["cap"] == round(ceiling(cap), 2)
    assert category["capped"] is False


def test_the_history_category_reports_the_cap_it_was_scored_under() -> None:
    """The history cap follows the structure half, so the breakdown must show
    the live cap (1.0 + structure), not the 3.5 ceiling it never reached."""
    from repowise.core.analysis.health.scoring import HISTORY_CATEGORY, history_cap

    shape = _Finding(_category_biomarker("structural_complexity"), health_impact=0.5)
    hist = _Finding("prior_defect", severity="critical", health_impact=1.5)
    by_cat = {c["category"]: c for c in score_breakdown([shape, hist])["categories"]}
    assert by_cat[HISTORY_CATEGORY]["cap"] == round(history_cap(0.5), 2) == 1.5
    assert by_cat[HISTORY_CATEGORY]["capped"] is True


def test_destacked_history_under_its_cap_is_not_flagged_capped() -> None:
    """History findings de-stack before the cap; that alone is not a cap binding."""
    from repowise.core.analysis.health.scoring import HISTORY_CATEGORY

    shape = _Finding(_category_biomarker("structural_complexity"), health_impact=2.5)
    top = _Finding("prior_defect", severity="critical", health_impact=2.0)
    rest = _Finding("prior_defect", severity="high", health_impact=0.3)
    history = {c["category"]: c for c in score_breakdown([shape, top, rest])["categories"]}[
        HISTORY_CATEGORY
    ]
    assert history["raw_deduction"] == 2.3
    assert [f["raw_impact"] for f in history["findings"]] == [2.0, 0.3]
    assert history["capped"] is False


def test_a_governance_finding_does_not_reshape_the_history_breakdown() -> None:
    """Governance findings are written after scoring, so they add no raw history."""
    from repowise.core.analysis.health.scoring import HISTORY_CATEGORY

    shape = _Finding(_category_biomarker("structural_complexity"), health_impact=2.5)
    real = _Finding("prior_defect", severity="high", health_impact=1.2)
    governance = _Finding("ungoverned_hotspot", severity="critical", health_impact=0.0)
    history = {c["category"]: c for c in score_breakdown([shape, real, governance])["categories"]}[
        HISTORY_CATEGORY
    ]
    assert [f["raw_impact"] for f in history["findings"]] == [1.2, 0.0]
    assert history["capped"] is False


def test_a_category_with_no_findings_is_absent_rather_than_zero_filled() -> None:
    biomarker = _category_biomarker("structural_complexity")
    out = score_breakdown([_Finding(biomarker, health_impact=1.0)])
    assert [c["category"] for c in out["categories"]] == ["structural_complexity"]


def test_the_breakdown_never_reports_below_the_floor() -> None:
    biomarker = _category_biomarker("structural_complexity")
    findings = [_Finding(biomarker, health_impact=50.0)]
    assert score_breakdown(findings)["score"] == SCORE_FLOOR


def test_the_breakdown_is_identical_for_dataclasses_and_stored_rows() -> None:
    biomarker = _category_biomarker("structural_complexity")
    as_objects = [_Finding(biomarker, severity="high", health_impact=1.5, id="x")]
    as_dicts = [
        {
            "biomarker_type": biomarker,
            "severity": "high",
            "health_impact": 1.5,
            "details_json": "{}",
            "id": "x",
            "function_name": None,
            "reason": "",
        }
    ]
    assert score_breakdown(as_objects) == score_breakdown(as_dicts)


def test_a_null_health_impact_counts_as_no_deduction() -> None:
    biomarker = _category_biomarker("structural_complexity")
    out = score_breakdown([{"biomarker_type": biomarker, "severity": "high", "health_impact": None}])
    assert out["total_deduction"] == 0.0
    assert out["score"] == SCORE_MAX