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): 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.pyindex 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.pyindex 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_findingsfrom 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.pyindex 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.pyindex 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 annotationsfrom ....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_pairfrom ..models import Severityfrom .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.pyindex 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_pathfrom ..models import Severityfrom .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.pyindex 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_readerfrom .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):+ continuetry:fcx = self._walk(pf)except Exception as exc:@@ -678,7 +687,8 @@ class HealthAnalyzer:target_files = [pffor 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 cohesiondiff --git a/packages/core/src/repowise/core/analysis/health/governance.py b/packages/core/src/repowise/core/analysis/health/governance.pyindex 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 annotationsfrom typing import Any+from ...test_paths import is_test_related_pathfrom .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 singlearchitectural 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 findingswithout 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):+ continueout.append(HealthFindingData(biomarker_type="ungoverned_hotspot",@@ -101,7 +121,7 @@ def _ungoverned_hotspot_findings(health_summary: dict[str, Any]) -> list[HealthFline_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.pynew file mode 100644index 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 outdiff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.pyindex 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 = Nonemaintainability_score: float | None = Noneperformance_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@dataclassdiff --git a/packages/core/src/repowise/core/analysis/health/scope.py b/packages/core/src/repowise/core/analysis/health/scope.pynew file mode 100644index 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.pyindex 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 | Noreturn 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`` (staticperformance 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.pyindex 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__.pyindex 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.pyindex 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 PerfCoveragefrom ....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_pathfrom ...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 repowhose writers disagree gets a history that changes depth depending on whichcommand 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.pyindex 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.pyindex 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.pyindex 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) -> Nonfrom repowise.core.persistence.crud import upsert_git_function_blame_bulkawait 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.pyindex 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 therun 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_findingsfrom 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.pyindex 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.pynew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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.pyindex 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]