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(cli): stage the fast-to-full upgrade (#4069)

Raghav Chamadiya0c5955644abc
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index dcf0e9412..9aa1ba393 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -251,30 +251,9 @@ async def _run_upgrade(
checkpoint: Any | None = None,
) -> tuple[list[Any], int, dict[str, Any]]:
"""Drive the full upgrade and return the generated pages."""
- from repowise.cli.helpers import get_db_url_for_repo
- from repowise.core.generation.cost_tracker import CostTracker
- from repowise.core.persistence import (
- create_engine,
- create_session_factory,
- get_session,
- init_db,
- upsert_repository,
- )
from repowise.core.pipeline import rehydrate_graph_builder
- url = get_db_url_for_repo(repo_path)
- engine = create_engine(url)
- await init_db(engine)
- sf = create_session_factory(engine)
-
- # 1. Repo row FIRST — this is the fix for the deferred CLI job_store
- # wiring: pipeline_jobs.repository_id is an FK to repositories.id, so the
- # row must exist before the backfill creates its checkpoint job.
- async with get_session(sf) as session:
- repo = await upsert_repository(
- session, name=repo_path.name, local_path=str(repo_path), stamp_head=True
- )
- repo_id = repo.id
+ engine, sf, repo_id = await _open_repository(repo_path)
# 2. Backfill the git tier ESSENTIAL -> FULL (resumable via JobStore).
git_meta_map, history_coverage = await _backfill_git(
@@ -288,6 +267,8 @@ async def _run_upgrade(
checkpoint("git_backfill", git_history_coverage=history_coverage)
# 3. Rehydrate the graph from SQL — no parse, no resolution, no recompute.
+ from repowise.core.persistence import get_session
+
async with get_session(sf) as session:
graph_builder = await rehydrate_graph_builder(session, repo_id, repo_path)
@@ -301,30 +282,137 @@ async def _run_upgrade(
"(graph reused from index — not re-resolved)."
)
- # Show the bill before running it. `init` gates its generation phase and
- # this one did not, which mattered little while `--full` only ever followed
- # an explicit `--mode fast`, and matters now that it is the advertised way
- # to turn a template wiki into a written one: the user reaching for it has
- # never been shown a cost for this repo.
+ # Show the bill before running it, as init does: the user reaching for
+ # `--full` has never been shown a cost for this repo.
_gate_cost(parsed_files, graph_builder, config, provider, repo_path, yes=yes)
- # 5. Generate the docs the fast index skipped. Honor the cost-tracking
- # opt-out (issue #326) so REPOWISE_NO_COST_TRACKING is respected here too;
- # an in-memory tracker still powers the live cost readout.
+ # 5. Generate the docs the fast index skipped, embedding as we go.
+ cost_tracker = _upgrade_cost_tracker(sf, repo_id)
+ provider._cost_tracker = cost_tracker
+ embedder, vector_store, embedding_error = _upgrade_embedding(repo_path, embedder_name)
+ generation_scope: dict[str, int | None] = {}
+ generated_pages = await _generate_upgrade_pages(
+ repo_path,
+ provider,
+ config,
+ inputs=(parsed_files, source_map, graph_builder, repo_structure, git_meta_map),
+ embedder=embedder,
+ vector_store=vector_store,
+ cost_tracker=cost_tracker,
+ generation_scope=generation_scope,
+ )
+ stub_fallbacks, stub_reasons = _stub_fallback_summary(generated_pages)
+ if checkpoint:
+ checkpoint("generation")
+
+ # Flush buffered cost rows now generation is done (best-effort).
+ await cost_tracker.flush()
+
+ # 6. Persist pages + a GenerationJob marker, then build the FTS index.
+ retired_page_ids = await _persist_upgrade_pages(
+ sf, repo_id, generated_pages, vector_store, stub_fallbacks
+ )
+ try:
+ await _sync_authoritative_fts(
+ engine=engine,
+ repo_path=repo_path,
+ generated_pages=generated_pages,
+ retired_page_ids=retired_page_ids,
+ )
+ except BaseException:
+ await engine.dispose()
+ raise
+ if checkpoint:
+ checkpoint("search")
+
+ # 7. Recompute + persist code health against the now-FULL git tier.
+ await _recompute_full_tier_health(
+ engine, sf, repo_id, repo_path, graph_builder, git_meta_map, parsed_files
+ )
+ if checkpoint:
+ checkpoint("health")
+
+ total_pages = await _repository_page_count(sf, repo_id, fallback=len(generated_pages))
+
+ await engine.dispose()
+ from repowise.core.generation.selection import count_documentable_files
+
+ return (
+ generated_pages,
+ total_pages,
+ {
+ "git_history_coverage": history_coverage,
+ "file_pages": {
+ "configured_cap": getattr(config, "max_file_pages", None),
+ **(
+ generation_scope
+ or file_page_scope(
+ configured_cap=getattr(config, "max_file_pages", None),
+ eligible=count_documentable_files(parsed_files),
+ generated_pages=generated_pages,
+ )
+ ),
+ },
+ "search": {
+ "full_text": "available",
+ "semantic": "available" if vector_store is not None else "unavailable",
+ "next_command": "repowise reindex" if vector_store is None else None,
+ },
+ "embedding_error": embedding_error,
+ "stub_fallbacks": stub_fallbacks,
+ "stub_reasons": stub_reasons,
+ },
+ )
+
+
+async def _open_repository(repo_path: Path) -> tuple[Any, Any, Any]:
+ """Open the repo DB and upsert its repository row; returns engine, factory, id.
+
+ The row comes FIRST: pipeline_jobs.repository_id is an FK to repositories.id,
+ so it must exist before the backfill creates its checkpoint job.
+ """
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_repository,
+ )
+
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ async with get_session(sf) as session:
+ repo = await upsert_repository(
+ session, name=repo_path.name, local_path=str(repo_path), stamp_head=True
+ )
+ repo_id = repo.id
+ return engine, sf, repo_id
+
+
+def _upgrade_cost_tracker(sf: Any, repo_id: Any) -> Any:
+ """A cost tracker honoring the cost-tracking opt-out.
+
+ An in-memory tracker still powers the live cost readout. ``buffered=True``
+ defers cost INSERTs to one post-generation flush so they never contend with
+ the generation writer.
+ """
from repowise.cli.providers import cost_tracking_disabled
+ from repowise.core.generation.cost_tracker import CostTracker
if cost_tracking_disabled():
- cost_tracker = CostTracker()
- else:
- # buffered=True defers cost INSERTs to a single post-generation flush so
- # they never contend with the generation writer (issue #326).
- cost_tracker = CostTracker(session_factory=sf, repo_id=repo_id, buffered=True)
- provider._cost_tracker = cost_tracker
+ return CostTracker()
+ return CostTracker(session_factory=sf, repo_id=repo_id, buffered=True)
- # Embed as we generate. Leaving this None meant the upgrade produced a
- # fully written wiki that semantic search could not see, and the user had
- # no reason to suspect it: nothing in the output mentions embedding. The
- # store is the same LanceDB directory `init` and `update` write to.
+
+def _upgrade_embedding(repo_path: Path, embedder_name: str | None) -> tuple[Any, Any, str | None]:
+ """The embedder and vector store pages are embedded into as they are generated.
+
+ The store is the same LanceDB directory `init` and `update` write to; without
+ it the written wiki would be invisible to semantic search.
+ """
from repowise.cli.providers import build_embedder, build_vector_store, resolve_embedder
embedder = None
@@ -336,14 +424,27 @@ async def _run_upgrade(
except Exception as exc:
embedding_error = str(exc)
console.print(f"[yellow]Embedding skipped: {exc}[/yellow]")
+ return embedder, vector_store, embedding_error
+
- # Generate with init's persistence wrapper: pages are written to the DB the
- # instant each one completes (so a Ctrl-C loses at most the in-flight page,
- # not the whole run), prior pages are reused from the store, and the
- # progress bar the user expected to see actually advances. The old path
- # passed ``progress=None`` and buffered every page in memory until the end —
- # hour eight of a long run showed a dead screen and an interrupt cost the
- # entire run (issue #1709).
+async def _generate_upgrade_pages(
+ repo_path: Path,
+ provider: Any,
+ config: Any,
+ *,
+ inputs: tuple[Any, Any, Any, Any, Any],
+ embedder: Any,
+ vector_store: Any,
+ cost_tracker: Any,
+ generation_scope: dict[str, int | None],
+) -> list[Any]:
+ """Generate through init's persistence wrapper under a live progress bar.
+
+ Pages are written the instant each completes (a Ctrl-C loses at most the
+ in-flight page), prior pages are reused from the store, and the bar advances.
+ ``inputs`` is (parsed_files, source_map, graph_builder, repo_structure,
+ git_meta_map).
+ """
from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
from repowise.cli.commands.init_cmd._generation_persist import (
@@ -357,6 +458,7 @@ async def _run_upgrade(
RichProgressCallback,
)
+ parsed_files, source_map, graph_builder, repo_structure, git_meta_map = inputs
with Progress(
SpinnerColumn(spinner_name=OWL_SPINNER, style=BRAND_STYLE),
TextColumn("[progress.description]{task.description}"),
@@ -367,8 +469,7 @@ async def _run_upgrade(
console=console,
) as upgrade_progress:
gen_callback = RichProgressCallback(upgrade_progress, console)
- generation_scope: dict[str, int | None] = {}
- generated_pages = await run_generation_with_persistence(
+ return await run_generation_with_persistence(
repo_path=repo_path,
repo_name=repo_path.name,
parsed_files=parsed_files,
@@ -385,33 +486,40 @@ async def _run_upgrade(
generation_config=config,
selection_out=generation_scope,
)
+
+
+def _stub_fallback_summary(generated_pages: list[Any]) -> tuple[int, list[str]]:
+ """Placeholders the model failed to fill, and why.
+
+ `repowise generate` refills them; failing the run would discard every page
+ that succeeded.
+ """
from repowise.core.generation.models import (
STUB_FALLBACK_ERROR,
count_stub_fallbacks,
is_stub_fallback,
)
- # A page the model failed keeps its placeholder, which `repowise generate`
- # refills. Failing the run over it would discard every page that succeeded.
stub_fallbacks = count_stub_fallbacks(generated_pages)
stub_reasons = sorted(
{str(p.metadata.get(STUB_FALLBACK_ERROR, "")).strip() for p in generated_pages if is_stub_fallback(p)}
- {""}
)
- if checkpoint:
- checkpoint("generation")
+ return stub_fallbacks, stub_reasons
- # Flush buffered cost rows now generation is done (best-effort).
- await cost_tracker.flush()
- # 6. Persist pages + a GenerationJob marker, then build the FTS index.
+async def _persist_upgrade_pages(
+ sf: Any, repo_id: Any, generated_pages: list[Any], vector_store: Any, stub_fallbacks: int
+) -> list[str]:
+ """Persist pages, place them in the tree and record the job; returns retired ids.
+
+ A successful full generation is authoritative for every generated page
+ type, so rows absent from its selection are retired even when their file
+ still exists; otherwise doctor keeps reporting them stale.
+ """
+ from repowise.core.persistence import get_session
+
async with get_session(sf) as session:
- # A successful full generation is authoritative for every generated
- # page type. Retire rows that are absent from its selection even when
- # their backing file still exists (for example, a once-nontrivial file
- # that no longer qualifies for a file page). Without this sweep,
- # `update --full` can report success while doctor keeps reporting those
- # old rows stale forever.
retired_page_ids = await _persist_authoritative_pages(
session=session,
repository_id=repo_id,
@@ -423,8 +531,7 @@ async def _run_upgrade(
await rebuild_page_tree(session, repo_id)
except Exception:
- # Placement is navigation, not content. An upgrade that produced
- # pages should not fail because they could not be ordered.
+ # Placement is navigation, not content: never fail the upgrade on it.
pass
try:
from datetime import UTC, datetime
@@ -432,8 +539,7 @@ async def _run_upgrade(
from repowise.core.persistence.crud import upsert_generation_job
now = datetime.now(UTC)
- # See init_cmd/persistence.py: a stub the provider failure put up
- # has a row but no prose, so it is not a completed page.
+ # A stub has a row but no prose, so it is not a completed page.
job = await upsert_generation_job(
session,
repository_id=repo_id,
@@ -447,27 +553,25 @@ async def _run_upgrade(
job.finished_at = now
except Exception:
pass # job recording is best-effort
+ return retired_page_ids
- try:
- await _sync_authoritative_fts(
- engine=engine,
- repo_path=repo_path,
- generated_pages=generated_pages,
- retired_page_ids=retired_page_ids,
- )
- except BaseException:
- await engine.dispose()
- raise
- if checkpoint:
- checkpoint("search")
- # 7. Recompute + persist code health against the now-FULL git tier.
- # The fast index persisted ESSENTIAL-tier findings only, so the blame /
- # co-change biomarkers (function_hotspot, code_age_volatility,
- # hidden_coupling) were no-ops. Now that the backfill has promoted the git
- # tier and rehydrated the graph, re-run the full-repo health pass so those
- # biomarkers land — otherwise the upgrade leaves the health tables frozen
- # at the fast index's ESSENTIAL state. Mirrors what `init` / `update` do.
+async def _recompute_full_tier_health(
+ engine: Any,
+ sf: Any,
+ repo_id: Any,
+ repo_path: Path,
+ graph_builder: Any,
+ git_meta_map: Any,
+ parsed_files: list[Any],
+) -> None:
+ """Re-run health at the FULL git tier, or dispose the engine and raise.
+
+ The fast index persisted ESSENTIAL-tier findings only, so the blame and
+ co-change biomarkers were no-ops at that tier. Mirrors `init` / `update`.
+ """
+ from repowise.core.persistence import get_session
+
try:
from repowise.core.analysis.health.trends import snapshot_fields
from repowise.core.persistence.crud import (
@@ -512,13 +616,16 @@ async def _run_upgrade(
if health_report is None:
await engine.dispose()
raise RuntimeError("FULL-tier health recompute returned no report")
- if checkpoint:
- checkpoint("health")
- # The repo's real page count, not this run's. An upgrade regenerates rather
- # than appends, and it does not necessarily cover every page the repo
- # already had, so `len(generated_pages)` under-reports the wiki that
- # `repowise status` then displays.
+
+async def _repository_page_count(sf: Any, repo_id: Any, *, fallback: int) -> int:
+ """The repo's real page count, not this run's.
+
+ An upgrade regenerates rather than appends and need not cover every page the
+ repo had, so this run's count would under-report what `status` shows.
+ """
+ from repowise.core.persistence import get_session
+
try:
from sqlalchemy import func as sa_func
from sqlalchemy import select as sa_select
@@ -526,7 +633,7 @@ async def _run_upgrade(
from repowise.core.persistence.models import Page
async with get_session(sf) as session:
- total_pages = int(
+ return int(
(
await session.execute(
sa_select(sa_func.count())
@@ -536,37 +643,7 @@ async def _run_upgrade(
).scalar_one()
)
except Exception:
- total_pages = len(generated_pages)
-
- await engine.dispose()
- from repowise.core.generation.selection import count_documentable_files
-
- return (
- generated_pages,
- total_pages,
- {
- "git_history_coverage": history_coverage,
- "file_pages": {
- "configured_cap": getattr(config, "max_file_pages", None),
- **(
- generation_scope
- or file_page_scope(
- configured_cap=getattr(config, "max_file_pages", None),
- eligible=count_documentable_files(parsed_files),
- generated_pages=generated_pages,
- )
- ),
- },
- "search": {
- "full_text": "available",
- "semantic": "available" if vector_store is not None else "unavailable",
- "next_command": "repowise reindex" if vector_store is None else None,
- },
- "embedding_error": embedding_error,
- "stub_fallbacks": stub_fallbacks,
- "stub_reasons": stub_reasons,
- },
- )
+ return fallback
def _report_placeholders(count: int, reasons: list[str]) -> None:
@@ -581,6 +658,22 @@ def _report_placeholders(count: int, reasons: list[str]) -> None:
)
+#: The resumable stages of a full upgrade, in run order.
+_UPGRADE_STAGES = ["git_backfill", "generation", "search", "health"]
+
+
+def _completed_stages(state: dict[str, Any]) -> list[str]:
+ return list(
+ state.get("full_upgrade", {}).get("completed_stages", [])
+ if isinstance(state.get("full_upgrade"), dict)
+ else []
+ )
+
+
+def _next_stage(stages: list[str]) -> str:
+ return next((item for item in _UPGRADE_STAGES if item not in stages), "finalize")
+
+
def upgrade_to_full(
repo_path: Path,
*,
@@ -643,28 +736,11 @@ def upgrade_to_full(
f"Provider: [cyan]{provider.provider_name}[/cyan] / "
f"[cyan]{provider.model_name}[/cyan]. This generates docs for the whole repo."
)
+ embedder_name = _upgrade_embedder_name(cfg)
- # An index-only repo records the mock embedder, because that mode promises
- # no spend and a hosted embedder is a real bill. That promise is void here:
- # the user is already paying a model. Keeping the mock would leave the
- # upgrade with a fully written wiki that semantic search cannot read, which
- # is the failure this whole path exists to end. So re-resolve, and record
- # the answer so later updates stay on it.
- embedder_name = cfg.get("embedder")
- if not embedder_name or embedder_name == "mock":
- from repowise.cli.providers import resolve_embedder
-
- resolved = resolve_embedder(None)
- if resolved != (embedder_name or "mock"):
- console.print(f"Embedder: [cyan]{resolved}[/cyan] (was mock, index-only's default).")
- embedder_name = resolved
-
- # A full upgrade is the same class of state/DB writer as an incremental
- # update, so it must sit under the same single-flight lock: without it, a
- # concurrent `repowise update` could race this run's save_state (the exact
- # race the lock exists to prevent). If another update holds the lock, the
- # full upgrade defers the same way update_cmd does — the running update
- # will roll forward to HEAD.
+ # The same single-flight lock as an incremental update: a concurrent
+ # `repowise update` must not race this run's save_state. If another update
+ # holds it, defer the same way; that update rolls forward to HEAD.
existing_lock = try_acquire_update_lock(repo_path, head)
if existing_lock is not None:
from repowise.cli.helpers import write_update_pending
@@ -675,73 +751,17 @@ def upgrade_to_full(
"The full upgrade is deferred; it will run on the next pass."
)
- # We own the lock from here on; release it when this function returns
- # (success, cost-gate Abort, or unexpected failure) rather than at process
- # exit — atexit would leave the lock held for the rest of the CLI process.
+ # Released when this function returns (success, cost-gate Abort or failure),
+ # not at process exit.
try:
- completed_stages = list(
- state.get("full_upgrade", {}).get("completed_stages", [])
- if isinstance(state.get("full_upgrade"), dict)
- else []
- )
-
- def _checkpoint(stage: str, **fields: Any) -> None:
- current = load_state(repo_path)
- stages = list(
- current.get("full_upgrade", {}).get("completed_stages", [])
- if isinstance(current.get("full_upgrade"), dict)
- else []
- )
- if stage not in stages:
- stages.append(stage)
- order = ["git_backfill", "generation", "search", "health"]
- next_stage = next((item for item in order if item not in stages), "finalize")
- current["full_upgrade"] = {
- "status": "running",
- "retryable": True,
- "completed_stages": stages,
- "next_stage": next_stage,
- "provider": provider.provider_name,
- "model": provider.model_name,
- "embedder": embedder_name,
- }
- if fields.get("git_history_coverage") is not None:
- current["git_history_coverage"] = fields["git_history_coverage"]
- stamp_index_scope(current, cfg, upgrade=current["full_upgrade"])
- save_state(repo_path, current)
-
- # Durable before any backfill or model work. A killed process therefore
- # leaves an honest resumable transition while the prior index_scope
- # continues to describe the usable index.
- state["full_upgrade"] = {
- "status": "running",
- "retryable": True,
- "completed_stages": completed_stages,
- "next_stage": next(
- (
- item
- for item in ["git_backfill", "generation", "search", "health"]
- if item not in completed_stages
- ),
- "finalize",
- ),
- "provider": provider.provider_name,
+ provider_block = {
+ "name": provider.provider_name,
"model": provider.model_name,
"embedder": embedder_name,
+ "reused": provider_reused,
+ "model_cost_possible": True,
}
- stamp_index_scope(
- state,
- cfg,
- upgrade=state["full_upgrade"],
- provider={
- "name": provider.provider_name,
- "model": provider.model_name,
- "embedder": embedder_name,
- "reused": provider_reused,
- "model_cost_possible": True,
- },
- )
- save_state(repo_path, state)
+ _start_transition(repo_path, state, cfg, provider, embedder_name, provider_block)
try:
upgrade_result = run_async(
_run_upgrade(
@@ -753,134 +773,222 @@ def upgrade_to_full(
follow_renames=follow_renames,
embedder_name=embedder_name,
yes=yes,
- checkpoint=_checkpoint,
+ checkpoint=_upgrade_checkpoint(repo_path, cfg, provider, embedder_name),
)
)
- if len(upgrade_result) == 2: # compatibility for third-party/test wrappers
- generated_pages, total_pages = upgrade_result
- outcome = {
- "git_history_coverage": None,
- "file_pages": {
- "configured_cap": resolve_max_file_pages(config=cfg),
- "effective_cap": None,
- "eligible": None,
- "generated": None,
- "omitted": None,
- },
- "search": {
- "full_text": "unknown",
- "semantic": "unknown",
- "next_command": None,
- },
- "embedding_error": None,
- }
- else:
- generated_pages, total_pages, outcome = upgrade_result
+ generated_pages, total_pages, outcome = _unpack_upgrade_result(upgrade_result, cfg)
except click.Abort:
- # Declined at the cost gate. The git backfill that ran before it is
- # kept (it costs nothing to keep and everything to redo), and the
- # persisted docs mode is left alone so the repo keeps whatever wiki it
- # already had.
- current = load_state(repo_path)
- transition = current.get("full_upgrade", {})
- transition.update(status="resumable", retryable=True)
- current["full_upgrade"] = transition
- stamp_index_scope(current, cfg, upgrade=transition)
- save_state(repo_path, current)
+ # Declined at the cost gate. The git backfill is kept (free to keep,
+ # costly to redo) and the docs mode is left alone, so the repo keeps
+ # whatever wiki it already had.
+ _mark_transition(repo_path, cfg, status="resumable", retryable=True)
console.print("[yellow]Nothing generated.[/yellow] The prior index remains usable.")
return
except BaseException as exc:
- current = load_state(repo_path)
- transition = current.get("full_upgrade", {})
- transition.update(
+ _mark_transition(
+ repo_path,
+ cfg,
status="resumable"
if isinstance(exc, (KeyboardInterrupt, SystemExit))
else "failed",
retryable=True,
error=type(exc).__name__,
)
- current["full_upgrade"] = transition
- stamp_index_scope(current, cfg, upgrade=transition)
- save_state(repo_path, current)
raise
- # Flip persisted state to full so subsequent `repowise update` runs the
- # normal incremental LLM path rather than offering upgrade.
- state["last_sync_commit"] = head
- state.update(docs_mode_state_fields("llm"))
- state["git_tier"] = "full"
- state["run_mode"] = "standard"
- if outcome["git_history_coverage"] is not None:
- state["git_history_coverage"] = outcome["git_history_coverage"]
- state["total_pages"] = total_pages
- # Record who wrote the pages. Without this, `repowise status` on a repo
- # upgraded this way reports its provider and model as unknown, which reads
- # as "nothing wrote this wiki" right after a run that did.
- state["provider"] = provider.provider_name
- state["model"] = provider.model_name
- # `update --full` regenerates the whole wiki (concept tree included), so it
- # brings the store to the terminal store format the same way a full init
- # does. Stamp it as such rather than clamping at the reindex gate.
- #
- # This is also the run that answers the missing-slot notice: it evaluates
- # 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
- # The git backfill walked every file under the current history rules.
- state[GIT_HISTORY_VERSION_KEY] = GIT_HISTORY_VERSION
- state["full_upgrade"] = {
- "status": "complete",
- "retryable": False,
- "completed_stages": ["git_backfill", "generation", "search", "health", "finalize"],
- "next_stage": None,
- }
- stamp_index_scope(
+ _finish_upgrade_state(
state,
cfg,
- run_mode="standard",
- content_provenance="model",
- git_tier="full",
- git_commit_cap=(
- commit_limit if isinstance(commit_limit, int) else _DEFAULT_COMMIT_LIMIT
- ),
- git_history_coverage=outcome["git_history_coverage"],
- file_pages=outcome["file_pages"],
- analysis={"unavailable": [], "skipped": []},
- upgrade=state["full_upgrade"],
- provider={
- "name": provider.provider_name,
- "model": provider.model_name,
- "embedder": embedder_name,
- "reused": provider_reused,
- "model_cost_possible": True,
- },
- search=outcome["search"],
+ head=head,
+ provider=provider,
+ config=config,
+ commit_limit=commit_limit,
+ total_pages=total_pages,
+ outcome=outcome,
+ provider_block=provider_block,
)
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
- # Explicit `embedding_model=None`, not a bare `embedder=`: the
- # embedder just changed, so any model pinned for the old one no
- # longer describes what this table was built with, and
- # `save_config_partial` only clears the pin when told the model
- # changed, not merely because `embedder` was passed (#2627).
+ # `embedding_model=None` clears a model pinned for the old embedder;
+ # passing `embedder` alone does not.
save_config_partial(repo_path, embedder=embedder_name, embedding_model=None)
- elapsed = time.monotonic() - start
- console.print(
- f"[bold green]Upgrade complete[/bold green] in {elapsed:.1f}s — "
- f"{len(generated_pages)} pages generated, git tier now FULL."
- )
- _report_placeholders(outcome.get("stub_fallbacks", 0), outcome.get("stub_reasons", []))
- if outcome["search"]["semantic"] != "available":
- console.print(
- "[yellow]Semantic search is unavailable.[/yellow] Set an embedder key and run "
- "[bold]repowise reindex[/bold] (embedding calls only; no model calls)."
- )
+ _report_upgrade(time.monotonic() - start, generated_pages, outcome)
finally:
release_update_lock(repo_path)
+
+
+def _upgrade_embedder_name(cfg: dict[str, Any]) -> str | None:
+ """The embedder to write with: re-resolved when the index recorded the mock.
+
+ Index-only promises no spend, so it records the mock embedder. The user is
+ paying a model here, and the mock would leave the written wiki invisible to
+ semantic search, so re-resolve; the answer is recorded for later updates.
+ """
+ embedder_name = cfg.get("embedder")
+ if not embedder_name or embedder_name == "mock":
+ from repowise.cli.providers import resolve_embedder
+
+ resolved = resolve_embedder(None)
+ if resolved != (embedder_name or "mock"):
+ console.print(f"Embedder: [cyan]{resolved}[/cyan] (was mock, index-only's default).")
+ embedder_name = resolved
+ return embedder_name
+
+
+def _start_transition(
+ repo_path: Path,
+ state: dict[str, Any],
+ cfg: dict[str, Any],
+ provider: Any,
+ embedder_name: str | None,
+ provider_block: dict[str, Any],
+) -> None:
+ """Record the running transition before any backfill or model work.
+
+ A killed process then leaves an honest resumable transition while the prior
+ index_scope keeps describing the usable index.
+ """
+ completed_stages = _completed_stages(state)
+ state["full_upgrade"] = {
+ "status": "running",
+ "retryable": True,
+ "completed_stages": completed_stages,
+ "next_stage": _next_stage(completed_stages),
+ "provider": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name,
+ }
+ stamp_index_scope(state, cfg, upgrade=state["full_upgrade"], provider=dict(provider_block))
+ save_state(repo_path, state)
+
+
+def _upgrade_checkpoint(
+ repo_path: Path, cfg: dict[str, Any], provider: Any, embedder_name: str | None
+) -> Any:
+ """A callback that records each completed stage in state.json."""
+
+ def _checkpoint(stage: str, **fields: Any) -> None:
+ current = load_state(repo_path)
+ stages = _completed_stages(current)
+ if stage not in stages:
+ stages.append(stage)
+ current["full_upgrade"] = {
+ "status": "running",
+ "retryable": True,
+ "completed_stages": stages,
+ "next_stage": _next_stage(stages),
+ "provider": provider.provider_name,
+ "model": provider.model_name,
+ "embedder": embedder_name,
+ }
+ if fields.get("git_history_coverage") is not None:
+ current["git_history_coverage"] = fields["git_history_coverage"]
+ stamp_index_scope(current, cfg, upgrade=current["full_upgrade"])
+ save_state(repo_path, current)
+
+ return _checkpoint
+
+
+def _mark_transition(repo_path: Path, cfg: dict[str, Any], **updates: Any) -> None:
+ """Update the recorded transition after the upgrade stopped early."""
+ current = load_state(repo_path)
+ transition = current.get("full_upgrade", {})
+ transition.update(**updates)
+ current["full_upgrade"] = transition
+ stamp_index_scope(current, cfg, upgrade=transition)
+ save_state(repo_path, current)
+
+
+def _unpack_upgrade_result(
+ upgrade_result: tuple[Any, ...], cfg: dict[str, Any]
+) -> tuple[list[Any], int, dict[str, Any]]:
+ """Pages, page count and outcome; a 2-tuple from a wrapper gets an unknown outcome."""
+ if len(upgrade_result) != 2:
+ generated_pages, total_pages, outcome = upgrade_result
+ return generated_pages, total_pages, outcome
+ generated_pages, total_pages = upgrade_result
+ outcome = {
+ "git_history_coverage": None,
+ "file_pages": {
+ "configured_cap": resolve_max_file_pages(config=cfg),
+ "effective_cap": None,
+ "eligible": None,
+ "generated": None,
+ "omitted": None,
+ },
+ "search": {
+ "full_text": "unknown",
+ "semantic": "unknown",
+ "next_command": None,
+ },
+ "embedding_error": None,
+ }
+ return generated_pages, total_pages, outcome
+
+
+def _finish_upgrade_state(
+ state: dict[str, Any],
+ cfg: dict[str, Any],
+ *,
+ head: str | None,
+ provider: Any,
+ config: Any,
+ commit_limit: Any,
+ total_pages: int,
+ outcome: dict[str, Any],
+ provider_block: dict[str, Any],
+) -> None:
+ """Flip the persisted state to full, so later updates take the normal LLM path."""
+ state["last_sync_commit"] = head
+ state.update(docs_mode_state_fields("llm"))
+ state["git_tier"] = "full"
+ state["run_mode"] = "standard"
+ if outcome["git_history_coverage"] is not None:
+ state["git_history_coverage"] = outcome["git_history_coverage"]
+ state["total_pages"] = total_pages
+ # Record who wrote the pages, or `status` reports them as unknown.
+ state["provider"] = provider.provider_name
+ state["model"] = provider.model_name
+ # Every onboarding slot was evaluated against whole-repo signals, so the
+ # missing-slot notice has nothing left to report.
+ stamp_offered_slots(state, enabled=config.enable_onboarding)
+ # Health and the git backfill ran over the whole repo under the current
+ # analyzer and history rules, so the next update need not redo them.
+ state["health_analyzer_version"] = HEALTH_ANALYZER_VERSION
+ state[GIT_HISTORY_VERSION_KEY] = GIT_HISTORY_VERSION
+ state["full_upgrade"] = {
+ "status": "complete",
+ "retryable": False,
+ "completed_stages": [*_UPGRADE_STAGES, "finalize"],
+ "next_stage": None,
+ }
+ stamp_index_scope(
+ state,
+ cfg,
+ run_mode="standard",
+ content_provenance="model",
+ git_tier="full",
+ git_commit_cap=(commit_limit if isinstance(commit_limit, int) else _DEFAULT_COMMIT_LIMIT),
+ git_history_coverage=outcome["git_history_coverage"],
+ file_pages=outcome["file_pages"],
+ analysis={"unavailable": [], "skipped": []},
+ upgrade=state["full_upgrade"],
+ provider=dict(provider_block),
+ search=outcome["search"],
+ )
+
+
+def _report_upgrade(elapsed: float, generated_pages: list[Any], outcome: dict[str, Any]) -> None:
+ console.print(
+ f"[bold green]Upgrade complete[/bold green] in {elapsed:.1f}s — "
+ f"{len(generated_pages)} pages generated, git tier now FULL."
+ )
+ _report_placeholders(outcome.get("stub_fallbacks", 0), outcome.get("stub_reasons", []))
+ if outcome["search"]["semantic"] != "available":
+ console.print(
+ "[yellow]Semantic search is unavailable.[/yellow] Set an embedder key and run "
+ "[bold]repowise reindex[/bold] (embedding calls only; no model calls)."
+ )
diff --git a/tests/unit/cli/test_full_upgrade_progress.py b/tests/unit/cli/test_full_upgrade_progress.py
index 902eb4cef..aeb246dd3 100644
--- a/tests/unit/cli/test_full_upgrade_progress.py
+++ b/tests/unit/cli/test_full_upgrade_progress.py
@@ -26,7 +26,14 @@ from repowise.core.pipeline.cleanup_debt import load_cleanup_debt
def _upgrade_source() -> str:
- return inspect.getsource(upgrade_flow._run_upgrade)
+ return "".join(
+ inspect.getsource(fn)
+ for fn in (
+ upgrade_flow._run_upgrade,
+ upgrade_flow._generate_upgrade_pages,
+ upgrade_flow._persist_upgrade_pages,
+ )
+ )
def test_full_upgrade_uses_the_persistence_wrapper() -> None: