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): re-render a wiki written before the renderer stamp (#3557)

Raghav Chamadiyadf3854ebd336
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 554982d7d..4a3f297c7 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -1938,6 +1938,12 @@ def init_command(
# Same reasoning for the security scanner (#3072): this run just
# scanned every file, so start tracking its version here too.
base_state["security_scanner_version"] = SECURITY_SCANNER_VERSION
+ # The pages were just rendered by this release's structural renderer.
+ # Unstamped, the first update would read the index as pre-stamp and
+ # re-render the whole wiki it had only just written.
+ from repowise.cli.commands.update_cmd.command import _current_renderer_fingerprint
+
+ base_state["renderer_fingerprint"] = _current_renderer_fingerprint(repo_path)
# This run just scored every file, so the periodic re-score cadence
# starts now. Without the stamp the gate reads "never re-scored" and the
# very next update re-scores the whole repo init had only just scored.
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 cf5d04d4d..2c7722370 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -536,6 +536,12 @@ def save_full_state_and_config(
# Same reasoning for the security scanner (#3072): this run just scanned
# every file, so start tracking its version here too.
state["security_scanner_version"] = SECURITY_SCANNER_VERSION
+ # The pages were just rendered by this release's structural renderer.
+ # Unstamped, the first update would read the index as pre-stamp and
+ # re-render the whole wiki it had only just written.
+ from repowise.cli.commands.update_cmd.command import _current_renderer_fingerprint
+
+ state["renderer_fingerprint"] = _current_renderer_fingerprint(repo_path)
# This run just scored every file, so the periodic re-score cadence starts
# now. Without the stamp the gate reads "never re-scored" and the very next
# update re-scores the whole repo that init had only just finished scoring.
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 5d24ee432..0c0aa66d1 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -1043,9 +1043,23 @@ def run_update(
# full reparse below happens and the per-page staleness sweep can pick up
# exactly the pages the old renderer wrote. Distinct from config_changed,
# which routes to a health re-score rather than to page regeneration.
+ #
+ # A missing stamp is a change: ``init`` stamps every index it builds, so an
+ # unstamped one was written by a release older than the stamp, whose pages
+ # quote that release's graph. Reading absence as current stamped it on the
+ # spot and left the whole wiki a release behind. An empty current value
+ # (the fingerprint failed) still disables the gate, and an index with no
+ # wiki has no page a renderer could have written.
prev_renderer_fp = state.get("renderer_fingerprint")
curr_renderer_fp = _current_renderer_fingerprint(repo_path)
- renderer_changed = prev_renderer_fp is not None and prev_renderer_fp != curr_renderer_fp
+ # A model wiki on an index-only run waits for its next full update, which
+ # is the run that can re-render it.
+ renderer_changed = (
+ bool(curr_renderer_fp)
+ and prev_renderer_fp != curr_renderer_fp
+ and resolve_docs_mode(state) != "none"
+ and not (resolved_index_only and resolve_docs_mode(state) == "llm")
+ )
# Uncommitted work, when the caller asked for it. Computed before the
# "already up to date" gate below, because on a watched repo that gate is
@@ -1107,6 +1121,11 @@ def run_update(
if analyzer_changed
else "[yellow]Parser changed since this index was built; re-parsing.[/yellow]"
)
+ if renderer_changed:
+ console.print(
+ "[yellow]Wiki renderer changed since these pages were written; "
+ "re-rendering structural pages once, no model needed.[/yellow]"
+ )
if history_stale:
console.print(
"[yellow]Git history rules changed since this index was built; "
@@ -1577,7 +1596,8 @@ def run_update(
include_submodules=bool(state.get("include_submodules", False)),
include_nested_repos=bool(state.get("include_nested_repos", False)),
idle_decay_sink=None if working_tree_only else git_decay_map,
- force_full_git=git_config_changed or history_stale,
+ # A full re-render quotes every file's history, as init does.
+ force_full_git=git_config_changed or history_stale or renderer_changed,
git_summary_sink=full_git_summaries,
timings=timings,
)
@@ -1631,11 +1651,28 @@ def run_update(
stale_extra = list(dict.fromkeys([*stale_renderer_paths, *stale_db_paths]))
if stale_extra:
affected.regenerate = list(dict.fromkeys([*affected.regenerate, *stale_extra]))
- if generation_config_changed:
+ if generation_config_changed or renderer_changed:
# Generation settings affect selection and repo-wide synthesis, not
# merely the files touched by this commit. Recreate the same complete
- # page set a clean init would choose.
+ # page set a clean init would choose. A renderer change does the same
+ # for the structural pages: every one quotes the graph an older release
+ # built, and a file that release did not index has no page at all.
affected.regenerate = [pf.file_info.path for pf in parsed_files]
+ if renderer_changed and not generation_config_changed and not index_only:
+ # A model wiki: the generator below re-renders the file-scoped pages
+ # (all structural) and stops before the model-written levels. Those are
+ # only marked stale, through the same ``none`` cascade a budget overflow
+ # uses, so the rewrite stays the opt-in `generate --stale` it always is.
+ from .deterministic import load_cascade_overflow_split
+
+ affected.decay_only = list(dict.fromkeys([*affected.decay_only, *affected.regenerate]))
+ split = load_cascade_overflow_split(repo_path, affected.regenerate)
+ if split and split[0]:
+ console.print(
+ f" {split[0]} model-written pages are marked stale: run "
+ "[cyan]repowise generate --stale[/cyan] to rewrite them "
+ "(it estimates the cost first)."
+ )
if affected.stale_due_to_budget > 0:
from .deterministic import load_cascade_overflow_split
@@ -1665,6 +1702,14 @@ def run_update(
)
return UpdateOutcome.DRY_RUN
+ # Pages re-rendered for files this run did not change need the complexity
+ # the last full health run measured, which only the store still holds.
+ from .deterministic import hydrate_symbol_complexity
+
+ hydrate_symbol_complexity(
+ repo_path, parsed_files, set(affected.regenerate) - {fd.path for fd in file_diffs}
+ )
+
# ``git_meta_map`` holds this run's changed files only; the dead-code
# analyzer scores confidence per file and would read every unchanged file
# as "no commits" without the stored rows. The stored function-mod p80
@@ -1739,6 +1784,15 @@ def run_update(
"Configuration-driven knowledge-graph refresh failed; the previous "
"fingerprint was retained so the next update retries."
) from exc
+ elif renderer_changed and knowledge_graph_result is not None:
+ # Same reason for a full re-render: a file's layer comes from the KG,
+ # and a file the old one never saw would render with none.
+ from repowise.cli.state_persistence import save_knowledge_graph_json
+
+ try:
+ save_knowledge_graph_json(repo_path, knowledge_graph_result)
+ except Exception as exc:
+ degraded.append(f"Knowledge-graph publish before render: {exc}")
if index_only:
# A repo whose wiki was rendered from templates keeps it current here.
@@ -1750,6 +1804,11 @@ def run_update(
render_stats: dict[str, int] = {}
index_only_cost = 0.0
docs_mode = resolve_docs_mode(state)
+ # False when a renderer-driven full render failed: pages outside its
+ # set must not be retired then, and the old stamp stays so the next run
+ # retries. A model wiki renders nothing here, so it keeps its stamp for
+ # the full update that will.
+ renderer_render_ok = docs_mode != "llm"
if docs_mode == "deterministic":
from .deterministic import (
load_prior_page_ids,
@@ -1782,10 +1841,12 @@ def run_update(
degraded=degraded,
dead_code_report=dead_code_report,
prior_page_ids=prior_ids,
- full_scope=generation_config_changed,
+ full_scope=generation_config_changed or renderer_changed,
stats_out=render_stats,
)
- if stale_deterministic_ids and not generation_config_changed:
+ if stale_deterministic_ids and not (
+ generation_config_changed or renderer_changed
+ ):
det_pages.extend(
regenerate_deterministic_page_ids(
repo_path=repo_path,
@@ -1803,6 +1864,9 @@ def run_update(
stats_out=render_stats,
)
)
+ renderer_render_ok = not renderer_changed or (
+ bool(det_pages) and len(degraded) == degraded_before_render
+ )
if generation_config_changed and len(degraded) > degraded_before_render:
raise RuntimeError(
"Configuration-driven page generation failed; the previous "
@@ -1906,9 +1970,11 @@ def run_update(
reconcile_full_scope=traversal_config_changed,
full_generation_page_ids=(
{page.page_id for page in det_pages}
- if generation_config_changed and docs_mode == "deterministic"
+ if docs_mode == "deterministic"
+ and (generation_config_changed or (renderer_changed and renderer_render_ok))
else None
),
+ stamp_renderer=renderer_render_ok,
dependency_fingerprints=curr_dependency_fps,
vector_store=config_vector_store,
require_config_rebuild_success=config_rebuild_required,
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
index 00af8a2e2..ad0b3f3ec 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -480,6 +480,57 @@ async def _load_file_page_render_keys(repo_path: Path) -> dict[str, str]:
await engine.dispose()
+def hydrate_symbol_complexity(repo_path: Path, parsed_files: list, paths: set[str]) -> None:
+ """Restore stored ``complexity_estimate`` on the symbols of *paths*.
+
+ A parse leaves every symbol at the default of 1; only health analysis
+ measures it, and an update analyses the changed files alone. Any other
+ file it re-renders would otherwise print 1 on every spotlight. The stored
+ value is what the last full health run measured for code that has not
+ changed since. Best effort: an unreadable store leaves the defaults.
+ """
+ if not paths:
+ return
+ stored = run_async(_load_symbol_complexity(repo_path))
+ if not stored:
+ return
+ for pf in parsed_files:
+ if pf.file_info.path not in paths:
+ continue
+ for sym in pf.symbols:
+ sid = getattr(sym, "id", None) or f"{pf.file_info.path}::{sym.name}"
+ value = stored.get(sid)
+ if value:
+ sym.complexity_estimate = value
+
+
+async def _load_symbol_complexity(repo_path: Path) -> dict[str, int]:
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import create_engine, create_session_factory, get_session
+
+ engine = create_engine(get_db_url_for_repo(repo_path))
+ try:
+ from sqlalchemy import select as sa_select
+
+ from repowise.core.persistence.crud import get_repository_by_path
+ from repowise.core.persistence.models import WikiSymbol
+
+ async with get_session(create_session_factory(engine)) as session:
+ repo = await get_repository_by_path(session, str(repo_path))
+ if repo is None:
+ return {}
+ rows = await session.execute(
+ sa_select(WikiSymbol.symbol_id, WikiSymbol.complexity_estimate).where(
+ WikiSymbol.repository_id == repo.id
+ )
+ )
+ return {sid: int(value or 0) for sid, value in rows}
+ except Exception:
+ return {}
+ finally:
+ await engine.dispose()
+
+
def load_spotlight_render_keys(repo_path: Path) -> dict[str, list[str]]:
"""``defining file path -> render keys`` for the wiki's symbol spotlights.
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 386472b43..2dfa1504d 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -528,6 +528,7 @@ def _persist_index_only_update(
full_git_summary: Any | None = None,
reconcile_full_scope: bool = False,
full_generation_page_ids: set[str] | None = None,
+ stamp_renderer: bool = True,
dependency_fingerprints: dict[str, str] | None = None,
vector_store: Any | None = None,
require_config_rebuild_success: bool = False,
@@ -542,6 +543,9 @@ def _persist_index_only_update(
rather than re-scoring separately and returning — doing that advanced
``last_sync_commit`` past commits it never indexed.
+ ``stamp_renderer`` False keeps the stored renderer fingerprint: the full
+ re-render a renderer change asked for failed, so the next run retries it.
+
``timings`` is the run's phase table. Its ``run`` row is closed here, at
the state write, and the whole table lands in ``state.json`` as
``phase_timings`` the way ``init`` records its own run.
@@ -623,7 +627,11 @@ def _persist_index_only_update(
# update pays a full reparse forever even though nothing is stale. This
# is the keyless hot path (the post-commit hook), so a lingering reparse
# here is exactly the cost the mode exists to avoid.
- "renderer_fingerprint": _current_renderer_fingerprint(repo_path),
+ "renderer_fingerprint": (
+ _current_renderer_fingerprint(repo_path)
+ if stamp_renderer
+ else state.get("renderer_fingerprint")
+ ),
}
_stamp_git_history(new_state, full_git_summary, failed_steps)
# Before save_state, and reading ``state`` (the pre-update dict) for the old
diff --git a/tests/unit/cli/test_update_reconciles_stale_pages.py b/tests/unit/cli/test_update_reconciles_stale_pages.py
index d1d74ea51..c7c6f2a7c 100644
--- a/tests/unit/cli/test_update_reconciles_stale_pages.py
+++ b/tests/unit/cli/test_update_reconciles_stale_pages.py
@@ -104,6 +104,7 @@ def _update(repo: Path) -> str:
def _state_at(repo: Path, head: str) -> None:
+ from repowise.cli.commands.update_cmd.command import _current_renderer_fingerprint
from repowise.cli.helpers import save_state
save_state(
@@ -112,6 +113,8 @@ def _state_at(repo: Path, head: str) -> None:
"last_sync_commit": head,
"last_docs_commit": head,
"docs_mode": "deterministic",
+ # Written by this release, as init stamps it.
+ "renderer_fingerprint": _current_renderer_fingerprint(repo),
**CURRENT_GIT_HISTORY,
},
)
diff --git a/tests/unit/cli/test_update_renderer_upgrade.py b/tests/unit/cli/test_update_renderer_upgrade.py
new file mode 100644
index 000000000..2d69a4920
--- /dev/null
+++ b/tests/unit/cli/test_update_renderer_upgrade.py
@@ -0,0 +1,177 @@
+"""An index with no renderer stamp is a renderer change.
+
+``init`` stamps the renderer it wrote the pages with, so an unstamped index was
+written by an older release: its pages quote that release's graph, and a file
+that release did not index has no page. The first update re-renders every
+structural page from the current graph and gives such a file its page. A model
+wiki's prose pages are only marked stale, for ``generate --stale``, so the
+upgrade never calls a model.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+import pytest
+from sqlalchemy import select
+
+from repowise.cli.commands.update_cmd import command as upd_cmd
+from repowise.cli.commands.update_cmd.command import _current_renderer_fingerprint
+from repowise.core.providers.llm.mock import MockProvider
+
+from .test_update_reconciles_stale_pages import (
+ CURRENT_GIT_HISTORY,
+ _db_url,
+ _repo_at_head,
+ _update,
+)
+
+UP_TO_DATE = "Already up to date"
+OLD_CONTENT = "# written by an older release\n"
+
+
+async def _seed(repo: Path, *, with_overview: bool) -> None:
+ """A page for foo.py only, as an older release left it."""
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_page,
+ upsert_repository,
+ )
+
+ engine = create_engine(_db_url(repo))
+ await init_db(engine)
+ async with get_session(create_session_factory(engine)) as session:
+ row = await upsert_repository(session, name=repo.name, local_path=str(repo))
+ common = {"repository_id": row.id, "summary": "", "source_hash": ""}
+ await upsert_page(
+ session,
+ page_id="file_page:foo.py",
+ page_type="file_page",
+ title="File: foo.py",
+ content=OLD_CONTENT,
+ target_path="foo.py",
+ model_name="template",
+ provider_name="template",
+ **common,
+ )
+ if with_overview:
+ await upsert_page(
+ session,
+ page_id="repo_overview:repo",
+ page_type="repo_overview",
+ title="Overview",
+ content="Prose a model wrote.",
+ target_path="repo",
+ model_name="mock",
+ provider_name="mock",
+ **common,
+ )
+ await session.commit()
+ await engine.dispose()
+
+
+async def _pages(repo: Path) -> dict[str, tuple[str, str]]:
+ from repowise.core.persistence import create_engine, create_session_factory, get_session
+ from repowise.core.persistence.models import Page
+
+ engine = create_engine(_db_url(repo))
+ try:
+ async with get_session(create_session_factory(engine)) as session:
+ rows = await session.execute(select(Page.id, Page.content, Page.freshness_status))
+ return {pid: (content, status) for pid, content, status in rows.all()}
+ finally:
+ await engine.dispose()
+
+
+def _state(repo: Path) -> dict:
+ return json.loads((repo / ".repowise" / "state.json").read_text(encoding="utf-8"))
+
+
+def _add_bar(tmp_path: Path) -> None:
+ import subprocess
+
+ repo = tmp_path / "repo"
+ (repo / "bar.py").write_text(
+ "from foo import foo\n\n\ndef bar():\n return foo() + 1\n", encoding="utf-8"
+ )
+ for args in (["add", "bar.py"], ["commit", "-q", "--amend", "--no-edit"]):
+ subprocess.run(["git", *args], cwd=str(repo), check=True, capture_output=True)
+
+
+def no_model(monkeypatch: pytest.MonkeyPatch) -> MockProvider:
+ monkeypatch.setenv("REPOWISE_SKIP_EDITOR_SETUP", "1")
+ provider = MockProvider()
+ monkeypatch.setattr(upd_cmd, "resolve_provider_or_prompt", lambda *a, **k: provider)
+ return provider
+
+
+def _build(tmp_path: Path, docs_mode: str, *, with_overview: bool = False) -> Path:
+ """An unstamped index at HEAD. bar.py is committed but has no page, the
+ shape #3221's newly indexed directories were left in."""
+ import shutil
+ import subprocess
+
+ from repowise.cli.helpers import save_state
+
+ repo, _ = _repo_at_head(tmp_path)
+ _add_bar(tmp_path)
+ head = subprocess.run(
+ ["git", "rev-parse", "HEAD"], cwd=str(repo), capture_output=True, text=True, check=True
+ ).stdout.strip()
+ shutil.rmtree(repo / ".repowise")
+ (repo / ".repowise").mkdir()
+ asyncio.run(_seed(repo, with_overview=with_overview))
+ save_state(
+ repo,
+ {
+ "last_sync_commit": head,
+ "last_docs_commit": head,
+ "docs_mode": docs_mode,
+ **CURRENT_GIT_HISTORY,
+ },
+ )
+ return repo
+
+
+def test_template_wiki_rerenders_and_pages_a_newly_indexed_file(
+ tmp_path: Path, no_model: MockProvider
+) -> None:
+ repo = _build(tmp_path, "deterministic")
+
+ out = _update(repo)
+
+ assert UP_TO_DATE not in out
+ assert "Wiki renderer changed" in out
+ pages = asyncio.run(_pages(repo))
+ assert pages["file_page:foo.py"][0] != OLD_CONTENT
+ assert "file_page:bar.py" in pages
+ assert _state(repo)["renderer_fingerprint"] == _current_renderer_fingerprint(repo)
+ assert no_model.call_count == 0
+ # Stamped, so the next run is quiet again.
+ assert UP_TO_DATE in _update(repo)
+
+
+def test_model_wiki_marks_prose_stale_without_calling_the_model(
+ tmp_path: Path, no_model: MockProvider, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ repo = _build(tmp_path, "llm", with_overview=True)
+ # Layer naming is keyed on the graph's shape, not on the renderer. This
+ # seeded store has no knowledge graph yet, so pin the shape as unchanged.
+ monkeypatch.setattr(upd_cmd, "_refresh_knowledge_graph", lambda *a, **k: None)
+
+ out = _update(repo)
+
+ assert "Wiki renderer changed" in out
+ assert "repowise generate --stale" in out
+ pages = asyncio.run(_pages(repo))
+ assert pages["file_page:foo.py"][0] != OLD_CONTENT
+ assert pages["file_page:foo.py"][1] == "fresh"
+ assert "file_page:bar.py" in pages
+ assert pages["repo_overview:repo"] == ("Prose a model wrote.", "stale")
+ assert no_model.call_count == 0
diff --git a/tests/unit/cli/test_workspace_autodetect_e2e.py b/tests/unit/cli/test_workspace_autodetect_e2e.py
index 4bc13ec47..87d95f2a6 100644
--- a/tests/unit/cli/test_workspace_autodetect_e2e.py
+++ b/tests/unit/cli/test_workspace_autodetect_e2e.py
@@ -15,6 +15,7 @@ from click.testing import CliRunner
from repowise.cli.commands.status_cmd import status_command
from repowise.cli.commands.update_cmd import update_command
+from repowise.cli.commands.update_cmd.command import _current_renderer_fingerprint
from repowise.core.ingestion.git_indexer import GIT_HISTORY_VERSION, GIT_HISTORY_VERSION_KEY
# An index written by this build: its git rows follow the current rules.
@@ -28,7 +29,14 @@ def _build_workspace(root: Path) -> None:
(frontend / ".git").mkdir(parents=True)
(backend / ".repowise").mkdir()
(backend / ".repowise" / "state.json").write_text(
- json.dumps({"last_sync_commit": "abc123", "docs_enabled": True, **CURRENT_GIT_HISTORY}),
+ json.dumps(
+ {
+ "last_sync_commit": "abc123",
+ "docs_enabled": True,
+ "renderer_fingerprint": _current_renderer_fingerprint(backend),
+ **CURRENT_GIT_HISTORY,
+ }
+ ),
)
(root / ".repowise-workspace.yaml").write_text(
"version: 1\n"
diff --git a/tests/unit/cli/test_workspace_docs_pointer.py b/tests/unit/cli/test_workspace_docs_pointer.py
index 6f5ad8b79..9d1b1c792 100644
--- a/tests/unit/cli/test_workspace_docs_pointer.py
+++ b/tests/unit/cli/test_workspace_docs_pointer.py
@@ -15,6 +15,7 @@ from pathlib import Path
from click.testing import CliRunner
+from repowise.cli.commands.update_cmd.command import _current_renderer_fingerprint
from repowise.cli.helpers import load_state, save_state
from repowise.cli.main import cli
from repowise.core.ingestion.git_indexer import GIT_HISTORY_VERSION, GIT_HISTORY_VERSION_KEY
@@ -238,7 +239,15 @@ def test_docs_early_exit_advances_docs_pointer(tmp_path: Path) -> None:
c0 = _git(repo, "rev-parse", "HEAD")
# Legacy state: no docs pointer recorded yet.
- save_state(repo, {SYNC_POINTER_KEY: c0, "docs_enabled": True, **CURRENT_GIT_HISTORY})
+ save_state(
+ repo,
+ {
+ SYNC_POINTER_KEY: c0,
+ "docs_enabled": True,
+ "renderer_fingerprint": _current_renderer_fingerprint(repo),
+ **CURRENT_GIT_HISTORY,
+ },
+ )
_git(repo, "commit", "--allow-empty", "-m", "empty")
c1 = _git(repo, "rev-parse", "HEAD")