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
fix: preserve last_docs_commit pointer during index-only updates (Fixes #873) (#878)
Jyotirmya Sharma751dec7b01b7
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.mdindex b66b52a42..0f9ac18df 100644--- a/docs/CLI_REFERENCE.md+++ b/docs/CLI_REFERENCE.md@@ -161,7 +161,7 @@ See [WORKTREES.md](WORKTREES.md).| `--no-workspace` | Force single-repo mode (handy when running from a workspace root) || `--repo` | Update a specific workspace repo by alias || `--index-only` | Refresh the index only, skip doc regeneration for this run |-| `--docs` / `--no-docs` | Regenerate wiki pages for changed files, or skip doc regeneration entirely |+| `--docs` / `--no-docs` | Regenerate wiki pages for changed files, or skip doc regeneration entirely. Not supported in workspace mode yet: with `--workspace` the flag is ignored (with a warning) and you should run docs per repo, e.g. `repowise update --docs --no-workspace` from inside the repo. || `--full` | Upgrade a fast (`--mode fast`) index to a full one, see below. Single-repo only; errors in workspace mode. || `--no-cost-tracking` | Don't record LLM spend for this run || `--agents` / `--no-agents` | Generate or skip managed `AGENTS.md` after update. Persists the preference. |diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.pyindex 626c410e7..a21c89853 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py@@ -376,6 +376,11 @@ def run_update("--full is single-repo only. Run it inside a specific repo ""(or pass --no-workspace / --repo <alias>).")+ if docs_flag:+ console.print(+ "[yellow]--docs is not supported in workspace mode yet; run it per repo, "+ "e.g. repowise update --docs --no-workspace from inside the repo.[/yellow]"+ )try:_workspace_update(target, dry_run=dry_run, agents_md=agents_md, verbose=verbose)except Exception as exc:@@ -457,12 +462,12 @@ def run_update(load_dotenv(repo_path)state = load_state(repo_path)- from repowise.cli.commands.update_cmd.mode import _resolve_index_only_moderesolved_index_only = _resolve_index_only_mode(index_only=index_only, docs_flag=docs_flag, state=state)base_ref = since or (- state.get("last_sync_commit") if resolved_index_only+ state.get("last_sync_commit")+ if resolved_index_onlyelse state.get("last_docs_commit", state.get("last_sync_commit")))head = get_head_commit(repo_path)@@ -617,10 +622,14 @@ def run_update(if not file_diffs and not config_changed:console.print("[green]No changed files detected.[/green]")- save_state(- repo_path,- {**state, "last_sync_commit": head, "config_fingerprint": curr_config_fp},- )+ # Always advance the sync pointer so the on-disk freshness marker stays+ # current on no-op syncs. In docs mode, no changed files means no docs+ # work is pending, so the docs pointer can advance to head too, which+ # also heals legacy state that never recorded one.+ persisted = {**state, "last_sync_commit": head, "config_fingerprint": curr_config_fp}+ if not resolved_index_only and head:+ persisted["last_docs_commit"] = head+ save_state(repo_path, persisted)# Keep the DB freshness stamp in lockstep with state.json: the server's# /repos endpoint reads head_commit from the row, not the state file.stamp_head_commit(repo_path, head)diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.pyindex 483f2fbe6..5d34d8c56 100644--- a/packages/core/src/repowise/core/workspace/update.py+++ b/packages/core/src/repowise/core/workspace/update.py@@ -674,6 +674,10 @@ async def update_workspace(if state_path.is_file():with suppress(Exception):state = _json.loads(state_path.read_text(encoding="utf-8"))++ if "last_docs_commit" not in state and "last_sync_commit" in state:+ state["last_docs_commit"] = state["last_sync_commit"]+state["last_sync_commit"] = new_headif result.kg_state:state["knowledge_graph"] = result.kg_statediff --git a/tests/unit/cli/test_issue_847_fix.py b/tests/unit/cli/test_docs_pointer.pysimilarity index 96%rename from tests/unit/cli/test_issue_847_fix.pyrename to tests/unit/cli/test_docs_pointer.pyindex 46c7de9fc..e8fce9889 100644--- a/tests/unit/cli/test_issue_847_fix.py+++ b/tests/unit/cli/test_docs_pointer.py@@ -1,4 +1,4 @@-"""Verification suite for issue #847.+"""Single-repo docs-pointer separation (issue #847).Bug: index-only ``repowise update`` advances ``last_sync_commit`` to HEADwithout regenerating pages. Because ``repowise update --docs`` used@@ -6,13 +6,8 @@ without regenerating pages. Because ``repowise update --docs`` usedand silently regenerated nothing ("No changed files detected", exit 0),leaving stale prose permanently unreachable.-Drop this file into tests/unit/cli/ in your fork (matches the conventions-of tests/unit/cli/test_update_e2e.py) and run:-- pytest tests/unit/cli/test_issue_847_fix.py -v--It does NOT try to guess your exact implementation. It only asserts the-externally-observable behavior the issue and its suggested fix require:+These assert the externally-observable behavior the fix requires (the+workspace-side counterpart lives in test_workspace_docs_pointer.py):1. An index-only update must never advance the docs pointer.2. A run that actually generates pages must advance the docs pointer.diff --git a/tests/unit/cli/test_workspace_docs_pointer.py b/tests/unit/cli/test_workspace_docs_pointer.pynew file mode 100644index 000000000..9312f79bc--- /dev/null+++ b/tests/unit/cli/test_workspace_docs_pointer.py@@ -0,0 +1,192 @@+"""Docs-pointer preservation across workspace and index-only updates (issue #873).++Bug: workspace and index-only updates advanced ``last_sync_commit`` without+backfilling ``last_docs_commit``. Because ``repowise update --docs`` diffs from+``last_docs_commit``, a later docs run saw an empty diff and no-oped while the+wiki prose was actually stale.+"""++from __future__ import annotations++import json+import os+import subprocess+from pathlib import Path++from click.testing import CliRunner++from repowise.cli.helpers import load_state, save_state+from repowise.cli.main import cli+from repowise.core.workspace.config import RepoEntry, WorkspaceConfig++DOCS_POINTER_KEY = "last_docs_commit"+SYNC_POINTER_KEY = "last_sync_commit"+++def _git(repo: Path, *args: str) -> str:+ result = subprocess.run(["git", *args], cwd=str(repo), capture_output=True, text=True)+ return result.stdout.strip()+++def _make_git_repo(tmp_path: Path) -> Path:+ repo = tmp_path / "repo"+ repo.mkdir(parents=True)+ _git(repo, "init")+ _git(repo, "config", "user.email", "[email protected]")+ _git(repo, "config", "user.name", "Test")+ (repo / "a.py").write_text("def alpha():\n return 1\n")+ (repo / "b.py").write_text("from a import alpha\n\n\ndef beta():\n return alpha() + 1\n")+ _git(repo, "add", ".")+ _git(repo, "commit", "-m", "initial")+ return repo+++def _index_full(repo: Path) -> None:+ import asyncio++ from repowise.core.pipeline.full_index import index_repo_full++ asyncio.run(index_repo_full(repo))+++def _state(repo: Path) -> dict:+ return json.loads((repo / ".repowise" / "state.json").read_text(encoding="utf-8"))+++def _commit_change(repo: Path, filename: str, content: str, message: str) -> str:+ (repo / filename).write_text(content)+ _git(repo, "add", ".")+ _git(repo, "commit", "-m", message)+ return _git(repo, "rev-parse", "HEAD")+++def _make_workspace(tmp_path: Path) -> Path:+ ws_root = tmp_path / "workspace"+ ws_root.mkdir()+ repo = _make_git_repo(ws_root)+ WorkspaceConfig(+ version=1,+ repos=[RepoEntry(alias="my-repo", path="repo")],+ ).save(ws_root)+ return repo+++def test_workspace_update_backfills_docs_pointer(tmp_path: Path) -> None:+ """A workspace update on a legacy state.json must backfill the docs pointer."""+ repo = _make_workspace(tmp_path)++ _index_full(repo)+ c0 = _git(repo, "rev-parse", "HEAD")++ # Simulate a state.json written before last_docs_commit existed.+ save_state(repo, {SYNC_POINTER_KEY: c0, "docs_enabled": True})+ assert DOCS_POINTER_KEY not in load_state(repo)++ c1 = _commit_change(repo, "c.py", "def gamma():\n return 3\n", "add c.py")++ old_cwd = os.getcwd()+ try:+ os.chdir(str(repo))+ result = CliRunner().invoke(cli, ["update", "--workspace"])+ finally:+ os.chdir(old_cwd)+ assert result.exit_code == 0, result.output++ state = _state(repo)+ assert state[SYNC_POINTER_KEY] == c1, "sync pointer should advance to new commit"+ assert state.get(DOCS_POINTER_KEY) == c0, (+ "workspace update must backfill docs pointer from the old sync pointer"+ )+++def test_stale_prose_is_reachable_after_workspace_update(tmp_path: Path) -> None:+ """Docs generated at C0, a workspace update walks last_sync_commit forward, then+ new source lands. The next --docs run must diff from C0, not the advanced pointer.+ """+ repo = _make_workspace(tmp_path)++ _index_full(repo)+ c0 = _git(repo, "rev-parse", "HEAD")+ save_state(repo, {SYNC_POINTER_KEY: c0, "docs_enabled": True})++ c1 = _commit_change(repo, "c.py", "def gamma():\n return 3\n", "add c.py")+ old_cwd = os.getcwd()+ try:+ os.chdir(str(repo))+ result = CliRunner().invoke(cli, ["update", "--workspace"])+ finally:+ os.chdir(old_cwd)+ assert result.exit_code == 0, result.output+ assert _state(repo)[SYNC_POINTER_KEY] == c1+ assert _state(repo)[DOCS_POINTER_KEY] == c0++ # A second source change that must still be picked up by the next docs run.+ c2 = _commit_change(repo, "d.py", "def delta():\n return 4\n", "add d.py")++ from repowise.cli.commands.update_cmd.command import clear_update_queued, release_update_lock++ release_update_lock(repo)+ clear_update_queued(repo)++ result = CliRunner().invoke(+ cli, ["update", str(repo), "--docs", "--provider", "mock", "--no-workspace"]+ )+ assert result.exit_code == 0, result.output+ assert "No changed files detected" not in result.output, (+ "docs run used the workspace-advanced pointer as its diff base and saw an empty diff"+ )++ state = _state(repo)+ assert state.get(DOCS_POINTER_KEY) == c2, "docs pointer should now reach HEAD"+++def test_docs_early_exit_advances_docs_pointer(tmp_path: Path) -> None:+ """When a docs run finds no changed files, it must advance the docs pointer to+ HEAD (and, on legacy state, the sync pointer as well). An empty commit advances+ HEAD without touching any file, so the docs run diffs an empty set and takes the+ no-changed-files early exit.+ """+ repo = _make_git_repo(tmp_path)+ _index_full(repo)+ c0 = _git(repo, "rev-parse", "HEAD")++ # Legacy state: no docs pointer recorded yet.+ save_state(repo, {SYNC_POINTER_KEY: c0, "docs_enabled": True})++ _git(repo, "commit", "--allow-empty", "-m", "empty")+ c1 = _git(repo, "rev-parse", "HEAD")++ result = CliRunner().invoke(+ cli, ["update", str(repo), "--docs", "--provider", "mock", "--no-workspace"]+ )+ assert result.exit_code == 0, result.output+ assert "No changed files detected" in result.output, "expected an early exit"++ state = _state(repo)+ assert state.get(SYNC_POINTER_KEY) == c1, "sync pointer should advance to HEAD"+ assert state.get(DOCS_POINTER_KEY) == c1, "docs pointer should advance to HEAD on early exit"+++def test_index_only_early_exit_advances_sync_pointer(tmp_path: Path) -> None:+ """An index-only run that finds no changed files must still advance+ last_sync_commit to HEAD (keep the freshness marker current on no-op syncs)+ and must leave the docs pointer untouched. Guards against the early-exit+ regressing into a state.json <-> DB head_commit split.+ """+ repo = _make_git_repo(tmp_path)+ _index_full(repo)+ c0 = _git(repo, "rev-parse", "HEAD")++ # docs disabled -> a plain `update` resolves to index-only mode.+ save_state(repo, {SYNC_POINTER_KEY: c0, DOCS_POINTER_KEY: c0, "docs_enabled": False})++ _git(repo, "commit", "--allow-empty", "-m", "empty")+ c1 = _git(repo, "rev-parse", "HEAD")++ result = CliRunner().invoke(cli, ["update", str(repo), "--no-workspace"])+ assert result.exit_code == 0, result.output+ assert "No changed files detected" in result.output, "expected an early exit"++ state = _state(repo)+ assert state.get(SYNC_POINTER_KEY) == c1, "index-only early exit must advance the sync pointer"+ assert state.get(DOCS_POINTER_KEY) == c0, "index-only run must not advance the docs pointer"