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(update): stop a config change advancing the sync pointer past commits it never indexed (#1360)

Raghav Chamadiya71e719487bc5
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index abdbae4e2..241420c89 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -68,6 +68,7 @@ from repowise.cli.ui import (
quick_repo_scan,
should_offer_fast_mode,
)
+from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from repowise.core.docs_mode import docs_mode_state_fields, resolve_docs_mode
from repowise.core.generation.languages import SUPPORTED_LANGUAGES
from repowise.core.generation.styles import DEFAULT_STYLE, list_styles, resolve_style
@@ -1553,6 +1554,10 @@ def init_command(
)
# Fingerprint after config writes so the first update doesn't false-positive.
base_state["config_fingerprint"] = config_fingerprint(repo_path)
+ # Index-only is the keyless default, so this is where most installs get
+ # their stamp. Without it `health_analyzer_changed` reads absent-as-
+ # unchanged and the version trigger never fires for them.
+ base_state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
# Index-only still renders the full concept tree (deterministically, from
# templates), so the store has the current capability — stamp the terminal
# version rather than clamping it below the reindex gate and falsely
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
index 151c051de..5022ebe5e 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -25,6 +25,7 @@ from repowise.cli.helpers import (
stamp_offered_slots,
)
from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_json
+from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from repowise.core.docs_mode import docs_mode_state_fields
from repowise.core.generation.models import count_stub_fallbacks
@@ -389,4 +390,8 @@ def save_full_state_and_config(
# Re-save state with the fingerprint now that config.yaml is written.
state["config_fingerprint"] = config_fingerprint(repo_path)
+ # This index's health rows were written by the current analyzer, so start
+ # tracking it here — otherwise a fresh install carries no stamp and the
+ # first analyzer change after it cannot tell it needs a re-score.
+ state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
save_state(repo_path, state, full_index=True)
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index d9204267e..18b1a6e28 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -985,6 +985,17 @@ def run_update(
# Full re-score (not the partial update) so unchanged files pick up the
# new rules/excludes instead of being left stale.
console.print("[yellow]Config files changed — re-running health analysis.[/yellow]")
+
+ # A config change with commits still to index must NOT stop here. The
+ # standalone re-score below advances ``last_sync_commit`` to head, and in
+ # index-only mode ``base_ref`` *is* ``last_sync_commit`` — so returning
+ # early would move the pointer past commits this run never indexed, losing
+ # their churn / ownership / co-change / page state until a manual --full.
+ # (Docs mode limped on because ``last_docs_commit`` stayed put.) With
+ # changed files present we fall through to the normal incremental path and
+ # force the full re-score at its existing hook, which reuses the graph that
+ # path already builds — same re-score, no second traverse.
+ if config_changed and not file_diffs:
if dry_run:
console.print("[yellow]Dry run — health would be re-scored. No changes made.[/yellow]")
if emitter is not None:
@@ -1006,6 +1017,11 @@ def run_update(
if emitter is not None:
emitter.error(str(exc))
raise
+ # No stamp_head_commit here, which is the behaviour this branch has
+ # always had: the re-score's `upsert_repository` re-reads HEAD from
+ # disk and advances the row itself. It re-reads rather than being told,
+ # so it is a no-op in a linked worktree or a non-git checkout — both
+ # pre-existing, and neither is what this change is about.
_refresh_editor_stamp(repo_path, agents_md)
consume_update_pending(repo_path, head)
if emitter is not None:
@@ -1204,6 +1220,7 @@ def run_update(
git_decay_map=git_decay_map,
exclude_patterns=exclude_patterns,
head_ts=head_ts,
+ force_full_rescore=config_changed,
)
except Exception as exc:
if emitter is not None:
@@ -1693,12 +1710,25 @@ def run_update(
# DB, so re-score every file's findings against the decayed inputs. Reuses
# the already-built graph (no second rebuild); gated to ~weekly. Stamped into
# ``state`` below via the final save_state.
+ from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+
from .persistence import full_rescore_due, run_decay_health_rescore
- if full_rescore_due(state, head_ts) and run_decay_health_rescore(
+ # ``config_changed`` forces the same re-score off this path's graph rather
+ # than letting the config branch above run a standalone one and return: a
+ # config edit invalidates every persisted score, and the partial health
+ # update only reaches the changed files. Reusing this hook is what makes
+ # falling through cost nothing extra — the graph is already built.
+ if (config_changed or full_rescore_due(state, head_ts)) and run_decay_health_rescore(
repo_path, graph_builder, parsed_files, exclude_patterns
):
- state["last_full_rescore_at"] = head_ts
+ # Only the time gate reads this stamp, and it treats a non-numeric
+ # value as "never re-scored". A forced re-score with git unavailable
+ # has no timestamp to record, so leave a real stamp alone rather than
+ # writing None over it.
+ if head_ts is not None:
+ state["last_full_rescore_at"] = head_ts
+ state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
# ---- Editor project files (best-effort) ----
_refresh_editor_stamp(repo_path, agents_md, degraded)
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
index 42a027333..492e5b43d 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -17,6 +17,7 @@ from typing import Any
import structlog
from repowise.cli.helpers import console, run_async, save_state
+from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from .incremental import _build_repo_graph
@@ -195,10 +196,16 @@ def _persist_index_only_update(
git_decay_map: dict | None = None,
exclude_patterns: list[str] | None = None,
head_ts: float | None = None,
+ force_full_rescore: bool = False,
) -> None:
"""Persist the index-only update (graph + symbols + git + dead-code + health + KG),
save state, and print the completion line. No LLM regeneration.
+ ``force_full_rescore`` runs the full health re-score regardless of the
+ periodic gate. Set by the config-changed caller, which relies on this path
+ rather than re-scoring separately and returning — doing that advanced
+ ``last_sync_commit`` past commits it never indexed.
+
DB persistence delegates to :mod:`repowise.core.pipeline.incremental`;
state-file updates and console reporting stay here. Best-effort steps
that fail land in ``degraded`` and surface in the completion panel.
@@ -229,16 +236,26 @@ def _persist_index_only_update(
# Periodic idle-file health re-score (#728): git_metadata is now fresh in the
# DB, so re-score every file's findings against the decayed inputs. Gated to
# ~weekly since only the findings (not their cheap git inputs) lag here.
+ # ``force_full_rescore`` is the config-changed caller: a config edit
+ # invalidates every persisted score, and the partial health update above
+ # only reached the changed files.
last_full_rescore_at = state.get("last_full_rescore_at")
- if full_rescore_due(state, head_ts) and run_decay_health_rescore(
+ health_analyzer_version = state.get("health_analyzer_version")
+ if (force_full_rescore or full_rescore_due(state, head_ts)) and run_decay_health_rescore(
repo_path, graph_builder, parsed_files or [], exclude_patterns or []
):
- last_full_rescore_at = head_ts
+ # Only the time gate reads this, and it treats a non-numeric value as
+ # "never re-scored", so leave a real stamp alone rather than writing
+ # None over it when git gave us no timestamp.
+ if head_ts is not None:
+ last_full_rescore_at = head_ts
+ health_analyzer_version = HEALTH_ANALYZER_VERSION
new_state = {
**state,
"last_sync_commit": head,
"last_full_rescore_at": last_full_rescore_at,
+ "health_analyzer_version": health_analyzer_version,
"config_fingerprint": config_fingerprint(repo_path),
# Record the renderer this run rendered with. Without this an index-only
# update that regenerated stale file pages leaves the stored fingerprint
@@ -1025,7 +1042,13 @@ def _run_full_health_rescore(
save_state(
repo_path,
- {**state, "last_sync_commit": head, "config_fingerprint": curr_fingerprint},
+ {
+ **state,
+ "last_sync_commit": head,
+ "config_fingerprint": curr_fingerprint,
+ # These rows were just rewritten by this analyzer.
+ "health_analyzer_version": HEALTH_ANALYZER_VERSION,
+ },
)
elapsed = time.monotonic() - start
console.print(f"[green]Config-triggered health re-score complete[/green] in {elapsed:.1f}s")
@@ -1050,12 +1073,37 @@ def _full_rescore_interval_days() -> float:
return _FULL_RESCORE_INTERVAL_DAYS
+def health_analyzer_changed(state: dict) -> bool:
+ """Whether the stored health rows were written by a different analyzer.
+
+ A legacy state file with no stamp is **not** a change: the rows it wrote
+ are no more suspect than any other pre-upgrade rows, and treating absence
+ as drift would re-score every existing install once on upgrade for no
+ stated defect. They pick the stamp up on their first re-score from any
+ other trigger.
+ """
+ stored = state.get("health_analyzer_version")
+ return stored is not None and stored != HEALTH_ANALYZER_VERSION
+
+
def full_rescore_due(state: dict, head_ts: float | None) -> bool:
- """Whether a periodic idle-file health re-score is due this update (#728).
+ """Whether a full health re-score is due this update.
- Absent ``head_ts`` (git unavailable) → not due. Absent stamp (never
- re-scored, or legacy state) → due, to establish the recovered baseline.
+ Two independent triggers:
+
+ * the analyzer changed since these rows were written — re-score now, so a
+ correction lands on the next update rather than waiting out the timer;
+ * the periodic idle-file cadence (#728).
+
+ The version check is deliberately ahead of the ``head_ts`` guard: an
+ analyzer change invalidates the rows whether or not git is readable.
+
+ Absent ``head_ts`` (git unavailable) → the time gate cannot fire. Absent
+ time stamp (never re-scored, or legacy state) → due, to establish the
+ recovered baseline.
"""
+ if health_analyzer_changed(state):
+ return True
if head_ts is None:
return False
last = state.get("last_full_rescore_at")
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index e0bedd672..544f2c051 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -44,6 +44,7 @@ from repowise.cli.helpers import (
save_state,
stamp_offered_slots,
)
+from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
from repowise.core.docs_mode import docs_mode_state_fields
@@ -517,6 +518,10 @@ def upgrade_to_full(
# every registered onboarding slot against whole-repo signals, so after it
# there is nothing left for the notice to report.
stamp_offered_slots(state, enabled=config.enable_onboarding)
+ # This run re-ran health analysis over the whole repo, so its rows come
+ # from the current analyzer. Without the stamp the next plain `update`
+ # would read a stale version and pay a redundant full re-score.
+ state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
save_state(repo_path, state, full_index=True)
if embedder_name and embedder_name != cfg.get("embedder"):
from repowise.cli.helpers import save_config_partial
diff --git a/packages/core/src/repowise/core/analysis/health/__init__.py b/packages/core/src/repowise/core/analysis/health/__init__.py
index e1ab4ae63..1bdb2b4db 100644
--- a/packages/core/src/repowise/core/analysis/health/__init__.py
+++ b/packages/core/src/repowise/core/analysis/health/__init__.py
@@ -7,7 +7,7 @@ tests).
from __future__ import annotations
-from .engine import HealthAnalyzer
+from .engine import HEALTH_ANALYZER_VERSION, HealthAnalyzer
from .models import (
HealthFileMetricData,
HealthFindingData,
@@ -16,6 +16,7 @@ from .models import (
)
__all__ = [
+ "HEALTH_ANALYZER_VERSION",
"HealthAnalyzer",
"HealthFileMetricData",
"HealthFindingData",
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 7ec4baa23..64a295bf6 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -57,6 +57,28 @@ from .scoring import attach_impacts, compute_kpis, remap_severities, score_file
log = structlog.get_logger(__name__)
+# Bump when a change to this analyzer makes already-persisted health rows wrong
+# — a new or removed biomarker, a changed attribution rule, a different finding
+# shape. ``repowise update`` compares it against the value stored in state.json
+# and re-scores on mismatch (see ``update_cmd.persistence.full_rescore_due``),
+# instead of waiting out the 7-day decay timer.
+#
+# Reach, stated honestly: the gate is only consulted once an update reaches the
+# incremental path, so this lands on the next update that has changed files. A
+# repo with no new commits returns at the "already up to date" branch and picks
+# the correction up on its next commit; workspace members and the hosted
+# indexer do not run this path at all. That is the same reach the decay timer
+# already has — this extends that trigger rather than adding a wider one.
+#
+# Deliberately *not* folded into ``config_fingerprint``: that fingerprint means
+# "this repo's config content changed", and a workspace update answers drift in
+# it by full-re-indexing every member repo. An analyzer change invalidates the
+# scores, not the parse or the git index, so it routes to the re-score alone.
+#
+# Not a licence to move a calibrated scoring weight — those are frozen
+# independently of this stamp.
+HEALTH_ANALYZER_VERSION = 1
+
# 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.
_EXTRACT_METHOD_SOURCES = frozenset({"large_method", "brain_method", "complex_method"})
diff --git a/tests/integration/test_cli.py b/tests/integration/test_cli.py
index 483e4a83f..841935eb0 100644
--- a/tests/integration/test_cli.py
+++ b/tests/integration/test_cli.py
@@ -408,11 +408,45 @@ class TestUpdateConfigChangeDetection:
# Fingerprint must NOT advance, so a real update still re-scores later.
assert self._state(git_work_repo)["config_fingerprint"] == fp_before
- def test_config_change_with_source_diffs_runs_full_rescore(self, runner, git_work_repo):
- """A config change must take the full re-score path even when there are
- also source-file commits (not the partial update)."""
+ # The no-diffs half of the branch — which keeps its early return — is
+ # already covered by test_init_stores_fingerprint_and_update_detects_config_change
+ # above, which asserts exactly the same three things.
+
+ @pytest.mark.parametrize("mode", ["index-only", "docs"])
+ def test_config_change_with_source_diffs_still_indexes_the_commits(
+ self, runner, git_work_repo, mode
+ ):
+ """A config change must never advance the sync pointer past commits it
+ did not index.
+
+ The config branch used to re-score health and return early, skipping the
+ graph rebuild, git re-index, dead-code and page regeneration — and then
+ ``_run_full_health_rescore`` saved ``last_sync_commit=head`` anyway. In
+ index-only mode ``base_ref`` *is* ``last_sync_commit``, so the very next
+ update saw ``base_ref == head``, said "Already up to date", and the
+ commit's files stayed out of the index until a manual ``--full``.
+
+ Parameterized because the two modes lose different amounts: index-only
+ loses the commits permanently, while docs mode self-heals on the next
+ update via its separate ``last_docs_commit`` pointer — but skips the git
+ re-index on the run itself either way, which is what this asserts.
+ """
+ import json
+
+ # Docs mode regenerates pages, so it needs a provider; ``mock`` is the
+ # registered test one and keeps this a CLI test, not a provider test.
+ args = ["--index-only"] if mode == "index-only" else ["--docs", "--provider", "mock"]
runner.invoke(cli, ["init", str(git_work_repo), "--index-only"], catch_exceptions=False)
+ # Switch the *periodic* re-score gate off. `init` writes no
+ # ``last_full_rescore_at``, so without this the #728 time gate is due on
+ # the very first update and fires the full re-score on its own — which
+ # would let this test pass even with the config-forced re-score deleted.
+ state_file = git_work_repo / ".repowise" / "state.json"
+ seeded = json.loads(state_file.read_text(encoding="utf-8"))
+ seeded["last_full_rescore_at"] = 9e18 # far future: never "due"
+ state_file.write_text(json.dumps(seeded), encoding="utf-8")
+
# New source commit AND a config change in the same update window.
(git_work_repo / "new_module.py").write_text("def f():\n return 1\n", encoding="utf-8")
_git(["add", "-A"], git_work_repo)
@@ -421,12 +455,31 @@ class TestUpdateConfigChangeDetection:
'{"disabled_biomarkers": ["ungoverned_hotspot"]}', encoding="utf-8"
)
- result = runner.invoke(
- cli, ["update", str(git_work_repo), "--index-only"], catch_exceptions=False
- )
+ result = runner.invoke(cli, ["update", str(git_work_repo), *args], catch_exceptions=False)
assert result.exit_code == 0, result.output
assert "Config files changed" in result.output
- assert "health re-score complete" in result.output.lower()
+ # The re-score still happens — it just runs off the graph the
+ # incremental path already built instead of a second traverse. With the
+ # time gate seeded off above, this line can only come from the
+ # config-forced re-score, so it pins that the force is wired to the
+ # path this mode actually takes (they are different code).
+ assert "Health re-score:" in result.output
+
+ # git_metadata is the decisive table: the standalone re-score rebuilds
+ # and persists the graph itself, so graph_nodes / health_file_metrics
+ # carry the new file either way and prove nothing. Only the git
+ # re-index — churn, ownership, co-change — is genuinely skipped by the
+ # early return, and it is 0 rows there.
+ db = git_work_repo / ".repowise" / "wiki.db"
+ assert (
+ _db_scalar(db, "SELECT COUNT(*) FROM git_metadata WHERE file_path = 'new_module.py'")
+ == 1
+ ), "the config branch returned before the git re-index reached the commit's files"
+
+ # And nothing is left pending: a second update has no work to find.
+ r2 = runner.invoke(cli, ["update", str(git_work_repo), *args], catch_exceptions=False)
+ assert r2.exit_code == 0, r2.output
+ assert "Already up to date" in r2.output
class TestUpdatePreservesDeadCode:
diff --git a/tests/unit/cli/test_health_rescore_gate.py b/tests/unit/cli/test_health_rescore_gate.py
new file mode 100644
index 000000000..49645e970
--- /dev/null
+++ b/tests/unit/cli/test_health_rescore_gate.py
@@ -0,0 +1,74 @@
+"""The gate that decides when `repowise update` re-scores health in full.
+
+Two independent triggers: the analyzer version moving, and the periodic #728
+time cadence. These pin the interaction between them, because the version
+trigger deliberately sits *ahead* of the time gate's ``head_ts`` guard.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.cli.commands.update_cmd.persistence import (
+ full_rescore_due,
+ health_analyzer_changed,
+)
+from repowise.core.analysis.health import HEALTH_ANALYZER_VERSION
+
+
+class TestHealthAnalyzerChanged:
+ def test_absent_stamp_is_not_a_change(self):
+ """A legacy state file must not read as drift.
+
+ Treating absence as a change would re-score every existing install
+ once on upgrade, for no stated defect in its rows.
+ """
+ assert health_analyzer_changed({}) is False
+
+ def test_matching_stamp_is_not_a_change(self):
+ assert (
+ health_analyzer_changed({"health_analyzer_version": HEALTH_ANALYZER_VERSION}) is False
+ )
+
+ @pytest.mark.parametrize("stored", [HEALTH_ANALYZER_VERSION - 1, HEALTH_ANALYZER_VERSION + 1])
+ def test_any_different_stamp_is_a_change(self, stored):
+ """Not `<`: a downgrade also leaves rows this analyzer did not write."""
+ assert health_analyzer_changed({"health_analyzer_version": stored}) is True
+
+
+class TestFullRescoreDue:
+ def test_analyzer_change_fires_without_git(self):
+ """The version trigger must clear the ``head_ts`` guard.
+
+ An analyzer change invalidates the stored rows whether or not git is
+ readable, so `head_ts=None` — which switches the *time* gate off — must
+ not switch this one off with it.
+ """
+ state = {"health_analyzer_version": HEALTH_ANALYZER_VERSION - 1}
+ assert full_rescore_due(state, None) is True
+
+ def test_analyzer_change_fires_inside_the_time_window(self):
+ """A fresh time stamp would say "not due"; the version still forces it."""
+ head_ts = 1_000_000.0
+ state = {
+ "last_full_rescore_at": head_ts, # re-scored this very instant
+ "health_analyzer_version": HEALTH_ANALYZER_VERSION - 1,
+ }
+ assert full_rescore_due(state, head_ts) is True
+ # Same state, current analyzer: the time gate governs and says no.
+ current = {**state, "health_analyzer_version": HEALTH_ANALYZER_VERSION}
+ assert full_rescore_due(current, head_ts) is False
+
+ def test_time_gate_still_governs_when_the_analyzer_is_current(self):
+ head_ts = 1_000_000.0
+ state = {
+ "last_full_rescore_at": head_ts - (8 * 86400.0),
+ "health_analyzer_version": HEALTH_ANALYZER_VERSION,
+ }
+ assert full_rescore_due(state, head_ts) is True
+
+ def test_no_git_and_current_analyzer_is_not_due(self):
+ """Guards the ordering: the version check returning False must fall
+ through to the ``head_ts`` guard rather than short-circuiting True."""
+ state = {"health_analyzer_version": HEALTH_ANALYZER_VERSION}
+ assert full_rescore_due(state, None) is False