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.

refactor(core): extract persist_analysis decision steps into named helpers (#3999)

Raghav Chamadiya0db57fd26b3f
diff --git a/packages/core/src/repowise/core/pipeline/persist/__init__.py b/packages/core/src/repowise/core/pipeline/persist/__init__.py
index b44f7b61c..4eb71bbb3 100644
--- a/packages/core/src/repowise/core/pipeline/persist/__init__.py
+++ b/packages/core/src/repowise/core/pipeline/persist/__init__.py
@@ -20,6 +20,11 @@ import structlog
from .analysis import (
persist_analysis,
)
+from .decisions import (
+ apply_decision_lifecycle,
+ repair_decision_store,
+ store_decisions,
+)
from .generation import (
persist_generation,
persist_kg,
diff --git a/packages/core/src/repowise/core/pipeline/persist/analysis.py b/packages/core/src/repowise/core/pipeline/persist/analysis.py
index 1b2db3888..6a48c32f7 100644
--- a/packages/core/src/repowise/core/pipeline/persist/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/persist/analysis.py
@@ -11,6 +11,8 @@ import structlog
# ``repowise.core.pipeline.persist`` reaches this module too.
from repowise.core.pipeline import persist as _persist
+from .decisions import apply_decision_lifecycle, repair_decision_store, store_decisions
+
logger = structlog.get_logger("repowise.core.pipeline.persist")
@@ -23,8 +25,6 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
phase has fully completed.
"""
from repowise.core.persistence.crud import (
- bulk_upsert_decisions,
- recompute_decision_staleness,
replace_doc_drift_guarded,
save_coverage_files,
save_dead_code_findings,
@@ -102,157 +102,17 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:
if result.decision_report and result.decision_report.decisions:
decision_dicts.extend(dataclasses.asdict(d) for d in result.decision_report.decisions)
- # Restore records the semantic supersession detector retired before it was
- # turned off. ``superseded`` is a protected status, so nothing else will
- # ever walk these back, and a store that only stops retiring is still a
- # store with a quarter of its corpus hidden. Runs whether or not this run
- # produced decisions.
- #
- # BEFORE the purge below, not after: restoring puts a row back at
- # ``proposed``, which is exactly what the purge deletes. Un-retire first and
- # a run ends in one consistent state — good records visible, retired-source
- # records gone. The other order leaves a restored changelog row alive for
- # one run and silently deletes it on the next.
- try:
- from repowise.core.persistence.crud import unretire_auto_superseded
-
- await unretire_auto_superseded(session)
- except Exception as _unretire_err:
- logger.debug("decision_unretire_skipped", error=str(_unretire_err))
-
- # One-shot drain of proposals left by retired extraction sources; without
- # this, DBs indexed before a removal keep a flooded review queue forever
- # (#751 for code_comment). Confirmed/dismissed rows are kept.
- try:
- from repowise.core.analysis.decision_provenance import RETIRED_SOURCES
- from repowise.core.persistence.crud import purge_proposed_decisions_by_source
-
- for _retired in RETIRED_SOURCES:
- await purge_proposed_decisions_by_source(session, repo_id, _retired)
- except Exception as _purge_err:
- logger.debug("decision_purge_skipped", error=str(_purge_err))
-
- # Re-stamp evidence rows left on a previous SOURCE_RANK ladder. Local stores
- # are created by ``init_db`` and never see Alembic, so the migration alone
- # would only reach hosted; this is the same repair on the path every store
- # takes. No-op scan once reconciled, and it runs whether or not this run
- # produced decisions, because a store with nothing new still holds the rows.
- try:
- from repowise.core.persistence.crud import reconcile_source_ranks
-
- await reconcile_source_ranks(session)
- except Exception as _rank_err:
- logger.debug("decision_rank_reconcile_skipped", error=str(_rank_err))
-
- # The same repair for the scoring formula, which leaves every input valid
- # and every stored score stale, so no filter can find it. Its own try, so
- # a failure here is not logged as the rank repair's.
- try:
- from repowise.core.persistence.crud import reconcile_decision_confidence
-
- await reconcile_decision_confidence(session)
- except Exception as _conf_err:
- logger.debug("decision_confidence_reconcile_skipped", error=str(_conf_err))
-
- # Move legacy records onto ids derived from their own identity, before
- # anything else reads or writes one. A random id is re-minted whenever a
- # store is rebuilt rather than updated, which strands every reference held
- # outside the row. Idempotent, and it never deletes a record.
- try:
- from repowise.core.persistence.decision_id_migration import apply_id_migration
-
- await apply_id_migration(
- session, repo_id, vector_store=getattr(result, "vector_store", None)
- )
- except Exception as _id_err:
- logger.debug("decision_id_migration_skipped", error=str(_id_err))
-
- # Classify legacy rows against the entity split. A record promoted by
- # recurrence rather than by a person becomes a candidate, which visibly
- # shrinks what governs; leaving it to an explicit command would instead
- # leave the status column and the acceptance log permanently disagreeing,
- # with half the surfaces reading each. Idempotent, and it never reopens a
- # review action somebody already performed.
- try:
- from repowise.core.persistence.decision_migration import (
- apply_migration,
- backfill_decision_node_links,
- backfill_scope_basis,
- backfill_session_scope_basis,
- prune_unindexed_scope_files,
- )
-
- await apply_migration(session, repo_id)
- # Beside it, and for the same reason: these repair rows written before
- # the rule existed, and nothing re-extracts them. The prune runs first
- # so the two basis repairs judge the file list they will leave behind.
- await prune_unindexed_scope_files(session, repo_id)
- await backfill_scope_basis(session, repo_id)
- await backfill_session_scope_basis(session, repo_id)
- await backfill_decision_node_links(session, repo_id)
- except Exception as _migrate_err:
- logger.debug("decision_entity_migration_skipped", error=str(_migrate_err))
-
+ vector_store = getattr(result, "vector_store", None)
+ await repair_decision_store(session, repo_id, vector_store=vector_store)
if decision_dicts:
- # Reuse the run's shared vector store for semantic (paraphrase) dedup
- # and to make decisions searchable; title dedup still runs when None.
- store = getattr(result, "vector_store", None)
- touched_ids = await bulk_upsert_decisions(
+ await store_decisions(
session,
repo_id,
decision_dicts,
- vector_store=store,
+ vector_store=vector_store,
+ git_metadata=result.git_metadata_list,
)
- # Phase 3B: detect supersession/conflict among the just-upserted
- # decisions and record typed edges (auto-flipping the older only above
- # the high-confidence threshold). Heuristic-only here (no provider on
- # the persist path); the update path adds the gated LLM tiebreaker.
- if touched_ids and store is not None:
- try:
- from repowise.core.analysis.decision_evolution import (
- detect_supersessions_and_conflicts,
- )
-
- evo = await detect_supersessions_and_conflicts(
- session,
- repo_id,
- touched_ids=touched_ids,
- vector_store=store,
- )
- if any(evo.values()):
- logger.info("decision_supersession_detected", **evo)
- except Exception as _evo_err:
- logger.debug("supersession_detection_skipped", error=str(_evo_err))
- # Recompute staleness scores using git metadata.
- if result.git_metadata_list:
- try:
- git_meta_map: dict[str, dict] = {}
- for gm in result.git_metadata_list:
- gm_dict = gm if isinstance(gm, dict) else dataclasses.asdict(gm)
- fp = gm_dict.get("file_path", "")
- if fp:
- git_meta_map[fp] = gm_dict
- if git_meta_map:
- updated = await recompute_decision_staleness(session, repo_id, git_meta_map)
- if updated:
- logger.info("decision_staleness_recomputed", updated=updated)
- except Exception as _stale_err:
- logger.debug("staleness_scoring_skipped", error=str(_stale_err))
-
- # Retire records whose commits were reverted. Outside the block above: a
- # new revert retires a decision stored by an earlier run just as well.
- try:
- from repowise.core.analysis.decisions.reverts import apply_revert_supersession
-
- await apply_revert_supersession(session, repo_id, getattr(result, "repo_path", None))
- except Exception as _revert_err:
- logger.debug("revert_supersession_skipped", error=str(_revert_err))
- try:
- from repowise.core.analysis.decisions.head_artifacts import apply_head_artifact_check
-
- await apply_head_artifact_check(session, repo_id, getattr(result, "repo_path", None))
- except Exception as _artifact_err:
- logger.debug("head_artifact_check_skipped", error=str(_artifact_err))
+ await apply_decision_lifecycle(session, repo_id, getattr(result, "repo_path", None))
# ---- Governance findings (additive pass, after decisions are persisted) ----
# Runs after bulk_upsert_decisions + detect_supersessions_and_conflicts so
diff --git a/packages/core/src/repowise/core/pipeline/persist/decisions.py b/packages/core/src/repowise/core/pipeline/persist/decisions.py
new file mode 100644
index 000000000..7d993a579
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/persist/decisions.py
@@ -0,0 +1,201 @@
+"""Decision store repairs, decision upserts and decision lifecycle passes.
+
+Shared steps of every path that persists decision records.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Iterable
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger("repowise.core.pipeline.persist")
+
+
+async def repair_decision_store(session: Any, repo_id: str, *, vector_store: Any = None) -> None:
+ """Run the idempotent store repairs, in order, each failure logged and skipped.
+
+ Runs whether or not the caller has new decisions: every repair fixes rows
+ an earlier run left behind.
+ """
+ # Restore records the semantic supersession detector retired before it was
+ # turned off. ``superseded`` is a protected status, so nothing else will
+ # ever walk these back, and a store that only stops retiring is still a
+ # store with a quarter of its corpus hidden. Runs whether or not this run
+ # produced decisions.
+ #
+ # BEFORE the purge below, not after: restoring puts a row back at
+ # ``proposed``, which is exactly what the purge deletes. Un-retire first and
+ # a run ends in one consistent state — good records visible, retired-source
+ # records gone. The other order leaves a restored changelog row alive for
+ # one run and silently deletes it on the next.
+ try:
+ from repowise.core.persistence.crud import unretire_auto_superseded
+
+ await unretire_auto_superseded(session)
+ except Exception as _unretire_err:
+ logger.debug("decision_unretire_skipped", error=str(_unretire_err))
+
+ # One-shot drain of proposals left by retired extraction sources; without
+ # this, DBs indexed before a removal keep a flooded review queue forever
+ # (#751 for code_comment). Confirmed/dismissed rows are kept.
+ try:
+ from repowise.core.analysis.decision_provenance import RETIRED_SOURCES
+ from repowise.core.persistence.crud import purge_proposed_decisions_by_source
+
+ for _retired in RETIRED_SOURCES:
+ await purge_proposed_decisions_by_source(session, repo_id, _retired)
+ except Exception as _purge_err:
+ logger.debug("decision_purge_skipped", error=str(_purge_err))
+
+ # Re-stamp evidence rows left on a previous SOURCE_RANK ladder. Local stores
+ # are created by ``init_db`` and never see Alembic, so the migration alone
+ # would only reach hosted; this is the same repair on the path every store
+ # takes. No-op scan once reconciled, and it runs whether or not this run
+ # produced decisions, because a store with nothing new still holds the rows.
+ try:
+ from repowise.core.persistence.crud import reconcile_source_ranks
+
+ await reconcile_source_ranks(session)
+ except Exception as _rank_err:
+ logger.debug("decision_rank_reconcile_skipped", error=str(_rank_err))
+
+ # The same repair for the scoring formula, which leaves every input valid
+ # and every stored score stale, so no filter can find it. Its own try, so
+ # a failure here is not logged as the rank repair's.
+ try:
+ from repowise.core.persistence.crud import reconcile_decision_confidence
+
+ await reconcile_decision_confidence(session)
+ except Exception as _conf_err:
+ logger.debug("decision_confidence_reconcile_skipped", error=str(_conf_err))
+
+ # Move legacy records onto ids derived from their own identity, before
+ # anything else reads or writes one. A random id is re-minted whenever a
+ # store is rebuilt rather than updated, which strands every reference held
+ # outside the row. Idempotent, and it never deletes a record.
+ try:
+ from repowise.core.persistence.decision_id_migration import apply_id_migration
+
+ await apply_id_migration(session, repo_id, vector_store=vector_store)
+ except Exception as _id_err:
+ logger.debug("decision_id_migration_skipped", error=str(_id_err))
+
+ # Classify legacy rows against the entity split. A record promoted by
+ # recurrence rather than by a person becomes a candidate, which visibly
+ # shrinks what governs; leaving it to an explicit command would instead
+ # leave the status column and the acceptance log permanently disagreeing,
+ # with half the surfaces reading each. Idempotent, and it never reopens a
+ # review action somebody already performed.
+ try:
+ from repowise.core.persistence.decision_migration import (
+ apply_migration,
+ backfill_decision_node_links,
+ backfill_scope_basis,
+ backfill_session_scope_basis,
+ prune_unindexed_scope_files,
+ )
+
+ await apply_migration(session, repo_id)
+ # Beside it, and for the same reason: these repair rows written before
+ # the rule existed, and nothing re-extracts them. The prune runs first
+ # so the two basis repairs judge the file list they will leave behind.
+ await prune_unindexed_scope_files(session, repo_id)
+ await backfill_scope_basis(session, repo_id)
+ await backfill_session_scope_basis(session, repo_id)
+ await backfill_decision_node_links(session, repo_id)
+ except Exception as _migrate_err:
+ logger.debug("decision_entity_migration_skipped", error=str(_migrate_err))
+
+
+async def store_decisions(
+ session: Any,
+ repo_id: str,
+ decisions: list[dict],
+ *,
+ vector_store: Any = None,
+ git_metadata: Iterable[Any] | None = None,
+ provider: Any = None,
+) -> list[str]:
+ """Upsert ``decisions``, then detect supersession and rescore staleness.
+
+ Returns the ids the upsert touched. A failing upsert propagates; the two
+ passes after it are best-effort. ``git_metadata`` holds per-file git rows
+ (dicts or dataclasses) for the staleness rescore; ``provider`` enables
+ the LLM tiebreaker in supersession detection.
+ """
+ from repowise.core.persistence.crud import (
+ bulk_upsert_decisions,
+ recompute_decision_staleness,
+ )
+
+ if not decisions:
+ return []
+ # The run's shared vector store gives semantic (paraphrase) dedup and
+ # makes decisions searchable; title dedup still runs when None.
+ touched_ids = await bulk_upsert_decisions(
+ session,
+ repo_id,
+ decisions,
+ vector_store=vector_store,
+ )
+ # Detect supersession/conflict among the just-upserted decisions and
+ # record typed edges (auto-flipping the older only above the
+ # high-confidence threshold). Heuristic-only without a provider; with one,
+ # the gated LLM tiebreaker runs too.
+ if touched_ids and vector_store is not None:
+ try:
+ from repowise.core.analysis.decision_evolution import (
+ detect_supersessions_and_conflicts,
+ )
+
+ evo = await detect_supersessions_and_conflicts(
+ session,
+ repo_id,
+ touched_ids=touched_ids,
+ vector_store=vector_store,
+ provider=provider,
+ )
+ if any(evo.values()):
+ logger.info("decision_supersession_detected", **evo)
+ except Exception as _evo_err:
+ logger.debug("supersession_detection_skipped", error=str(_evo_err))
+ # Recompute staleness scores using git metadata.
+ if git_metadata:
+ try:
+ git_meta_map: dict[str, dict] = {}
+ for gm in git_metadata:
+ gm_dict = gm if isinstance(gm, dict) else dataclasses.asdict(gm)
+ fp = gm_dict.get("file_path", "")
+ if fp:
+ git_meta_map[fp] = gm_dict
+ if git_meta_map:
+ updated = await recompute_decision_staleness(session, repo_id, git_meta_map)
+ if updated:
+ logger.info("decision_staleness_recomputed", updated=updated)
+ except Exception as _stale_err:
+ logger.debug("staleness_scoring_skipped", error=str(_stale_err))
+ return touched_ids
+
+
+async def apply_decision_lifecycle(session: Any, repo_id: str, repo_path: Any) -> None:
+ """Retire decisions whose commits were reverted or whose HEAD artifacts are gone.
+
+ Every run, whether or not it stored decisions. Each pass is best-effort.
+ """
+ # Retire records whose commits were reverted. Not tied to new records: a
+ # new revert retires a decision stored by an earlier run just as well.
+ try:
+ from repowise.core.analysis.decisions.reverts import apply_revert_supersession
+
+ await apply_revert_supersession(session, repo_id, repo_path)
+ except Exception as _revert_err:
+ logger.debug("revert_supersession_skipped", error=str(_revert_err))
+ try:
+ from repowise.core.analysis.decisions.head_artifacts import apply_head_artifact_check
+
+ await apply_head_artifact_check(session, repo_id, repo_path)
+ except Exception as _artifact_err:
+ logger.debug("head_artifact_check_skipped", error=str(_artifact_err))
diff --git a/tests/unit/pipeline/test_persist_decision_helpers.py b/tests/unit/pipeline/test_persist_decision_helpers.py
new file mode 100644
index 000000000..2e2ce0c8a
--- /dev/null
+++ b/tests/unit/pipeline/test_persist_decision_helpers.py
@@ -0,0 +1,124 @@
+"""The decision helpers ``persist_analysis`` runs, called on their own."""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.pipeline.persist import (
+ apply_decision_lifecycle,
+ repair_decision_store,
+ store_decisions,
+)
+from tests.unit._persist_step_recorders import FAILURE, StepRecorder, install_decision_chain
+
+_STORE = object()
+
+
+async def test_repairs_run_in_order_and_take_the_vector_store(monkeypatch):
+ from repowise.core.analysis.decision_provenance import RETIRED_SOURCES
+
+ rec = StepRecorder(monkeypatch)
+ install_decision_chain(rec)
+
+ await repair_decision_store(object(), "repo-1", vector_store=_STORE)
+
+ assert rec.order == [
+ "unretire_auto_superseded",
+ *["purge_proposed_decisions_by_source"] * len(RETIRED_SOURCES),
+ "reconcile_source_ranks",
+ "reconcile_decision_confidence",
+ "apply_id_migration",
+ "apply_migration",
+ "prune_unindexed_scope_files",
+ "backfill_scope_basis",
+ "backfill_session_scope_basis",
+ "backfill_decision_node_links",
+ ]
+ assert rec.args_of("apply_id_migration")[0][1] == {"vector_store": _STORE}
+
+
+async def test_no_decisions_writes_nothing(monkeypatch):
+ rec = StepRecorder(monkeypatch)
+ install_decision_chain(rec)
+
+ assert await store_decisions(object(), "repo-1", [], git_metadata=[{"file_path": "a.py"}]) == []
+ assert rec.order == []
+
+
+async def test_store_upserts_then_detects_then_rescores(monkeypatch):
+ rec = StepRecorder(monkeypatch)
+ install_decision_chain(rec)
+ rows = [{"file_path": "src/a.py"}, {"file_path": ""}]
+
+ touched = await store_decisions(
+ object(),
+ "repo-1",
+ [{"title": "t"}],
+ vector_store=_STORE,
+ git_metadata=rows,
+ provider="llm",
+ )
+
+ assert touched == ["decision-1"]
+ assert rec.order == [
+ "bulk_upsert_decisions",
+ "detect_supersessions_and_conflicts",
+ "recompute_decision_staleness",
+ ]
+ assert rec.args_of("detect_supersessions_and_conflicts")[0][1]["provider"] == "llm"
+ assert rec.args_of("recompute_decision_staleness")[0][0][2] == {
+ "src/a.py": {"file_path": "src/a.py"}
+ }
+
+
+async def test_supersession_is_skipped_without_a_vector_store(monkeypatch):
+ rec = StepRecorder(monkeypatch)
+ install_decision_chain(rec)
+
+ await store_decisions(object(), "repo-1", [{"title": "t"}])
+
+ assert rec.order == ["bulk_upsert_decisions"]
+
+
+async def test_a_failing_upsert_propagates(monkeypatch):
+ rec = StepRecorder(monkeypatch, fail=frozenset({"bulk_upsert_decisions"}))
+ install_decision_chain(rec)
+
+ with pytest.raises(RuntimeError, match=FAILURE):
+ await store_decisions(object(), "repo-1", [{"title": "t"}], vector_store=_STORE)
+ assert rec.order == ["bulk_upsert_decisions"]
+
+
+async def test_lifecycle_passes_are_isolated(monkeypatch):
+ rec = StepRecorder(
+ monkeypatch, fail=frozenset({"apply_revert_supersession", "apply_head_artifact_check"})
+ )
+ install_decision_chain(rec)
+
+ await apply_decision_lifecycle(object(), "repo-1", "/repo")
+
+ assert rec.order == ["apply_revert_supersession", "apply_head_artifact_check"]
+ assert rec.args_of("apply_head_artifact_check")[0][0][2] == "/repo"
+
+
+async def test_failing_passes_after_the_upsert_are_swallowed(monkeypatch):
+ rec = StepRecorder(
+ monkeypatch,
+ fail=frozenset({"detect_supersessions_and_conflicts", "recompute_decision_staleness"}),
+ )
+ install_decision_chain(rec)
+
+ touched = await store_decisions(
+ object(),
+ "repo-1",
+ [{"title": "t"}],
+ vector_store=_STORE,
+ git_metadata=[{"file_path": "src/a.py"}],
+ )
+
+ assert touched == ["decision-1"]
+ assert rec.order == [
+ "bulk_upsert_decisions",
+ "detect_supersessions_and_conflicts",
+ "recompute_decision_staleness",
+ ]