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(generation): the overview carries the architecture map (#1164)
Swati Ahujafce08cafcd42
diff --git a/packages/core/src/repowise/core/cost_estimator/approx.py b/packages/core/src/repowise/core/cost_estimator/approx.pyindex 2e38f8f97..d7ae66a74 100644--- a/packages/core/src/repowise/core/cost_estimator/approx.py+++ b/packages/core/src/repowise/core/cost_estimator/approx.py@@ -58,7 +58,6 @@ def approximate_generation_plan(PageTypePlan(page_type="file_page", count=file_pages, level=0),PageTypePlan(page_type="module_page", count=module_pages, level=1),PageTypePlan(page_type="repo_overview", count=1 if file_count else 0, level=2),- PageTypePlan(page_type="architecture_diagram", count=1 if file_count else 0, level=2),]if onboarding and file_count:plans.append(PageTypePlan(page_type="onboarding", count=_ONBOARDING_SLOTS, level=2))diff --git a/packages/core/src/repowise/core/cost_estimator/plans.py b/packages/core/src/repowise/core/cost_estimator/plans.pyindex d3421e4e8..05468ca5a 100644--- a/packages/core/src/repowise/core/cost_estimator/plans.py+++ b/packages/core/src/repowise/core/cost_estimator/plans.py@@ -85,7 +85,6 @@ def build_generation_plan("scc_page","module_page","repo_overview",- "architecture_diagram","infra_page",):count = counts.get(page_type, 0)diff --git a/packages/core/src/repowise/core/generation/onboarding/__init__.py b/packages/core/src/repowise/core/generation/onboarding/__init__.pyindex f2c2720c5..9098fe183 100644--- a/packages/core/src/repowise/core/generation/onboarding/__init__.py+++ b/packages/core/src/repowise/core/generation/onboarding/__init__.py@@ -5,7 +5,7 @@ Guided Tour, Getting Started, Codebase Map, Key Concepts, How It Works,Development Guide, Active Landscape, designed to be the first thing a newcontributor (or LLM agent) reads.-Two slots ("project_overview", "architecture_guide") are *promoted*: they+One slot ("project_overview") is *promoted*: itreuse the existing ``repo_overview`` and ``architecture_diagram`` pages,tagged via ``metadata.onboarding_slot``. The other seven slots are new pagesgenerated at level 8 with ``page_type='onboarding'`` and a@@ -28,7 +28,6 @@ from .slots import (ONBOARDING_ORDER,PROMOTED_SLOTS,SLOT_ACTIVE_LANDSCAPE,- SLOT_ARCHITECTURE_GUIDE,SLOT_CODEBASE_MAP,SLOT_DEVELOPMENT_GUIDE,SLOT_GETTING_STARTED,@@ -45,7 +44,6 @@ __all__ = ["ONBOARDING_ORDER","PROMOTED_SLOTS","SLOT_ACTIVE_LANDSCAPE",- "SLOT_ARCHITECTURE_GUIDE","SLOT_CODEBASE_MAP","SLOT_DEVELOPMENT_GUIDE","SLOT_GETTING_STARTED",diff --git a/packages/core/src/repowise/core/generation/onboarding/registry.py b/packages/core/src/repowise/core/generation/onboarding/registry.pyindex 1f9ae5082..8242adc2a 100644--- a/packages/core/src/repowise/core/generation/onboarding/registry.py+++ b/packages/core/src/repowise/core/generation/onboarding/registry.py@@ -70,7 +70,7 @@ def get_spec(slot: str) -> SubkindSpec | None:def iter_specs() -> list[SubkindSpec]:"""Return registered specs in canonical reading order.- Promoted slots (project_overview, architecture_guide) are not generated+ The promoted slot (project_overview) is not generatedthrough this path and are excluded here."""promoted = set(PROMOTED_SLOTS.values())diff --git a/packages/core/src/repowise/core/generation/onboarding/slots.py b/packages/core/src/repowise/core/generation/onboarding/slots.pyindex 29ffa6bad..b97dffcda 100644--- a/packages/core/src/repowise/core/generation/onboarding/slots.py+++ b/packages/core/src/repowise/core/generation/onboarding/slots.py@@ -1,9 +1,9 @@"""Onboarding slot identifiers and reading order.-The Onboarding collection is a fixed set of nine curated slots. Two slots are-"promoted": they reuse the existing `repo_overview` and `architecture_diagram`-pages, tagged via ``metadata.onboarding_slot``. The other seven are new pages-with ``page_type='onboarding'`` and a ``metadata.subkind`` discriminator.+The Onboarding collection is a fixed set of eight curated slots. One slot is+"promoted": it reuses the existing `repo_overview` page, tagged via+``metadata.onboarding_slot``. The other seven are new pages with+``page_type='onboarding'`` and a ``metadata.subkind`` discriminator.Slot identifiers are used three ways:- as the ``metadata.subkind`` value on generated pages,@@ -12,7 +12,7 @@ Slot identifiers are used three ways:Keep the order list in lockstep with ``packages/ui/src/lib/page-types.ts````ONBOARDING_ORDER``. A slot without enough signal is skipped at generation-time, so a repo can end up with fewer than nine.+time, so a repo can end up with fewer than eight."""from __future__ import annotations@@ -28,7 +28,6 @@ ONBOARDING_GENERATION_VERSION = "2"# ---- Slot identifiers ----SLOT_PROJECT_OVERVIEW = "project_overview"-SLOT_ARCHITECTURE_GUIDE = "architecture_guide"SLOT_GUIDED_TOUR = "guided_tour"SLOT_GETTING_STARTED = "getting_started"SLOT_CODEBASE_MAP = "codebase_map"@@ -41,7 +40,6 @@ SLOT_ACTIVE_LANDSCAPE = "active_landscape"# generation time and absent from the UI tree.ONBOARDING_ORDER: tuple[str, ...] = (SLOT_PROJECT_OVERVIEW,- SLOT_ARCHITECTURE_GUIDE,SLOT_GUIDED_TOUR,SLOT_GETTING_STARTED,SLOT_CODEBASE_MAP,@@ -56,14 +54,12 @@ ONBOARDING_ORDER: tuple[str, ...] = (# extra content is generated for promoted slots.PROMOTED_SLOTS: dict[str, str] = {"repo_overview": SLOT_PROJECT_OVERVIEW,- "architecture_diagram": SLOT_ARCHITECTURE_GUIDE,}# Human-readable titles used both server-side (page title) and as a fallback# label in the UI when a page hasn't been hydrated yet.SLOT_TITLES: dict[str, str] = {SLOT_PROJECT_OVERVIEW: "Project Overview",- SLOT_ARCHITECTURE_GUIDE: "Architecture Guide",SLOT_GUIDED_TOUR: "Guided Tour",SLOT_GETTING_STARTED: "Getting Started",SLOT_CODEBASE_MAP: "Codebase Map",@@ -76,12 +72,11 @@ SLOT_TITLES: dict[str, str] = {SLOT_PREREQUISITES: dict[str, tuple[str, ...]] = {SLOT_PROJECT_OVERVIEW: (),- SLOT_ARCHITECTURE_GUIDE: (),SLOT_GUIDED_TOUR: (SLOT_PROJECT_OVERVIEW,),SLOT_GETTING_STARTED: (),SLOT_CODEBASE_MAP: (SLOT_PROJECT_OVERVIEW,),- SLOT_KEY_CONCEPTS: (SLOT_PROJECT_OVERVIEW, SLOT_ARCHITECTURE_GUIDE),- SLOT_HOW_IT_WORKS: (SLOT_ARCHITECTURE_GUIDE, SLOT_KEY_CONCEPTS),+ SLOT_KEY_CONCEPTS: (SLOT_PROJECT_OVERVIEW,),+ SLOT_HOW_IT_WORKS: (SLOT_KEY_CONCEPTS,),SLOT_DEVELOPMENT_GUIDE: (SLOT_GETTING_STARTED, SLOT_HOW_IT_WORKS),SLOT_ACTIVE_LANDSCAPE: (SLOT_CODEBASE_MAP,),}diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.pyindex a22a6ca61..2374b6a69 100644--- a/packages/core/src/repowise/core/generation/page_generator/levels.py+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py@@ -356,8 +356,26 @@ def build_level5_coros(run: _GenerationRun) -> list[tuple[str, Any]]:def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:- """Level 6 (repo_overview + architecture_diagram)."""+ """Level 6 (repo_overview).++ The overview carries the architecture map. That map used to sit on a page+ of its own, which described the same repository at the same altitude in the+ same words — the two shared roughly a quarter of their vocabulary, so a+ reader meeting both read one thing twice. The diagram is what that page+ uniquely had, so it moved here and the page retired; its id redirects.+ """+ from ..architecture_mermaid import build_overview_mermaid+gen = run.gen+ overview_mermaid = build_overview_mermaid(run.kg_ctx)+ if not overview_mermaid:+ # The retired page drew its own diagram when the graph could not supply+ # one, so this used to degrade to a worse map rather than to none. Now+ # the wiki simply ships without one, which is worth knowing about.+ log.warning(+ "generation.overview_architecture_map_empty",+ repo_name=run.repo_name,+ )coros: list[tuple[str, Any]] = []if run._emit(compute_page_id("repo_overview", run.repo_name)):coros.append(@@ -373,22 +391,6 @@ def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:repo_name=run.repo_name,external_systems=run.external_systems,decision_records=run.decisions_all[:10],- ),- )- )- if run._emit(compute_page_id("architecture_diagram", run.repo_name)):- from ..architecture_mermaid import build_overview_mermaid-- overview_mermaid = build_overview_mermaid(run.kg_ctx)- coros.append(- (- compute_page_id("architecture_diagram", run.repo_name),- gen.generate_architecture_diagram(- run.graph,- run.pagerank,- run.community,- run.sccs,- run.repo_name,overview_mermaid=overview_mermaid,),)diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.pyindex ea51de553..112bfedb9 100644--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py@@ -464,7 +464,6 @@ class _GenerationRun:+ counts["module_page"]+ layer_page_count+ int(self.selection.emit_repo_overview)- + int(self.selection.emit_arch_diagram)+ counts["infra_page"]+ onboarding_page_count)diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex 9a2ef7998..b2f173787 100644--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py@@ -54,6 +54,20 @@ def _stub_fallback(page: GeneratedPage, page_type: str, exc: Exception) -> Generreturn page+def _with_architecture_map(page: GeneratedPage, overview_mermaid: str | None) -> GeneratedPage:+ """Embed the KG-derived architecture map into an already-built page.++ The overview is where the map lives, so the stub paths carry it too — a+ provider outage should cost the prose around the diagram, not the diagram.+ Embedding is idempotent, so calling this on a page that already has one is+ safe.+ """+ if not overview_mermaid:+ return page+ page.content = embed_mermaid(page.content, overview_mermaid, heading="## Architecture map")+ return page++class PerTypeGenerationMixin:"""Per-type ``generate_*`` methods. Requires the host to provide``_assembler``, ``_render``, ``_call_provider`` and@@ -252,6 +266,7 @@ class PerTypeGenerationMixin:repo_name: str | None = None,external_systems: list[dict] | None = None,decision_records: list[dict] | None = None,+ overview_mermaid: str | None = None,) -> GeneratedPage:ctx = self._assembler.assemble_repo_overview(repo_structure,@@ -282,9 +297,10 @@ class PerTypeGenerationMixin:if not repo_name:repo_name = getattr(repo_structure, "name", None) or "repo"if self._config.deterministic:- return self._stub_repo_overview(+ stub = self._stub_repo_overview(ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary)+ return _with_architecture_map(stub, overview_mermaid)user_prompt = self._render("repo_overview.j2", ctx=ctx, repo_git_summary=repo_git_summary)try:response = await self._call_provider(@@ -294,7 +310,19 @@ class PerTypeGenerationMixin:stub = self._stub_repo_overview(ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary)- return _stub_fallback(stub, "repo_overview", exc)+ return _with_architecture_map(+ _stub_fallback(stub, "repo_overview", exc), overview_mermaid+ )+ # The overview carries the architecture map itself. It is the+ # deterministic KG-derived diagram, not one the model drew, and+ # embedding is idempotent so a reused page picks it up too.+ if overview_mermaid:+ response = replace(+ response,+ content=embed_mermaid(+ response.content, overview_mermaid, heading="## Architecture map"+ ),+ )return self._build_generated_page("repo_overview",repo_name,diff --git a/packages/core/src/repowise/core/generation/page_redirects.py b/packages/core/src/repowise/core/generation/page_redirects.pyindex 3a041c62b..0d058a6ca 100644--- a/packages/core/src/repowise/core/generation/page_redirects.py+++ b/packages/core/src/repowise/core/generation/page_redirects.py@@ -31,8 +31,13 @@ from __future__ import annotations# Retired page type → the page type that took over its material. The target# path is carried across unchanged.-SUPERSEDED_TYPES: dict[str, str] = {}+SUPERSEDED_TYPES: dict[str, str] = {+ # The architecture diagram described the same repository at the same+ # altitude as the overview, in the same words. Its diagram moved to the+ # overview and the page retired.+ "architecture_diagram": "repo_overview",+}# Retired page id → successor page id, in full. For pages whose target path is# the same in every repository.SUPERSEDED_IDS: dict[str, str] = {}diff --git a/packages/core/src/repowise/core/generation/scope.py b/packages/core/src/repowise/core/generation/scope.pyindex 46f1c0c41..93d97a2eb 100644--- a/packages/core/src/repowise/core/generation/scope.py+++ b/packages/core/src/repowise/core/generation/scope.py@@ -34,7 +34,7 @@ from repowise.core.generation.page_selection import (from repowise.core.generation.selection import Selection, 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"})+_REPO_WIDE_TYPES = frozenset({"repo_overview", "onboarding"})# Structural pages the coverage budget does not rank: layer pages come from KG# membership and onboarding is curated, so init emits every one of them at every@@ -160,10 +160,7 @@ def build_dependencies())- repo_wide_ids = [- compute_page_id("repo_overview", repo_name),- compute_page_id("architecture_diagram", repo_name),- ]+ repo_wide_ids = [compute_page_id("repo_overview", repo_name)]repo_wide_ids += [r.page_id for r in records if r.page_type == "onboarding"]return build_page_dependencies(@@ -179,7 +176,7 @@ def selection_page_ids(sel: Selection, repo_name: str) -> set[str]:Mirrors the id assignment in the page generator's level builders exactly(``levels.py``), so a ranked coverage pick names the same pages a full run- at that coverage would write. Repo-wide overview/architecture pages are+ at that coverage would write. The repo-wide overview page iskeyed by the repo name; onboarding is not budgeted here (the caller adds it)."""ids: set[str] = set()@@ -194,8 +191,6 @@ def selection_page_ids(sel: Selection, repo_name: str) -> set[str]:)if sel.emit_repo_overview:ids.add(compute_page_id("repo_overview", repo_name))- if sel.emit_arch_diagram:- ids.add(compute_page_id("architecture_diagram", repo_name))return idsdiff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.pyindex a52d8d4f5..dedb06ea0 100644--- a/packages/core/src/repowise/core/generation/selection/selector.py+++ b/packages/core/src/repowise/core/generation/selection/selector.py@@ -119,7 +119,6 @@ class Selection:infra_paths: list[str] = field(default_factory=list)scc_groups: list[tuple[str, list[str]]] = field(default_factory=list) # (scc_id, files)emit_repo_overview: bool = True- emit_arch_diagram: bool = True# The concept partition behind ``module_groups``, one entry per group, plus# the layer names the grouper steered by. Carried so a caller holding a# provider can name these groups; selection itself stays free of the model@@ -142,7 +141,6 @@ class Selection:"scc_page": len(self.scc_groups),"module_page": len(self.module_groups),"repo_overview": int(self.emit_repo_overview),- "architecture_diagram": int(self.emit_arch_diagram),"infra_page": len(self.infra_paths),}@@ -701,7 +699,6 @@ def select_pages(inputs: SelectionInputs) -> Selection:infra_paths=[p for _, p in infras],scc_groups=[g for _, g in sccs],emit_repo_overview=True,- emit_arch_diagram=True,)log.info("page_selection.complete", counts=sel.counts())return seldiff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.tsindex 251716eef..6826d8043 100644--- a/packages/ui/src/lib/page-types.ts+++ b/packages/ui/src/lib/page-types.ts@@ -81,9 +81,9 @@ export function isStubPage(// Onboarding collection// ---------------------------------------------------------------------------//-// Two slots — project_overview and architecture_guide — are *promoted*: their-// content lives in the existing repo_overview / architecture_diagram pages,-// tagged via `metadata.onboarding_slot`. The other seven are dedicated+// One slot — project_overview — is *promoted*: its+// content lives in the existing repo_overview page, tagged via+// `metadata.onboarding_slot`. The other seven are dedicated// `page_type === "onboarding"` pages with `metadata.subkind` discriminating// them.//@@ -95,7 +95,6 @@ export function isStubPage(export const ONBOARDING_SLOT_TITLES = {project_overview: "Project Overview",- architecture_guide: "Architecture Guide",guided_tour: "Guided Tour",getting_started: "Getting Started",codebase_map: "Codebase Map",diff --git a/tests/integration/test_deterministic_generation.py b/tests/integration/test_deterministic_generation.pyindex ee12c0f85..d175628a1 100644--- a/tests/integration/test_deterministic_generation.py+++ b/tests/integration/test_deterministic_generation.py@@ -136,7 +136,7 @@ class TestDeterministicGeneration:types = {p.page_type for p in deterministic_pages}assert "file_page" in typesassert "repo_overview" in types- assert "architecture_diagram" in types+ assert "architecture_diagram" not in typesassert len(types) >= 4, f"only got {types}"def test_full_file_coverage(self, deterministic_pages):diff --git a/tests/integration/test_generation_pipeline.py b/tests/integration/test_generation_pipeline.pyindex 5c80fcde1..943762f93 100644--- a/tests/integration/test_generation_pipeline.py+++ b/tests/integration/test_generation_pipeline.py@@ -392,9 +392,18 @@ class TestGenerationPipeline:types = [p.page_type for p in pipeline_result["pages"]]assert types.count("repo_overview") == 1- def test_generates_architecture_diagram(self, pipeline_result):- types = [p.page_type for p in pipeline_result["pages"]]- assert types.count("architecture_diagram") == 1+ def test_architecture_map_lives_on_the_overview(self, pipeline_result):+ """The diagram no longer gets a page of its own.++ It described the same repository at the same altitude as the overview+ and in the same words, so the map moved onto the overview and the page+ retired. A run that still emits one has regressed.+ """+ pages = pipeline_result["pages"]+ types = [p.page_type for p in pages]+ assert types.count("architecture_diagram") == 0+ assert types.count("repo_overview") == 1+def test_generates_file_page_for_py_files(self, pipeline_result):"""There should be at least one file_page for Python files."""diff --git a/tests/unit/cli/test_cost_estimator.py b/tests/unit/cli/test_cost_estimator.pyindex 47d8947b0..973a5f51d 100644--- a/tests/unit/cli/test_cost_estimator.py+++ b/tests/unit/cli/test_cost_estimator.py@@ -79,9 +79,8 @@ class TestBuildGenerationPlan:def test_empty_repo(self):builder = _make_graph_builder([])plans = build_generation_plan([], builder, FakeConfig())- # Still get repo_overview + architecture_diagram+ # Still get repo_overviewassert any(p.page_type == "repo_overview" for p in plans)- assert any(p.page_type == "architecture_diagram" for p in plans)def test_single_python_file_with_symbol(self):fi = FakeFileInfo(path="src/app.py", language="python")diff --git a/tests/unit/cli/test_generate_scope.py b/tests/unit/cli/test_generate_scope.pyindex 28913012a..ca8f7ed0c 100644--- a/tests/unit/cli/test_generate_scope.py+++ b/tests/unit/cli/test_generate_scope.py@@ -119,7 +119,6 @@ class _FakeSelection:self.infra_paths = ["Dockerfile"]self.symbol_spotlights = [("src/a.py", "Widget")]self.emit_repo_overview = True- self.emit_arch_diagram = Truedef test_selection_page_ids_mirrors_generation_id_assignment() -> None:@@ -133,17 +132,14 @@ def test_selection_page_ids_mirrors_generation_id_assignment() -> None:compute_page_id("infra_page", "Dockerfile"),compute_page_id("symbol_spotlight", "src/a.py::Widget"),compute_page_id("repo_overview", "demo"),- compute_page_id("architecture_diagram", "demo"),}def test_selection_page_ids_honors_emit_flags() -> None:sel = _FakeSelection()sel.emit_repo_overview = False- sel.emit_arch_diagram = Falseids = selection_page_ids(sel, "demo")assert compute_page_id("repo_overview", "demo") not in ids- assert compute_page_id("architecture_diagram", "demo") not in idsdef test_ranked_ids_to_seed_keeps_unwritten_and_adds_structural() -> None:diff --git a/tests/unit/generation/test_onboarding.py b/tests/unit/generation/test_onboarding.pyindex 3201a4b21..a8e881d52 100644--- a/tests/unit/generation/test_onboarding.py+++ b/tests/unit/generation/test_onboarding.py@@ -174,10 +174,7 @@ def test_target_path_format() -> None:def test_promoted_slots_map() -> None:- assert PROMOTED_SLOTS == {- "repo_overview": "project_overview",- "architecture_diagram": "architecture_guide",- }+ assert PROMOTED_SLOTS == {"repo_overview": "project_overview"}# ---------------------------------------------------------------------------@@ -511,7 +508,10 @@ def test_tag_promoted_pages_sets_onboarding_slot() -> None:]PageGenerator._tag_promoted_pages(pages)assert pages[0].metadata["onboarding_slot"] == "project_overview"- assert pages[1].metadata["onboarding_slot"] == "architecture_guide"+ # The architecture diagram is no longer a page, so nothing promotes it. A+ # stale row from an older index must not be tagged into a slot that the+ # reading order no longer has.+ assert "onboarding_slot" not in pages[1].metadata# Non-promoted pages stay untouched.assert "onboarding_slot" not in pages[2].metadatadiff --git a/tests/unit/generation/test_overview_architecture_map.py b/tests/unit/generation/test_overview_architecture_map.pynew file mode 100644index 000000000..609ba905b--- /dev/null+++ b/tests/unit/generation/test_overview_architecture_map.py@@ -0,0 +1,101 @@+"""The architecture map is part of the repository overview.++It used to have a page of its own that described the same repository at the+same altitude and in the same words as the overview — the two shared roughly a+quarter of their vocabulary, so a reader who met both read one thing twice.+The diagram was the only thing that page uniquely had, so it moved here.++The map is the deterministic graph-derived one, not a diagram the model drew,+and it has to survive every path the overview can be produced by: the model+path, the deterministic path, and the fallback taken when the provider fails.+Losing it on the fallback would mean a provider outage silently costs the wiki+its architecture diagram.+"""++from __future__ import annotations++from dataclasses import dataclass, replace++import pytest++from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.models import GeneratedPage+from repowise.core.generation.page_generator import PageGenerator+from repowise.core.providers.llm.mock import MockProvider++_MERMAID = "graph TD\n A[cli] --> B[core]\n B --> C[server]"+++class _OutageProvider(MockProvider):+ """A provider that fails the way a real outage does: every call raises."""++ async def generate(self, *args, **kwargs):+ raise RuntimeError("upstream 529 overloaded")+++@dataclass+class _Case:+ name: str+ gen: PageGenerator+++def model_gen(sample_config) -> PageGenerator:+ return PageGenerator(MockProvider(), ContextAssembler(sample_config), sample_config)+++def outage_gen(sample_config) -> PageGenerator:+ return PageGenerator(_OutageProvider(), ContextAssembler(sample_config), sample_config)+++def deterministic_gen(sample_config) -> PageGenerator:+ cfg = replace(sample_config, deterministic=True)+ return PageGenerator(MockProvider(), ContextAssembler(cfg), cfg)+++async def _overview(+ gen: PageGenerator, sample_repo_structure, mermaid: str | None+) -> GeneratedPage:+ return await gen.generate_repo_overview(+ sample_repo_structure,+ pagerank={},+ sccs=[],+ community={},+ repo_name="demo",+ overview_mermaid=mermaid,+ )+++async def test_model_written_overview_carries_the_map(model_gen, sample_repo_structure):+ page = await _overview(model_gen, sample_repo_structure, _MERMAID)+ assert "## Architecture map" in page.content+ assert "```mermaid" in page.content+ assert "A[cli] --> B[core]" in page.content+++async def test_deterministic_overview_carries_the_map(deterministic_gen, sample_repo_structure):+ page = await _overview(deterministic_gen, sample_repo_structure, _MERMAID)+ assert "```mermaid" in page.content+ assert "A[cli] --> B[core]" in page.content+++async def test_provider_outage_keeps_the_map(outage_gen, sample_repo_structure):+ """A provider outage costs the prose around the diagram, never the diagram."""+ page = await _overview(outage_gen, sample_repo_structure, _MERMAID)+ assert "```mermaid" in page.content+ assert "A[cli] --> B[core]" in page.content+++async def test_embedding_is_idempotent(model_gen, sample_repo_structure):+ """Reused and cached pages are re-embedded on every run; that must be a no-op."""+ page = await _overview(model_gen, sample_repo_structure, _MERMAID)+ assert page.content.count("```mermaid") == 1+++async def test_no_map_available_leaves_the_page_alone(model_gen, sample_repo_structure):+ """An empty map must not stamp an empty diagram block onto the page."""+ page = await _overview(model_gen, sample_repo_structure, "")+ assert "```mermaid" not in page.content+ assert page.content.strip()diff --git a/tests/unit/generation/test_page_redirects.py b/tests/unit/generation/test_page_redirects.pyindex 0797b60ff..06096ab6c 100644--- a/tests/unit/generation/test_page_redirects.py+++ b/tests/unit/generation/test_page_redirects.py@@ -176,3 +176,22 @@ class TestShippedTables:def test_no_retired_type_is_also_a_successor_of_itself(self):for retired_type, successor in SUPERSEDED_TYPES.items():assert retired_type != successor+++# ---------------------------------------------------------------------------+# The architecture map moved onto the overview+# ---------------------------------------------------------------------------+++class TestArchitectureDiagramRetirement:+ def test_the_retired_page_resolves_to_the_overview(self):+ assert resolve_superseded("architecture_diagram:repowise") == "repo_overview:repowise"++ def test_it_resolves_for_any_repository(self):+ """The rule is a type rewrite, so it cannot be repo-specific."""+ for repo in ("repowise", "some/other-repo", "a"):+ assert resolve_superseded(f"architecture_diagram:{repo}") == f"repo_overview:{repo}"++ def test_the_overview_itself_is_not_redirected(self):+ assert resolve_superseded("repo_overview:repowise") is None+