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): score code files only and split the score in two (#2153)

Raghav Chamadiyae06a5e4b4c13
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py b/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
index a4b9b2802..b3030a53c 100644
--- a/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
+++ b/packages/cli/src/repowise/cli/commands/health_cmd/persist.py
@@ -169,6 +169,9 @@ def _persist_health(repo_path: object, *, report: object) -> None:
worst_performer_score=kpis.get("worst_performer_score"),
per_file_scores=scores_map,
per_file_deductions=deductions_map,
+ structure_average=kpis.get("structure_average"),
+ history_average=kpis.get("history_average"),
+ production_average=kpis.get("production_average"),
)
except Exception as exc:
console.print(f"[yellow]Snapshot write skipped: {exc}[/yellow]")
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
index c43acd770..1fd9465f6 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -910,6 +910,7 @@ async def _persist_full_update_async(
from repowise.core.analysis.health.governance import build_governance_findings
from repowise.core.persistence.crud import (
get_decision_health_summary,
+ get_scored_file_paths,
replace_governance_findings,
)
from repowise.core.persistence.models import DecisionRecord
@@ -922,6 +923,7 @@ async def _persist_full_update_async(
_gov = build_governance_findings(
health_summary=_summary,
decisions=_decisions,
+ scored_paths=await get_scored_file_paths(session, repo_id),
)
await replace_governance_findings(session, repo_id, _gov)
except Exception as exc:
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index 5ebef2042..7240a4cd0 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -417,6 +417,9 @@ async def _run_upgrade(
worst_performer_score=kpis.get("worst_performer_score"),
per_file_scores=scores_map,
per_file_deductions=deductions_map,
+ structure_average=kpis.get("structure_average"),
+ history_average=kpis.get("history_average"),
+ production_average=kpis.get("production_average"),
)
console.print(
f"Code health recomputed at FULL tier: "
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py b/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py
index 51fcc31f0..be4e89aff 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/hidden_coupling.py
@@ -34,7 +34,7 @@ short-circuit is explicit so backfill behavior is testable.
from __future__ import annotations
from ....co_change import STRUCTURAL_UNEXPLAINED, parse_partners
-from ....test_paths import is_test_to_production_pair
+from ....test_paths import is_test_related_path, is_test_to_production_pair
from ..models import Severity
from .base import BiomarkerResult, FileContext
@@ -69,6 +69,11 @@ class HiddenCouplingDetector:
category = "organizational"
def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ # A test file has no undeclared coupling worth reporting: its
+ # production partners are expected to co-change, and two tests moving
+ # together is the suite tracking the code, not a hidden dependency.
+ if is_test_related_path(ctx.file_path, ctx.language):
+ return []
meta = ctx.git_meta or {}
partners = parse_partners(meta.get("co_change_partners_json"))
# Explicit ESSENTIAL-tier short-circuit.
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py b/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py
index 8cfc89959..600266cdd 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/untested_hotspot.py
@@ -22,6 +22,7 @@ is an accusation.
from __future__ import annotations
+from ....test_paths import is_test_related_path
from ..models import Severity
from .base import BiomarkerResult, FileContext
@@ -53,6 +54,11 @@ class UntestedHotspotDetector:
category = "test_coverage"
def detect(self, ctx: FileContext) -> list[BiomarkerResult]:
+ # A test file is not undertested. Coverage reports rarely instrument
+ # the suite itself, so where coverage is ingested every test file reads
+ # as 0% covered and a churning one would be accused of it.
+ if is_test_related_path(ctx.file_path, ctx.language):
+ return []
if not _is_hotspot(ctx):
return []
if ctx.dependents_count < _DEPENDENTS_THRESHOLD:
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index e0834c8ab..9bcee0b83 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -65,7 +65,14 @@ from .refactoring import (
rank_suggestions,
)
from .refactoring.graph_signals import build_file_scc_index, build_methods_by_file
-from .scoring import attach_impacts, compute_kpis, remap_severities, score_file
+from .scope import scores_language
+from .scoring import (
+ attach_impacts,
+ compute_kpis,
+ deduction_split,
+ remap_severities,
+ score_file,
+)
from .source_reader import SourceReader, disk_source_reader
from .walk_cache import HealthWalkCache
@@ -106,7 +113,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 = 9
+HEALTH_ANALYZER_VERSION = 10
# Method-level smells that make the dataflow / Extract Method pass worthwhile.
# Only files carrying one of these get a CFG + def/use + reaching pass built.
@@ -500,6 +507,8 @@ class HealthAnalyzer:
for pf in self.parsed_files:
if changed_set is not None and pf.file_info.path not in changed_set:
continue
+ if not scores_language(pf.file_info.language):
+ continue
try:
fcx = self._walk(pf)
except Exception as exc:
@@ -678,7 +687,8 @@ class HealthAnalyzer:
target_files = [
pf
for pf in self.parsed_files
- if changed_set is None or pf.file_info.path in changed_set
+ if (changed_set is None or pf.file_info.path in changed_set)
+ and scores_language(pf.file_info.language)
]
if not target_files:
if dup_task is not None:
@@ -1106,6 +1116,7 @@ class HealthAnalyzer:
defect_score = scores["defect"]
maint_score = scores["maintainability"]
perf_score = scores["performance"]
+ structure_deduction, history_deduction = deduction_split(findings)
metric = HealthFileMetricData(
file_path=file_path,
score=round(defect_score, 2),
@@ -1128,6 +1139,9 @@ class HealthAnalyzer:
defect_score=round(defect_score, 2),
maintainability_score=(round(maint_score, 2) if maint_score is not None else None),
performance_score=(round(perf_score, 2) if perf_score is not None else None),
+ structure_deduction=structure_deduction,
+ history_deduction=history_deduction,
+ is_test=bool(pf.file_info.is_test),
)
# Refactoring layer: reuse the data just computed (class cohesion
diff --git a/packages/core/src/repowise/core/analysis/health/governance.py b/packages/core/src/repowise/core/analysis/health/governance.py
index b38c880b9..bc5988c41 100644
--- a/packages/core/src/repowise/core/analysis/health/governance.py
+++ b/packages/core/src/repowise/core/analysis/health/governance.py
@@ -21,8 +21,8 @@ from __future__ import annotations
from typing import Any
+from ...test_paths import is_test_related_path
from .models import HealthFindingData, Severity
-from .scoring import severity_deduction
# ---------------------------------------------------------------------------
# Tunables
@@ -35,9 +35,18 @@ Keeps the finding table bounded for large mono-repos where a single
architectural decision might reference hundreds of files.
"""
-# Impact values anchored to the severity → deduction table in scoring.py.
-_IMPACT_MEDIUM = round(severity_deduction(Severity.MEDIUM), 3) # 0.7
-_IMPACT_HIGH = round(severity_deduction(Severity.HIGH), 3) # 1.2
+# This pass runs after scoring and never moves ``HealthFileMetric.score``, so
+# zero is the honest impact. Anything else is summed by every surface that adds
+# impacts up, and outranks findings that did cost the file points. Severity
+# still carries the urgency.
+_IMPACT_NONE = 0.0
+
+#: The biomarker types this pass owns. Anything rewriting health findings has
+#: to leave them alone: they are produced here, after scoring, and no scoring
+#: path ever sees them.
+GOVERNANCE_BIOMARKERS: frozenset[str] = frozenset(
+ {"ungoverned_hotspot", "stale_governance", "contradictory_decision"}
+)
# ---------------------------------------------------------------------------
@@ -49,6 +58,7 @@ def build_governance_findings(
*,
health_summary: dict[str, Any],
decisions: list[Any],
+ scored_paths: set[str] | None = None,
) -> list[HealthFindingData]:
"""Derive governance ``HealthFindingData`` rows from a decision health summary.
@@ -64,6 +74,10 @@ def build_governance_findings(
The full list of ``DecisionRecord`` ORM rows for the repository
(used to resolve ``affected_files_json`` for conflict findings
without hitting the DB).
+ scored_paths:
+ The files health scores. Governance findings outside it are dropped,
+ so a decision covering a design document does not put a finding on a
+ file that carries no score to attach it to. ``None`` keeps every file.
Returns
-------
@@ -80,6 +94,8 @@ def build_governance_findings(
findings.extend(_stale_governance_findings(health_summary))
findings.extend(_contradictory_decision_findings(health_summary, decision_by_id))
+ if scored_paths is not None:
+ findings = [f for f in findings if f.file_path in scored_paths]
return findings
@@ -92,6 +108,10 @@ def _ungoverned_hotspot_findings(health_summary: dict[str, Any]) -> list[HealthF
"""One MEDIUM finding per ungoverned churn hotspot."""
out: list[HealthFindingData] = []
for path in health_summary.get("ungoverned_hotspots", []):
+ # A churning test file is the suite keeping up with the code, not a
+ # corner of the system nobody has decided anything about.
+ if is_test_related_path(path):
+ continue
out.append(
HealthFindingData(
biomarker_type="ungoverned_hotspot",
@@ -101,7 +121,7 @@ def _ungoverned_hotspot_findings(health_summary: dict[str, Any]) -> list[HealthF
line_start=None,
line_end=None,
details={"is_hotspot": True},
- health_impact=_IMPACT_MEDIUM,
+ health_impact=_IMPACT_NONE,
reason="Churn hotspot with no governing architectural decision.",
)
)
@@ -147,7 +167,7 @@ def _stale_governance_findings(health_summary: dict[str, Any]) -> list[HealthFin
"decision_title": decision.title,
"staleness_score": round(staleness, 3),
},
- health_impact=_IMPACT_HIGH,
+ health_impact=_IMPACT_NONE,
reason=(
f"Governing decision '{decision.title}' is stale "
f"(staleness_score={staleness:.2f})."
@@ -218,7 +238,7 @@ def _contradictory_decision_findings(
"src_title": src_title,
"dst_title": dst_title,
},
- health_impact=_IMPACT_HIGH,
+ health_impact=_IMPACT_NONE,
reason=f"Contradicts decision '{dst_title}'.",
)
)
diff --git a/packages/core/src/repowise/core/analysis/health/history_refresh.py b/packages/core/src/repowise/core/analysis/health/history_refresh.py
new file mode 100644
index 000000000..6e495cd4a
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/history_refresh.py
@@ -0,0 +1,203 @@
+"""Re-score a file's git-derived markers without re-reading its source.
+
+An update only walks the files whose bytes changed, so every other file kept
+whatever its history markers said at the last full index — a file could sit at
+"bug-fixed 9 times recently" long after the fixes stopped, and its score with
+it. These markers read git metadata, which the update refreshes for the whole
+repository anyway, so they can be re-evaluated for untouched files at the cost
+of a dictionary lookup.
+
+Two history markers are missing here on purpose: ``function_hotspot`` and
+``code_age_volatility`` need per-function complexity and a blame index, which
+means a parse. They keep their stored findings until the file itself changes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .biomarkers.base import BiomarkerResult, FileContext
+from .biomarkers.registry import registered_biomarkers
+from .governance import GOVERNANCE_BIOMARKERS
+from .models import HealthFindingData, Severity
+from .rows import detail_map, field
+from .scoring import attach_impacts, deduction_split, remap_severities, score_file
+
+#: History markers whose whole input is the file's git metadata.
+REFRESHABLE_MARKERS: frozenset[str] = frozenset(
+ {
+ "change_entropy",
+ "churn_risk",
+ "co_change_scatter",
+ "developer_congestion",
+ "hidden_coupling",
+ "knowledge_loss",
+ "ownership_risk",
+ "prior_defect",
+ }
+)
+
+
+@dataclass
+class RefreshedFile:
+ """One file's re-scored findings and the numbers that follow from them."""
+
+ file_path: str
+ findings: list[HealthFindingData]
+ score: float
+ defect_score: float
+ maintainability_score: float | None
+ performance_score: float | None
+ structure_deduction: float
+ history_deduction: float
+
+
+def as_biomarker_result(finding: Any) -> BiomarkerResult:
+ """Lift a stored finding back into the shape the scorer takes.
+
+ Everything the scorer reads was stored: the biomarker type, the severity
+ that indexes the deduction table, and — for ``coverage_gradient``, the one
+ marker whose magnitude is continuous rather than banded — the magnitude
+ itself, which the detector writes into its own details rounded to 4dp. So
+ a replayed score matches the original well inside the 2dp it is shown at.
+ """
+ details = detail_map(finding)
+ raw = details.get("deduction")
+ return BiomarkerResult(
+ biomarker_type=field(finding, "biomarker_type", ""),
+ severity=Severity(field(finding, "severity", Severity.LOW)),
+ function_name=field(finding, "function_name"),
+ line_start=field(finding, "line_start"),
+ line_end=field(finding, "line_end"),
+ details=details,
+ reason=field(finding, "reason", "") or "",
+ deduction=float(raw) if isinstance(raw, int | float) else None,
+ )
+
+
+def refresh_history(
+ *,
+ metrics: list[Any],
+ findings_by_path: dict[str, list[Any]],
+ git_meta_by_path: dict[str, dict],
+ languages: dict[str, str],
+ repo_active_contributors_90d: int | None = None,
+ severity_overrides: dict[str, Severity] | None = None,
+) -> list[RefreshedFile]:
+ """Re-run the git-only markers over *metrics* and rescore each file.
+
+ Findings outside :data:`REFRESHABLE_MARKERS` are carried through untouched,
+ so a file keeps every structural finding the last parse produced. The whole
+ set then goes back through the shared scorer rather than having the
+ organizational total patched in place: that category is capped across all
+ of its markers at once, refreshed and kept alike.
+ """
+ detectors = [b for b in registered_biomarkers() if b.name in REFRESHABLE_MARKERS]
+ out: list[RefreshedFile] = []
+
+ for metric in metrics:
+ path = field(metric, "file_path", "")
+ git_meta = git_meta_by_path.get(path)
+ if not git_meta:
+ continue
+
+ ctx = FileContext(
+ file_path=path,
+ language=languages.get(path, ""),
+ nloc=int(field(metric, "nloc", 0) or 0),
+ has_test_file=bool(field(metric, "has_test_file", False)),
+ module=field(metric, "module"),
+ git_meta=git_meta,
+ repo_active_contributors_90d=repo_active_contributors_90d,
+ )
+
+ fresh: list[BiomarkerResult] = []
+ for detector in detectors:
+ try:
+ fresh.extend(detector.detect(ctx))
+ except Exception:
+ continue
+ fresh = remap_severities(fresh, severity_overrides)
+
+ kept: list[BiomarkerResult] = []
+ governance: list[HealthFindingData] = []
+ for stored in findings_by_path.get(path, []):
+ marker = field(stored, "biomarker_type", "")
+ if marker in REFRESHABLE_MARKERS:
+ continue
+ if marker in GOVERNANCE_BIOMARKERS:
+ # Produced by a later pass that deducts nothing. Scoring them
+ # here would invent a deduction and charge it to the capped
+ # organizational category; dropping them would delete findings
+ # this pass has no business deciding about.
+ governance.append(_carry(stored, path))
+ continue
+ kept.append(as_biomarker_result(stored))
+
+ results = kept + fresh
+ scores, deductions = score_file(results)
+ rescored = attach_impacts(results, deductions)
+ for finding in rescored:
+ finding.file_path = path
+ structure, history = deduction_split(rescored)
+ rescored.extend(governance)
+
+ out.append(
+ RefreshedFile(
+ file_path=path,
+ findings=rescored,
+ score=round(scores["defect"], 2),
+ defect_score=round(scores["defect"], 2),
+ maintainability_score=_round_opt(scores["maintainability"]),
+ performance_score=_round_opt(scores["performance"]),
+ structure_deduction=structure,
+ history_deduction=history,
+ )
+ )
+ return out
+
+
+def _carry(stored: Any, path: str) -> HealthFindingData:
+ """A stored finding re-emitted unchanged, so a rewrite does not lose it."""
+ return HealthFindingData(
+ biomarker_type=field(stored, "biomarker_type", ""),
+ severity=Severity(field(stored, "severity", Severity.LOW)),
+ file_path=path,
+ function_name=field(stored, "function_name"),
+ line_start=field(stored, "line_start"),
+ line_end=field(stored, "line_end"),
+ details=detail_map(stored),
+ health_impact=float(field(stored, "health_impact", 0.0) or 0.0),
+ reason=field(stored, "reason", "") or "",
+ dimension=field(stored, "dimension", "defect") or "defect",
+ )
+
+
+def _round_opt(value: float | None) -> float | None:
+ return round(value, 2) if value is not None else None
+
+
+def active_contributors(git_meta_by_path: dict[str, dict]) -> int | None:
+ """Repo-wide active-contributor count over stored git metadata."""
+ from ...ingestion.git_indexer.enrich import count_active_contributors
+
+ try:
+ return count_active_contributors(list(git_meta_by_path.values()))
+ except Exception:
+ return None
+
+
+def git_meta_rows_to_map(rows: Any) -> dict[str, dict]:
+ """``{path: metadata dict}`` from stored ``GitMetadata`` rows.
+
+ The detectors read git metadata as a mapping, which is how the indexer
+ hands it to the engine, so ORM rows are flattened to the same shape.
+ """
+ out: dict[str, dict] = {}
+ for row in rows:
+ meta = {c.name: getattr(row, c.name, None) for c in row.__table__.columns}
+ path = meta.get("file_path")
+ if path:
+ out[str(path)] = meta
+ return out
diff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.py
index ab4a61b4e..6a1b7c897 100644
--- a/packages/core/src/repowise/core/analysis/health/models.py
+++ b/packages/core/src/repowise/core/analysis/health/models.py
@@ -67,6 +67,29 @@ def primary_finding(findings: Sequence[Any]) -> Any | None:
return max(discrete or findings, key=lambda item: float(item.health_impact or 0.0))
+def split_by_origin(findings: Iterable[Any]) -> tuple[list[Any], list[Any]]:
+ """Partition findings into ``(code_shape, history)``.
+
+ History markers are derived from git rather than from the file, so a reader
+ cannot act on one: the fix for "changed with 25 other files" is not an edit.
+ Surfaces that instruct rather than describe lead with the first list and
+ report the second as context.
+ """
+ # Deferred: ``scoring`` imports this module for its data classes.
+ from .scoring import HISTORY_CATEGORY, biomarker_category
+
+ code_shape: list[Any] = []
+ history: list[Any] = []
+ for f in findings:
+ target = (
+ history
+ if biomarker_category(getattr(f, "biomarker_type", "")) == HISTORY_CATEGORY
+ else code_shape
+ )
+ target.append(f)
+ return code_shape, history
+
+
def primary_biomarker_by_file(findings: Iterable[Any]) -> dict[str, str]:
"""Each file's dominant cause, keyed by path. See :func:`primary_finding`."""
by_file: dict[str, list[Any]] = {}
@@ -98,6 +121,16 @@ class HealthFileMetricData:
defect_score: float | None = None
maintainability_score: float | None = None
performance_score: float | None = None
+ # The defect deduction split into the half a rewrite can move and the half
+ # only time can. They sum to the total deduction, so ``SCORE_MAX`` minus
+ # both is the file's unclamped score — the only way a file held at the
+ # floor can show progress. NULL on rows written before the split.
+ structure_deduction: float | None = None
+ history_deduction: float | None = None
+ # Whether this file is test material, decided at ingestion by the shared
+ # path classifier and carried here so every surface that narrows to
+ # production reads a column instead of re-deriving the answer.
+ is_test: bool = False
@dataclass
diff --git a/packages/core/src/repowise/core/analysis/health/scope.py b/packages/core/src/repowise/core/analysis/health/scope.py
new file mode 100644
index 000000000..52919f332
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/health/scope.py
@@ -0,0 +1,46 @@
+"""What health scores, and the names of the halves it can report on.
+
+Production/test narrowing itself is a column read (``HealthFileMetric.is_test``,
+stamped from the shared path classifier), so only the vocabulary lives here.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from typing import Literal
+
+HealthScope = Literal["all", "production"]
+DEFAULT_SCOPE: HealthScope = "all"
+SCOPES: tuple[HealthScope, ...] = ("all", "production")
+
+# SQL is declared non-code by the language registry — nothing parses it into
+# symbols or import edges — but health walks it through sqlglot and carries
+# markers of its own for it, so it scores here.
+_ALSO_SCORED = frozenset({"sql"})
+
+
+@cache
+def _scored_languages() -> frozenset[str]:
+ # Deferred: the language registry reaches ingestion, which imports this
+ # package back. The same cycle ``test_paths`` breaks the same way.
+ from ...ingestion.languages.registry import REGISTRY
+
+ return frozenset(s.tag for s in REGISTRY.all_specs() if s.is_code) | _ALSO_SCORED
+
+
+def scores_language(language: str | None) -> bool:
+ """Whether health scores a file written in *language*.
+
+ True for every language the registry declares as code, plus SQL. False for
+ prose, configuration, data and markup — Markdown, JSON, YAML, TOML, HTML,
+ Protobuf, GraphQL, lockfiles and anything unrecognised. None of them carry
+ code shape to measure, while the history markers fire on them hard: a
+ changelog every fix commit touches reads as a bug magnet. They get no
+ score, no findings and no metric row.
+ """
+ return bool(language) and language in _scored_languages()
+
+
+def parse_scope(value: str | None) -> HealthScope:
+ """Normalise a caller's scope, falling back to the default on anything else."""
+ return value if value in SCOPES else DEFAULT_SCOPE # type: ignore[return-value]
diff --git a/packages/core/src/repowise/core/analysis/health/scoring.py b/packages/core/src/repowise/core/analysis/health/scoring.py
index cb7f3c66f..ecb7a88e8 100644
--- a/packages/core/src/repowise/core/analysis/health/scoring.py
+++ b/packages/core/src/repowise/core/analysis/health/scoring.py
@@ -222,6 +222,13 @@ _BIOMARKER_DIMENSIONS: dict[str, set[str]] = {
"god_class": {"defect", "maintainability"},
"large_method": {"defect", "maintainability"},
"nested_complexity": {"defect", "maintainability"},
+ # The rest of the pure code-shape markers. Maintainability is the pillar a
+ # refactor is supposed to move, so every marker a reader can fix by
+ # rewriting the code belongs in it - a method too complex to follow is a
+ # maintainability problem whether or not it is also a defect predictor.
+ "complex_method": {"defect", "maintainability"},
+ "complex_conditional": {"defect", "maintainability"},
+ "bumpy_road": {"defect", "maintainability"},
# Performance-risk detectors contribute to ``performance`` ONLY. They are
# NOT defect predictors and must never move the surfaced (defect) score -
# that exclusion is what keeps the defect golden guarantee intact.
@@ -272,6 +279,9 @@ _MAINTAINABILITY_WEIGHT_MULTIPLIER: dict[str, float] = {
"god_class": 1.0,
"large_method": 1.0,
"nested_complexity": 1.0,
+ "complex_method": 1.0,
+ "complex_conditional": 1.0,
+ "bumpy_road": 1.0,
# SQL smells ship advisory (0.7) pending a precision spot-check on a
# migrations-heavy corpus, mirroring how new perf markers land.
"sql_high_complexity": 0.7,
@@ -287,6 +297,9 @@ _MAINTAINABILITY_CATEGORY: dict[str, str] = {
"god_class": "structural_complexity",
"nested_complexity": "structural_complexity",
"large_method": "structural_complexity",
+ "complex_conditional": "structural_complexity",
+ "bumpy_road": "structural_complexity",
+ "complex_method": "size_and_complexity",
"primitive_obsession": "size_and_complexity",
"dry_violation": "duplication",
"error_handling": "error_handling",
@@ -642,6 +655,41 @@ def score_file(results: Iterable[BiomarkerResult]) -> tuple[dict[str, float | No
return scores, defect_deductions
+# The one defect category derived from git rather than from the code itself.
+# Splitting on it is what lets a surface say which half of the score moved: a
+# refactor changes the structure half, and nothing a reader types today changes
+# the history half.
+HISTORY_CATEGORY = "organizational"
+
+
+def deduction_split(findings: Iterable[Any]) -> tuple[float, float]:
+ """``(structure, history)`` defect deduction over already-scored findings.
+
+ Reads each finding's stored ``health_impact``, so the two halves sum to the
+ file's total deduction and ``SCORE_MAX`` minus that sum is its unclamped
+ score. Governance findings carry no impact and so fall out on their own.
+ """
+ structure = history = 0.0
+ for f in findings:
+ impact = float(field(f, "health_impact", 0.0) or 0.0)
+ if biomarker_category(field(f, "biomarker_type", "")) == HISTORY_CATEGORY:
+ history += impact
+ else:
+ structure += impact
+ return round(structure, 3), round(history, 3)
+
+
+def unclamped_score(structure: float | None, history: float | None) -> float | None:
+ """The score a file would carry without the floor, or ``None`` if unrecorded.
+
+ The floor is lossy: a file 12.9 points deep and one 9.1 points deep both
+ print 1.0, so neither can show progress until it climbs back over the floor.
+ """
+ if structure is None and history is None:
+ return None
+ return round(SCORE_MAX - (structure or 0.0) - (history or 0.0), 2)
+
+
def attach_impacts(
results: list[BiomarkerResult], deductions: list[float]
) -> list[HealthFindingData]:
@@ -674,7 +722,7 @@ def _row_score(row: Any) -> float:
return float(field(row, "score", SCORE_MAX))
-def _wavg_attr(rows: list[HealthFileMetricData], attr: str) -> float | None:
+def nloc_weighted_attr(rows: list[HealthFileMetricData], attr: str) -> float | None:
"""NLOC-weighted average of one metric attribute, skipping ``None`` values.
Returns ``None`` when no row carries the attribute (e.g. a repo whose
@@ -753,6 +801,11 @@ def compute_kpis(
NLOC-weighted averages over the per-file ``performance_score`` (static
performance RISK), so the performance pillar surfaces a repo headline too.
``None`` when no file carries a performance score.
+ - ``structure_average`` / ``history_average`` and their hotspot pair: the
+ headline's two halves, in deduction points, so a surface can say which
+ one is holding the score down. ``None`` until files carry the split.
+ - ``production_average``: ``average_health`` over non-test files, weighted
+ identically, so a narrowed view and a narrowed trend agree.
"""
if not metrics:
return {
@@ -765,14 +818,26 @@ def compute_kpis(
"maintainability_hotspot": None,
"performance_average": None,
"performance_hotspot": None,
+ "structure_average": None,
+ "structure_hotspot": None,
+ "history_average": None,
+ "history_hotspot": None,
+ "production_average": None,
+ "production_file_count": 0,
}
hotspots = [m for m in metrics if field(m, "file_path") in hotspot_paths]
worst = min(metrics, key=_row_score)
- maint_avg = _wavg_attr(metrics, "maintainability_score")
- maint_hotspot = _wavg_attr(hotspots, "maintainability_score")
- perf_avg = _wavg_attr(metrics, "performance_score")
- perf_hotspot = _wavg_attr(hotspots, "performance_score")
+ maint_avg = nloc_weighted_attr(metrics, "maintainability_score")
+ maint_hotspot = nloc_weighted_attr(hotspots, "maintainability_score")
+ perf_avg = nloc_weighted_attr(metrics, "performance_score")
+ perf_hotspot = nloc_weighted_attr(hotspots, "performance_score")
+ production = [m for m in metrics if not field(m, "is_test", False)]
+ splits = {
+ f"{half}_{scope}": nloc_weighted_attr(rows, f"{half}_deduction")
+ for half in ("structure", "history")
+ for scope, rows in (("average", metrics), ("hotspot", hotspots))
+ }
# Floored to 10.0 when the repo has no hotspot files, because this dict is
# what ``save_health_snapshot`` persists into a non-nullable column and what
# the trend alerts diff against. The floor lives here, at the one point that
@@ -789,4 +854,9 @@ def compute_kpis(
"maintainability_hotspot": round(maint_hotspot, 2) if maint_hotspot is not None else None,
"performance_average": round(perf_avg, 2) if perf_avg is not None else None,
"performance_hotspot": round(perf_hotspot, 2) if perf_hotspot is not None else None,
+ **{k: round(v, 2) if v is not None else None for k, v in splits.items()},
+ "production_average": (
+ round(nloc_weighted_score(production), 2) if production else None
+ ),
+ "production_file_count": len(production),
}
diff --git a/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py b/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py
index ca1328a45..80bf75506 100644
--- a/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py
+++ b/packages/core/src/repowise/core/persistence/_interfaces/_analysis.py
@@ -222,6 +222,9 @@ class AnalysisIndexStore(ABC):
worst_performer_score: float | None,
per_file_scores: dict[str, float] | None = None,
per_file_deductions: dict[str, float] | None = None,
+ structure_average: float | None = None,
+ history_average: float | None = None,
+ production_average: float | None = None,
taken_at: datetime | None = None,
) -> HealthSnapshot: ...
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
index 7cc4b4549..e7247a8c8 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py
@@ -34,6 +34,7 @@ from .health import (
HEALTH_SNAPSHOT_RETENTION,
HealthSnapshotHeadline,
HealthSnapshotScalars,
+ backfill_is_test,
backfill_module_attribution,
get_average_health,
get_deduction_by_path,
@@ -44,7 +45,9 @@ from .health import (
get_health_snapshot_headline,
get_health_summary,
get_perf_coverage,
+ get_scored_file_paths,
list_health_snapshots,
+ prune_unscored_health_rows,
replace_governance_findings,
save_health_findings,
save_health_metrics,
@@ -90,6 +93,7 @@ __all__ = [
"HEALTH_SNAPSHOT_RETENTION",
"HealthSnapshotHeadline",
"HealthSnapshotScalars",
+ "backfill_is_test",
"backfill_module_attribution",
"count_refactoring_suggestions",
"covered_source_files",
@@ -117,6 +121,7 @@ __all__ = [
"get_refactoring_suggestion",
"get_refactoring_suggestions",
"get_refactoring_summary",
+ "get_scored_file_paths",
"get_test_coverage_summary",
"list_evidence_for_opportunities",
"list_health_snapshots",
@@ -127,6 +132,7 @@ __all__ = [
"opportunity_details",
"performance_facet_counts",
"performance_file_rollups",
+ "prune_unscored_health_rows",
"refactoring_facet_counts",
"replace_dead_code_findings",
"replace_governance_findings",
diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
index 265729399..1cb60bcaa 100644
--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py
+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
from ....analysis.health.perf.coverage import PerfCoverage
from ....analysis.health.finding_identity import finding_public_id
+from ....analysis.health.governance import GOVERNANCE_BIOMARKERS
# The comparator is pure and lives with the health read models; only the SQL
# that feeds it belongs here. Re-imported rather than moved out of reach: the
@@ -25,6 +26,8 @@ from ....analysis.health.ranking import (
worst_metric,
)
from ....analysis.health.rows import detail_map
+from ....analysis.health.scope import scores_language
+from ....test_paths import is_test_related_path
from ...models import (
GraphNode,
HealthFileMetric,
@@ -104,11 +107,6 @@ async def save_health_findings(
await session.flush()
-_GOVERNANCE_BIOMARKER_TYPES = frozenset(
- {"ungoverned_hotspot", "stale_governance", "contradictory_decision"}
-)
-
-
async def replace_governance_findings(
session: AsyncSession,
repository_id: str,
@@ -140,7 +138,7 @@ async def replace_governance_findings(
existing = await session.execute(
select(HealthFinding).where(
HealthFinding.repository_id == repository_id,
- HealthFinding.biomarker_type.in_(list(_GOVERNANCE_BIOMARKER_TYPES)),
+ HealthFinding.biomarker_type.in_(list(GOVERNANCE_BIOMARKERS)),
)
)
for row in existing.scalars().all():
@@ -157,6 +155,28 @@ async def replace_governance_findings(
await session.flush()
+def _health_metric_row_data(metric: Any) -> dict:
+ """One metric dataclass as column values. Both writers go through here."""
+ return {
+ "file_path": metric.file_path,
+ "score": float(metric.score),
+ "max_ccn": int(metric.max_ccn),
+ "max_nesting": int(metric.max_nesting),
+ "nloc": int(metric.nloc),
+ "duplication_pct": metric.duplication_pct,
+ "has_test_file": bool(metric.has_test_file),
+ "line_coverage_pct": metric.line_coverage_pct,
+ "branch_coverage_pct": metric.branch_coverage_pct,
+ "module": metric.module,
+ "defect_score": getattr(metric, "defect_score", None),
+ "maintainability_score": getattr(metric, "maintainability_score", None),
+ "performance_score": getattr(metric, "performance_score", None),
+ "structure_deduction": getattr(metric, "structure_deduction", None),
+ "history_deduction": getattr(metric, "history_deduction", None),
+ "is_test": bool(getattr(metric, "is_test", False)),
+ }
+
+
async def save_health_metrics(
session: AsyncSession,
repository_id: str,
@@ -187,24 +207,7 @@ async def save_health_metrics(
for i in range(0, len(metrics), _BATCH_SIZE):
batch = metrics[i : i + _BATCH_SIZE]
for m in batch:
- if hasattr(m, "file_path"):
- data = {
- "file_path": m.file_path,
- "score": float(m.score),
- "max_ccn": int(m.max_ccn),
- "max_nesting": int(m.max_nesting),
- "nloc": int(m.nloc),
- "duplication_pct": m.duplication_pct,
- "has_test_file": bool(m.has_test_file),
- "line_coverage_pct": m.line_coverage_pct,
- "branch_coverage_pct": m.branch_coverage_pct,
- "module": m.module,
- "defect_score": getattr(m, "defect_score", None),
- "maintainability_score": getattr(m, "maintainability_score", None),
- "performance_score": getattr(m, "performance_score", None),
- }
- else:
- data = dict(m)
+ data = _health_metric_row_data(m) if hasattr(m, "file_path") else dict(m)
# After the dict-passthrough branch so an explicit per-row value in a
# raw dict still wins; the sha is a property of the pass, not the row.
if analyzed_commit is not None:
@@ -224,6 +227,70 @@ async def save_health_metrics(
await session.flush()
+async def get_scored_file_paths(session: AsyncSession, repository_id: str) -> set[str]:
+ """The files health currently scores, read off the stored metric rows."""
+ q = select(HealthFileMetric.file_path).where(
+ HealthFileMetric.repository_id == repository_id
+ )
+ return {path for (path,) in (await session.execute(q)).all()}
+
+
+async def backfill_is_test(session: AsyncSession, repository_id: str) -> int:
+ """Stamp ``is_test`` on rows written before the column existed.
+
+ The answer comes from the path, not from a score, so an existing store gets
+ it on the next update instead of waiting for a re-index. Without this a
+ ``scope=production`` request on an un-rescored store would quietly answer
+ with the whole repository. Returns the number of rows filled.
+ """
+ rows = (
+ await session.execute(
+ select(HealthFileMetric).where(
+ HealthFileMetric.repository_id == repository_id,
+ HealthFileMetric.is_test.is_(None),
+ )
+ )
+ ).scalars().all()
+ if not rows:
+ return 0
+ languages = await get_file_language_map(session, repository_id)
+ for row in rows:
+ row.is_test = is_test_related_path(row.file_path, languages.get(row.file_path))
+ await session.flush()
+ return len(rows)
+
+
+async def prune_unscored_health_rows(session: AsyncSession, repository_id: str) -> int:
+ """Drop metrics and findings for files health no longer scores.
+
+ A full index rewrites the whole population and needs nothing here, but an
+ update only touches the files that changed, so prose and configuration rows
+ written by an older version would otherwise sit in the average forever.
+ Files with no graph node are left alone: no language is not the same answer
+ as a language health does not score. Returns the number of rows removed,
+ which is zero on every update after the first.
+ """
+ languages = await get_file_language_map(session, repository_id)
+ stale = [path for path, language in languages.items() if not scores_language(language)]
+ if not stale:
+ return 0
+ removed = 0
+ for i in range(0, len(stale), _BATCH_SIZE):
+ batch = stale[i : i + _BATCH_SIZE]
+ for model in (HealthFileMetric, HealthFinding):
+ rows = await session.execute(
+ select(model).where(
+ model.repository_id == repository_id,
+ model.file_path.in_(batch),
+ )
+ )
+ for row in rows.scalars().all():
+ await session.delete(row)
+ removed += 1
+ await session.flush()
+ return removed
+
+
async def backfill_module_attribution(
session: AsyncSession,
repository_id: str,
@@ -689,6 +756,9 @@ async def save_health_snapshot(
worst_performer_score: float | None,
per_file_scores: dict[str, float] | None = None,
per_file_deductions: dict[str, float] | None = None,
+ structure_average: float | None = None,
+ history_average: float | None = None,
+ production_average: float | None = None,
taken_at: datetime | None = None,
) -> HealthSnapshot:
"""Append a snapshot; prune oldest rows past ``HEALTH_SNAPSHOT_RETENTION``.
@@ -702,6 +772,9 @@ async def save_health_snapshot(
Build both with ``trends.snapshot_file_maps`` rather than by hand: a repo
whose writers disagree gets a history that changes depth depending on which
command last wrote it.
+
+ ``structure_average`` / ``history_average`` are ``average_health``'s two
+ halves in deduction points, so a later trend can name which one moved.
"""
snap = HealthSnapshot(
id=_new_uuid(),
@@ -715,6 +788,9 @@ async def save_health_snapshot(
),
per_file_scores_json=json.dumps(per_file_scores or {}, separators=(",", ":")),
per_file_deductions_json=json.dumps(per_file_deductions or {}, separators=(",", ":")),
+ structure_average=structure_average,
+ history_average=history_average,
+ production_average=production_average,
)
session.add(snap)
await session.flush()
@@ -965,24 +1041,7 @@ async def upsert_health_metrics(
by_path = {row.file_path: row for row in existing.scalars().all()}
for m in metrics:
- if hasattr(m, "file_path"):
- data = {
- "file_path": m.file_path,
- "score": float(m.score),
- "max_ccn": int(m.max_ccn),
- "max_nesting": int(m.max_nesting),
- "nloc": int(m.nloc),
- "duplication_pct": m.duplication_pct,
- "has_test_file": bool(m.has_test_file),
- "line_coverage_pct": m.line_coverage_pct,
- "branch_coverage_pct": m.branch_coverage_pct,
- "module": m.module,
- "defect_score": getattr(m, "defect_score", None),
- "maintainability_score": getattr(m, "maintainability_score", None),
- "performance_score": getattr(m, "performance_score", None),
- }
- else:
- data = dict(m)
+ data = _health_metric_row_data(m) if hasattr(m, "file_path") else dict(m)
# Only when the caller knows the sha. An unconditional set would push a
# None over a sha already on the row, so a caller that simply does not
# track the commit would erase the stamp a caller that does had written.
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 129faa5e3..b43f4f558 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -1797,6 +1797,19 @@ class HealthFileMetric(Base):
defect_score: Mapped[float | None] = mapped_column(Float, nullable=True)
maintainability_score: Mapped[float | None] = mapped_column(Float, nullable=True)
performance_score: Mapped[float | None] = mapped_column(Float, nullable=True)
+ # The defect deduction split into the half a rewrite can move and the half
+ # only time can. They sum to the total deduction, so ``SCORE_MAX`` minus
+ # both is the file's unclamped score — the only way a file held at the
+ # floor can show progress. NULL on rows written before the split.
+ structure_deduction: Mapped[float | None] = mapped_column(Float, nullable=True)
+ history_deduction: Mapped[float | None] = mapped_column(Float, nullable=True)
+ # Whether this file is test material, decided by the shared path
+ # classifier and stamped here so every surface that narrows to production
+ # reads a column instead of re-deriving the answer. The performance pillar
+ # stores ``execution_context`` for the same reason. NULL on rows written
+ # before the column existed; derived from the path, so ``backfill_is_test``
+ # fills those in without re-scoring anything.
+ is_test: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
# Commit this row was scored against. Health is a separate pass from indexing
# and can lag it, so ``Repository.head_commit`` does not answer "how old is
# this score". Per-row rather than per-repo because the incremental path
@@ -1837,6 +1850,16 @@ class HealthSnapshot(Base):
# because that blob's ``{path: score}`` shape is parsed by three readers,
# two of which would fail quietly if a value became a dict.
per_file_deductions_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
+ # The repo-wide halves of ``average_health``, in deduction points, so a
+ # trend can attribute a move to code shape or to history without replaying
+ # every finding at every snapshot. NULL on snapshots taken before the split.
+ structure_average: Mapped[float | None] = mapped_column(Float, nullable=True)
+ history_average: Mapped[float | None] = mapped_column(Float, nullable=True)
+ # ``average_health`` over production files only, NLOC-weighted the same
+ # way. Stored rather than derived: the per-file map carries scores without
+ # the line counts that weight them, so a narrowed trend rebuilt at read
+ # time would be a differently-weighted number wearing the same name.
+ production_average: Mapped[float | None] = mapped_column(Float, nullable=True)
class CoverageFile(Base):
diff --git a/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py b/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py
index b2dc02c18..2e4d9abe8 100644
--- a/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py
+++ b/packages/core/src/repowise/core/persistence/stores/_sql_analysis.py
@@ -259,6 +259,9 @@ class _SqlAnalysisMixin(AnalysisIndexStore):
worst_performer_score: float | None,
per_file_scores: dict[str, float] | None = None,
per_file_deductions: dict[str, float] | None = None,
+ structure_average: float | None = None,
+ history_average: float | None = None,
+ production_average: float | None = None,
taken_at: datetime | None = None,
) -> HealthSnapshot:
return await crud.save_health_snapshot(
@@ -270,6 +273,9 @@ class _SqlAnalysisMixin(AnalysisIndexStore):
worst_performer_score=worst_performer_score,
per_file_scores=per_file_scores,
per_file_deductions=per_file_deductions,
+ structure_average=structure_average,
+ history_average=history_average,
+ production_average=production_average,
taken_at=taken_at,
)
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index c0bbac27c..02843a861 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -988,7 +988,170 @@ def _carry_forward_kg_enrichment(kg: Any, prior_kg: Any) -> None:
kg.tour = prior_kg.tour
-async def persist_partial_health(session: Any, repo_id: str, report: Any) -> None:
+async def refresh_unchanged_history(
+ session: Any, repo_id: str, repo_path: Any, *, skip_paths: set[str]
+) -> int:
+ """Re-score the git-derived markers on files this run did not walk.
+
+ The update refreshes git metadata for the whole repository, so a file the
+ change set never touched can still have moved in every way history
+ measures — new co-change partners, a fix that landed elsewhere in the same
+ commit, an owner who left. Only those markers are re-evaluated; each file
+ keeps the structural findings its last parse produced, so nothing here
+ needs the source.
+
+ Returns the number of files rewritten. Best-effort: the update is not worth
+ failing over a refresh.
+ """
+ from repowise.core.analysis.health.config import HealthConfig
+ from repowise.core.analysis.health.history_refresh import (
+ REFRESHABLE_MARKERS,
+ active_contributors,
+ git_meta_rows_to_map,
+ refresh_history,
+ )
+ from repowise.core.persistence.crud import (
+ get_all_git_metadata,
+ get_file_language_map,
+ get_health_findings,
+ get_health_metrics,
+ upsert_health_findings,
+ upsert_health_metrics,
+ )
+
+ stored = {
+ m.file_path: m
+ for m in await get_health_metrics(session, repo_id)
+ if m.file_path not in skip_paths
+ }
+ if not stored:
+ return 0
+ git_meta = git_meta_rows_to_map((await get_all_git_metadata(session, repo_id)).values())
+ if not git_meta:
+ return 0
+
+ findings_by_path: dict[str, list[Any]] = {}
+ for finding in await get_health_findings(session, repo_id):
+ findings_by_path.setdefault(finding.file_path, []).append(finding)
+
+ cfg = HealthConfig.load(repo_path)
+ refreshed = refresh_history(
+ metrics=list(stored.values()),
+ findings_by_path=findings_by_path,
+ git_meta_by_path=git_meta,
+ languages=await get_file_language_map(session, repo_id),
+ repo_active_contributors_90d=active_contributors(git_meta),
+ severity_overrides=cfg.severity_overrides or None,
+ )
+ if not refreshed:
+ return 0
+
+ # The two writes are scoped separately on purpose. A metric row is cheap to
+ # rewrite and carries no identity, but rewriting findings deletes and
+ # re-inserts them, which means new ids and a reset ``created_at`` — so that
+ # only happens for a file whose history findings actually changed, not for
+ # every file whose stored split was merely never recorded.
+ metric_writes = [
+ _refreshed_metric(r, stored[r.file_path])
+ for r in refreshed
+ if _numbers_moved(r, stored[r.file_path])
+ ]
+ finding_writes = [
+ r for r in refreshed if _history_findings_moved(r, findings_by_path.get(r.file_path, []))
+ ]
+ if not metric_writes and not finding_writes:
+ return 0
+
+ # One savepoint over both: a file whose findings were rewritten but whose
+ # score was not would report a deduction its own findings cannot account
+ # for, and the caller logs this step and carries on to commit the rest.
+ async with session.begin_nested():
+ if finding_writes:
+ await upsert_health_findings(
+ session,
+ repo_id,
+ [f for r in finding_writes for f in r.findings],
+ file_paths=[r.file_path for r in finding_writes],
+ )
+ if metric_writes:
+ await upsert_health_metrics(session, repo_id, metric_writes)
+ logger.debug(
+ "health_history_refreshed",
+ repo_id=repo_id,
+ metric_rows=len(metric_writes),
+ finding_rows=len(finding_writes),
+ markers=len(REFRESHABLE_MARKERS),
+ )
+ return len(finding_writes)
+
+
+def _numbers_moved(refreshed: Any, stored: Any) -> bool:
+ """Whether the stored row's numbers differ from the re-scored ones.
+
+ Includes a row whose split was never recorded, so the first update after
+ the split ships backfills it without touching any finding.
+ """
+ return (
+ round(refreshed.score, 2) != round(float(stored.score), 2)
+ or stored.structure_deduction is None
+ or stored.history_deduction is None
+ or round(refreshed.structure_deduction, 3) != round(float(stored.structure_deduction), 3)
+ or round(refreshed.history_deduction, 3) != round(float(stored.history_deduction), 3)
+ )
+
+
+def _history_findings_moved(refreshed: Any, stored_findings: list[Any]) -> bool:
+ """Whether the git-derived findings themselves changed.
+
+ Compared on what a reader sees — which markers fired, where, and how
+ severely — so a file keeps its finding ids and their ages across an update
+ that re-derived the same history.
+ """
+
+ def key(findings: Any) -> set:
+ return {
+ (
+ getattr(f, "biomarker_type", ""),
+ str(getattr(f, "severity", "")),
+ getattr(f, "function_name", None),
+ round(float(getattr(f, "health_impact", 0.0) or 0.0), 3),
+ )
+ for f in findings
+ }
+
+ return key(refreshed.findings) != key(stored_findings)
+
+
+def _refreshed_metric(refreshed: Any, stored: Any) -> dict:
+ """The stored metric row with the rescored numbers written over it.
+
+ A dict rather than a dataclass so the fields this pass cannot know — the
+ complexity and coverage columns, which need a parse — keep their stored
+ values instead of being reset to a default.
+ """
+ return {
+ "file_path": refreshed.file_path,
+ "score": refreshed.score,
+ "max_ccn": stored.max_ccn,
+ "max_nesting": stored.max_nesting,
+ "nloc": stored.nloc,
+ "duplication_pct": stored.duplication_pct,
+ "has_test_file": stored.has_test_file,
+ "line_coverage_pct": stored.line_coverage_pct,
+ "branch_coverage_pct": stored.branch_coverage_pct,
+ "module": stored.module,
+ "defect_score": refreshed.defect_score,
+ "maintainability_score": refreshed.maintainability_score,
+ "performance_score": refreshed.performance_score,
+ "structure_deduction": refreshed.structure_deduction,
+ "history_deduction": refreshed.history_deduction,
+ "is_test": stored.is_test,
+ }
+
+
+async def persist_partial_health(
+ session: Any, repo_id: str, report: Any, repo_path: Any = None
+) -> None:
"""Upsert health findings + metrics for the changed-files subset.
Unlike ``persist_pipeline_result`` (which delete-then-inserts the
@@ -1078,6 +1241,27 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non
from repowise.core.persistence.crud import upsert_git_function_blame_bulk
await upsert_git_function_blame_bulk(session, repo_id, fn_blame_rows)
+ # Only a full index rewrites the whole population, so rows an older version
+ # scored for prose or configuration go here rather than lingering in the
+ # average, and rows written before ``is_test`` existed get it from their
+ # path. Both before the refresh, which should not re-score a row that is
+ # about to be deleted.
+ from repowise.core.persistence.crud import backfill_is_test, prune_unscored_health_rows
+
+ await prune_unscored_health_rows(session, repo_id)
+ await backfill_is_test(session, repo_id)
+ # Then the files this run did not walk, whose git-derived markers the fresh
+ # metadata may have moved. Before the snapshot, or the trend would describe
+ # the store as it stood one update ago.
+ if repo_path is not None:
+ try:
+ await refresh_unchanged_history(
+ session, repo_id, repo_path, skip_paths=set(changed_paths)
+ )
+ except Exception as exc:
+ # Never fails the run: the next update re-derives the whole thing
+ # from the stored git metadata, so nothing is stranded behind.
+ logger.debug("health_history_refresh_skipped", repo_id=repo_id, error=str(exc))
# The store now holds the merged repository, so the snapshot describes the
# whole of it, not this run's changed files.
from repowise.core.pipeline.persist import snapshot_health_from_store
@@ -1657,7 +1841,9 @@ async def persist_incremental_index(
if partial_health_report is not None:
try:
with timed(timings, "persist.health"):
- await persist_partial_health(session, repo_id, partial_health_report)
+ await persist_partial_health(
+ session, repo_id, partial_health_report, repo_path
+ )
except Exception as exc:
_skip("Health persist", exc, range_scoped=True)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 7785ca973..c27791489 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1562,13 +1562,10 @@ async def _analyzed_commit(session: Any, repo_id: str) -> str | None:
async def snapshot_health_from_store(session: Any, repo_id: str) -> None:
"""Append a ``HealthSnapshot`` built from the repository's stored rows.
- One writer for the full index and the incremental update. The full path
- used to snapshot from the in-memory report and the update path never
- snapshotted at all, so ``health --trend`` and the CLAUDE.md trend only
- moved on a full re-index however many updates ran in between. A partial
- report cannot be snapshotted directly, because it holds the changed files
- and the snapshot has to describe the whole repository; the store after the
- write holds exactly that, on both paths.
+ One writer for the full index and the incremental update. A partial report
+ cannot be snapshotted directly, because it holds only the changed files and
+ a snapshot has to describe the whole repository; the store after the write
+ holds exactly that, on both paths.
Best-effort: a snapshot that fails to write is logged and never fails the
run that produced the rows it describes.
@@ -1615,6 +1612,9 @@ async def snapshot_health_from_store(session: Any, repo_id: str) -> None:
worst_performer_score=kpis.get("worst_performer_score"),
per_file_scores=scores_map,
per_file_deductions=deductions_map,
+ structure_average=kpis.get("structure_average"),
+ history_average=kpis.get("history_average"),
+ production_average=kpis.get("production_average"),
)
except Exception as exc:
logger.warning("health_snapshot_skipped", error=str(exc))
@@ -1878,6 +1878,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
from repowise.core.analysis.health.governance import build_governance_findings
from repowise.core.persistence.crud import (
get_decision_health_summary,
+ get_scored_file_paths,
replace_governance_findings,
)
from repowise.core.persistence.models import DecisionRecord
@@ -1890,6 +1891,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
_gov_findings = build_governance_findings(
health_summary=_health_summary,
decisions=_decisions,
+ scored_paths=await get_scored_file_paths(session, repo_id),
)
await replace_governance_findings(session, repo_id, _gov_findings)
if _gov_findings:
diff --git a/tests/unit/health/test_governance.py b/tests/unit/health/test_governance.py
index 81b4862f4..a3917d4d6 100644
--- a/tests/unit/health/test_governance.py
+++ b/tests/unit/health/test_governance.py
@@ -74,11 +74,41 @@ def test_ungoverned_hotspot_details_has_is_hotspot():
assert hit.details.get("is_hotspot") is True
-def test_ungoverned_hotspot_health_impact_nonzero():
- summary = _summary(ungoverned_hotspots=["src/main.py"])
+def test_governance_findings_carry_no_health_impact():
+ """This pass runs after scoring and deducts nothing, so it claims nothing.
+
+ A severity-shaped impact here was summed as though it had been deducted,
+ putting governance above findings that had actually cost the file points.
+ """
+ summary = _summary(
+ ungoverned_hotspots=["src/main.py"],
+ stale_decisions=[
+ _Decision(
+ id="d1",
+ title="Keep the pipeline synchronous",
+ affected_files_json=json.dumps(["src/main.py"]),
+ staleness_score=0.9,
+ )
+ ],
+ )
findings = build_governance_findings(health_summary=summary, decisions=[])
- hit = next(f for f in findings if f.biomarker_type == "ungoverned_hotspot")
- assert hit.health_impact > 0
+ assert findings
+ assert all(f.health_impact == 0.0 for f in findings)
+
+
+def test_ungoverned_hotspot_skips_test_files():
+ summary = _summary(ungoverned_hotspots=["tests/test_main.py", "src/main.py"])
+ findings = build_governance_findings(health_summary=summary, decisions=[])
+ paths = [f.file_path for f in findings if f.biomarker_type == "ungoverned_hotspot"]
+ assert paths == ["src/main.py"]
+
+
+def test_scored_paths_drops_findings_health_does_not_score():
+ summary = _summary(ungoverned_hotspots=["docs/CHANGELOG.md", "src/main.py"])
+ findings = build_governance_findings(
+ health_summary=summary, decisions=[], scored_paths={"src/main.py"}
+ )
+ assert [f.file_path for f in findings] == ["src/main.py"]
def test_ungoverned_hotspot_empty():
diff --git a/tests/unit/health/test_history_refresh.py b/tests/unit/health/test_history_refresh.py
new file mode 100644
index 000000000..93c0cc539
--- /dev/null
+++ b/tests/unit/health/test_history_refresh.py
@@ -0,0 +1,163 @@
+"""Re-scoring git-derived markers on files an update never walked."""
+
+from __future__ import annotations
+
+import json
+
+from repowise.core.analysis.health.history_refresh import (
+ REFRESHABLE_MARKERS,
+ as_biomarker_result,
+ refresh_history,
+)
+from repowise.core.analysis.health.models import (
+ HealthFileMetricData,
+ HealthFindingData,
+ Severity,
+)
+
+
+def _metric(path: str = "src/auth.py", **kwargs) -> HealthFileMetricData:
+ return HealthFileMetricData(
+ file_path=path,
+ score=kwargs.pop("score", 8.0),
+ max_ccn=9,
+ max_nesting=3,
+ nloc=kwargs.pop("nloc", 400),
+ has_test_file=True,
+ module="src",
+ **kwargs,
+ )
+
+
+def _finding(biomarker: str, severity: Severity = Severity.HIGH, **kwargs) -> HealthFindingData:
+ return HealthFindingData(
+ biomarker_type=biomarker,
+ severity=severity,
+ file_path=kwargs.pop("file_path", "src/auth.py"),
+ function_name=None,
+ line_start=None,
+ line_end=None,
+ details=kwargs.pop("details", {}),
+ health_impact=kwargs.pop("health_impact", 1.2),
+ )
+
+
+def _run(*, git_meta: dict, findings: list) -> list:
+ return refresh_history(
+ metrics=[_metric()],
+ findings_by_path={"src/auth.py": findings},
+ git_meta_by_path={"src/auth.py": git_meta},
+ languages={"src/auth.py": "python"},
+ )
+
+
+def test_parse_free_markers_only() -> None:
+ """The two that need a blame index and function metrics are excluded.
+
+ Refreshing them without a parse would mean inventing their inputs.
+ """
+ assert "function_hotspot" not in REFRESHABLE_MARKERS
+ assert "code_age_volatility" not in REFRESHABLE_MARKERS
+ assert "prior_defect" in REFRESHABLE_MARKERS
+ assert "co_change_scatter" in REFRESHABLE_MARKERS
+
+
+def test_a_marker_that_stopped_firing_stops_deducting() -> None:
+ """The point of the pass: history that has moved on stops holding a score down."""
+ stale = _finding("prior_defect", details={"fix_count": 9})
+ (refreshed,) = _run(git_meta={"prior_defect_count": 0}, findings=[stale])
+ assert not any(f.biomarker_type == "prior_defect" for f in refreshed.findings)
+ assert refreshed.history_deduction == 0.0
+ assert refreshed.score > 8.0
+
+
+def test_structural_findings_survive_untouched() -> None:
+ """Nothing here reads the source, so nothing here may discard what a parse found."""
+ structural = _finding("god_class", Severity.CRITICAL)
+ (refreshed,) = _run(git_meta={"prior_defect_count": 0}, findings=[structural])
+ kept = [f for f in refreshed.findings if f.biomarker_type == "god_class"]
+ assert len(kept) == 1
+ assert refreshed.structure_deduction > 0
+
+
+def test_a_file_with_no_git_metadata_is_left_alone() -> None:
+ result = refresh_history(
+ metrics=[_metric()],
+ findings_by_path={"src/auth.py": [_finding("prior_defect")]},
+ git_meta_by_path={},
+ languages={"src/auth.py": "python"},
+ )
+ assert result == []
+
+
+def test_governance_findings_survive_without_being_scored() -> None:
+ """They are produced after scoring and deduct nothing.
+
+ Rescoring them here would invent a deduction and charge it to the capped
+ organizational category, which is the one this pass is rewriting; dropping
+ them would delete findings a different pass owns.
+ """
+ stored = _finding("ungoverned_hotspot", Severity.MEDIUM, health_impact=0.0)
+ (refreshed,) = _run(git_meta={"prior_defect_count": 0}, findings=[stored])
+ carried = [f for f in refreshed.findings if f.biomarker_type == "ungoverned_hotspot"]
+ assert len(carried) == 1
+ assert carried[0].health_impact == 0.0
+ assert refreshed.history_deduction == 0.0
+ assert refreshed.score == 10.0
+
+
+def test_a_row_whose_split_was_never_recorded_is_backfilled() -> None:
+ """The first update after the split ships must fill it in.
+
+ Separately from the findings: rewriting those deletes and re-inserts them,
+ which resets every id and ``created_at``, and a row that merely lacks a
+ recorded split has no finding that changed.
+ """
+ from repowise.core.pipeline.incremental import _history_findings_moved, _numbers_moved
+
+ stored = _metric()
+ assert stored.structure_deduction is None
+ (refreshed,) = _run(git_meta={"prior_defect_count": 0}, findings=[])
+ assert _numbers_moved(refreshed, stored)
+ assert not _history_findings_moved(refreshed, [])
+
+
+def test_an_unchanged_file_keeps_its_finding_identity() -> None:
+ """Re-deriving the same history must not churn ids or ages."""
+ from repowise.core.pipeline.incremental import _history_findings_moved
+
+ structural = _finding("god_class", Severity.CRITICAL, health_impact=2.26)
+ (refreshed,) = _run(git_meta={"prior_defect_count": 0}, findings=[structural])
+ assert not _history_findings_moved(refreshed, refreshed.findings)
+
+
+def test_stored_findings_rebuild_exactly() -> None:
+ """The rescore replays stored findings, so the lift has to be lossless.
+
+ ``coverage_gradient`` is the one marker whose magnitude is continuous rather
+ than banded, and it writes that magnitude into its own details.
+ """
+ rebuilt = as_biomarker_result(
+ _finding("coverage_gradient", Severity.LOW, details={"deduction": 3.2})
+ )
+ assert rebuilt.biomarker_type == "coverage_gradient"
+ assert rebuilt.severity == Severity.LOW
+ assert rebuilt.deduction == 3.2
+ assert as_biomarker_result(_finding("god_class")).deduction is None
+
+
+def test_rebuild_reads_a_stored_row_shape() -> None:
+ """Findings arrive as ORM rows after persistence, with details as JSON text."""
+
+ class _Row:
+ biomarker_type = "coverage_gradient"
+ severity = "low"
+ function_name = None
+ line_start = None
+ line_end = None
+ details_json = json.dumps({"deduction": 2.5})
+ reason = "half the lines uncovered"
+
+ rebuilt = as_biomarker_result(_Row())
+ assert rebuilt.deduction == 2.5
+ assert rebuilt.reason == "half the lines uncovered"
diff --git a/tests/unit/health/test_model_version_coupling.py b/tests/unit/health/test_model_version_coupling.py
index 568d25df5..18b1a519f 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 = (9, 2, 2)
+_STAMPS = (10, 2, 2)
def test_the_identity_models_and_the_analyzer_stamp_are_pinned_together() -> None:
diff --git a/tests/unit/health/test_scope_and_split.py b/tests/unit/health/test_scope_and_split.py
new file mode 100644
index 000000000..665270196
--- /dev/null
+++ b/tests/unit/health/test_scope_and_split.py
@@ -0,0 +1,143 @@
+"""What health scores, and the two halves of the number it produces."""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.analysis.health.biomarkers.base import BiomarkerResult, FileContext
+from repowise.core.analysis.health.biomarkers.hidden_coupling import HiddenCouplingDetector
+from repowise.core.analysis.health.biomarkers.untested_hotspot import UntestedHotspotDetector
+from repowise.core.analysis.health.models import Severity, split_by_origin
+from repowise.core.analysis.health.scope import parse_scope, scores_language
+from repowise.core.analysis.health.scoring import (
+ SCORE_MAX,
+ attach_impacts,
+ deduction_split,
+ score_file,
+ unclamped_score,
+)
+
+
+def _result(biomarker: str, severity: Severity = Severity.HIGH) -> BiomarkerResult:
+ return BiomarkerResult(
+ biomarker_type=biomarker,
+ severity=severity,
+ function_name=None,
+ line_start=None,
+ line_end=None,
+ details={},
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Which files are scored at all
+# --------------------------------------------------------------------------- #
+
+
[email protected]("language", ["python", "typescript", "go", "shell", "elixir"])
+def test_code_is_scored(language: str) -> None:
+ assert scores_language(language)
+
+
+ "language", ["markdown", "json", "yaml", "toml", "unknown", "html", None, ""]
+)
+def test_prose_and_configuration_are_not_scored(language: str | None) -> None:
+ """A changelog every fix commit touches otherwise reads as a bug magnet."""
+ assert not scores_language(language)
+
+
+def test_sql_is_scored_despite_being_declared_non_code() -> None:
+ """The registry calls it non-code because nothing parses it into symbols.
+
+ Health does walk it, through sqlglot, and carries markers of its own for it,
+ so excluding it on the registry flag alone would silently drop them.
+ """
+ assert scores_language("sql")
+
+
+def test_unrecognised_scope_falls_back_to_the_default() -> None:
+ """A bad value reads everything rather than silently reading nothing."""
+ assert parse_scope("nonsense") == "all"
+ assert parse_scope(None) == "all"
+
+
+# --------------------------------------------------------------------------- #
+# Test-file gating
+# --------------------------------------------------------------------------- #
+
+
+def test_a_test_file_is_never_an_untested_hotspot() -> None:
+ """With coverage ingested the suite reads as 0% covered and would fire."""
+ ctx = FileContext(
+ file_path="tests/unit/test_auth.py",
+ language="python",
+ nloc=400,
+ has_test_file=False,
+ module="tests",
+ git_meta={"is_hotspot": True, "commit_count_90d": 40},
+ dependents_count=12,
+ line_coverage_pct=0.0,
+ )
+ assert UntestedHotspotDetector().detect(ctx) == []
+
+
+def test_two_tests_moving_together_is_not_hidden_coupling() -> None:
+ partners = (
+ '[{"file_path": "tests/unit/test_db.py", "support": 20, "self_commits": 22, '
+ '"partner_commits": 24, "structural": "unexplained"}]'
+ )
+ ctx = FileContext(
+ file_path="tests/unit/test_auth.py",
+ language="python",
+ nloc=400,
+ has_test_file=True,
+ module="tests",
+ git_meta={"co_change_partners_json": partners},
+ )
+ assert HiddenCouplingDetector().detect(ctx) == []
+
+
+# --------------------------------------------------------------------------- #
+# The structure / history split
+# --------------------------------------------------------------------------- #
+
+
+def test_the_two_halves_sum_to_the_whole_deduction() -> None:
+ results = [
+ _result("god_class", Severity.CRITICAL),
+ _result("complex_method"),
+ _result("change_entropy"),
+ _result("co_change_scatter", Severity.CRITICAL),
+ ]
+ scores, deductions = score_file(results)
+ findings = attach_impacts(results, deductions)
+ structure, history = deduction_split(findings)
+ assert structure > 0 and history > 0
+ assert round(structure + history, 3) == round(sum(deductions), 3)
+ assert round(SCORE_MAX - structure - history, 2) == round(scores["defect"], 2)
+
+
+def test_history_alone_can_hold_a_score_down() -> None:
+ results = [_result("co_change_scatter", Severity.CRITICAL) for _ in range(5)]
+ _, deductions = score_file(results)
+ structure, history = deduction_split(attach_impacts(results, deductions))
+ assert structure == 0.0
+ assert history > 0
+
+
+def test_a_floored_file_still_shows_its_depth() -> None:
+ """Two files pinned at 1.0 are not equally deep, and the score cannot say so."""
+ shallow = unclamped_score(6.0, 4.0)
+ deep = unclamped_score(6.0, 12.0)
+ assert shallow == 0.0
+ assert deep == -8.0
+ assert unclamped_score(None, None) is None
+
+
+def test_split_by_origin_separates_what_an_edit_can_fix() -> None:
+ code_shape, history = split_by_origin(
+ [_result("complex_method"), _result("prior_defect"), _result("god_class")]
+ )
+ assert [f.biomarker_type for f in code_shape] == ["complex_method", "god_class"]
+ assert [f.biomarker_type for f in history] == ["prior_defect"]
diff --git a/tests/unit/health/test_scoring_dimensions.py b/tests/unit/health/test_scoring_dimensions.py
index 93234f01e..cfd3a9bd7 100644
--- a/tests/unit/health/test_scoring_dimensions.py
+++ b/tests/unit/health/test_scoring_dimensions.py
@@ -175,6 +175,31 @@ def test_defect_dimension_matches_legacy_golden():
assert scores["defect"] == _legacy_score_file(fixture)
+# The widened maintainability pillar, pinned per fixture. Maintainability is
+# the number a refactor is meant to move, so it needs a golden of its own: the
+# defect gate above cannot see a change here, and every pure code-shape marker
+# now counts toward it. A deliberate retune updates these; a surprise does not.
+_MAINTAINABILITY_GOLDEN: list[float] = [10.0, 8.0, 6.0, 6.1, 8.0, 10.0, 4.2, 10.0, 10.0]
+
+
+def test_maintainability_dimension_matches_golden():
+ for fixture, expected in zip(_FIXTURES, _MAINTAINABILITY_GOLDEN, strict=True):
+ scores, _ = score_file(fixture)
+ assert round(scores["maintainability"], 4) == expected
+
+
+def test_code_shape_markers_reach_maintainability():
+ """A method too complex to follow is a maintainability problem.
+
+ These three are calibrated defect predictors and were scored as nothing
+ else, which left the pillar a reader watches while refactoring blind to the
+ most common thing a refactor removes.
+ """
+ for marker in ("complex_method", "complex_conditional", "bumpy_road"):
+ scores, _ = score_file([_r(marker, Severity.CRITICAL)])
+ assert scores["maintainability"] < 10.0, marker
+
+
def test_defect_deductions_unchanged():
"""The returned per-finding deductions still drive defect-based health_impact."""
fixture = _FIXTURES[3]