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: 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.md
index 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.py
index 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_mode
resolved_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_only
else 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.py
index 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_head
if result.kg_state:
state["knowledge_graph"] = result.kg_state
diff --git a/tests/unit/cli/test_issue_847_fix.py b/tests/unit/cli/test_docs_pointer.py
similarity index 96%
rename from tests/unit/cli/test_issue_847_fix.py
rename to tests/unit/cli/test_docs_pointer.py
index 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 HEAD
without regenerating pages. Because ``repowise update --docs`` used
@@ -6,13 +6,8 @@ without regenerating pages. Because ``repowise update --docs`` used
and 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.py
new file mode 100644
index 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"