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.

fix(health): stamp a full index with its commit and compose after governance (#2001)

Raghav Chamadiya7a368e05f33e
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 5816bf8ed..ad41b5733 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -909,26 +909,6 @@ def _carry_forward_kg_enrichment(kg: Any, prior_kg: Any) -> None:
kg.tour = prior_kg.tour
-async def _analyzed_commit(session: Any, repo_id: str) -> str | None:
- """Live HEAD of the repo being updated, for stamping health rows.
-
- Read off disk rather than from ``Repository.head_commit``: the health pass
- just scored the working tree, and the stored column is written by a
- different step whose ordering relative to this one is not guaranteed.
- ``None`` on any failure — an unstamped row reads as "not recorded", which
- is honest, while a wrong sha would not be.
- """
- from repowise.core.persistence.models import Repository
- from repowise.core.workspace.update import get_head_commit
-
- try:
- repo = await session.get(Repository, repo_id)
- local_path = getattr(repo, "local_path", None) if repo else None
- return get_head_commit(Path(local_path)) if local_path else None
- except Exception:
- return None
-
-
async def persist_partial_health(session: Any, repo_id: str, report: Any) -> None:
"""Upsert health findings + metrics for the changed-files subset.
@@ -944,6 +924,7 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non
upsert_health_metrics,
upsert_refactoring_suggestions,
)
+ from repowise.core.pipeline.persist import _analyzed_commit
changed_paths = sorted(
set(getattr(report, "authoritative_paths", None) or ())
@@ -1722,6 +1703,7 @@ async def persist_incremental_index(
finalize_performance_opportunities,
finalize_refactoring_opportunities,
)
+ from repowise.core.pipeline.persist import _analyzed_commit
analyzed_commit = await _analyzed_commit(session, repo_id)
await finalize_performance_opportunities(
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 97a131c98..abff43aa6 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1501,6 +1501,27 @@ async def persist_git(result: Any, session: Any, repo_id: str) -> None:
)
+async def _analyzed_commit(session: Any, repo_id: str) -> str | None:
+ """Live HEAD of the repo being indexed, for stamping health rows.
+
+ Read off disk rather than from ``Repository.head_commit``: the health pass
+ just scored the working tree, and the stored column is written by a
+ different step whose ordering relative to this one is not guaranteed.
+ ``None`` on any failure — an unstamped row reads as "not recorded", which
+ is honest, while a wrong sha would not be. Both index paths read it here;
+ the pipeline result carries no sha, so the full path used to stamp ``NULL``.
+ """
+ from repowise.core.persistence.models import Repository
+ from repowise.core.workspace.update import get_head_commit
+
+ try:
+ repo = await session.get(Repository, repo_id)
+ local_path = getattr(repo, "local_path", None) if repo else None
+ return get_head_commit(Path(local_path)) if local_path else None
+ except Exception:
+ return None
+
+
async def save_full_health_report(
session: Any,
repo_id: str,
@@ -1607,7 +1628,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
# Hoisted out of the coverage branch below: the same sha now stamps the
# metric rows, so a reader can tell how far the health pass lags the
# index instead of assuming the two moved together.
- head_sha = getattr(result, "head_commit", None) or getattr(result, "commit_sha", None)
+ head_sha = await _analyzed_commit(session, repo_id)
await save_full_health_report(session, repo_id, hr, analyzed_commit=head_sha)
# Resolved coverage rows, when a report was ingested this run.
coverage_files = getattr(hr, "coverage_files", None)
@@ -1769,6 +1790,24 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
repo_id=repo_id,
count=len(_gov_findings),
)
+ # The refactoring queue is a fold over the stored findings and was
+ # composed above, before these rows existed, so without a second
+ # pass a fresh index ranks every opportunity against a finding set
+ # holding none of its governance causes. Only this queue: the
+ # performance finalizer reads ``performance`` findings, and every
+ # governance biomarker is ``organizational``.
+ from repowise.core.persistence.crud import (
+ finalize_refactoring_opportunities,
+ )
+
+ # Savepointed like the first composition: this writer reconciles
+ # the whole queue, so a half-failed one would leave it half-described.
+ async with session.begin_nested():
+ await finalize_refactoring_opportunities(
+ session,
+ repo_id,
+ analyzed_commit=await _analyzed_commit(session, repo_id),
+ )
except Exception as _gov_err:
logger.debug("governance_findings_skipped", error=str(_gov_err))
diff --git a/tests/unit/health/test_model_version_coupling.py b/tests/unit/health/test_model_version_coupling.py
new file mode 100644
index 000000000..647f0411b
--- /dev/null
+++ b/tests/unit/health/test_model_version_coupling.py
@@ -0,0 +1,34 @@
+"""The identity models and the analyzer stamp have to move together.
+
+A stored opportunity id names the model that minted it. Nothing re-mints those
+ids except the re-score, and the re-score is triggered by
+``HEALTH_ANALYZER_VERSION`` alone - neither identity model version is an input
+to that gate. So a model bump that lands without an analyzer bump leaves every
+stored id describing a model that no longer exists, on a store that will never
+be told to recompute.
+
+``REFACTORING_MODEL_VERSION`` went 1 -> 2 with no matching analyzer bump. It was
+harmless only because an unrelated change had already moved the analyzer in the
+same release. This pins the three so that cannot happen quietly again.
+"""
+
+from __future__ import annotations
+
+from repowise.core.analysis.health.engine import HEALTH_ANALYZER_VERSION
+from repowise.core.analysis.health.perf.causal import PERFORMANCE_MODEL_VERSION
+from repowise.core.analysis.health.refactoring.identity import (
+ REFACTORING_MODEL_VERSION,
+)
+
+# 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 = (7, 2, 2)
+
+
+def test_the_identity_models_and_the_analyzer_stamp_are_pinned_together() -> None:
+ """If you changed an identity kernel: bump the analyzer too, then ``_STAMPS``."""
+ assert (
+ HEALTH_ANALYZER_VERSION,
+ PERFORMANCE_MODEL_VERSION,
+ REFACTORING_MODEL_VERSION,
+ ) == _STAMPS
diff --git a/tests/unit/persistence/test_persist_analysis_health_stamps.py b/tests/unit/persistence/test_persist_analysis_health_stamps.py
new file mode 100644
index 000000000..5aec0bd63
--- /dev/null
+++ b/tests/unit/persistence/test_persist_analysis_health_stamps.py
@@ -0,0 +1,223 @@
+"""What the analysis phase must have written by the time it returns.
+
+Two orderings inside :func:`persist_analysis` are load-bearing. The commit the
+scores were computed against is read off disk, because the pipeline result does
+not carry one. And the governance findings land *after* the writer that folds
+findings into the refactoring queue, so that queue has to be composed a second
+time or it describes a repository whose governance causes do not exist.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from sqlalchemy import select
+
+from repowise.core.analysis.health.governance import HealthFindingData, Severity
+from repowise.core.persistence.models import (
+ HealthFileMetric,
+ RefactoringOpportunity,
+)
+from repowise.core.pipeline.persist import persist_analysis
+from tests.unit.persistence.helpers import insert_repo
+
+_PATH = "src/app.py"
+
+
+def _metric(path: str = _PATH) -> dict:
+ return {
+ "file_path": path,
+ "score": 5.0,
+ "max_ccn": 3,
+ "max_nesting": 1,
+ "nloc": 40,
+ "duplication_pct": 0.0,
+ "has_test_file": False,
+ "line_coverage_pct": None,
+ "branch_coverage_pct": None,
+ "module": "src",
+ }
+
+
+def _finding(path: str = _PATH, *, impact: float = 1.0) -> dict:
+ return {
+ "file_path": path,
+ "biomarker_type": "complex_method",
+ "severity": "high",
+ "function_name": "f",
+ "line_start": 10,
+ "line_end": 30,
+ "details": {},
+ "health_impact": impact,
+ "reason": "seeded",
+ "dimension": "defect",
+ }
+
+
+def _plan(path: str = _PATH) -> dict:
+ return {
+ "refactoring_type": "extract_method",
+ "file_path": path,
+ "target_symbol": "f",
+ "line_start": 10,
+ "line_end": 30,
+ "plan": {"extracted_name": "_f_part", "local_scope": True},
+ "evidence": {"ccn_removed": 6, "slice_nloc": 20},
+ "impact_delta": 1.0,
+ "effort_bucket": "S",
+ "blast_radius": {"scope": "local"},
+ "confidence": "high",
+ "source_biomarker": "complex_method",
+ }
+
+
+def _result(**over) -> SimpleNamespace:
+ """A pipeline result carrying only what the analysis phase reads.
+
+ Deliberately without ``head_commit`` or ``commit_sha``: that is the shape
+ the real init path hands over, and the reason the sha has to come from disk.
+ """
+ base = dict(
+ dead_code_report=None,
+ decision_report=None,
+ health_report=SimpleNamespace(
+ metrics=[_metric()],
+ findings=[_finding()],
+ refactoring_suggestions=[_plan()],
+ performance_plan_policy=None,
+ kpis={},
+ coverage_files=None,
+ function_blame_rows=None,
+ ),
+ )
+ base.update(over)
+ return SimpleNamespace(**base)
+
+
+async def _metric_commits(session, repo_id: str) -> set[str | None]:
+ rows = (
+ (
+ await session.execute(
+ select(HealthFileMetric).where(HealthFileMetric.repository_id == repo_id)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ assert rows, "the analysis phase must have written metric rows"
+ return {row.analyzed_commit for row in rows}
+
+
+async def _leads(session, repo_id: str) -> dict[str, str | None]:
+ rows = (
+ (
+ await session.execute(
+ select(RefactoringOpportunity).where(
+ RefactoringOpportunity.repository_id == repo_id
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ return {row.file_path: row.lead_biomarker for row in rows}
+
+
+class TestAnalyzedCommit:
+ async def test_it_stamps_the_metric_rows_with_head_read_off_disk(
+ self, async_session, monkeypatch
+ ):
+ """The defect this exists for: every row of a fresh index was NULL.
+
+ The sha was taken off the pipeline result, which carries neither
+ ``head_commit`` nor ``commit_sha``, so a full index stamped nothing
+ while the update path stamped correctly.
+ """
+ import repowise.core.workspace.update as update_mod
+
+ monkeypatch.setattr(update_mod, "get_head_commit", lambda _path: "d" * 40)
+ repo = await insert_repo(async_session)
+ await persist_analysis(_result(), async_session, repo.id)
+ assert await _metric_commits(async_session, repo.id) == {"d" * 40}
+
+ async def test_an_unreadable_head_leaves_the_column_null(
+ self, async_session, monkeypatch
+ ):
+ """``None`` reads as "not recorded", which is honest; a guess is not."""
+ import repowise.core.workspace.update as update_mod
+
+ monkeypatch.setattr(update_mod, "get_head_commit", lambda _path: None)
+ repo = await insert_repo(async_session)
+ await persist_analysis(_result(), async_session, repo.id)
+ assert await _metric_commits(async_session, repo.id) == {None}
+
+
+class TestGovernanceReachesTheComposer:
+ async def test_the_queue_leads_with_a_governance_cause(
+ self, async_session, monkeypatch
+ ):
+ """The defect this exists for: governance lands after the composer.
+
+ ``replace_governance_findings`` runs well after the writer that folds
+ findings into the refactoring queue, so without a second composition a
+ freshly indexed repository ranks every opportunity against a finding
+ set holding none of its governance causes.
+ """
+ import repowise.core.pipeline.persist as persist_mod
+
+ monkeypatch.setattr(
+ persist_mod,
+ "_analyzed_commit",
+ _stub_commit("e" * 40),
+ )
+ _stub_governance(
+ monkeypatch,
+ [
+ HealthFindingData(
+ biomarker_type="ungoverned_hotspot",
+ severity=Severity.MEDIUM,
+ file_path=_PATH,
+ function_name=None,
+ line_start=None,
+ line_end=None,
+ details={"is_hotspot": True},
+ health_impact=9.0,
+ reason="Churn hotspot with no governing architectural decision.",
+ )
+ ],
+ )
+ repo = await insert_repo(async_session)
+ await persist_analysis(_result(), async_session, repo.id)
+ assert (await _leads(async_session, repo.id))[_PATH] == "ungoverned_hotspot"
+
+ async def test_a_run_with_no_governance_causes_keeps_its_structural_lead(
+ self, async_session, monkeypatch
+ ):
+ """The recomposition must not disturb a repository that has none."""
+ import repowise.core.pipeline.persist as persist_mod
+
+ monkeypatch.setattr(persist_mod, "_analyzed_commit", _stub_commit("e" * 40))
+ _stub_governance(monkeypatch, [])
+ repo = await insert_repo(async_session)
+ await persist_analysis(_result(), async_session, repo.id)
+ assert (await _leads(async_session, repo.id))[_PATH] == "complex_method"
+
+
+def _stub_commit(sha: str):
+ async def _fake(_session, _repo_id):
+ return sha
+
+ return _fake
+
+
+def _stub_governance(monkeypatch, findings: list) -> None:
+ """Pin the governance pass's output without standing up a decision graph.
+
+ ``persist_analysis`` imports it inside the function body, so the module
+ attribute is what the call resolves to.
+ """
+ import repowise.core.analysis.health.governance as gov_mod
+
+ monkeypatch.setattr(
+ gov_mod, "build_governance_findings", lambda **_kwargs: findings
+ )