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(cli): keep the index-only wiki honest, current and free (#976)

Raghav Chamadiyab55bc6c08880
diff --git a/docs/reference/TELEMETRY.md b/docs/reference/TELEMETRY.md
index b525b1885..c0e8f7bbe 100644
--- a/docs/reference/TELEMETRY.md
+++ b/docs/reference/TELEMETRY.md
@@ -56,7 +56,7 @@ generation is used. Never exact counts, never repo or file names:
|---|---|---|
| `properties.file_count_bucket` | `500-999` | Repo size distribution (a range, not a count) |
| `properties.top_language` | `python` | Which languages to prioritise |
-| `properties.docs_mode` | `true` / `false` | AI docs vs index-only adoption |
+| `properties.docs_mode` | `none` / `deterministic` / `llm` | How the wiki was produced: not at all, from templates, or by a model. Sent as `true` / `false` by versions before template wikis existed |
| `properties.provider` / `properties.model` | `anthropic` / `claude-opus` | Which models generate docs |
| `properties.embedder` | `openai` | Which embedders are in use |
| `properties.pages_bucket` | `100-499` | Docs volume (a range) |
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 df735ecae..47730c116 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -66,7 +66,7 @@ from repowise.cli.ui import (
quick_repo_scan,
should_offer_fast_mode,
)
-from repowise.core.docs_mode import docs_mode_state_fields
+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
from repowise.core.reasoning import REASONING_MODES
@@ -115,16 +115,20 @@ def _record_init_outcome(
if isinstance(lang_dist, dict) and lang_dist:
outcome["top_language"] = max(lang_dist.items(), key=lambda kv: kv[1])[0]
+ # docs_mode carries the same three values as the state field of that
+ # name. It used to be a bool, which collapsed "template wiki" and "no
+ # wiki" into one number, and template runs are the ones worth counting.
+ pages = getattr(result, "generated_pages", None) or []
+ det = sum(1 for p in pages if getattr(p, "provider_name", "") == "template")
if not effective_index_only and provider is not None:
- outcome["docs_mode"] = True
+ outcome["docs_mode"] = "llm"
outcome["provider"] = getattr(provider, "provider_name", None)
outcome["model"] = getattr(provider, "model_name", None)
- pages = getattr(result, "generated_pages", None) or []
+ else:
+ outcome["docs_mode"] = "deterministic" if pages else "none"
+ if pages:
outcome["pages_bucket"] = telemetry.bucket_count(len(pages))
- det = sum(1 for p in pages if getattr(p, "provider_name", "") == "template")
outcome["deterministic_pages_bucket"] = telemetry.bucket_count(det)
- else:
- outcome["docs_mode"] = False
if embedder_name_resolved:
outcome["embedder"] = embedder_name_resolved
@@ -146,7 +150,7 @@ def _run_deterministic_generation_phase(
embedder_name_resolved: str,
embedder_was_requested: bool,
resume: bool,
-) -> None:
+) -> str:
"""Render the whole wiki from templates, for ``init --index-only``.
Every page type has a deterministic renderer, so an index-only run is no
@@ -154,6 +158,9 @@ def _run_deterministic_generation_phase(
from structure rather than written by a model. There is nothing to
estimate and nothing to gate, since no provider is involved and the run
costs nothing, so this skips the coverage chooser the LLM phase runs.
+
+ Returns the embedder actually used, which the caller persists so a later
+ ``repowise update`` embeds the same way rather than re-deciding.
"""
from repowise.core.generation import GenerationConfig
from repowise.core.providers.llm.template import TemplateProvider
@@ -177,6 +184,21 @@ def _run_deterministic_generation_phase(
"Generation",
"Building wiki pages from the code's structure (no model, no cost)",
)
+ # Both knobs only reach a model. Templates carry their own English prose
+ # and render without the style directive, so saying so beats letting the
+ # user find out from the output (and beats recording a style the pages do
+ # not have, which would leave `restyle` thinking there is nothing to do).
+ if language != "en":
+ console.print(
+ f" [dim]Templates are written in English, so [bold]--language "
+ f"{language}[/bold] has no effect here. Run [bold]repowise update "
+ "--full[/bold] to write the wiki with a model in that language.[/dim]"
+ )
+ if wiki_style != DEFAULT_STYLE:
+ console.print(
+ f" [dim]Wiki styles shape how a model writes, so [bold]--wiki-style "
+ f"{wiki_style}[/bold] has no effect here.[/dim]"
+ )
if embedder != embedder_name_resolved:
console.print(
f" [dim]Not embedding with [bold]{embedder_name_resolved}[/bold]: it was "
@@ -198,10 +220,11 @@ def _run_deterministic_generation_phase(
provider=TemplateProvider(),
gen_config=gen_config,
concurrency=concurrency,
- embedder_name_resolved=embedder_name_resolved,
+ embedder_name_resolved=embedder,
resume=resume,
verbose=True,
)
+ return embedder
def _run_generation_phase(
@@ -843,11 +866,15 @@ def init_command(
exclude = adv["exclude"]
include_submodules = adv.get("include_submodules", include_submodules)
run_mode = adv.get("run_mode", run_mode)
+ # Asked in both branches: an index-only run renders a wiki too,
+ # and those pages embed like any other, so the answer applies
+ # either way. Read outside the docs-only block or the index-only
+ # run would show the user their choice and then ignore it.
+ embedder_name = adv.get("embedder") or embedder_name
# Generation knobs (only gathered when docs are on).
if generate_docs:
concurrency = adv["concurrency"]
reasoning = adv.get("reasoning") or reasoning
- embedder_name = adv.get("embedder") or embedder_name
test_run = adv["test_run"]
tier1_top_n = adv.get("tier1_top_n")
tier2_tail_enabled = adv.get("tier2_tail_enabled", True)
@@ -925,11 +952,39 @@ def init_command(
# resolve_embedder inferring one from an LLM key it found lying around.
# The deterministic generation phase needs the distinction: it advertises
# itself as costing nothing, so it will not put a hosted embedder on the
- # user's bill unless they named it.
- embedder_was_requested = bool(embedder_name) or bool(
- os.environ.get("REPOWISE_EMBEDDER", "").strip()
+ # user's bill unless they named it. A repo whose config already names one
+ # counts as asked: the choice was made on an earlier run, and silently
+ # dropping to the mock here would re-embed the whole store at a different
+ # vector width, which the LanceDB writer resolves by dropping the table.
+ embedder_was_requested = (
+ bool(embedder_name)
+ or bool(os.environ.get("REPOWISE_EMBEDDER", "").strip())
+ or bool(config.get("embedder"))
)
+ # A template wiki overwrites a model-written one page for page: the upsert
+ # replaces content and stamps provider_name="template", keeping the old
+ # text only as a version snapshot. That is a fine outcome when it is what
+ # the user meant and a bad surprise when they were reaching for a re-index,
+ # so ask. Non-interactive runs refuse rather than guess.
+ # ``--yes`` and ``--force`` both mean "do not ask me", which is the answer
+ # here as much as at the cost gate.
+ _prior_docs_mode = resolve_docs_mode(load_state(repo_path))
+ if index_only and _prior_docs_mode == "llm" and not (force or yes):
+ console.print(
+ "\n[yellow]This repo already has a model-written wiki.[/yellow] "
+ "Indexing without a model\nrewrites every page from templates; the "
+ "written versions stay in page history."
+ )
+ if not sys.stdin.isatty():
+ raise click.ClickException(
+ "Refusing to replace a model-written wiki with template pages. "
+ "Re-run with --yes to confirm, or drop --index-only."
+ )
+ if not click.confirm(" Replace the written wiki with template pages?", default=False):
+ console.print("[dim]Nothing changed.[/dim]")
+ return
+
# ---- Resolve provider ----
provider = None
decision_provider = None
@@ -1107,6 +1162,9 @@ def init_command(
show_analysis_summary(result)
# ---- Phase 3: Generation ----
+ # The embedder the template wiki was actually built with, persisted below
+ # so `repowise update` reuses it. None means no template wiki was rendered.
+ _index_only_embedder: str | None = None
# Both modes generate. Index-only renders from templates; full mode picks
# a coverage level, estimates the spend and prompts a model.
#
@@ -1124,7 +1182,7 @@ def init_command(
"to write it with a model.[/dim]"
)
elif index_only:
- _run_deterministic_generation_phase(
+ _index_only_embedder = _run_deterministic_generation_phase(
repo_path=repo_path,
result=result,
total_phases=total_phases,
@@ -1156,11 +1214,24 @@ def init_command(
skip_tests=skip_tests,
skip_infra=skip_infra,
embedder_name_resolved=embedder_name_resolved,
- resume=resume,
+ # Resume seeds "already done" from the page ids in the vector
+ # store, and a completed template wiki put one there for every
+ # file. Resuming against it would skip the entire model run and
+ # say nothing, so a template wiki is never a run to continue.
+ resume=resume and _prior_docs_mode != "deterministic",
)
if gen_stop:
return
- if cost_declined:
+ if cost_declined and _prior_docs_mode == "llm":
+ # The repo already has written pages. Declining the price of new
+ # ones is not a request to replace the old ones with templates,
+ # which is what the fallback below would do.
+ cost_declined = False
+ console.print(
+ " [dim]Keeping the wiki this repo already has. Nothing was "
+ "generated and nothing was replaced.[/dim]"
+ )
+ elif cost_declined:
# Declining the gate used to mean leaving with no wiki at all.
# It only ever meant "not at that price", so fall back to the
# free renderer rather than to nothing.
@@ -1169,7 +1240,7 @@ def init_command(
"[bold]repowise update --full[/bold] to write it with a "
"model later.[/dim]"
)
- _run_deterministic_generation_phase(
+ _index_only_embedder = _run_deterministic_generation_phase(
repo_path=repo_path,
result=result,
total_phases=total_phases,
@@ -1210,13 +1281,17 @@ def init_command(
# re-passing the flag. Written before any config_fingerprint is computed
# below so the first update doesn't false-positive on a config change. The
# default is omitted to keep config files tidy — only an override is recorded.
- if wiki_style != DEFAULT_STYLE:
+ #
+ # A template wiki records neither style nor language: it has neither, and
+ # recording them would make `restyle` believe the pages are already in that
+ # style and refuse the very run that would put them there.
+ if wiki_style != DEFAULT_STYLE and not effective_index_only:
save_config_partial(repo_path, wiki_style=wiki_style)
# Persist the output language so `repowise update` regenerates changed
# pages in the same language. Written only when the run's language differs
# from what config.yaml already holds; the default stays unrecorded.
- if language != config.get("language", "en"):
+ if language != config.get("language", "en") and not effective_index_only:
save_config_partial(repo_path, language=language)
# ---- Post-run: config, state, MCP, editor project files ----
@@ -1278,10 +1353,24 @@ def init_command(
save_knowledge_graph_json(repo_path, kg)
if effective_index_only or provider is None:
# Index-only mode skips save_config(); persist exclude_patterns/commit_limit here.
+ # The embedder rides along now that this mode produces pages: without
+ # it `repowise update` would re-resolve from the environment and could
+ # start embedding, at a different width, a store this run deliberately
+ # built with the mock.
+ # ``embedding_model`` rides with it, the way save_config() writes the
+ # pair: `serve` pins the model from it, and the store-format upgrade
+ # check reads it to notice an embedder change. Half the pair is not
+ # enough for either.
+ from repowise.cli.providers.embedders import resolve_embedding_model
+
save_config_partial(
repo_path,
exclude_patterns=exclude_patterns if exclude_patterns else None,
commit_limit=resolved_commit_limit if commit_limit is not None else None,
+ embedder=_index_only_embedder,
+ embedding_model=(
+ resolve_embedding_model(_index_only_embedder) if _index_only_embedder else None
+ ),
)
# Fingerprint after config writes so the first update doesn't false-positive.
base_state["config_fingerprint"] = config_fingerprint(repo_path)
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 45f250f97..9597de320 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -84,6 +84,7 @@ def _record_update_outcome(
changed_count: int,
provider: Any = None,
generated_pages: list | None = None,
+ docs_mode: str | None = None,
) -> None:
"""Attach an anonymous update-shape outcome to the ``command_run`` event.
@@ -93,16 +94,26 @@ def _record_update_outcome(
try:
from repowise.cli.platform import telemetry
+ # docs_mode carries the same three values as the state field of that
+ # name; it was a bool until an index-only update started re-rendering
+ # template pages, which that shape could not express. It comes from the
+ # repo's persisted mode, not from this run's page count: a commit that
+ # touched no source file re-renders nothing, and that is not the same
+ # as the repo having no wiki.
+ pages = generated_pages or []
+ if docs_mode is None:
+ docs_mode = "llm" if (not index_only and provider is not None) else "none"
outcome: dict[str, Any] = {
"outcome": "success",
"index_only": bool(index_only),
- "docs_mode": not index_only and provider is not None,
+ "docs_mode": docs_mode,
"changed_files_bucket": telemetry.bucket_count(changed_count),
}
if not index_only and provider is not None:
outcome["provider"] = getattr(provider, "provider_name", None)
outcome["model"] = getattr(provider, "model_name", None)
- outcome["pages_bucket"] = telemetry.bucket_count(len(generated_pages or []))
+ if pages:
+ outcome["pages_bucket"] = telemetry.bucket_count(len(pages))
telemetry.add_command_outcome(**{k: v for k, v in outcome.items() if v is not None})
except Exception:
return
@@ -227,6 +238,14 @@ def _surface_release_news(*, written_by: str | None) -> None:
"(set during `repowise init`)."
),
)
+ "--yes",
+ "-y",
+ "yes",
+ is_flag=True,
+ default=False,
+ help="Skip the cost confirmation on `--full`.",
+)
@click.option(
"--full",
"full",
@@ -296,6 +315,7 @@ def update_command(
index_only: bool = False,
docs_flag: bool | None = None,
full: bool = False,
+ yes: bool = False,
agents_md: bool | None = None,
concurrency: int = 10,
no_cost_tracking: bool = False,
@@ -322,6 +342,7 @@ def update_command(
index_only=index_only,
docs_flag=docs_flag,
full=full,
+ yes=yes,
agents_md=agents_md,
concurrency=concurrency,
no_cost_tracking=no_cost_tracking,
@@ -344,6 +365,7 @@ def run_update(
index_only: bool = False,
docs_flag: bool | None = None,
full: bool = False,
+ yes: bool = False,
agents_md: bool | None = None,
concurrency: int = 10,
no_cost_tracking: bool = False,
@@ -478,6 +500,7 @@ def run_update(
model=model,
reasoning=reasoning,
concurrency=concurrency,
+ yes=yes,
)
except Exception as exc:
if emitter is not None:
@@ -790,6 +813,48 @@ def run_update(
)
if index_only:
+ # A repo whose wiki was rendered from templates keeps it current here.
+ # Re-rendering is free, so the changed files' pages are refreshed on
+ # every update rather than frozen at the commit `init` ran on. Repos
+ # with no pages (fast mode, or an index from before templates existed)
+ # skip this and stay a pure index.
+ det_pages: list = []
+ docs_mode = resolve_docs_mode(state)
+ if docs_mode == "deterministic":
+ from .deterministic import (
+ load_prior_page_ids,
+ persist_deterministic_pages,
+ regenerate_deterministic_pages,
+ )
+
+ if emitter is not None:
+ emitter.stage("generate")
+ det_pages = regenerate_deterministic_pages(
+ repo_path=repo_path,
+ parsed_files=parsed_files,
+ source_map=source_map,
+ graph_builder=graph_builder,
+ repo_structure=repo_structure,
+ git_meta_map=git_meta_map,
+ regenerate_paths=affected.regenerate,
+ cfg=cfg,
+ concurrency=concurrency,
+ degraded=degraded,
+ dead_code_report=dead_code_report,
+ prior_page_ids=load_prior_page_ids(repo_path),
+ )
+ if det_pages:
+ state["total_pages"] = persist_deterministic_pages(
+ repo_path=repo_path,
+ generated_pages=det_pages,
+ decay_paths=affected.decay_only,
+ degraded=degraded,
+ )
+ state["last_docs_commit"] = head
+ console.print(
+ f" [green]✓[/green] Re-rendered [bold]{len(det_pages)}[/bold] "
+ "wiki pages from structure"
+ )
if emitter is not None:
emitter.stage("persist")
try:
@@ -807,17 +872,27 @@ def run_update(
knowledge_graph_result=knowledge_graph_result,
parsed_files=parsed_files,
degraded=degraded,
+ # The repo's docs mode, not this run's page count: a commit
+ # that touched no source file re-renders nothing, and that is
+ # not the same as having no wiki.
+ template_wiki=docs_mode == "deterministic",
+ pages_rendered=len(det_pages),
)
except Exception as exc:
if emitter is not None:
emitter.error(str(exc))
raise
_refresh_editor_stamp(repo_path, agents_md, degraded)
- _record_update_outcome(index_only=True, changed_count=len(file_diffs))
+ _record_update_outcome(
+ index_only=True,
+ changed_count=len(file_diffs),
+ generated_pages=det_pages,
+ docs_mode=docs_mode,
+ )
if emitter is not None:
emitter.done(
ok=True,
- pages_generated=0,
+ pages_generated=len(det_pages),
cost_usd=0.0,
duration_s=time.monotonic() - start,
degraded=degraded,
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
new file mode 100644
index 000000000..d0e1f9cbf
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -0,0 +1,267 @@
+"""Refresh a template wiki on an index-only update.
+
+``repowise init --index-only`` renders a complete wiki from the repo's
+structure. Without this module that wiki would be frozen at the commit it was
+built from: an index-only update refreshes the graph, git history, health and
+dead code, but never touched a page, because before templates existed there
+were no pages on that path to touch.
+
+Re-rendering costs nothing (no provider, no tokens), so the changed files'
+pages are re-rendered on every update, the same set the LLM path would
+regenerate. The work is deliberately narrow compared with
+``_persist_full_update``: no decision extraction, no decision evolution, no KG
+enrichment. All three are prompting, and this path has no model.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from repowise.cli.helpers import console, run_async
+
+
+def deterministic_embedder_name(cfg: dict) -> str:
+ """Resolve the embedder for a no-spend run, honouring only an explicit one.
+
+ Same rule as ``init --index-only``: a hosted embedder is a real bill, and
+ ``resolve_embedder`` will infer one from any LLM key that happens to be in
+ the environment. On a run sold as costing nothing, only a name the user
+ actually chose counts, and index-only init persists that choice to
+ ``.repowise/config.yaml``. Everything else falls back to the mock, which
+ leaves full-text search working.
+ """
+ from repowise.cli.providers import resolve_embedder
+
+ chosen = cfg.get("embedder") or os.environ.get("REPOWISE_EMBEDDER", "").strip()
+ if chosen:
+ return str(chosen)
+ # Nothing was chosen, so whatever resolve_embedder returns was inferred
+ # from a key. Only the ones that cannot bill survive that.
+ resolved = resolve_embedder(None)
+ return resolved if resolved in ("mock", "ollama") else "mock"
+
+
+def load_prior_page_ids(repo_path: Path) -> dict:
+ """Every page id already in the wiki, mapped to a placeholder.
+
+ Interlinking and related-pages resolve references against this, so a
+ re-rendered page can still link to the pages this run did not touch.
+ Only the ids are read: the full ``load_prior_pages`` pulls every page's
+ content, and nothing here needs the bodies since template pages never go
+ through the content-reuse gate.
+ """
+ return run_async(_load_prior_page_ids(repo_path))
+
+
+async def _load_prior_page_ids(repo_path: Path) -> dict:
+ 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.models import Page
+
+ async with get_session(create_session_factory(engine)) as session:
+ rows = await session.execute(sa_select(Page.id))
+ return dict.fromkeys((r[0] for r in rows), None)
+ except Exception:
+ return {}
+ finally:
+ await engine.dispose()
+
+
+def regenerate_deterministic_pages(
+ *,
+ repo_path: Path,
+ parsed_files: list,
+ source_map: dict,
+ graph_builder: Any,
+ repo_structure: Any,
+ git_meta_map: dict,
+ regenerate_paths: list[str],
+ cfg: dict,
+ concurrency: int,
+ degraded: list[str],
+ dead_code_report: Any = None,
+ prior_page_ids: dict | None = None,
+) -> list:
+ """Re-render the template pages for *regenerate_paths*. Never raises.
+
+ Only the changed files' own pages. The repo-wide pages (cycles, modules,
+ layers, overview, architecture diagram, onboarding) describe the whole
+ repository and would be rendered here from a view containing only the
+ changed files, so they are left as the last full run wrote them.
+
+ A failure here degrades the run rather than failing it: the index half of
+ an index-only update is the half the post-commit hook depends on, and it
+ has already been computed by the time this runs.
+ """
+ from repowise.core.generation import ContextAssembler, GenerationConfig, PageGenerator
+ from repowise.core.providers.llm.template import TemplateProvider
+
+ regen_set = set(regenerate_paths)
+ affected_parsed = [pf for pf in parsed_files if pf.file_info.path in regen_set]
+ affected_source = {p: s for p, s in source_map.items() if p in regen_set}
+ if not affected_parsed:
+ return []
+
+ try:
+ config = GenerationConfig(
+ deterministic=True,
+ file_pages_only=True,
+ max_concurrency=concurrency,
+ language=cfg.get("language", "en"),
+ enable_onboarding=bool(cfg.get("enable_onboarding", True)),
+ wiki_style=cfg.get("wiki_style", "comprehensive"),
+ )
+
+ # Only build a store when there is a real embedder to build it with.
+ # The mock is the index-only default, and writing its 8-wide vectors
+ # into a store some earlier run filled at 1536 makes LanceDB drop the
+ # table, taking every page and decision embedding with it. Skipping
+ # leaves that store untouched; full-text search is unaffected either
+ # way. It also keeps the lancedb import off the post-commit hook's
+ # path, which is the one place in this command that avoids it.
+ vector_store = None
+ embedder_name = deterministic_embedder_name(cfg)
+ if embedder_name != "mock":
+ from repowise.cli.providers import build_embedder, build_vector_store
+
+ try:
+ vector_store = build_vector_store(repo_path, build_embedder(embedder_name))
+ except Exception as exc: # embedding is optional; FTS still indexes
+ degraded.append(f"Page embedding: {exc}")
+
+ generator = PageGenerator(
+ TemplateProvider(),
+ ContextAssembler(config),
+ config,
+ vector_store=vector_store,
+ language=config.language,
+ # Every persisted page id, so interlinking and related-pages can
+ # resolve references to pages outside this run's slice. Not a reuse
+ # gate: template pages persist an empty content_hash precisely so a
+ # later model run cannot inherit their content.
+ prior_pages=prior_page_ids or {},
+ repo_path=repo_path,
+ )
+ with console.status(" Re-rendering wiki pages from structure…"):
+ return run_async(
+ generator.generate_all(
+ affected_parsed,
+ affected_source,
+ graph_builder,
+ repo_structure,
+ repo_path.name,
+ git_meta_map=git_meta_map,
+ repo_path=repo_path,
+ dead_code_report=dead_code_report,
+ )
+ )
+ except Exception as exc:
+ degraded.append(f"Template page refresh: {exc}")
+ return []
+
+
+def persist_deterministic_pages(
+ *,
+ repo_path: Path,
+ generated_pages: list,
+ decay_paths: list[str],
+ degraded: list[str],
+) -> int:
+ """Write the re-rendered pages, decay the rest, and index them for search.
+
+ Returns the repository's total page count, so the caller can stamp
+ ``state["total_pages"]`` with the real DB number rather than accumulating.
+ Runs before ``persist_incremental_index`` and in its own session: the pages
+ must land before that call tombstones the ones whose files are gone, and
+ page upserts are idempotent, so an interrupted run re-runs rather than
+ tearing the index.
+ """
+ return run_async(
+ _persist_async(
+ repo_path=repo_path,
+ generated_pages=generated_pages,
+ decay_paths=decay_paths,
+ degraded=degraded,
+ )
+ )
+
+
+async def _persist_async(
+ *,
+ repo_path: Path,
+ generated_pages: list,
+ decay_paths: list[str],
+ degraded: list[str],
+) -> int:
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import (
+ FullTextSearch,
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_pages_from_generated,
+ upsert_repository,
+ )
+
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ total = 0
+ try:
+ 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))
+ repo_id = repo.id
+ await upsert_pages_from_generated(session, generated_pages, repo_id)
+
+ # No related-pages backfill here. ``persist_incremental_index``
+ # runs one repo-wide immediately after this, unskipped, so it
+ # already heals these pages; doing it first and exempting them
+ # would skip the only pages that need it.
+
+ # Pages the cascade reached but the budget did not: marked stale so
+ # the coverage view is honest about which template pages predate
+ # the current commit.
+ try:
+ from repowise.core.pipeline.persist import mark_stale_pages
+
+ await mark_stale_pages(session, repo_id, decay_paths or [])
+ except Exception as exc:
+ degraded.append(f"Stale-page decay: {exc}")
+
+ # Real DB total, not an accumulation: regeneration upserts, so
+ # adding len(generated_pages) each run inflates the count forever.
+ total = len(generated_pages)
+ try:
+ from sqlalchemy import func as sa_func
+ from sqlalchemy import select as sa_select
+
+ from repowise.core.persistence.models import Page
+
+ count_result = await session.execute(
+ sa_select(sa_func.count())
+ .select_from(Page)
+ .where(Page.repository_id == repo_id)
+ )
+ total = int(count_result.scalar_one())
+ except Exception as exc:
+ degraded.append(f"Page count: {exc}")
+
+ try:
+ fts = FullTextSearch(engine)
+ await fts.ensure_index()
+ for page in generated_pages:
+ await fts.index(page.page_id, page.title, page.content)
+ except Exception as exc:
+ degraded.append(f"Full-text index: {exc}")
+ finally:
+ await engine.dispose()
+ return total
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 70451895a..f2a44c7ae 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -141,6 +141,8 @@ def _persist_index_only_update(
knowledge_graph_result: Any | None = None,
parsed_files: list | None = None,
degraded: list[str] | None = None,
+ pages_rendered: int = 0,
+ template_wiki: 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.
@@ -196,6 +198,8 @@ def _persist_index_only_update(
git_files=len(git_meta_map or {}),
elapsed=elapsed,
degraded=degraded,
+ pages_rendered=pages_rendered,
+ template_wiki=template_wiki,
)
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py
index c2cab5f01..665fe43aa 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py
@@ -225,8 +225,15 @@ def show_index_only_completion(
git_files: int,
elapsed: float,
degraded: list[str] | None = None,
+ pages_rendered: int = 0,
+ template_wiki: bool = False,
) -> None:
- """Render the completion panel for an index-only update (no LLM regen)."""
+ """Render the completion panel for an index-only update (no LLM regen).
+
+ *pages_rendered* is non-zero on a repo whose wiki was rendered from
+ templates: those pages are re-rendered here for free, so the panel says so
+ rather than leaving the user to assume the wiki went stale.
+ """
render_degraded(degraded)
graph = graph_builder.graph()
unreachable, unused = _dead_code_counts(dead_code_report)
@@ -236,6 +243,8 @@ def show_index_only_completion(
("Graph", f"{graph.number_of_nodes():,} nodes · {graph.number_of_edges():,} edges"),
("Dead code", f"{unreachable} unreachable · {unused} unused exports"),
]
+ if pages_rendered:
+ metrics.append(("Wiki pages", f"{pages_rendered} re-rendered from structure"))
if degraded:
metrics.append(("Degraded", f"{len(degraded)} step(s)"))
if git_files:
@@ -244,8 +253,11 @@ def show_index_only_completion(
next_steps = [
("repowise serve", "browse the index at localhost:3000"),
- ("repowise update --docs", "regenerate docs for the changed files"),
]
+ if template_wiki:
+ next_steps.append(("repowise update --full", "rewrite the wiki with a model (needs a key)"))
+ else:
+ next_steps.append(("repowise update --docs", "regenerate docs for the changed files"))
console.print()
console.print(
build_completion_panel("repowise index-only update complete", metrics, next_steps=next_steps)
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index 2f7cf651e..176a3a13c 100644
--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py
+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
@@ -25,6 +25,7 @@ when ``--full`` is passed.
from __future__ import annotations
import dataclasses
+import sys
import time
from pathlib import Path
from typing import Any
@@ -44,6 +45,50 @@ from repowise.cli.helpers import (
from repowise.core.docs_mode import docs_mode_state_fields
+def _gate_cost(
+ parsed_files: list[Any],
+ graph_builder: Any,
+ config: Any,
+ provider: Any,
+ repo_path: Path,
+ *,
+ yes: bool,
+) -> None:
+ """Print the estimated spend and confirm past the gate. Raises on decline.
+
+ Best-effort on the estimate itself: a failure there prints the reason and
+ lets the run proceed rather than blocking an upgrade on a number that is
+ advisory anyway.
+ """
+ try:
+ from repowise.cli.commands.init_cmd.generation import (
+ COST_GATE_USD,
+ cost_gate_declined,
+ format_cost,
+ )
+ from repowise.core.cost_estimator import build_generation_plan, estimate_cost
+
+ plans = build_generation_plan(parsed_files, graph_builder, config)
+ est = estimate_cost(plans, provider.provider_name, provider.model_name, repo_path=repo_path)
+ except Exception as exc:
+ console.print(f"[yellow]Cost estimate unavailable ({exc}); continuing.[/yellow]")
+ return
+
+ pages = sum(p.count for p in plans)
+ console.print(f"Estimated: [bold]{pages}[/bold] pages, [bold]{format_cost(est)}[/bold].")
+
+ # Nothing to ask on a run that cannot be asked. Without this the confirm
+ # reads EOF, raises, and the caller reports a successful run that generated
+ # nothing, which is the worst of the three possible answers.
+ if est.estimated_cost_usd > COST_GATE_USD and not yes and not sys.stdin.isatty():
+ raise click.ClickException(
+ f"This would spend about {format_cost(est)} and there is no terminal to "
+ "confirm on. Re-run with --yes to accept the cost."
+ )
+ if cost_gate_declined(est, yes=yes, message=" Generate the wiki at this cost?"):
+ raise click.Abort()
+
+
def _reparse(repo_path: Path, exclude_patterns: list[str]) -> tuple[list[Any], dict[str, bytes], Any]:
"""Parse files for ASTs + source bytes WITHOUT building/resolving the graph.
@@ -147,6 +192,8 @@ async def _run_upgrade(
exclude_patterns: list[str],
commit_limit: int | None,
follow_renames: bool,
+ embedder_name: str | None,
+ yes: bool,
) -> list[Any]:
"""Drive the full upgrade and return the generated pages."""
from repowise.cli.helpers import get_db_url_for_repo
@@ -195,6 +242,14 @@ 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.
+ _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.
@@ -207,6 +262,21 @@ async def _run_upgrade(
# 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
+
+ # 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.
+ from repowise.cli.providers import build_embedder, build_vector_store, resolve_embedder
+
+ embedder = None
+ vector_store = None
+ try:
+ embedder = build_embedder(resolve_embedder(embedder_name))
+ vector_store = build_vector_store(repo_path, embedder)
+ except Exception as exc:
+ console.print(f"[yellow]Embedding skipped: {exc}[/yellow]")
+
generated_pages = await run_generation(
repo_path=repo_path,
parsed_files=parsed_files,
@@ -215,8 +285,8 @@ async def _run_upgrade(
repo_structure=repo_structure,
git_meta_map=git_meta_map,
llm_client=provider,
- embedder=None,
- vector_store=None,
+ embedder=embedder,
+ vector_store=vector_store,
concurrency=config.max_concurrency,
progress=None,
cost_tracker=cost_tracker,
@@ -306,8 +376,31 @@ async def _run_upgrade(
except Exception as exc:
console.print(f"[yellow]Health recompute skipped: {exc}[/yellow]")
+ # 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.
+ try:
+ from sqlalchemy import func as sa_func
+ from sqlalchemy import select as sa_select
+
+ from repowise.core.persistence.models import Page
+
+ async with get_session(sf) as session:
+ total_pages = int(
+ (
+ await session.execute(
+ sa_select(sa_func.count())
+ .select_from(Page)
+ .where(Page.repository_id == repo_id)
+ )
+ ).scalar_one()
+ )
+ except Exception:
+ total_pages = len(generated_pages)
+
await engine.dispose()
- return generated_pages
+ return generated_pages, total_pages
def upgrade_to_full(
@@ -317,11 +410,14 @@ def upgrade_to_full(
model: str | None,
reasoning: str | None,
concurrency: int,
+ yes: bool = False,
) -> None:
- """Upgrade a fast (index-only / ESSENTIAL git) index to a full one.
+ """Write the repo's wiki with a model, reusing the persisted graph.
- Backfills the git tier and generates the LLM docs the fast index skipped,
- reusing the persisted graph instead of rebuilding it.
+ Two repos arrive here. A ``--mode fast`` index has no pages and an
+ ESSENTIAL git tier, both of which this fills in. An ``--index-only`` repo
+ has a full git tier and a wiki rendered from templates, and this replaces
+ those pages with written ones.
"""
from repowise.cli.ui import load_dotenv
from repowise.core.generation import GenerationConfig
@@ -361,24 +457,58 @@ def upgrade_to_full(
f"[cyan]{provider.model_name}[/cyan]. This generates docs for the whole repo."
)
- generated_pages = run_async(
- _run_upgrade(
- repo_path,
- provider,
- config,
- exclude_patterns=exclude_patterns,
- commit_limit=commit_limit,
- follow_renames=follow_renames,
+ # 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
+
+ try:
+ generated_pages, total_pages = run_async(
+ _run_upgrade(
+ repo_path,
+ provider,
+ config,
+ exclude_patterns=exclude_patterns,
+ commit_limit=commit_limit,
+ follow_renames=follow_renames,
+ embedder_name=embedder_name,
+ yes=yes,
+ )
)
- )
+ 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.
+ console.print("[yellow]Nothing generated.[/yellow] The index is unchanged.")
+ return
# 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["total_pages"] = len(generated_pages)
+ 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
save_state(repo_path, state)
+ if embedder_name and embedder_name != cfg.get("embedder"):
+ from repowise.cli.helpers import save_config_partial
+
+ save_config_partial(repo_path, embedder=embedder_name)
elapsed = time.monotonic() - start
console.print(
diff --git a/packages/cli/src/repowise/cli/ui/mode_selection.py b/packages/cli/src/repowise/cli/ui/mode_selection.py
index ea1ae677d..b42c722a2 100644
--- a/packages/cli/src/repowise/cli/ui/mode_selection.py
+++ b/packages/cli/src/repowise/cli/ui/mode_selection.py
@@ -446,6 +446,9 @@ def _build_summary_table(
# Bullet-list when many patterns — comma-joined wraps unreadably.
summary.add_row("Exclude", "\n".join(f"• {p}" for p in patterns))
+ if not generate_docs and result.get("embedder"):
+ summary.add_row("Embedder", result["embedder"])
+
# ── Generation (docs only) ─────────────────────────────────────────────
if generate_docs:
summary.add_row("Concurrency", str(result["concurrency"]))
@@ -531,6 +534,9 @@ def interactive_advanced_config(
wiki_style=wiki_style,
language=language,
)
+ elif result.get("run_mode") != "fast":
+ # Fast mode renders no wiki at all, so there would be nothing to embed.
+ _prompt_index_only_search(console, result)
result["generate_docs"] = generate_docs
# ── Summary ───────────────────────────────────────────────────────────
@@ -550,6 +556,29 @@ def interactive_advanced_config(
return result
+def _prompt_index_only_search(console: Console, result: dict[str, Any]) -> None:
+ """Ask an index-only run which embedder its template wiki should use.
+
+ Index-only renders a full wiki now, and those pages embed like any other,
+ so the choice is real. It is not asked outside advanced mode because the
+ honest default is the one that cannot bill anyone: a hosted embedder is
+ picked up automatically from an API key in the environment, and this mode
+ promises no spend. Choosing one here counts as asking for it.
+ """
+ console.print()
+ console.print(f" [{BRAND}]Search[/]")
+ console.print(
+ " [dim]Full-text search always works. Semantic search needs an embedder;\n"
+ " ollama is the keyless one, and the hosted ones charge per page.[/dim]"
+ )
+ console.print()
+ result["embedder"] = click.prompt(
+ " Embedder for semantic search (mock = full-text only)",
+ default="mock",
+ type=click.Choice(["mock", "ollama", "gemini", "openai", "openrouter"]),
+ )
+
+
def _resolve_embedder_from_env() -> str:
"""Auto-detect embedder from env vars (for advanced config default)."""
if os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index d3da3b625..a3389d926 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -197,6 +197,18 @@ class GenerationConfig:
# ``metadata["deterministic"]=True``, exactly like the tier-2 tail.
deterministic: bool = False
+ # ---- Incremental regeneration: file-level pages only ---------------
+ # Levels 3 to 8 (cycles, modules, layers, repo overview, architecture
+ # diagram, infra, onboarding) describe the repository, not a file. They
+ # render from the graph and from ``parsed_files``, and an incremental run
+ # holds only the files that changed, so letting them run would overwrite a
+ # whole-repo page with a view of one commit: a codebase map with no
+ # directories, a module page claiming one file. Their inputs are also
+ # unchanged by most commits, so the work is wasted as well as wrong.
+ # Set by the incremental deterministic path, which regenerates the changed
+ # files' pages and leaves the repo-wide ones to a full run.
+ file_pages_only: bool = False
+
def __post_init__(self) -> None:
if self.embed_concurrency is None:
object.__setattr__(self, "embed_concurrency", self.max_concurrency)
diff --git a/packages/core/src/repowise/core/generation/page_generator/deterministic.py b/packages/core/src/repowise/core/generation/page_generator/deterministic.py
index 302b72eb8..5822829a2 100644
--- a/packages/core/src/repowise/core/generation/page_generator/deterministic.py
+++ b/packages/core/src/repowise/core/generation/page_generator/deterministic.py
@@ -86,7 +86,7 @@ class DeterministicRenderMixin:
page_type=page_type,
title=title,
content=content,
- summary=_extract_summary(content),
+ summary=_extract_summary(content, skip_metadata=True),
source_hash=compute_source_hash(content),
model_name=self._provider.model_name,
provider_name="template",
diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.py
index 155a8a275..83da30f63 100644
--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py
+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py
@@ -26,18 +26,31 @@ def _now_iso() -> str:
return datetime.now(UTC).isoformat()
-def _extract_summary(content: str, max_chars: int = 320) -> str:
+def _extract_summary(content: str, max_chars: int = 320, skip_metadata: bool = False) -> str:
"""Extract a 1-3 sentence purpose blurb from rendered wiki markdown.
Strategy: walk lines top-to-bottom, skip blanks/headings/list-markers/HTML
comments, and take the first prose paragraph. Truncate at sentence boundary
near max_chars. Fully deterministic — no extra LLM call.
+
+ *skip_metadata* skips what several deterministic templates put between the
+ H1 and the prose: a bold field line (``**Language:** Python | **Files:**
+ 412``) and a fenced signature block. Both would otherwise become the
+ summary, and the summary is what the wiki list, search results and
+ ``get_context`` display. Off by default: a model that opens with
+ ``**Purpose:** …`` means it as prose.
"""
if not content:
return ""
para_lines: list[str] = []
+ in_lead_fence = False
for raw in content.splitlines():
line = raw.strip()
+ if in_lead_fence:
+ # Inside a fenced block that preceded any prose: the fence's
+ # contents are code, and its closing marker ends the skip.
+ in_lead_fence = not line.startswith("```")
+ continue
if not line:
if para_lines:
break
@@ -45,6 +58,10 @@ def _extract_summary(content: str, max_chars: int = 320) -> str:
if line.startswith(("#", ">", "```", "---", "<!--", "|", "- ", "* ", "1.")):
if para_lines:
break
+ if skip_metadata and line.startswith("```"):
+ in_lead_fence = True
+ continue
+ if skip_metadata and not para_lines and line.startswith("**") and ":**" in line:
continue
para_lines.append(line)
if not para_lines:
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index c66bda1ed..c7b0b3407 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -283,8 +283,14 @@ class _GenerationRun:
history, mining error) yields an empty map and selection stays
uniform. Runs only on real generation — the cost estimator builds its
own demand-free SelectionInputs, so estimates are untouched.
+
+ Skipped on a deterministic run. Demand exists to tilt a budget toward
+ the files agents ask about, and a template page costs nothing, so there
+ is no budget to tilt. The sweep reads every session transcript for the
+ repo, which grows with the user's chat history rather than the repo:
+ seconds of work per run, on the path a post-commit hook takes.
"""
- if not self.repo_path:
+ if not self.repo_path or self.config.deterministic:
return {}
try:
from repowise.core.repo_config import load_repo_config
@@ -521,6 +527,13 @@ class _GenerationRun:
level2 = await _levels.build_level2_coros(self)
all_pages.extend(await self.run_level(level2, 2))
+ # Levels 3 and up describe the repository rather than a file, and an
+ # incremental run holds only the changed files, so running them here
+ # would rewrite a whole-repo page from a one-commit view. They stay as
+ # the last full run left them.
+ if getattr(self.config, "file_pages_only", False):
+ return self._finalize(all_pages)
+
# Level 3 (scc_page).
all_pages.extend(await self.run_level(_levels.build_level3_coros(self), 3))
@@ -553,6 +566,15 @@ class _GenerationRun:
page.metadata["layer_order"] = self.layer_order
break
+ return self._finalize(all_pages)
+
+ def _finalize(self, all_pages: list[GeneratedPage]) -> list[GeneratedPage]:
+ """Run the post-generation passes and close out the job.
+
+ Shared with the ``file_pages_only`` early return, so an incremental
+ deterministic run still gets mermaid repair, interlinking, related
+ pages and tour links over the pages it did produce.
+ """
# Post-generation: repair mermaid diagrams so illegal node IDs / unquoted
# labels in LLM output don't break the whole diagram in the renderer.
try:
diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2
index b6184eb30..36ed29e27 100644
--- a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2
+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2
@@ -10,7 +10,9 @@ Traced from the entry points outward: which files each run touches, in order. Wh
## Shape
-`{{ ctx.repo_name }}` looks like {{ "an" if ctx.archetype[0] in "aeiou" else "a" }} **{{ ctx.archetype }}**{% if ctx.archetype_evidence %}, based on:
+{#- archetype can come through empty on a repo with no recognised sources;
+ indexing it unguarded raises under StrictUndefined and loses the page. -#}
+`{{ ctx.repo_name }}` looks like {{ "an" if ctx.archetype and ctx.archetype[0] in "aeiou" else "a" }} **{{ ctx.archetype or "codebase" }}**{% if ctx.archetype_evidence %}, based on:
{% for e in ctx.archetype_evidence %}
- {{ e }}
{% endfor %}
diff --git a/tests/integration/test_deterministic_generation.py b/tests/integration/test_deterministic_generation.py
index 36bd200bf..5879a93d4 100644
--- a/tests/integration/test_deterministic_generation.py
+++ b/tests/integration/test_deterministic_generation.py
@@ -146,3 +146,71 @@ class TestDeterministicGeneration:
for p in deterministic_pages:
assert "Generate a complete wiki page" not in p.content, p.page_id
assert not p.content.lstrip().startswith("You are "), p.page_id
+
+
+class TestFilePagesOnly:
+ """The incremental path: only the changed files' own pages.
+
+ An update holds only the files that changed. Levels 3 and up describe the
+ whole repository and read ``parsed_files``, so letting them run against
+ that slice rewrites a whole-repo page from a one-commit view: a codebase
+ map with no directories, a module page claiming one file. The flag stops
+ them, leaving those pages as the last full run wrote them.
+ """
+
+ @pytest.fixture(scope="class")
+ async def scoped_pages(self, tmp_path_factory):
+ tmp = tmp_path_factory.mktemp("det_scoped")
+ traverser = FileTraverser(SAMPLE_REPO)
+ parser = ASTParser()
+ builder = GraphBuilder()
+ parsed_files: list[ParsedFile] = []
+ source_map: dict[str, bytes] = {}
+ for fi in traverser.traverse():
+ try:
+ src = Path(fi.abs_path).read_bytes()
+ parsed = parser.parse_file(fi, src)
+ builder.add_file(parsed)
+ parsed_files.append(parsed)
+ source_map[fi.path] = src
+ except Exception:
+ pass
+ builder.build()
+ repo_structure = RepoStructure(
+ is_monorepo=False,
+ packages=[],
+ root_language_distribution={"python": 1.0},
+ total_files=len(parsed_files),
+ total_loc=0,
+ entry_points=[],
+ )
+ # One code file, the way an incremental run arrives. It has to be one
+ # the selector would pick: file pages are only built for code.
+ one = [p for p in parsed_files if p.file_info.language == "python"][:1]
+ one_src = {p.file_info.path: source_map[p.file_info.path] for p in one}
+ config = GenerationConfig(
+ deterministic=True,
+ file_pages_only=True,
+ max_concurrency=2,
+ jobs_dir=str(tmp / "jobs"),
+ )
+ generator = PageGenerator(TemplateProvider(), ContextAssembler(config), config)
+ return await generator.generate_all(
+ one, one_src, builder, repo_structure, "sample_repo", job_system=None
+ )
+
+ def test_no_repo_wide_pages(self, scoped_pages):
+ repo_wide = {
+ "scc_page",
+ "module_page",
+ "layer_page",
+ "repo_overview",
+ "architecture_diagram",
+ "onboarding",
+ }
+ produced = {p.page_type for p in scoped_pages}
+ assert not (produced & repo_wide), f"repo-wide pages rebuilt from one file: {produced}"
+
+ def test_still_produces_the_file_page(self, scoped_pages):
+ assert scoped_pages, "the changed file's own page must still be rendered"
+ assert all(p.provider_name == "template" for p in scoped_pages)
diff --git a/tests/unit/cli/test_deterministic_update.py b/tests/unit/cli/test_deterministic_update.py
new file mode 100644
index 000000000..f75b4f9d7
--- /dev/null
+++ b/tests/unit/cli/test_deterministic_update.py
@@ -0,0 +1,54 @@
+"""The no-spend rules around a template wiki.
+
+Two promises are under test. A run that says it costs nothing does not put a
+hosted embedder on the bill, and it does not silently change which embedder a
+repo uses between one run and the next. Both are easy to break by accident,
+because the embedder is resolved from whatever API key happens to be in the
+environment.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.cli.commands.update_cmd.deterministic import deterministic_embedder_name
+
+
[email protected](autouse=True)
+def _no_ambient_keys(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Start from an environment that infers nothing."""
+ for var in (
+ "REPOWISE_EMBEDDER",
+ "GEMINI_API_KEY",
+ "GOOGLE_API_KEY",
+ "OPENAI_API_KEY",
+ "OPENROUTER_API_KEY",
+ "OLLAMA_EMBEDDING_MODEL",
+ ):
+ monkeypatch.delenv(var, raising=False)
+
+
+class TestDeterministicEmbedderName:
+ def test_config_choice_wins(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # The repo was indexed with this embedder, so its store holds vectors
+ # of that width. Re-deciding here would rewrite the store.
+ monkeypatch.setenv("GEMINI_API_KEY", "k")
+ assert deterministic_embedder_name({"embedder": "openai"}) == "openai"
+
+ def test_ambient_key_alone_does_not_bill(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # The key is there to pay for a model somewhere else. Nobody asked for
+ # 2000 pages of embeddings on a run advertised as free.
+ monkeypatch.setenv("OPENAI_API_KEY", "k")
+ assert deterministic_embedder_name({}) == "mock"
+
+ def test_explicit_env_embedder_is_honoured(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("REPOWISE_EMBEDDER", "openai")
+ assert deterministic_embedder_name({}) == "openai"
+
+ def test_ollama_needs_no_permission(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # The keyless one: running it costs nothing, so inferring it is fine.
+ monkeypatch.setenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")
+ assert deterministic_embedder_name({}) == "ollama"
+
+ def test_nothing_configured_is_mock(self) -> None:
+ assert deterministic_embedder_name({}) == "mock"
diff --git a/tests/unit/cli/test_ui_package.py b/tests/unit/cli/test_ui_package.py
index af62b6a81..e10bc4f85 100644
--- a/tests/unit/cli/test_ui_package.py
+++ b/tests/unit/cli/test_ui_package.py
@@ -126,7 +126,12 @@ def test_advanced_config_default_keys_no_fast(monkeypatch: pytest.MonkeyPatch) -
def test_advanced_config_index_only_omits_generation_keys(
monkeypatch: pytest.MonkeyPatch,
) -> None:
- """generate_docs=False gathers indexing knobs only — no LLM-only keys."""
+ """generate_docs=False gathers indexing knobs only — no LLM-only keys.
+
+ ``embedder`` is the exception and is asked for: an index-only run renders a
+ template wiki, and those pages embed like any other, so the choice is real.
+ It defaults to the mock because this mode promises no spend.
+ """
result = _drive_advanced_config(monkeypatch, scan=None, allow_fast=False, generate_docs=False)
assert result == {
"generate_docs": False,
@@ -137,9 +142,10 @@ def test_advanced_config_index_only_omits_generation_keys(
"exclude": (),
"commit_limit": 500,
"follow_renames": False,
+ "embedder": "mock",
}
- # The generation-only knobs must not appear.
- for key in ("concurrency", "embedder", "onboarding", "harvest_decisions", "wiki_style"):
+ # The knobs that only shape a model's writing must not appear.
+ for key in ("concurrency", "reasoning", "onboarding", "harvest_decisions", "wiki_style"):
assert key not in result
diff --git a/tests/unit/generation/test_deterministic_templates.py b/tests/unit/generation/test_deterministic_templates.py
index bc3ca9ba4..0603a8572 100644
--- a/tests/unit/generation/test_deterministic_templates.py
+++ b/tests/unit/generation/test_deterministic_templates.py
@@ -241,3 +241,23 @@ def test_multiline_summaries_stay_inside_their_list_item(generator):
bullets = [ln for ln in body.splitlines() if ln.startswith("- ")]
assert len(bullets) == 2, f"list broke apart: {bullets}"
assert "First line. Second paragraph" in bullets[0]
+
+
+def test_summary_skips_the_stats_line():
+ """Several templates open with a bold field line under the H1.
+
+ The persisted summary is what the wiki list, search results and
+ get_context show, so a summary of "**Files:** 412 | **Lines:** 90210"
+ displaces the sentence that would have told the reader what the page is.
+ """
+ from repowise.core.generation.page_generator.helpers import _extract_summary
+
+ content = (
+ "# Module: core/ingestion\n\n"
+ "**Files:** 412 | **Lines:** 90210\n\n"
+ "## Overview\n\n"
+ "Walks the repository and parses every source file it recognises.\n"
+ )
+ assert _extract_summary(content, skip_metadata=True).startswith("Walks the repository")
+ # Off by default: a model that opens with **Purpose:** means it as prose.
+ assert _extract_summary(content).startswith("**Files:**")