Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(cli): add `repowise generate` for scoped, cost-gated wiki generation (#978)
Raghav Chamadiyaaa7581ef3ff9
diff --git a/README.md b/README.mdindex b1cce3420..9f5082522 100644--- a/README.md+++ b/README.md@@ -349,9 +349,19 @@ points, clusters and dependencies rather than what the project does end to end,because no template can derive that. Full-text search works on this index;semantic search needs an embedder configured (Ollama is the keyless option).-Want the wiki written by a model instead? Use `repowise init --provider-gemini|anthropic|openai` with the matching key, or upgrade an existing index later-with `repowise update --full`.+Want the wiki written by a model? You do not have to decide now. Upgrade the+index-only wiki whenever you like with `repowise generate`, a page, a directory,+or the whole thing at a time, each behind a cost estimate:++```bash+export ANTHROPIC_API_KEY="sk-ant-..." # or OPENAI_API_KEY / GEMINI_API_KEY+repowise generate --dry-run # preview the plan and the cost+repowise generate # write every unwritten page+repowise generate --path src/api # or just one area first+```++Or write the whole wiki as part of the first index with `repowise init --provider+gemini|anthropic|openai`.**3. Connect your agent.** The MCP server is `repowise mcp`, served from the repo directory.@@ -508,6 +518,7 @@ Doing a security review? **[docs/business/SECURITY_COMPLIANCE.md →](docs/busin```bashrepowise init [PATH] # index a codebase (one-time; --index-only needs no LLM)+repowise generate [PATH] # write wiki pages with a model, on demand (upgrade an index-only wiki)repowise serve [PATH] # MCP server + local dashboardrepowise update [PATH] # incremental update (seconds; --workspace for every repo)repowise watch # auto-sync daemon, re-index on file changediff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex f219a6997..018327938 100644--- a/docs/reference/CLI_REFERENCE.md+++ b/docs/reference/CLI_REFERENCE.md@@ -4,7 +4,7 @@ Complete reference for all `repowise` commands. For a guided introduction, see tCommand list (in `--help` order): `augment`, `init`, `delete`, `generate-claude-md`, `costs`, `update`, `dead-code`, `health`, `risk`, `decision`, `coverage`, `impacted-tests`, `search`, `distill`, `expand`, `saved`, `corrections`, `export`, `hook`, `status`, `doctor`, `watch`, `serve`, `mcp`, `reindex`, `restyle`, `wiki-styles`, `whats-new`, `telemetry`, `login`, `logout`, `whoami`, `workspace`. Two more ship as separate console scripts, not subcommands: `repowise-augment`, `repowise-rewrite` (both hook entry points, not meant to be run by hand).-**Do you need an LLM key?** Most commands are pure index/analysis and never call an LLM. The exceptions: `init` (unless `--index-only` or `--mode fast`), `update` (unless `--index-only` or `--no-docs`), `restyle`, `watch` (when it regenerates a page), `health --generate-code`, and `workspace add --docs`. Everything else, `search`, `dead-code`, `health`, `risk`, `impacted-tests`, `decision`, `coverage`, `export`, `mcp`, `reindex`, `doctor`, and so on, works index-only, with no provider configured.+**Do you need an LLM key?** Most commands are pure index/analysis and never call an LLM. The exceptions: `init` (unless `--index-only` or `--mode fast`), `update` (unless `--index-only` or `--no-docs`), `generate`, `restyle`, `watch` (when it regenerates a page), `health --generate-code`, and `workspace add --docs`. Everything else, `search`, `dead-code`, `health`, `risk`, `impacted-tests`, `decision`, `coverage`, `export`, `mcp`, `reindex`, `doctor`, and so on, works index-only, with no provider configured.## Workspace auto-detect (cross-cutting)@@ -65,7 +65,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `kimi`, `ollama`, `litellm`, `codex_cli`, `opencode`, `mock` || `--model` | Model name override (e.g., `claude-sonnet-4-6`) || `--embedder` | Embedder for semantic search: `gemini`, `openai`, `openrouter`, `ollama`, `mock` (default: auto-detect) |-| `--index-only` | No LLM calls, no API key, no spend. Parses, builds the graph, indexes git, and renders the whole wiki from that structure: file, module, layer and cycle (SCC) pages, the architecture diagram, the repo overview, API and infra pages, and the onboarding collection. Symbol spotlight pages are skipped, since the file pages already carry that content. Every page footer says it was derived from structure, and the repo overview covers composition, entry points, clusters and dependencies rather than what the project does end to end. Full-text search works; semantic search needs an embedder. Upgrade to model-written prose later with `update --full`, or restyle with `restyle`. |+| `--index-only` | No LLM calls, no API key, no spend. Parses, builds the graph, indexes git, and renders the whole wiki from that structure: file, module, layer and cycle (SCC) pages, the architecture diagram, the repo overview, API and infra pages, and the onboarding collection. Symbol spotlight pages are skipped, since the file pages already carry that content. Every page footer says it was derived from structure, and the repo overview covers composition, entry points, clusters and dependencies rather than what the project does end to end. Full-text search works; semantic search needs an embedder. Upgrade to model-written prose later, any subset at a time, with [`repowise generate`](#repowise-generate-path) (or `update --full` for the whole wiki in one shot). || `--mode` | Pipeline depth: `standard` (default) or `fast` (graph + essential-git only, no per-file blame/co-change, no LLM docs, for very large repos; upgrade later with `update --full`) || `--skip-tests` | Exclude test files from doc generation || `--skip-infra` | Exclude infrastructure files (Dockerfiles, Makefiles, Terraform) |@@ -189,12 +189,79 @@ repowise update --full --provider anthropic # upgrade a fast index to full---+### `repowise generate [PATH]`++Write wiki pages with a model, on demand. This is the upgrade path for an+`--index-only` repo: it turns the template (structure-rendered) pages into+model-written prose, one page, one directory, or the whole wiki at a time,+each behind a cost estimate. It also fills in the template tail a budgeted full+`init` leaves behind, and rewrites already-written pages.++Like `update --full` and `restyle`, it reuses the persisted index: the graph and+git metadata are rehydrated from SQL, only the per-file parse and the LLM+generation for the pages you selected run. A provider is required; a missing one+is an actionable error naming the key-setup path.++**Selection** (the default is `--unwritten`; combine freely, the result is their+union):++| Flag | Selects |+|------|---------|+| `--unwritten` | Every template (unwritten) page. The default. This is "finish writing the wiki". |+| `--all` | Every page, template or already written. A full rewrite. |+| `--stale` | Every page marked stale (its code changed since it was written). |+| `--path <glob>` | Every page under a path prefix or glob, e.g. `--path src/api` (repeatable). |+| `--page <id>` | One explicit page id, e.g. `--page file_page:src/app.py` (repeatable). |++**Cascade.** Regenerating a file page makes the pages that summarize it drift:+its module, cycle (SCC) and layer pages, and the repo overview, architecture and+onboarding pages. `--cascade` decides what happens to them:++| Value | Behavior |+|-------|----------|+| `none` | Generate exactly what you asked for; mark the dependents stale (truthful, free, instant). |+| `dependents` (default) | Also regenerate the module, SCC and layer pages that contain a selected file; mark the repo-wide pages stale. |+| `full` | Also regenerate the repo overview, architecture and onboarding pages. Nothing is left stale. |++The cost estimate includes the cascade fallout, so it does not under-quote.++**Options:**++| Flag | Description |+|------|-------------|+| `--unwritten` / `--all` / `--stale` | Selection (see above). Default: `--unwritten`. |+| `--path <glob>` | Restrict to a path prefix or glob (repeatable). |+| `--page <id>` | An explicit page id (repeatable). |+| `--cascade none\|dependents\|full` | Dependent-page policy (default: `dependents`). |+| `--provider` / `--model` / `--reasoning` | LLM overrides for this run. |+| `--concurrency` | Max concurrent LLM calls (default: 12). |+| `--dry-run` | Print the plan and the cost estimate; generate nothing. |+| `--yes` / `-y` | Skip the cost confirmation. |+| `--verbose` / `-v` | Show pipeline debug logs. |++```bash+repowise generate --dry-run # what would it write, and cost?+repowise generate # write every unwritten page+repowise generate --all # rewrite the whole wiki+repowise generate --path src/api # just the pages under src/api+repowise generate --page file_page:src/app.py --cascade none # one page, nothing else+repowise generate --stale # refresh pages whose code moved on+```++> It does not build the vector store. If you want semantic search over the new+> prose, run `repowise reindex` afterwards (embedding calls only, no LLM).++---+### `repowise restyle [STYLE] [PATH]`Switch a repo's wiki **style** and regenerate every page in the new voice. Reusesthe existing index, the dependency graph and git metadata are rehydrated fromSQL (no re-resolution, no re-blame), so only the per-file parse + LLM generation-run. Requires a full (docs-enabled) index and a provider; fails on index-only repos.+run. Requires a provider and an existing wiki. On an `--index-only` (template)+repo it doubles as the upgrade: it warns that it will spend, then writes every+page in the chosen style. To write only part of a template wiki, or to preserve+the current style, use [`repowise generate`](#repowise-generate-path) instead.With no `STYLE`, prints the current style and the available choices.diff --git a/docs/start/QUICKSTART.md b/docs/start/QUICKSTART.mdindex 23321c945..cbda02243 100644--- a/docs/start/QUICKSTART.md+++ b/docs/start/QUICKSTART.md@@ -139,24 +139,39 @@ file reads. That is the whole point.> the wiki, which step 2 already built, so they answer from pages rendered from> structure. `search_codebase` is full-text only until you configure an embedder.-## 4. Optional: add a provider for model-written prose+## 4. Optional: upgrade the wiki to model-written prose-Everything so far was deterministic. A provider rewrites the wiki pages as prose-and unlocks architectural decision mining and codebase chat. Semantic search is a-separate step: configure an embedder and run `repowise reindex` to build the-vector store.+Everything so far was deterministic. When you want richer pages, point `repowise+generate` at a provider and it rewrites the template pages as prose (and unlocks+architectural decision mining and chat). You do not have to redo anything: it+reuses the index you already built, so the graph is not re-parsed.++Set a key, preview the cost, then write:```bashexport ANTHROPIC_API_KEY="sk-ant-..." # or OPENAI_API_KEY / GEMINI_API_KEY-repowise init --provider anthropic++repowise generate --dry-run # what would it write, and what does it cost?+repowise generate # write every unwritten page```On Windows PowerShell: `$env:ANTHROPIC_API_KEY = "sk-ant-..."`-`repowise init` on its own is interactive: it asks which provider to use, shows a-cost estimate, and waits for you to confirm before spending anything. How long it-runs and what it costs depend on repo size and the model you pick, both of which-the estimate shows you up front.+You do not have to write the whole wiki at once. Start with the part you care+about and grow from there, each run behind its own cost estimate:++```bash+repowise generate --path src/api # just one area+repowise generate --page file_page:src/app.py # or a single page+repowise generate --all # or rewrite everything+```++Semantic search is a separate step: configure an embedder and run `repowise+reindex` to build the vector store.++Prefer to write the whole wiki as part of a fresh index instead? `repowise init`+on its own is interactive: it asks which provider to use, shows a cost estimate,+and waits for you to confirm before spending anything.Three ways to avoid paying a provider at all:diff --git a/docs/start/USER_GUIDE.md b/docs/start/USER_GUIDE.mdindex b6d138824..b1fef0ca7 100644--- a/docs/start/USER_GUIDE.md+++ b/docs/start/USER_GUIDE.md@@ -82,13 +82,26 @@ The failure mode to avoid is a stale index, because a confidently wrong answer iworse than no answer. Every MCP response carries the indexed commit and warns whenit has diverged from your live `HEAD`, but the real fix is step 3.-**Two modes.** `--index-only` gives you the graph, git intelligence, code health,-change risk and dead code, plus a complete wiki rendered from the code's-structure, with no LLM, no key and no network. Adding a provider rewrites those-pages as model-written prose and unlocks decision mining and chat. You can start-index-only and upgrade later with `repowise update --full`, which reuses the-persisted graph instead of re-parsing it. Semantic search is separate: it needs-an embedder, and `repowise reindex` is what builds the vector store.+**Two modes, one upgrade path.** `--index-only` gives you the graph, git+intelligence, code health, change risk and dead code, plus a complete wiki+rendered from the code's structure, with no LLM, no key and no network. Adding a+provider rewrites those pages as model-written prose and unlocks decision mining+and chat.++You do not have to choose up front. Start index-only, then upgrade the wiki with+`repowise generate` when you are ready, a page, a directory, or the whole thing+at a time, each behind a cost estimate:++```bash+repowise generate --dry-run # what it would write, and what it costs+repowise generate # write every unwritten page+repowise generate --path src/api # or just the part you care about+```++`generate` reuses the persisted graph instead of re-parsing it, so the upgrade is+cheap. (`repowise update --full` still does the whole wiki in one shot if you+prefer.) Semantic search is separate: it needs an embedder, and `repowise+reindex` is what builds the vector store.---@@ -123,6 +136,7 @@ Grouped by what you are trying to do. Every flag for every command lives in the| Command | What it is for ||---|---|| `repowise init` | First index. Interactive: asks for a provider, shows a cost estimate, waits for confirmation. `--index-only` builds the same wiki from structure, with no LLM. |+| `repowise generate` | Write wiki pages with a model, on demand. The upgrade path for an index-only repo: `--unwritten` (default) writes everything still on a template, `--path`/`--page` writes a subset, all behind a cost estimate. || `repowise update` | Incremental catch-up after pulling or committing. Seconds, not minutes. || `repowise watch` | File watcher that updates continuously while you work. || `repowise hook install` | Post-commit hook so syncing happens without you. |@@ -277,8 +291,9 @@ the [Docker image](../../docker/README.md) if you would rather not install Node.to move between views and repos.An index-only repo has a full Docs section, rendered from structure rather than-written by a model, so the pages read as structural summaries. Chat still needs a-provider. Everything else, including Architecture, Code Health, Files, Commits and+written by a model, so the pages read as structural summaries. Run `repowise+generate` to write any of them as model prose later. Chat still needs a provider.+Everything else, including Architecture, Code Health, Files, Commits andContributors, works off the parsed graph and git history alone.Every view and what it answers: **[Dashboard](DASHBOARD.md)**.@@ -296,13 +311,18 @@ repowise init --index-only -y # free, no key, secondsrepowise hook install # keep it current from here on```-Rewrite the wiki with a model and add semantic search when you want them:+Write the pages with a model when you want them, all at once or a piece at a+time, each behind a cost estimate:```bashexport ANTHROPIC_API_KEY="sk-ant-..."-repowise init --provider anthropic+repowise generate --dry-run # preview the plan and the cost+repowise generate # write every unwritten page+repowise generate --path src/api # or just one area first```+Then add semantic search with `repowise reindex` once an embedder is configured.+### First index, multi-repo workspace```bashdiff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/__init__.py b/packages/cli/src/repowise/cli/commands/generate_cmd/__init__.pynew file mode 100644index 000000000..bc7d80f81--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/__init__.py@@ -0,0 +1,7 @@+"""``repowise generate`` — scoped, cost-gated wiki generation."""++from __future__ import annotations++from .command import generate_command++__all__ = ["generate_command"]diff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/command.py b/packages/cli/src/repowise/cli/commands/generate_cmd/command.pynew file mode 100644index 000000000..fc24eafd7--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/command.py@@ -0,0 +1,262 @@+"""``repowise generate`` — write any subset of the wiki with a model.++The single, cost-gated entry point for turning template (unwritten) pages into+LLM prose, or regenerating written ones. Selection is explicit (all / unwritten+/ stale / path / page) and defaults to ``--unwritten``; the cascade mode decides+what happens to the pages that summarize a regenerated file.+"""++from __future__ import annotations++import dataclasses+import sys+import time+from pathlib import Path+from typing import Any++import click++from repowise.cli._setup import configure_cli_logging+from repowise.cli.helpers import (+ console,+ get_head_commit,+ load_config,+ load_state,+ resolve_provider,+ resolve_reasoning,+ resolve_repo_path,+ run_async,+ save_state,+)+from repowise.cli.ui import load_dotenv+from repowise.core.docs_mode import docs_mode_state_fields, resolve_docs_mode+from repowise.core.generation.page_selection import PageSelectionIntent++from .engine import run_scoped_generation+++def _build_intent(+ *,+ all_pages: bool,+ unwritten: bool,+ stale: bool,+ paths: tuple[str, ...],+ page_ids: tuple[str, ...],+) -> PageSelectionIntent:+ """Turn the CLI flags into an intent, defaulting to ``--unwritten``.++ No selection flag means "upgrade everything still on a template", the case+ an index-only user reaches for.+ """+ intent = PageSelectionIntent(+ all_pages=all_pages,+ unwritten=unwritten,+ stale=stale,+ path_globs=paths,+ page_ids=page_ids,+ )+ if intent.is_empty():+ return PageSelectionIntent(unwritten=True)+ return intent+++def _make_gate(dry_run: bool):+ """Return the ``gate_cost`` callback the engine invokes before generating.++ Prints the estimate, stops on ``--dry-run``, and enforces the LLM-cost+ confirmation (reusing init's gate constants). Returns True to proceed.+ """++ def gate_cost(+ cost_plans: Any, provider: Any, repo_path: Path, *, yes: bool, dry_run: bool+ ) -> bool:+ from repowise.cli.commands.init_cmd.generation import (+ COST_GATE_USD,+ cost_gate_declined,+ format_cost,+ )+ from repowise.core.cost_estimator import estimate_cost++ est = None+ try:+ est = estimate_cost(+ cost_plans, provider.provider_name, provider.model_name, repo_path=repo_path+ )+ except Exception as exc:+ console.print(f"[yellow]Cost estimate unavailable ({exc}).[/yellow]")++ if est is not None:+ pages = sum(p.count for p in cost_plans)+ console.print(+ f"Estimated: [bold]{pages}[/bold] pages, [bold]{format_cost(est)}[/bold]."+ )++ if dry_run:+ console.print("[dim]Dry run — nothing generated.[/dim]")+ return False++ if est is not None:+ 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 at this cost?"):+ console.print("[yellow]Aborted.[/yellow] Nothing generated.")+ return False+ return True++ return gate_cost++[email protected]("generate")[email protected]("path", required=False, default=None)[email protected]("--all", "all_pages", is_flag=True, default=False, help="Regenerate every page.")+ "--unwritten",+ is_flag=True,+ default=False,+ help="Write every template (unwritten) page. The default when no selection is given.",+)[email protected]("--stale", is_flag=True, default=False, help="Regenerate pages marked stale.")+ "--path",+ "path_globs",+ multiple=True,+ help="Restrict to pages under a path prefix or glob (repeatable).",+)+ "--page",+ "page_ids",+ multiple=True,+ help="An explicit page id to generate (repeatable).",+)+ "--cascade",+ type=click.Choice(["none", "dependents", "full"]),+ default="dependents",+ help="What to do with the module/overview pages that summarize a regenerated file.",+)[email protected]("--provider", "provider_name", default=None, help="LLM provider name.")[email protected]("--model", default=None, help="Model identifier override.")[email protected]("--reasoning", default=None, help="Reasoning mode override.")[email protected]("--concurrency", type=int, default=12, help="Max concurrent LLM calls.")+ "--dry-run", is_flag=True, default=False, help="Print the plan and estimate; generate nothing."+)[email protected]("--yes", "-y", is_flag=True, default=False, help="Skip the cost confirmation.")[email protected]("--verbose", "-v", is_flag=True, default=False, help="Show pipeline debug logs.")+def generate_command(+ path: str | None,+ all_pages: bool,+ unwritten: bool,+ stale: bool,+ path_globs: tuple[str, ...],+ page_ids: tuple[str, ...],+ cascade: str,+ provider_name: str | None,+ model: str | None,+ reasoning: str | None,+ concurrency: int,+ dry_run: bool,+ yes: bool,+ verbose: bool,+) -> None:+ """Write wiki pages with a model. Defaults to every unwritten page.++ Examples:+ repowise generate # write every template page+ repowise generate --all # rewrite the whole wiki+ repowise generate --path src/api # just the pages under src/api+ repowise generate --page file_page:src/app.py --cascade none+ """+ configure_cli_logging(verbose=verbose)++ repo_path = resolve_repo_path(path)+ load_dotenv(repo_path)+ state = load_state(repo_path)+ if not state:+ raise click.ClickException(f"No index found at {repo_path}. Run `repowise init` first.")++ cfg = load_config(repo_path)+ intent = _build_intent(+ all_pages=all_pages,+ unwritten=unwritten,+ stale=stale,+ paths=path_globs,+ page_ids=page_ids,+ )++ # Provider is required — a model writes these pages. A missing one is an+ # actionable error (resolve_provider names the key-setup path), not a trace.+ provider = resolve_provider(provider_name, model, repo_path=repo_path)++ console.print(+ f"[bold]repowise generate[/bold] — {repo_path}\n"+ f"Provider: [cyan]{provider.provider_name}[/cyan] / [cyan]{provider.model_name}[/cyan]"+ )++ from repowise.core.generation import GenerationConfig++ config = GenerationConfig(+ max_concurrency=concurrency,+ language=cfg.get("language", "en"),+ reasoning=resolve_reasoning(reasoning, cfg),+ enable_onboarding=bool(cfg.get("enable_onboarding", True)),+ wiki_style=cfg.get("wiki_style", "comprehensive"),+ )+ tier1_top_n = cfg.get("tier1_top_n")+ if tier1_top_n is not None:+ config = dataclasses.replace(config, tier1_top_n=tier1_top_n)++ exclude_patterns = list(cfg.get("exclude_patterns") or [])+ embedder_name = cfg.get("embedder")++ start = time.monotonic()+ outcome = run_async(+ run_scoped_generation(+ repo_path,+ provider,+ config,+ intent=intent,+ cascade_mode=cascade, # type: ignore[arg-type]+ exclude_patterns=exclude_patterns,+ embedder_name=embedder_name,+ yes=yes,+ dry_run=dry_run,+ gate_cost=_make_gate(dry_run),+ )+ )++ if outcome is None:+ return # nothing generated, dry run, or declined — messaging already printed++ _write_state(repo_path, state, provider, outcome)++ elapsed = time.monotonic() - start+ tail = (+ f", {outcome.remaining_template_pages} still unwritten"+ if outcome.remaining_template_pages+ else " — every page is now written"+ )+ stale_note = f", {outcome.marked_stale} marked stale" if outcome.marked_stale else ""+ console.print(+ f"[bold green]Generated {len(outcome.generated_pages)} pages[/bold green] "+ f"in {elapsed:.1f}s{stale_note}{tail}."+ )+++def _write_state(repo_path: Path, state: dict, provider: Any, outcome: Any) -> None:+ """Persist the post-run state: page count, provider, and docs mode.++ docs_mode flips to ``llm`` only once no template page remains — a partial+ upgrade leaves a mixed wiki, so it keeps its current mode rather than+ over-claiming that everything is written.+ """+ state["last_sync_commit"] = get_head_commit(repo_path)+ state["total_pages"] = outcome.total_pages+ state["provider"] = provider.provider_name+ state["model"] = provider.model_name+ if outcome.remaining_template_pages == 0 and resolve_docs_mode(state) != "llm":+ state.update(docs_mode_state_fields("llm"))+ save_state(repo_path, state)diff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/engine.py b/packages/cli/src/repowise/cli/commands/generate_cmd/engine.pynew file mode 100644index 000000000..1e39088fc--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/engine.py@@ -0,0 +1,308 @@+"""The ``repowise generate`` engine: rehydrate -> scope -> gate -> generate.++Mirrors the upgrade/restyle flows (rehydrate the graph and git from SQL,+re-parse for ASTs, run generation, persist + FTS + embed) but drives the+generation through ``only_page_ids`` so it writes exactly the requested subset,+then marks the uncovered dependents stale and heals backlinks LLM-free.+"""++from __future__ import annotations++from dataclasses import dataclass+from pathlib import Path+from typing import Any++from repowise.cli.helpers import console+from repowise.core.generation.cascade import CascadeMode+from repowise.core.generation.page_selection import PageSelectionIntent++from .scope import ScopePlan, build_dependencies, load_page_records, resolve_scope+++@dataclass+class GenerateOutcome:+ """What a generate run produced, for the command's state write + report."""++ generated_pages: list[Any]+ total_pages: int+ marked_stale: int+ remaining_template_pages: int+ plan: ScopePlan+++async def run_scoped_generation(+ repo_path: Path,+ provider: Any,+ config: Any,+ *,+ intent: PageSelectionIntent,+ cascade_mode: CascadeMode,+ exclude_patterns: list[str],+ embedder_name: str | None,+ yes: bool,+ dry_run: bool,+ gate_cost: Any,+) -> GenerateOutcome | None:+ """Resolve the scope, gate on cost, generate, persist, and heal.++ Returns ``None`` when there was nothing to do (empty scope) or the run was a+ ``--dry-run``. ``gate_cost`` is injected (the upgrade flow's estimator ++ confirm) so this module stays free of the cost-gate UI.+ """+ from repowise.cli.commands.upgrade_flow import _reparse+ from repowise.cli.helpers import get_db_url_for_repo+ from repowise.cli.providers import (+ build_embedder,+ build_vector_store,+ cost_tracking_disabled,+ resolve_embedder,+ )+ from repowise.core.generation.cost_tracker import CostTracker+ from repowise.core.generation.kg_context import KnowledgeGraphContext+ from repowise.core.persistence import (+ create_engine,+ create_session_factory,+ get_session,+ init_db,+ upsert_pages_from_generated,+ upsert_repository,+ )+ from repowise.core.persistence.crud import backfill_related_pages+ from repowise.core.pipeline import rehydrate_graph_builder, run_generation+ from repowise.core.pipeline.persist import mark_page_ids_stale+ from repowise.core.pipeline.resume.rehydrate import rehydrate_git_meta_map++ url = get_db_url_for_repo(repo_path)+ engine = create_engine(url)+ await init_db(engine)+ sf = create_session_factory(engine)++ try:+ 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++ # Rehydrate the graph + git signals from SQL — no re-resolve, no re-blame.+ async with get_session(sf) as session:+ graph_builder = await rehydrate_graph_builder(session, repo_id, repo_path)+ git_meta_map = await rehydrate_git_meta_map(session, repo_id)+ records = load_page_records(await _load_pages(session, repo_id))++ if not records:+ console.print(+ "[yellow]This repo has no wiki pages yet.[/yellow] "+ "Run `repowise init --index-only` or `repowise update --full` first."+ )+ return None++ parsed_files, source_map, repo_structure = _reparse(repo_path, exclude_patterns)+ console.print(+ f"Re-parsed [cyan]{len(parsed_files)}[/cyan] files (graph + git reused from index)."+ )++ repo_name = repo_path.name+ kg_ctx = _load_kg_ctx(repo_path, KnowledgeGraphContext)+ deps = build_dependencies(+ parsed_files=parsed_files,+ graph_builder=graph_builder,+ config=config,+ kg_ctx=kg_ctx,+ records=records,+ repo_name=repo_name,+ )+ plan = resolve_scope(records=records, intent=intent, cascade_mode=cascade_mode, deps=deps)++ if plan.unknown_page_ids:+ console.print(+ "[yellow]No such page(s), skipped:[/yellow] " + ", ".join(plan.unknown_page_ids)+ )+ if not plan.generate_ids:+ console.print("[yellow]Nothing to generate for that selection.[/yellow]")+ return None++ _report_plan(plan, cascade_mode)++ # Cost gate (and the dry-run stop) share the same estimate.+ proceed = gate_cost(plan.cost_plans, provider, repo_path, yes=yes, dry_run=dry_run)+ if not proceed:+ return None++ # Construct the tracker directly (we are already in the event loop, so+ # the run_async-based build_cost_tracker helper would fail here).+ # buffered=True defers cost INSERTs to a single post-generation flush.+ if cost_tracking_disabled():+ cost_tracker = CostTracker()+ else:+ cost_tracker = CostTracker(session_factory=sf, repo_id=repo_id, buffered=True)+ provider._cost_tracker = cost_tracker++ 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:+ # Null BOTH on any failure. If the embedder built but the store did+ # not, a non-None embedder would make run_generation embed into a+ # throwaway in-memory store — pages silently absent from semantic+ # search while we claimed embedding was skipped.+ embedder = None+ vector_store = None+ console.print(f"[yellow]Embedding skipped: {exc}[/yellow]")++ generated_pages = await run_generation(+ 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,+ llm_client=provider,+ embedder=embedder,+ vector_store=vector_store,+ concurrency=config.max_concurrency,+ progress=None,+ cost_tracker=cost_tracker,+ generation_config=config,+ only_page_ids=plan.generate_ids,+ )+ await cost_tracker.flush()++ marked_stale = 0+ async with get_session(sf) as session:+ await upsert_pages_from_generated(session, generated_pages, repo_id)+ # Dependents this run did not regenerate go stale, not wrong.+ marked_stale = await mark_page_ids_stale(session, repo_id, plan.stale_ids)+ # Heal backlinks + related-pages across the whole wiki, LLM-free. The+ # pages this run just wrote already carry fresh metadata, so skip them.+ # This is O(total pages), same as the incremental-update path's heal;+ # a narrow scope on a huge wiki pays for the whole table. Upgrade path+ # if that ever bites: scope the heal to the regenerated pages' import+ # neighborhood. Kept whole-wiki for now to match the update flow and+ # because it is LLM-free (cheap next to the generation it follows).+ try:+ from repowise.core.generation.related_pages import file_import_edges++ await backfill_related_pages(+ session,+ repo_id,+ import_edges=file_import_edges(graph_builder),+ git_meta_map=git_meta_map,+ pagerank=graph_builder.pagerank(),+ skip_page_ids={p.page_id for p in generated_pages},+ )+ except Exception as exc:+ console.print(f"[dim]Related-pages backfill skipped: {exc}[/dim]")++ await _index_fts(engine, generated_pages)++ total_pages, remaining_templates = await _page_stats(sf, repo_id)+ return GenerateOutcome(+ generated_pages=generated_pages,+ total_pages=total_pages,+ marked_stale=marked_stale,+ remaining_template_pages=remaining_templates,+ plan=plan,+ )+ finally:+ await engine.dispose()+++async def _load_pages(session: Any, repo_id: str) -> list[Any]:+ """Every non-tombstoned persisted page, lightweight columns only.++ ``load_page_records`` reads just id/type/target/provider/metadata/freshness,+ so ``load_only`` keeps the (potentially very large) ``content`` Text column+ out of this whole-wiki scan.+ """+ from sqlalchemy import select+ from sqlalchemy.orm import load_only++ from repowise.core.persistence.models import Page++ result = await session.execute(+ select(Page)+ .options(+ load_only(+ Page.id,+ Page.page_type,+ Page.target_path,+ Page.provider_name,+ Page.metadata_json,+ Page.freshness_status,+ )+ )+ .where(+ Page.repository_id == repo_id,+ Page.freshness_status != "tombstone",+ )+ )+ return list(result.scalars())+++def _load_kg_ctx(repo_path: Path, kg_ctx_cls: Any) -> Any:+ """Load the persisted KG artifact for layer membership (None-safe)."""+ kg_path = repo_path / ".repowise" / "knowledge-graph.json"+ if kg_path.exists():+ return kg_ctx_cls(kg_path)+ return kg_ctx_cls(None)+++async def _index_fts(engine: Any, generated_pages: list[Any]) -> None:+ """Best-effort full-text (re)index of the freshly generated pages."""+ try:+ from repowise.core.persistence import FullTextSearch++ fts = FullTextSearch(engine)+ await fts.ensure_index()+ for page in generated_pages:+ await fts.index(page.page_id, page.title, page.content)+ except Exception:+ pass # FTS indexing is best-effort+++async def _page_stats(sf: Any, repo_id: str) -> tuple[int, int]:+ """Return ``(total_pages, remaining_template_pages)`` from the DB."""+ from sqlalchemy import func as sa_func+ from sqlalchemy import select as sa_select++ from repowise.core.persistence import get_session+ from repowise.core.persistence.models import Page++ async with get_session(sf) as session:+ total = int(+ (+ await session.execute(+ sa_select(sa_func.count())+ .select_from(Page)+ .where(Page.repository_id == repo_id)+ )+ ).scalar_one()+ )+ templates = int(+ (+ await session.execute(+ sa_select(sa_func.count())+ .select_from(Page)+ .where(+ Page.repository_id == repo_id,+ Page.provider_name == "template",+ )+ )+ ).scalar_one()+ )+ return total, templates+++def _report_plan(plan: ScopePlan, cascade_mode: CascadeMode) -> None:+ """Print the resolved plan (counts by type + cascade summary)."""+ by_type: dict[str, int] = {}+ for p in plan.cost_plans:+ by_type[p.page_type] = p.count+ breakdown = ", ".join(f"{n} {t}" for t, n in by_type.items())+ console.print(+ f"Plan: [bold]{sum(by_type.values())}[/bold] pages "+ f"({breakdown or 'none'}) · cascade: [cyan]{cascade_mode}[/cyan]"+ )+ if plan.stale_ids:+ console.print(f" {len(plan.stale_ids)} dependent page(s) will be marked stale.")diff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/scope.py b/packages/cli/src/repowise/cli/commands/generate_cmd/scope.pynew file mode 100644index 000000000..e5e283bb3--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/scope.py@@ -0,0 +1,178 @@+"""Resolve a ``repowise generate`` request into a concrete page-id set.++Pure, side-effect-free helpers: given the persisted pages and the freshly+rehydrated graph, turn the user's intent (all / unwritten / stale / paths /+ids) plus a cascade mode into the ``only_page_ids`` set the engine generates,+the dependents to mark stale, and the cost plan (which includes the cascade+fallout, so the estimate does not under-quote).+"""++from __future__ import annotations++import json+from dataclasses import dataclass+from typing import Any++from repowise.core.cost_estimator.types import PageTypePlan+from repowise.core.generation import GENERATION_LEVELS+from repowise.core.generation.cascade import (+ CascadeMode,+ CascadeResult,+ PageDependencies,+ build_page_dependencies,+ expand_cascade,+)+from repowise.core.generation.models import compute_page_id+from repowise.core.generation.page_selection import (+ PageRecord,+ PageSelectionIntent,+ resolve_page_selection,+)+from repowise.core.generation.selection import SelectionInputs, select_pages++# Page types that describe the whole repository (as opposed to one file/module).+_REPO_WIDE_TYPES = frozenset({"repo_overview", "architecture_diagram", "onboarding"})+++@dataclass(frozen=True)+class ScopePlan:+ """Everything the engine needs to run and report one scoped generation."""++ generate_ids: set[str]+ stale_ids: set[str]+ cost_plans: list[PageTypePlan]+ unknown_page_ids: tuple[str, ...]+ seed_count: int+++def load_page_records(pages: list[Any]) -> list[PageRecord]:+ """Build :class:`PageRecord` views from persisted ``Page`` rows.++ A page is "template" (unwritten) when a model never touched it: the+ template provider stamps ``provider_name='template'`` and+ ``metadata.deterministic=True``. Either signal is enough.+ """+ records: list[PageRecord] = []+ for p in pages:+ try:+ meta = json.loads(getattr(p, "metadata_json", None) or "{}")+ except ValueError:+ meta = {}+ is_template = getattr(p, "provider_name", "") == "template" or bool(+ meta.get("deterministic")+ )+ records.append(+ PageRecord(+ page_id=p.id,+ page_type=p.page_type,+ target_path=p.target_path,+ is_template=is_template,+ freshness_status=getattr(p, "freshness_status", "fresh"),+ )+ )+ return records+++def _layer_membership(kg_ctx: Any) -> dict[str, str]:+ """Map each file path to its ``layer_page:<id>`` from KG layer membership."""+ out: dict[str, str] = {}+ if not (kg_ctx and getattr(kg_ctx, "available", False)):+ return out+ from repowise.core.analysis.knowledge_graph import _slugify++ for layer in kg_ctx.get_layers():+ layer_id = layer.get("id") or f"layer:{_slugify(layer.get('name', ''))}"+ page_id = compute_page_id("layer_page", layer_id)+ for nid in layer.get("nodeIds", []):+ if isinstance(nid, str) and nid.startswith("file:"):+ out.setdefault(nid[5:], page_id)+ return out+++def build_dependencies(+ *,+ parsed_files: list[Any],+ graph_builder: Any,+ config: Any,+ kg_ctx: Any,+ records: list[PageRecord],+ repo_name: str,+) -> PageDependencies:+ """Compute the structural file -> container-page map for cascade.++ Uses the same full-coverage selection the engine will use+ (``select_all=True``), so the module/SCC page ids it derives match the ones+ generation emits. Repo-wide ids are the overview + architecture pages+ (keyed by repo name) plus every persisted onboarding page.+ """+ try:+ community_info_map = graph_builder.community_info() or {}+ except Exception:+ community_info_map = {}++ kg_modules = None+ if kg_ctx and getattr(kg_ctx, "available", False):+ kg_modules = kg_ctx.get_modules() or None++ selection = select_pages(+ SelectionInputs(+ parsed_files=parsed_files,+ pagerank=graph_builder.pagerank(),+ betweenness=graph_builder.betweenness_centrality(),+ community=graph_builder.community_detection(),+ community_info=community_info_map,+ sccs=list(graph_builder.strongly_connected_components()),+ git_meta_map=None,+ config=config,+ kg_modules=kg_modules,+ select_all=True,+ )+ )++ repo_wide_ids = [+ compute_page_id("repo_overview", repo_name),+ compute_page_id("architecture_diagram", repo_name),+ ]+ repo_wide_ids += [r.page_id for r in records if r.page_type == "onboarding"]++ return build_page_dependencies(+ module_groups=selection.module_groups,+ scc_groups=selection.scc_groups,+ layer_page_of=_layer_membership(kg_ctx),+ repo_wide_ids=repo_wide_ids,+ )+++def build_cost_plans(generate_ids: set[str]) -> list[PageTypePlan]:+ """Group the id set by page type into cost-estimator plans.++ Because ``generate_ids`` already carries the cascade fallout, the resulting+ estimate covers it too — the under-quote the plan warned about.+ """+ counts: dict[str, int] = {}+ for pid in generate_ids:+ ptype = pid.split(":", 1)[0]+ counts[ptype] = counts.get(ptype, 0) + 1+ return [+ PageTypePlan(page_type=ptype, count=n, level=GENERATION_LEVELS.get(ptype, 2))+ for ptype, n in sorted(counts.items(), key=lambda kv: GENERATION_LEVELS.get(kv[0], 2))+ ]+++def resolve_scope(+ *,+ records: list[PageRecord],+ intent: PageSelectionIntent,+ cascade_mode: CascadeMode,+ deps: PageDependencies,+) -> ScopePlan:+ """Resolve intent -> seeds -> cascade -> the full scope plan."""+ seeds = resolve_page_selection(records, intent)+ cascade: CascadeResult = expand_cascade(set(seeds.page_ids), cascade_mode, deps)+ return ScopePlan(+ generate_ids=cascade.generate_ids,+ stale_ids=cascade.stale_ids,+ cost_plans=build_cost_plans(cascade.generate_ids),+ unknown_page_ids=seeds.unknown_page_ids,+ seed_count=len(seeds),+ )diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.pyindex 9597de320..b9a7ddcc3 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py@@ -563,6 +563,15 @@ def run_update(if head and head == base_ref and not config_changed:console.print("[green]Already up to date.[/green]")+ # D7: on a template (index-only) wiki, "up to date" is true of the code+ # but the pages are still unwritten. Point at the command that writes+ # them rather than leaving the user at a dead end, the way `update+ # --docs` used to (it computed base_ref == head and stopped here).+ if resolve_docs_mode(state) == "deterministic":+ console.print(+ "[dim]The wiki is rendered from templates. "+ "Run [bold]repowise generate[/bold] to write pages with a model.[/dim]"+ )if prev_config_fp is None and not dry_run:save_state(repo_path, {**state, "config_fingerprint": curr_config_fp})# Self-heal a row a pre-fix run left behind: state.json can already be@@ -925,6 +934,16 @@ def run_update(tier2_tail_enabled=bool(cfg.get("tier2_tail_enabled", True)),tier2_tail_cap=cfg.get("tier2_tail_cap"),tier2_tail_dirs=tuple(tail_dirs_cfg) if tail_dirs_cfg else None,+ # An incremental update regenerates only the changed files' pages, and+ # it feeds generate_all a parsed_files filtered to those files. Levels 3+ # and up describe the whole repository from parsed_files, so without+ # this a one-commit update would rewrite the codebase map, module and+ # overview pages from a truncated view (a module page claiming one file,+ # a codebase map with no directories). Stop the ladder after level 2 and+ # leave the repo-wide pages for a full run — the same guard the+ # deterministic index-only update already uses. `repowise generate`+ # refreshes the repo-wide pages correctly, from the complete view.+ file_pages_only=True,)# Resolve the generation provider. If the repo wants docs but was neverdiff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.pyindex fc60ae35c..93543b485 100644--- a/packages/cli/src/repowise/cli/main.py+++ b/packages/cli/src/repowise/cli/main.py@@ -18,6 +18,7 @@ from repowise.cli.commands.distill_cmd import distill_commandfrom repowise.cli.commands.doctor_cmd import doctor_commandfrom repowise.cli.commands.expand_cmd import expand_commandfrom repowise.cli.commands.export_cmd import export_command+from repowise.cli.commands.generate_cmd import generate_commandfrom repowise.cli.commands.health_cmd import health_commandfrom repowise.cli.commands.hook_cmd import hook_groupfrom repowise.cli.commands.impacted_tests_cmd import impacted_tests_command@@ -68,6 +69,7 @@ register_command(delete_command)register_command(claude_md_command)register_command(costs_command)register_command(update_command)+register_command(generate_command)register_command(dead_code_command)register_command(health_command)register_command(risk_command)diff --git a/packages/core/src/repowise/core/generation/__init__.py b/packages/core/src/repowise/core/generation/__init__.pyindex 1cb2d71bc..f163ef0ef 100644--- a/packages/core/src/repowise/core/generation/__init__.py+++ b/packages/core/src/repowise/core/generation/__init__.py@@ -55,6 +55,15 @@ _EXPORTS = {"attach_wiki_links_and_backlinks": ".interlinking","resolve_wiki_links": ".interlinking","attach_related_pages": ".related_pages",+ "CascadeMode": ".cascade",+ "CascadeResult": ".cascade",+ "PageDependencies": ".cascade",+ "build_page_dependencies": ".cascade",+ "expand_cascade": ".cascade",+ "PageRecord": ".page_selection",+ "PageSelectionIntent": ".page_selection",+ "PageSelectionResult": ".page_selection",+ "resolve_page_selection": ".page_selection","SUPPORTED_LANGUAGES": ".languages","SYSTEM_PROMPTS": ".page_generator","PageGenerator": ".page_generator",diff --git a/packages/core/src/repowise/core/generation/cascade.py b/packages/core/src/repowise/core/generation/cascade.pynew file mode 100644index 000000000..5d8c69c2f--- /dev/null+++ b/packages/core/src/repowise/core/generation/cascade.py@@ -0,0 +1,145 @@+"""Cascade policy for scoped generation.++Regenerating a file page makes the pages that summarize it drift: its module+page, the cycle (SCC) pages it belongs to, its architectural layer page, and+the repo-wide overview / architecture / onboarding pages. Backlinks on other+pages that point at it also go stale. The healer ``backfill_related_pages``+repairs backlinks LLM-free after any run; this module decides what to do about+the *content* of the dependent pages.++Three policies, chosen by the user:++* ``none`` — generate exactly what was asked; mark every structural dependent+ stale (truthful, free, instant).+* ``dependents`` — also regenerate the module, SCC and layer pages that+ contain a seeded file; mark the repo-wide pages stale.+* ``full`` — also regenerate the repo-wide pages. Nothing is left stale.++The dependent set is computed structurally from the selection graph and KG+layer membership, so it is exact rather than a heuristic cascade.+"""++from __future__ import annotations++from collections.abc import Iterable+from dataclasses import dataclass, field+from typing import Any, Literal++from .models import compute_page_id++CascadeMode = Literal["none", "dependents", "full"]++_FILE_PAGE_PREFIX = "file_page:"+++@dataclass(frozen=True)+class PageDependencies:+ """Which container pages each file page rolls up into.++ Built once per run from the in-memory selection and KG layers. All values+ are page ids (``module_page:...``, ``scc_page:...``, ``layer_page:...``),+ ready to drop straight into an ``only_page_ids`` set.+ """++ module_page_of: dict[str, str] = field(default_factory=dict)+ scc_pages_of: dict[str, tuple[str, ...]] = field(default_factory=dict)+ layer_page_of: dict[str, str] = field(default_factory=dict)+ repo_wide_ids: tuple[str, ...] = ()++ def containers_of(self, file_path: str) -> set[str]:+ """Module + SCC + layer page ids that summarize *file_path*."""+ ids: set[str] = set()+ mod = self.module_page_of.get(file_path)+ if mod:+ ids.add(mod)+ ids.update(self.scc_pages_of.get(file_path, ()))+ layer = self.layer_page_of.get(file_path)+ if layer:+ ids.add(layer)+ return ids+++@dataclass(frozen=True)+class CascadeResult:+ """Outcome of expanding a seed set under a cascade mode.++ ``generate_ids`` is the full ``only_page_ids`` set the engine should emit;+ ``stale_ids`` are dependents left unregenerated that the caller should mark+ stale (never overlaps ``generate_ids``).+ """++ generate_ids: set[str]+ stale_ids: set[str]+++def build_page_dependencies(+ *,+ module_groups: Iterable[Any],+ scc_groups: Iterable[tuple[str, Iterable[str]]],+ layer_page_of: dict[str, str] | None = None,+ repo_wide_ids: Iterable[str] = (),+) -> PageDependencies:+ """Invert the selection groups into per-file container page ids.++ ``module_groups`` are duck-typed selection ``ModuleGroup`` objects (``.key``+ + ``.file_paths``); ``scc_groups`` are ``(scc_id, files)`` pairs, exactly as+ :class:`~repowise.core.generation.selection.Selection` carries them.+ ``layer_page_of`` maps a file path to its ``layer_page:<id>`` (from KG layer+ membership; empty when the repo has no KG).+ """+ module_page_of: dict[str, str] = {}+ for group in module_groups:+ page_id = compute_page_id("module_page", group.key)+ for path in group.file_paths:+ module_page_of.setdefault(path, page_id)++ scc_pages_of: dict[str, list[str]] = {}+ for scc_id, files in scc_groups:+ page_id = compute_page_id("scc_page", scc_id)+ for path in files:+ scc_pages_of.setdefault(path, []).append(page_id)++ return PageDependencies(+ module_page_of=module_page_of,+ scc_pages_of={p: tuple(v) for p, v in scc_pages_of.items()},+ layer_page_of=dict(layer_page_of or {}),+ repo_wide_ids=tuple(repo_wide_ids),+ )+++def _seed_file_paths(seed_ids: set[str]) -> set[str]:+ """Repo-relative paths of the file-page seeds (others carry no file cascade)."""+ return {pid[len(_FILE_PAGE_PREFIX) :] for pid in seed_ids if pid.startswith(_FILE_PAGE_PREFIX)}+++def expand_cascade(+ seed_ids: set[str],+ mode: CascadeMode,+ deps: PageDependencies,+) -> CascadeResult:+ """Expand *seed_ids* into the pages to generate and the pages to mark stale.++ The container set (module/SCC/layer pages of the seeded files) and the+ repo-wide set are the two rings of fallout. ``none`` regenerates neither and+ marks both stale; ``dependents`` regenerates the containers and marks+ repo-wide stale; ``full`` regenerates both and marks nothing.+ """+ seed_files = _seed_file_paths(seed_ids)+ containers: set[str] = set()+ for path in seed_files:+ containers.update(deps.containers_of(path))+ repo_wide = set(deps.repo_wide_ids)++ if mode == "full":+ generate = seed_ids | containers | repo_wide+ stale: set[str] = set()+ elif mode == "dependents":+ generate = seed_ids | containers+ stale = repo_wide+ else: # "none"+ generate = set(seed_ids)+ stale = containers | repo_wide++ # A page is never both regenerated and marked stale; regeneration wins.+ stale -= generate+ return CascadeResult(generate_ids=generate, stale_ids=stale)diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.pyindex a3389d926..be40f0ab1 100644--- a/packages/core/src/repowise/core/generation/models.py+++ b/packages/core/src/repowise/core/generation/models.py@@ -205,8 +205,15 @@ class GenerationConfig:# 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.+ # Set by every incremental path (deterministic and LLM), which regenerates+ # the changed files' pages and leaves the repo-wide ones for a full run.+ #+ # This is the coarse, structural sibling of ``generate_all``'s per-call+ # ``only_page_ids``: it stops the level ladder entirely rather than+ # building levels 3-8 and filtering them to an empty set, so an incremental+ # run does no repo-wide work at all. ``only_page_ids`` is the general form+ # (emit an arbitrary subset from the complete repo view) and is what+ # ``repowise generate`` uses to refresh those repo-wide pages on demand.file_pages_only: bool = Falsedef __post_init__(self) -> None:diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.pyindex 37fa25f6a..163041cec 100644--- a/packages/core/src/repowise/core/generation/page_generator/core.py+++ b/packages/core/src/repowise/core/generation/page_generator/core.py@@ -217,12 +217,21 @@ class PageGenerator(PerTypeGenerationMixin, DeterministicRenderMixin):on_page_ready: Callable[[GeneratedPage], None] | None = None,kg_modules: list[dict] | None = None,kg_data: dict | None = None,+ only_page_ids: set[str] | None = None,) -> list[GeneratedPage]:"""Generate all wiki pages for a repository.Runs generation in ordered levels. Each level's pages are generatedconcurrently (up to config.max_concurrency). Failures within a levelare logged but do not abort the remaining levels.++ When ``only_page_ids`` is set, every level emits only the pages whose+ id is in the set. The whole repository is still parsed and its graph+ built, so a repo-wide page (overview, architecture, a module) that IS+ requested is generated from the complete view rather than a truncated+ one. This is the scoped-generation primitive behind ``repowise+ generate`` and the fix for callers that used to regenerate ten+ repo-wide pages as a side effect of asking for one file page."""from .orchestrate import run_generate_all@@ -246,6 +255,7 @@ class PageGenerator(PerTypeGenerationMixin, DeterministicRenderMixin):on_page_ready=on_page_ready,kg_modules=kg_modules,kg_data=kg_data,+ only_page_ids=only_page_ids,)# ------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.pyindex 4ebf664f9..d202d5001 100644--- a/packages/core/src/repowise/core/generation/page_generator/levels.py+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py@@ -40,7 +40,7 @@ def build_level01_coros(run: _GenerationRun) -> list[tuple[str, Any]]:gen.generate_api_contract(p, run.source_map.get(p.file_info.path, b"")),)for p in api_files- if compute_page_id("api_contract", p.file_info.path) not in run.completed_ids+ if run._emit(compute_page_id("api_contract", p.file_info.path))]# ---- Level 1: symbol_spotlight (allow-set filtered) ----@@ -62,8 +62,7 @@ def build_level01_coros(run: _GenerationRun) -> list[tuple[str, Any]]:),)for sym, pf in top_symbols- if compute_page_id("symbol_spotlight", f"{pf.file_info.path}::{sym.name}")- not in run.completed_ids+ if run._emit(compute_page_id("symbol_spotlight", f"{pf.file_info.path}::{sym.name}"))]return level0 + level1@@ -188,6 +187,13 @@ async def build_level2_coros(run: _GenerationRun) -> list[tuple[str, Any]]:Context is assembled for ALL code files (module pages need it). Pages areemitted only for files in the selection allow-set. Tier-1 paths get thefull LLM path; tier-2 paths get the deterministic template renderer.++ Known cost on a scoped run (``only_page_ids``): this still assembles every+ code file's context even when the scope emits a handful of pages, because+ ``run.file_page_contexts`` feeds the module/SCC/layer builders. It is pure+ CPU, no LLM, and bounded by the reparse the caller already paid. Upgrade+ path if it bites on a very large repo: restrict assembly to the emitted file+ pages plus the member files of the emitted module/SCC/layer pages."""gen = run.gen_topo_order_code_files(run)@@ -226,7 +232,7 @@ async def build_level2_coros(run: _GenerationRun) -> list[tuple[str, Any]]:return (path in run.sel_file_pathsand path in run.tier1_paths- and compute_page_id("file_page", path) not in run.completed_ids+ and run._emit(compute_page_id("file_page", path)))rag_prefetched = await _prefetch_rag_context(@@ -238,7 +244,7 @@ async def build_level2_coros(run: _GenerationRun) -> list[tuple[str, Any]]:for p, ctx in items:path = p.file_info.pathpid = compute_page_id("file_page", path)- if pid in run.completed_ids:+ if not run._emit(pid):continueif path in run.sel_file_paths:if path in run.tier1_paths:@@ -260,7 +266,7 @@ def build_level3_coros(run: _GenerationRun) -> list[tuple[str, Any]]:for scc_id, scc_files in run.sel_scc_groups:fc_list = [run.file_page_contexts[f] for f in scc_files if f in run.file_page_contexts]pid = compute_page_id("scc_page", scc_id)- if pid not in run.completed_ids:+ if run._emit(pid):coros.append((pid, gen.generate_scc_page(scc_id, scc_files, fc_list)))return coros@@ -274,7 +280,7 @@ def build_level4_coros(run: _GenerationRun) -> list[tuple[str, Any]]:if not fcs:continuepage_id = compute_page_id("module_page", mg.key)- if page_id in run.completed_ids:+ if not run._emit(page_id):continuecoros.append((@@ -329,7 +335,7 @@ def build_level5_coros(run: _GenerationRun) -> list[tuple[str, Any]]:# time and never changes under enrichment.layer_id = layer.get("id", "") or f"layer:{_slugify(layer_name)}"page_id = compute_page_id("layer_page", layer_id)- if page_id in run.completed_ids:+ if not run._emit(page_id):continuekey_files: list[dict] = []@@ -385,7 +391,7 @@ def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:"""Level 6 (repo_overview + architecture_diagram)."""gen = run.gencoros: list[tuple[str, Any]] = []- if compute_page_id("repo_overview", run.repo_name) not in run.completed_ids:+ if run._emit(compute_page_id("repo_overview", run.repo_name)):coros.append((compute_page_id("repo_overview", run.repo_name),@@ -402,7 +408,7 @@ def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:),))- if compute_page_id("architecture_diagram", run.repo_name) not in run.completed_ids:+ if run._emit(compute_page_id("architecture_diagram", run.repo_name)):from ..architecture_mermaid import build_overview_mermaidoverview_mermaid = build_overview_mermaid(run.kg_ctx)@@ -434,7 +440,7 @@ def build_level7_coros(run: _GenerationRun) -> list[tuple[str, Any]]:gen.generate_infra_page(p, run.source_map.get(p.file_info.path, b"")),)for p in infra_files- if compute_page_id("infra_page", p.file_info.path) not in run.completed_ids+ if run._emit(compute_page_id("infra_page", p.file_info.path))]@@ -478,7 +484,7 @@ def build_level8_coros(run: _GenerationRun) -> list[tuple[str, Any]]:)for spec in specs:page_id = compute_page_id("onboarding", _onboarding.target_path(spec.slot))- if page_id in run.completed_ids:+ if not run._emit(page_id):continuecoros.append((page_id, gen.generate_onboarding_page(spec, signals)))return corosdiff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.pyindex c7b0b3407..abeef61dd 100644--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py@@ -62,10 +62,17 @@ class _GenerationRun:on_page_ready: Callable[[GeneratedPage], None] | None = None,kg_modules: list[dict] | None = None,kg_data: dict | None = None,+ only_page_ids: set[str] | None = None,) -> None:self.gen = genself.config = gen._configself.vector_store = gen._vector_store+ # Scoped generation: when set, a level emits a page only if its id is+ # in this set (and not already completed). None means "every page the+ # selection allows", the historical behaviour. The whole repo is still+ # parsed and its graph built, so a requested repo-wide page is rendered+ # from the complete view. See ``_emit`` for the single choke point.+ self.only_page_ids = only_page_idsself.parsed_files = parsed_filesself.source_map = source_mapself.graph_builder = graph_builder@@ -176,6 +183,19 @@ class _GenerationRun:self.gen._provider.model_name,)+ def _emit(self, page_id: str) -> bool:+ """Whether this run should generate ``page_id``.++ The single gate every level builder consults. A page is emitted unless+ it was already completed (resume) or a scoped run (``only_page_ids``)+ did not ask for it. Because the builders call this in the ``if`` clause+ that guards coroutine construction, a filtered-out page never even+ allocates its coroutine.+ """+ if page_id in self.completed_ids:+ return False+ return self.only_page_ids is None or page_id in self.only_page_ids+async def _seed_resume(self) -> None:if self.job_system is not None and self.resume and self.vector_store is not None:self.completed_ids = await self.vector_store.list_page_ids()@@ -236,6 +256,10 @@ class _GenerationRun:# file_page budget toward modules agents ask about. Empty (no# session history / disabled) leaves selection uniform.demand=self._compute_demand() or None,+ # A scoped run (repowise generate) rations via only_page_ids, so+ # the coverage budget must not pre-filter the allow-set — every+ # requested page has to survive selection to be emittable.+ select_all=self.only_page_ids is not None,))@@ -309,6 +333,18 @@ class _GenerationRun:return {}def _announce_total(self) -> None:+ # A scoped run emits exactly the requested-and-not-yet-done ids, so the+ # selection-derived estimate below would badly over-count. The set is+ # still an upper bound (a page may gate-skip at build time), matching+ # the contract the caller reconciles against the real completed count.+ if self.only_page_ids is not None:+ remaining = len(self.only_page_ids - self.completed_ids)+ if self.on_total_known is not None:+ self.on_total_known(remaining)+ if self.job_system is not None and self.job_id is not None:+ self.job_system.start_job(self.job_id, remaining)+ return+counts = self.selection.counts()layer_page_count = 0if self.kg_ctx.available:diff --git a/packages/core/src/repowise/core/generation/page_selection.py b/packages/core/src/repowise/core/generation/page_selection.pynew file mode 100644index 000000000..0ea5f43c7--- /dev/null+++ b/packages/core/src/repowise/core/generation/page_selection.py@@ -0,0 +1,133 @@+"""Resolve a user intent into the set of wiki page ids to (re)generate.++``repowise generate`` lets a user name *which* pages to write with a model:+everything unwritten, everything, a path prefix, explicit ids, or the stale+ones. This module turns that intent into a concrete id set, evaluated against+the pages that already exist in the wiki.++It is deliberately pure: it takes a list of lightweight :class:`PageRecord`+views (built by the CLI/server from the persisted pages) plus a+:class:`PageSelectionIntent`, and returns a ``set[str]`` of page ids. The+scoped generation engine (``generate_all(only_page_ids=...)``) consumes that+set verbatim, and the cascade layer expands it before it reaches the engine.+"""++from __future__ import annotations++import fnmatch+from dataclasses import dataclass, field++# Page freshness values that count as "needs refresh" for ``--stale``.+_STALE_STATUSES = frozenset({"stale", "expired"})+++@dataclass(frozen=True)+class PageRecord:+ """A minimal view of one persisted wiki page.++ Built by the caller from the page store (id, type, target path, provenance+ and freshness). Kept tiny so the resolver never depends on persistence+ models and stays trivially unit-testable.+ """++ page_id: str+ page_type: str+ target_path: str+ is_template: bool+ freshness_status: str = "fresh"++ @property+ def is_stale(self) -> bool:+ return self.freshness_status in _STALE_STATUSES+++@dataclass(frozen=True)+class PageSelectionIntent:+ """What the user asked to generate.++ The flags and filters are additive: the resolved set is the union of every+ non-empty selector. An intent with nothing set resolves to the default the+ caller chooses (``repowise generate`` defaults to ``unwritten``); this+ module does not invent a default, it just unions what it is given.+ """++ all_pages: bool = False+ unwritten: bool = False+ stale: bool = False+ path_globs: tuple[str, ...] = ()+ page_ids: tuple[str, ...] = ()++ def is_empty(self) -> bool:+ return not (+ self.all_pages or self.unwritten or self.stale or self.path_globs or self.page_ids+ )+++@dataclass+class PageSelectionResult:+ """Resolved id set plus what was asked for but not found.++ ``unknown_page_ids`` lets the caller warn on an explicit ``--page`` id that+ matches no existing page (a typo, or a page type that must be generated+ fresh) rather than silently dropping it.+ """++ page_ids: set[str] = field(default_factory=set)+ unknown_page_ids: tuple[str, ...] = ()++ def __len__(self) -> int:+ return len(self.page_ids)+++def _matches_glob(target_path: str, globs: tuple[str, ...]) -> bool:+ """True if *target_path* matches any glob (both slash-normalized).++ A bare prefix like ``packages/cli`` matches everything under it, so callers+ can pass a directory without a trailing ``/**``.+ """+ norm = target_path.replace("\\", "/")+ for raw in globs:+ g = raw.replace("\\", "/").rstrip("/")+ if fnmatch.fnmatch(norm, g) or fnmatch.fnmatch(norm, f"{g}/*") or norm == g:+ return True+ return False+++def resolve_page_selection(+ records: list[PageRecord],+ intent: PageSelectionIntent,+) -> PageSelectionResult:+ """Resolve *intent* against the existing *records* into a page-id set.++ The result is the union of every selector the intent sets:++ * ``all_pages`` — every existing page.+ * ``unwritten`` — every template (deterministic) page, i.e. the pages a+ model has not written yet.+ * ``stale`` — every page whose freshness is stale or expired.+ * ``path_globs`` — every page whose ``target_path`` matches a glob/prefix.+ * ``page_ids`` — the named ids, when they exist. Names that match no record+ are returned in ``unknown_page_ids`` instead of being included.+ """+ by_id = {r.page_id: r for r in records}+ selected: set[str] = set()++ if intent.all_pages:+ selected.update(by_id)+ if intent.unwritten:+ selected.update(r.page_id for r in records if r.is_template)+ if intent.stale:+ selected.update(r.page_id for r in records if r.is_stale)+ if intent.path_globs:+ selected.update(+ r.page_id for r in records if _matches_glob(r.target_path, intent.path_globs)+ )++ unknown: list[str] = []+ for pid in intent.page_ids:+ if pid in by_id:+ selected.add(pid)+ else:+ unknown.append(pid)++ return PageSelectionResult(page_ids=selected, unknown_page_ids=tuple(unknown))diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.pyindex 72dbdedd9..cd6958ddb 100644--- a/packages/core/src/repowise/core/generation/selection/selector.py+++ b/packages/core/src/repowise/core/generation/selection/selector.py@@ -137,6 +137,14 @@ class SelectionInputs:# modules. ``None``/empty reproduces the uniform, demand-free selection# byte-for-byte (fresh installs with no session history).demand: dict[str, int] | None = None+ # Scoped generation: take every candidate in every bucket (no coverage+ # budget), the same full-coverage set deterministic mode uses but keeping+ # symbol spotlights so a caller can regenerate one on demand. The actual+ # rationing is done downstream by ``generate_all(only_page_ids=...)``, which+ # filters this full allow-set to exactly the requested pages. Without it,+ # ``repowise generate --unwritten`` would silently emit only the budgeted+ # ~20% of files instead of every template page the user asked to upgrade.+ select_all: bool = False# ---------------------------------------------------------------------------@@ -554,17 +562,26 @@ def _ensure_landmarks(selected: list[str], landmarks: list[str]) -> list[str]:def _select_everything(files: list,+ symbols: list,modules: list,apis: list,infras: list,sccs: list,available: dict[str, int],+ *,+ include_symbols: bool,) -> Selection:"""Return a Selection holding every scored candidate, budget bypassed.- Used by fully deterministic (no-LLM) generation, where every page is free- to produce. Candidates are already score-ordered, so the resulting page- order still puts the most central files first.+ Used by fully deterministic (no-LLM) generation and by scoped+ ``select_all`` generation, where the coverage budget has no job to do —+ the former because every page is free, the latter because+ ``only_page_ids`` rations downstream. Candidates are already score-ordered,+ so the resulting page order still puts the most central files first.++ ``include_symbols`` keeps the symbol-spotlight bucket (scoped generation, so+ a caller can regenerate a specific spotlight); deterministic mode drops it+ (see below)."""sel = Selection(file_page_paths=[p for _, p in files],@@ -575,9 +592,10 @@ def _select_everything(# renders, so taking every candidate would triple the index for no# new information and dilute retrieval, the same failure the tier-2# tail's importance floor exists to avoid. On the fixture repo that is- # 171 near-duplicate pages against 33 file pages. Users who want a- # spotlight on a specific symbol can generate one on demand.- symbol_spotlights=[],+ # 171 near-duplicate pages against 33 file pages. Scoped generation+ # keeps them (``include_symbols``) since ``only_page_ids`` filters to the+ # one the user asked for rather than emitting all of them.+ symbol_spotlights=[t for _, t in symbols] if include_symbols else [],module_groups=[m for _, m in modules],api_contract_paths=[p for _, p in apis],infra_paths=[p for _, p in infras],@@ -586,14 +604,18 @@ def _select_everything(emit_arch_diagram=True,allocation=BucketAllocation(file_page=available["file_page"],- symbol_spotlight=0,+ symbol_spotlight=available["symbol_spotlight"] if include_symbols else 0,module_page=available["module_page"],api_contract=available["api_contract"],infra_page=available["infra_page"],scc_page=available["scc_page"],),)- log.info("page_selection.complete", mode="deterministic", counts=sel.counts())+ log.info(+ "page_selection.complete",+ mode="select_all" if include_symbols else "deterministic",+ counts=sel.counts(),+ )return sel@@ -631,7 +653,17 @@ def select_pages(inputs: SelectionInputs) -> Selection:# Nothing to ration: a template page costs no tokens, so the coverage# budget has no job to do. Take every candidate in every bucket. The# tail stays empty because the file bucket already holds every file.- return _select_everything(files, modules, apis, infras, sccs, available)+ return _select_everything(+ files, symbols, modules, apis, infras, sccs, available, include_symbols=False+ )++ # Scoped generation (``repowise generate``): full-coverage allow-set so+ # ``only_page_ids`` can name any page. Spotlights kept so one can be+ # regenerated on demand.+ if getattr(inputs, "select_all", False):+ return _select_everything(+ files, symbols, modules, apis, infras, sccs, available, include_symbols=True+ )allocation = allocate_budget(budget=budget,diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 4ed474cb3..12aa10e25 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -8,12 +8,17 @@ from __future__ import annotationsimport dataclassesimport json+from collections.abc import Iterablefrom typing import Anyimport structloglogger = structlog.get_logger(__name__)+# Max page ids per UPDATE ... IN (...) so a large cascade cannot exceed+# SQLite's bound-variable limit on the local CLI store.+_STALE_ID_CHUNK = 500+def tombstone_candidates(file_diffs: list[Any]) -> list[tuple[str, list[str]]]:"""(dead_path, successor_paths) pairs from deleted/renamed file diffs.@@ -116,6 +121,45 @@ async def mark_stale_pages(session: Any, repo_id: str, paths: list[str]) -> int:return marked+async def mark_page_ids_stale(session: Any, repo_id: str, page_ids: Iterable[str]) -> int:+ """Decay arbitrary pages to ``freshness_status='stale'`` by full page id.++ The sibling of :func:`mark_stale_pages`, which only understands+ ``file_page:<path>`` ids. Scoped generation's cascade needs to mark+ dependents of every type — module, SCC, layer and the repo-wide overview /+ architecture / onboarding pages — stale when the run regenerated a file but+ not its summaries. Same ``fresh``-only downgrade so a tombstoned or+ already-stale page keeps its stronger status.++ Returns the number of pages marked.+ """+ ids = list(dict.fromkeys(page_ids)) # dedupe, preserve order+ if not ids:+ return 0+ from sqlalchemy import update++ from repowise.core.persistence.models import Page++ # Chunk the IN list: SQLite (the local CLI store) binds one variable per id+ # and caps at SQLITE_MAX_VARIABLE_NUMBER, so a large cascade could exceed it.+ marked = 0+ for i in range(0, len(ids), _STALE_ID_CHUNK):+ batch = ids[i : i + _STALE_ID_CHUNK]+ res = await session.execute(+ update(Page)+ .where(+ Page.repository_id == repo_id,+ Page.id.in_(batch),+ Page.freshness_status == "fresh",+ )+ .values(freshness_status="stale")+ )+ marked += int(res.rowcount or 0)+ if marked:+ logger.info("pages_decayed_stale", repo_id=repo_id, count=marked)+ return marked++def _derive_entry_point_scores(graph_builder: Any) -> dict[str, float]:"""Best-effort entry-point scores from the builder's execution-flow report.diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.pyindex de241f7d4..5d2db4c52 100644--- a/packages/core/src/repowise/core/pipeline/phases/generation.py+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py@@ -42,6 +42,7 @@ async def run_generation(prior_pages: dict[str, Any] | None = None,kg_modules: list[dict] | None = None,kg_data: dict | None = None,+ only_page_ids: set[str] | None = None,) -> list[Any]:"""Run LLM-powered page generation.@@ -51,6 +52,9 @@ async def run_generation(lets the generator skip the LLM call for any page whose freshly renderedprompt still hashes to the persisted value under the same model — the samecross-run reuse ``repowise update`` relies on. Defaults to empty.++ ``only_page_ids`` scopes the run to an explicit set of page ids (the+ ``repowise generate`` path). None means the full selection, as before."""from repowise.core.generation import (ContextAssembler,@@ -142,6 +146,7 @@ async def run_generation(on_page_ready=on_page_ready,kg_modules=kg_modules,kg_data=kg_data,+ only_page_ids=only_page_ids,)# Onboarding summary — count generated slots and surface which onesdiff --git a/tests/integration/test_deterministic_generation.py b/tests/integration/test_deterministic_generation.pyindex 5879a93d4..eb432ff43 100644--- a/tests/integration/test_deterministic_generation.py+++ b/tests/integration/test_deterministic_generation.py@@ -214,3 +214,78 @@ class TestFilePagesOnly: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)+++class TestOnlyPageIds:+ """Scoped generation: emit an arbitrary subset from the complete view.++ Unlike ``file_pages_only`` (which stops the level ladder), ``only_page_ids``+ runs every level over the whole parsed repo and emits only the requested+ ids. That is what lets ``repowise generate --page`` refresh one repo-wide+ page correctly rather than from a truncated slice.+ """++ @pytest.fixture(scope="class")+ async def full_ids(self, tmp_path_factory):+ """Every page id a full deterministic run over the fixture produces."""+ return {p.page_id for p in await _run_deterministic(tmp_path_factory, "only_full")}++ async def test_emits_exactly_the_requested_subset(self, tmp_path_factory, full_ids):+ # Ask for one file page plus the repo overview — a mix of a leaf page+ # and a level-6 whole-repo page.+ a_file = next(pid for pid in full_ids if pid.startswith("file_page:"))+ overview = next(pid for pid in full_ids if pid.startswith("repo_overview:"))+ requested = {a_file, overview}+ pages = await _run_deterministic(+ tmp_path_factory, "only_subset", only_page_ids=requested+ )+ produced = {p.page_id for p in pages}+ assert produced == requested, f"scoped run leaked or dropped pages: {produced ^ requested}"++ async def test_unrequested_repo_wide_page_is_absent(self, tmp_path_factory, full_ids):+ a_file = next(pid for pid in full_ids if pid.startswith("file_page:"))+ pages = await _run_deterministic(tmp_path_factory, "only_onefile", only_page_ids={a_file})+ assert {p.page_id for p in pages} == {a_file}+++async def _run_deterministic(tmp_path_factory, name, *, only_page_ids=None):+ """Run a full deterministic generate_all over the fixture repo."""+ tmp = tmp_path_factory.mktemp(name)+ 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=[],+ )+ config = GenerationConfig(+ deterministic=True,+ max_concurrency=3,+ jobs_dir=str(tmp / "jobs"),+ )+ generator = PageGenerator(TemplateProvider(), ContextAssembler(config), config)+ return await generator.generate_all(+ parsed_files,+ source_map,+ builder,+ repo_structure,+ "sample_repo",+ job_system=None,+ only_page_ids=only_page_ids,+ )diff --git a/tests/unit/cli/test_generate_scope.py b/tests/unit/cli/test_generate_scope.pynew file mode 100644index 000000000..39b5272b5--- /dev/null+++ b/tests/unit/cli/test_generate_scope.py@@ -0,0 +1,98 @@+"""Unit tests for the ``repowise generate`` scope/cascade resolution."""++from __future__ import annotations++from dataclasses import dataclass++from repowise.cli.commands.generate_cmd.scope import (+ build_cost_plans,+ load_page_records,+ resolve_scope,+)+from repowise.core.generation.cascade import build_page_dependencies+from repowise.core.generation.page_selection import PageSelectionIntent+++@dataclass+class _Row:+ """Duck-typed persisted Page row."""++ id: str+ page_type: str+ target_path: str+ provider_name: str+ freshness_status: str = "fresh"+ metadata_json: str = "{}"+++def test_load_page_records_flags_templates_by_provider_or_metadata() -> None:+ rows = [+ _Row("file_page:a.py", "file_page", "a.py", "template"),+ _Row("file_page:b.py", "file_page", "b.py", "openai"),+ _Row(+ "file_page:c.py",+ "file_page",+ "c.py",+ "openai",+ metadata_json='{"deterministic": true}',+ ),+ ]+ records = load_page_records(rows)+ by_id = {r.page_id: r for r in records}+ assert by_id["file_page:a.py"].is_template is True+ assert by_id["file_page:b.py"].is_template is False+ # deterministic metadata still marks it template even with a real provider.+ assert by_id["file_page:c.py"].is_template is True+++def test_build_cost_plans_groups_by_type_and_orders_by_level() -> None:+ ids = {+ "file_page:a.py",+ "file_page:b.py",+ "repo_overview:demo",+ "module_page:src",+ }+ plans = build_cost_plans(ids)+ counts = {p.page_type: p.count for p in plans}+ assert counts == {"file_page": 2, "module_page": 1, "repo_overview": 1}+ # Ordered by generation level (file_page=2 < module_page=4 < repo_overview=6).+ assert [p.page_type for p in plans] == ["file_page", "module_page", "repo_overview"]+++def test_resolve_scope_unwritten_with_cascade_none() -> None:+ rows = [+ _Row("file_page:src/a.py", "file_page", "src/a.py", "template"),+ _Row("file_page:src/b.py", "file_page", "src/b.py", "openai"),+ _Row("module_page:src", "module_page", "src", "template"),+ _Row("repo_overview:demo", "repo_overview", "demo", "template"),+ ]+ records = load_page_records(rows)++ @dataclass(frozen=True)+ class _MG:+ key: str+ file_paths: tuple[str, ...]++ deps = build_page_dependencies(+ module_groups=[_MG("src", ("src/a.py", "src/b.py"))],+ scc_groups=[],+ layer_page_of={},+ repo_wide_ids=("repo_overview:demo",),+ )+ plan = resolve_scope(+ records=records,+ intent=PageSelectionIntent(unwritten=True),+ cascade_mode="none",+ deps=deps,+ )+ # Seeds are the template pages: a.py, module_page:src, repo_overview:demo.+ assert plan.generate_ids == {+ "file_page:src/a.py",+ "module_page:src",+ "repo_overview:demo",+ }+ # cascade=none marks the file's containers stale, minus anything regenerated.+ # module_page:src is a container of a.py but is itself regenerated, so it is+ # not stale. No repo-wide left (overview is regenerated).+ assert plan.stale_ids == set()+ assert plan.seed_count == 3diff --git a/tests/unit/generation/test_announce_total.py b/tests/unit/generation/test_announce_total.pyindex 589f44757..932e45dca 100644--- a/tests/unit/generation/test_announce_total.py+++ b/tests/unit/generation/test_announce_total.py@@ -41,6 +41,9 @@ def _fake_run(*, enable_onboarding: bool, completed_ids: set[str]) -> SimpleNamekg_ctx=SimpleNamespace(available=False),config=SimpleNamespace(enable_onboarding=enable_onboarding),completed_ids=completed_ids,+ # None: the selection-derived total path (a scoped run short-circuits+ # to len(only_page_ids), tested in test_deterministic_generation).+ only_page_ids=None,on_total_known=announced.append,job_system=None,job_id=None,diff --git a/tests/unit/generation/test_cascade.py b/tests/unit/generation/test_cascade.pynew file mode 100644index 000000000..0c136dc29--- /dev/null+++ b/tests/unit/generation/test_cascade.py@@ -0,0 +1,107 @@+"""Unit tests for the cascade policy."""++from __future__ import annotations++from dataclasses import dataclass++from repowise.core.generation.cascade import (+ build_page_dependencies,+ expand_cascade,+)+++@dataclass(frozen=True)+class _MG:+ """Duck-typed stand-in for selection.ModuleGroup."""++ key: str+ file_paths: tuple[str, ...]+++def _deps():+ return build_page_dependencies(+ module_groups=[_MG("src", ("src/a.py", "src/b.py"))],+ scc_groups=[("scc-abc", ["src/a.py", "src/c.py"])],+ layer_page_of={"src/a.py": "layer_page:layer:core"},+ repo_wide_ids=(+ "repo_overview:demo",+ "architecture_diagram:demo",+ "onboarding:guided-tour",+ ),+ )+++def test_containers_of_collects_module_scc_layer() -> None:+ deps = _deps()+ assert deps.containers_of("src/a.py") == {+ "module_page:src",+ "scc_page:scc-abc",+ "layer_page:layer:core",+ }+ # b.py is only in the module.+ assert deps.containers_of("src/b.py") == {"module_page:src"}+++def test_cascade_none_marks_dependents_stale_generates_only_seed() -> None:+ deps = _deps()+ result = expand_cascade({"file_page:src/a.py"}, "none", deps)+ assert result.generate_ids == {"file_page:src/a.py"}+ assert result.stale_ids == {+ "module_page:src",+ "scc_page:scc-abc",+ "layer_page:layer:core",+ "repo_overview:demo",+ "architecture_diagram:demo",+ "onboarding:guided-tour",+ }+++def test_cascade_dependents_regenerates_containers_marks_repo_wide_stale() -> None:+ deps = _deps()+ result = expand_cascade({"file_page:src/a.py"}, "dependents", deps)+ assert result.generate_ids == {+ "file_page:src/a.py",+ "module_page:src",+ "scc_page:scc-abc",+ "layer_page:layer:core",+ }+ assert result.stale_ids == {+ "repo_overview:demo",+ "architecture_diagram:demo",+ "onboarding:guided-tour",+ }+++def test_cascade_full_regenerates_everything_marks_nothing() -> None:+ deps = _deps()+ result = expand_cascade({"file_page:src/a.py"}, "full", deps)+ assert result.generate_ids == {+ "file_page:src/a.py",+ "module_page:src",+ "scc_page:scc-abc",+ "layer_page:layer:core",+ "repo_overview:demo",+ "architecture_diagram:demo",+ "onboarding:guided-tour",+ }+ assert result.stale_ids == set()+++def test_regenerated_page_never_also_marked_stale() -> None:+ # Seed the module page directly plus its file: the module must not be stale.+ deps = _deps()+ result = expand_cascade({"file_page:src/a.py", "module_page:src"}, "none", deps)+ assert "module_page:src" in result.generate_ids+ assert "module_page:src" not in result.stale_ids+++def test_non_file_seed_has_no_file_cascade() -> None:+ deps = _deps()+ result = expand_cascade({"module_page:src"}, "dependents", deps)+ # A module-page seed drags no file containers in; repo-wide still decays.+ assert result.generate_ids == {"module_page:src"}+ assert result.stale_ids == {+ "repo_overview:demo",+ "architecture_diagram:demo",+ "onboarding:guided-tour",+ }diff --git a/tests/unit/generation/test_layer_pages.py b/tests/unit/generation/test_layer_pages.pyindex 93d88e6f1..b114e9e89 100644--- a/tests/unit/generation/test_layer_pages.py+++ b/tests/unit/generation/test_layer_pages.py@@ -228,6 +228,13 @@ class TestBuildLevel5Coros:run.pagerank = {}run.completed_page_summaries = {}run.completed_ids = set()+ run.only_page_ids = None+ # Emission now flows through the real _emit gate, so the mock must use+ # its real logic (completed_ids + only_page_ids) rather than a truthy+ # auto-mock that would emit everything.+ from repowise.core.generation.page_generator.orchestrate import _GenerationRun++ run._emit = lambda pid: _GenerationRun._emit(run, pid)run.gen = MagicMock()return rundiff --git a/tests/unit/generation/test_page_selection.py b/tests/unit/generation/test_page_selection.pynew file mode 100644index 000000000..cfb165de0--- /dev/null+++ b/tests/unit/generation/test_page_selection.py@@ -0,0 +1,83 @@+"""Unit tests for the PageSelection intent resolver."""++from __future__ import annotations++from repowise.core.generation.page_selection import (+ PageRecord,+ PageSelectionIntent,+ resolve_page_selection,+)+++def _records() -> list[PageRecord]:+ return [+ PageRecord("file_page:src/a.py", "file_page", "src/a.py", is_template=True),+ PageRecord("file_page:src/b.py", "file_page", "src/b.py", is_template=False),+ PageRecord(+ "file_page:tests/t.py",+ "file_page",+ "tests/t.py",+ is_template=True,+ freshness_status="stale",+ ),+ PageRecord("module_page:src", "module_page", "src", is_template=True),+ PageRecord("repo_overview:demo", "repo_overview", "demo", is_template=False),+ ]+++def test_unwritten_selects_template_pages_only() -> None:+ result = resolve_page_selection(_records(), PageSelectionIntent(unwritten=True))+ assert result.page_ids == {+ "file_page:src/a.py",+ "file_page:tests/t.py",+ "module_page:src",+ }+ assert result.unknown_page_ids == ()+++def test_all_pages_selects_everything() -> None:+ result = resolve_page_selection(_records(), PageSelectionIntent(all_pages=True))+ assert len(result) == 5+++def test_stale_selects_stale_and_expired() -> None:+ result = resolve_page_selection(_records(), PageSelectionIntent(stale=True))+ assert result.page_ids == {"file_page:tests/t.py"}+++def test_path_glob_matches_prefix_and_glob() -> None:+ # A bare directory prefix matches everything under it.+ result = resolve_page_selection(_records(), PageSelectionIntent(path_globs=("src",)))+ assert result.page_ids == {+ "file_page:src/a.py",+ "file_page:src/b.py",+ "module_page:src",+ }+ # An explicit glob works too.+ result = resolve_page_selection(_records(), PageSelectionIntent(path_globs=("src/*.py",)))+ assert result.page_ids == {"file_page:src/a.py", "file_page:src/b.py"}+++def test_explicit_ids_report_unknown() -> None:+ intent = PageSelectionIntent(page_ids=("file_page:src/a.py", "file_page:does/not/exist.py"))+ result = resolve_page_selection(_records(), intent)+ assert result.page_ids == {"file_page:src/a.py"}+ assert result.unknown_page_ids == ("file_page:does/not/exist.py",)+++def test_selectors_union() -> None:+ intent = PageSelectionIntent(stale=True, page_ids=("file_page:src/b.py",))+ result = resolve_page_selection(_records(), intent)+ assert result.page_ids == {"file_page:tests/t.py", "file_page:src/b.py"}+++def test_empty_intent_resolves_empty() -> None:+ intent = PageSelectionIntent()+ assert intent.is_empty()+ assert resolve_page_selection(_records(), intent).page_ids == set()+++def test_windows_target_paths_normalize() -> None:+ records = [PageRecord("file_page:src/a.py", "file_page", "src\\a.py", is_template=True)]+ result = resolve_page_selection(records, PageSelectionIntent(path_globs=("src",)))+ assert result.page_ids == {"file_page:src/a.py"}