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(pages): retired page ids keep resolving (#1163)
Swati Ahuja600efe7e0903
diff --git a/packages/core/src/repowise/core/generation/page_redirects.py b/packages/core/src/repowise/core/generation/page_redirects.pynew file mode 100644index 000000000..3a041c62b--- /dev/null+++ b/packages/core/src/repowise/core/generation/page_redirects.py@@ -0,0 +1,136 @@+"""Where a retired wiki page id sends the reader.++Wiki pages are public and linkable, so a page that stops being generated+cannot simply vanish — every id that was ever served has to keep resolving to+something. This module owns that mapping and nothing else: it turns a retired+page id into the id of the page that took over its material.++Page ids are ``{page_type}:{target_path}`` (see ``models.compute_page_id``).+Retirements come in two shapes and the tables mirror that:++* **A whole page type folds into another.** Its target path is usually the+ repository name, which differs per repo, so the rule cannot be written as a+ literal id. :data:`SUPERSEDED_TYPES` rewrites the type and carries the path+ across unchanged.+* **One page with a fixed target path retires.** The onboarding slots are+ ``onboarding/{slot}`` for every repo, so these can be written as exact ids in+ :data:`SUPERSEDED_IDS`.++Retirements chain: a page folded into a second page that later folds into a+third must land on the third, not the second, or the redirect leads somewhere+that is itself gone. :func:`resolve_superseded` follows the chain to its end.++Everything here fails loudly. A redirect table is exactly the kind of thing+that rots silently — a cycle would hang, a typo'd successor would strand every+inbound link — and either would read as "no redirect needed" rather than as an+error. So a cycle raises, a malformed id raises, and the shipped tables are+walked by a test that resolves every entry in them.+"""++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] = {}++# Retired page id → successor page id, in full. For pages whose target path is+# the same in every repository.+SUPERSEDED_IDS: dict[str, str] = {}++# A chain longer than this is a table authoring mistake rather than a real+# history — the orientation set has never held more than a handful of pages.+# Bounded so a table that somehow evades cycle detection cannot spin forever.+_MAX_CHAIN = 16+++class SupersededError(Exception):+ """Base for redirect-table failures."""+++class SupersededCycleError(SupersededError):+ """A retirement chain loops, so it has no destination."""+++class SupersededTargetError(SupersededError):+ """A page id is not ``{page_type}:{target_path}``."""+++def _split(page_id: str) -> tuple[str, str]:+ """Split an id into (page_type, target_path) on the first colon.++ Target paths may themselves contain colons, so only the first separator is+ significant.+ """+ page_type, sep, target_path = page_id.partition(":")+ if not sep or not page_type:+ raise SupersededTargetError(f"Page id {page_id!r} is not '{{page_type}}:{{target_path}}'.")+ return page_type, target_path+++def _successor(+ page_id: str,+ superseded_types: dict[str, str],+ superseded_ids: dict[str, str],+) -> str | None:+ """One hop, or ``None`` when this id is still live.++ An exact-id rule is more specific than a type-level one and wins.+ """+ exact = superseded_ids.get(page_id)+ if exact is not None:+ _split(exact) # a successor that is not a page id strands the link+ return exact++ page_type, target_path = _split(page_id)+ successor_type = superseded_types.get(page_type)+ if successor_type is None:+ return None+ return f"{successor_type}:{target_path}"+++def resolve_superseded(+ page_id: str,+ *,+ superseded_types: dict[str, str] | None = None,+ superseded_ids: dict[str, str] | None = None,+) -> str | None:+ """The live page id a retired one now points at, or ``None``.++ Follows retirement chains to their end, so the returned id is the page that+ is actually generated today rather than an intermediate that has itself+ been retired.++ Args:+ page_id: The id to resolve, ``{page_type}:{target_path}``.+ superseded_types: Overrides the shipped type table. For tests.+ superseded_ids: Overrides the shipped exact-id table. For tests.++ Returns:+ The successor id, or ``None`` when ``page_id`` is not retired.++ Raises:+ SupersededTargetError: ``page_id`` or a successor is malformed.+ SupersededCycleError: the chain loops and has no destination.+ """+ types = SUPERSEDED_TYPES if superseded_types is None else superseded_types+ ids = SUPERSEDED_IDS if superseded_ids is None else superseded_ids++ _split(page_id) # reject a malformed id even when no rule matches++ seen = [page_id]+ current = page_id+ for _ in range(_MAX_CHAIN):+ nxt = _successor(current, types, ids)+ if nxt is None:+ # ``current`` is live. It is a redirect only if we moved at all.+ return current if current != page_id else None+ if nxt in seen:+ raise SupersededCycleError(+ "Retirement chain loops and has no destination: " + " -> ".join([*seen, nxt])+ )+ seen.append(nxt)+ current = nxt++ raise SupersededCycleError(+ f"Retirement chain from {page_id!r} exceeded {_MAX_CHAIN} hops: " + " -> ".join(seen)+ )diff --git a/packages/server/src/repowise/server/routers/pages.py b/packages/server/src/repowise/server/routers/pages.pyindex f3176cbf5..80fe745f5 100644--- a/packages/server/src/repowise/server/routers/pages.py+++ b/packages/server/src/repowise/server/routers/pages.py@@ -7,10 +7,12 @@ parameter greedily matches the suffix as part of the page_id.from __future__ import annotations-from fastapi import APIRouter, Depends, HTTPException, Query, Request+import structlog+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Responsefrom pydantic import BaseModelfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.generation.page_redirects import SupersededError, resolve_supersededfrom repowise.core.persistence import crudfrom repowise.core.persistence.models import _now_utcfrom repowise.server.deps import get_db_session, verify_api_key@@ -20,12 +22,60 @@ from repowise.server.schemas import (PageVersionResponse,)+logger = structlog.get_logger(__name__)+router = APIRouter(prefix="/api/pages",tags=["pages"],dependencies=[Depends(verify_api_key)],)+# Names the id the reader actually asked for when they were moved. Without it a+# redirect is indistinguishable from having requested the successor directly,+# and a client cannot tell the reader their link is out of date.+REDIRECTED_FROM_HEADER = "X-Repowise-Redirected-From"+++async def _get_page_or_successor(session: AsyncSession, page_id: str, response: Response):+ """The requested page, or the page that took over from it.++ Wiki pages are public and linkable, so an id that stops being generated has+ to keep resolving. A miss is retried against the retirement table before it+ becomes a 404.++ Returns ``None`` when neither the page nor a successor exists — callers+ raise the 404, so a genuine miss can never be turned into a success here.+ """+ page = await crud.get_page(session, page_id)+ if page is not None:+ return page++ try:+ successor_id = resolve_superseded(page_id)+ except SupersededError:+ # The table is static and a test resolves every entry in it, so this+ # means a real bug. It must not take page serving down with it.+ logger.warning("page_redirect_table_broken", page_id=page_id, exc_info=True)+ return None++ if successor_id is None:+ return None++ successor = await crud.get_page(session, successor_id)+ if successor is None:+ # The table points at a page this index did not produce. Every inbound+ # link to the retired id is stranded, so say so rather than 404ing mute.+ logger.warning(+ "page_redirect_successor_missing",+ page_id=page_id,+ successor_id=successor_id,+ )+ return None++ logger.info("page_redirect_served", page_id=page_id, successor_id=successor_id)+ response.headers[REDIRECTED_FROM_HEADER] = page_id+ return successor+@router.get("", response_model=None)async def list_pages(@@ -77,6 +127,7 @@ async def list_pages(@router.get("/lookup", response_model=PageResponse)async def get_page_by_query(+ response: Response,page_id: str = Query(..., description="Page ID (e.g. file_page:src/main.py)"),repo_id: str | None = Query(None,@@ -95,8 +146,11 @@ async def get_page_by_query(workspace server looks the page up in whichever store is the default, and apage id that exists in another repo comes back as a 404 — so any callerthat knows the repo should say so.++ A retired page id resolves to whatever took over from it; the response then+ carries ``X-Repowise-Redirected-From``."""- page = await crud.get_page(session, page_id)+ page = await _get_page_or_successor(session, page_id, response)if page is None:raise HTTPException(status_code=404, detail="Page not found")return PageResponse.from_orm(page)@@ -205,13 +259,17 @@ async def regenerate_page_by_query(@router.get("/{page_id:path}", response_model=PageResponse)async def get_page(page_id: str,+ response: Response,session: AsyncSession = Depends(get_db_session),) -> PageResponse:"""Get a single wiki page by ID in path (e.g. ``file_page:src/main.py``).The page_id is URL-decoded automatically by FastAPI.++ A retired page id resolves to whatever took over from it; the response then+ carries ``X-Repowise-Redirected-From``."""- page = await crud.get_page(session, page_id)+ page = await _get_page_or_successor(session, page_id, response)if page is None:raise HTTPException(status_code=404, detail="Page not found")return PageResponse.from_orm(page)diff --git a/tests/unit/generation/test_page_redirects.py b/tests/unit/generation/test_page_redirects.pynew file mode 100644index 000000000..0797b60ff--- /dev/null+++ b/tests/unit/generation/test_page_redirects.py@@ -0,0 +1,178 @@+"""Resolution of retired wiki page ids onto their successors."""++from __future__ import annotations++import pytest++from repowise.core.generation.page_redirects import (+ SUPERSEDED_IDS,+ SUPERSEDED_TYPES,+ SupersededCycleError,+ SupersededTargetError,+ resolve_superseded,+)++# ---------------------------------------------------------------------------+# Page-type retirement — the target path is carried across unchanged+# ---------------------------------------------------------------------------+++class TestTypeRetirement:+ def test_retired_type_keeps_its_target_path(self):+ """A whole page type folded into another keeps the repo it described."""+ resolved = resolve_superseded(+ "architecture_diagram:repowise",+ superseded_types={"architecture_diagram": "repo_overview"},+ )+ assert resolved == "repo_overview:repowise"++ def test_target_path_containing_colons_survives(self):+ """Ids split on the first colon only — paths may contain more."""+ resolved = resolve_superseded(+ "architecture_diagram:weird:repo:name",+ superseded_types={"architecture_diagram": "repo_overview"},+ )+ assert resolved == "repo_overview:weird:repo:name"++ def test_live_type_resolves_to_nothing(self):+ assert (+ resolve_superseded(+ "repo_overview:repowise",+ superseded_types={"architecture_diagram": "repo_overview"},+ )+ is None+ )+++# ---------------------------------------------------------------------------+# Exact-id retirement — used where the target path is fixed, not per-repo+# ---------------------------------------------------------------------------+++class TestExactIdRetirement:+ def test_retired_id_resolves_to_its_successor(self):+ resolved = resolve_superseded(+ "onboarding:onboarding/how_it_works",+ superseded_ids={+ "onboarding:onboarding/how_it_works": "onboarding:onboarding/guided_tour"+ },+ )+ assert resolved == "onboarding:onboarding/guided_tour"++ def test_exact_id_wins_over_type_rule(self):+ """A page-level retirement is more specific than a type-level one.++ Both rules match the same source id and disagree; the exact one is the+ deliberate statement about this one page and takes precedence.+ """+ resolved = resolve_superseded(+ "architecture_diagram:repowise",+ superseded_ids={"architecture_diagram:repowise": "onboarding:onboarding/guided_tour"},+ superseded_types={"architecture_diagram": "repo_overview"},+ )+ assert resolved == "onboarding:onboarding/guided_tour"+++# ---------------------------------------------------------------------------+# Chains+# ---------------------------------------------------------------------------+++class TestTransitiveChains:+ def test_chain_resolves_to_its_final_destination(self):+ """A page retired twice lands on the page that is actually alive."""+ resolved = resolve_superseded(+ "onboarding:onboarding/a",+ superseded_ids={+ "onboarding:onboarding/a": "onboarding:onboarding/b",+ "onboarding:onboarding/b": "onboarding:onboarding/c",+ },+ )+ assert resolved == "onboarding:onboarding/c"++ def test_chain_across_both_rule_kinds(self):+ resolved = resolve_superseded(+ "architecture_diagram:repowise",+ superseded_types={"architecture_diagram": "repo_overview"},+ superseded_ids={"repo_overview:repowise": "onboarding:onboarding/overview"},+ )+ assert resolved == "onboarding:onboarding/overview"+++# ---------------------------------------------------------------------------+# Loud failures. A redirect table that quietly points nowhere strands every+# inbound link that depended on it, and reads as a pass.+# ---------------------------------------------------------------------------+++class TestFailuresAreLoud:+ def test_direct_cycle_raises(self):+ with pytest.raises(SupersededCycleError) as exc:+ resolve_superseded(+ "onboarding:onboarding/a",+ superseded_ids={+ "onboarding:onboarding/a": "onboarding:onboarding/b",+ "onboarding:onboarding/b": "onboarding:onboarding/a",+ },+ )+ assert "onboarding:onboarding/a" in str(exc.value)++ def test_self_cycle_raises(self):+ with pytest.raises(SupersededCycleError):+ resolve_superseded(+ "onboarding:onboarding/a",+ superseded_ids={"onboarding:onboarding/a": "onboarding:onboarding/a"},+ )++ def test_type_level_cycle_raises(self):+ with pytest.raises(SupersededCycleError):+ resolve_superseded(+ "architecture_diagram:repowise",+ superseded_types={+ "architecture_diagram": "repo_overview",+ "repo_overview": "architecture_diagram",+ },+ )++ def test_successor_without_a_page_type_raises(self):+ """A successor id must itself be ``{page_type}:{target_path}``."""+ with pytest.raises(SupersededTargetError):+ resolve_superseded(+ "onboarding:onboarding/a",+ superseded_ids={"onboarding:onboarding/a": "no-colon-here"},+ )++ def test_malformed_page_id_raises(self):+ with pytest.raises(SupersededTargetError):+ resolve_superseded("no-colon-here", superseded_types={"a": "b"})++ def test_empty_page_id_raises(self):+ with pytest.raises(SupersededTargetError):+ resolve_superseded("", superseded_types={"a": "b"})+++# ---------------------------------------------------------------------------+# The shipped tables+# ---------------------------------------------------------------------------+++class TestShippedTables:+ def test_unknown_id_resolves_to_nothing_against_the_real_tables(self):+ """A live page must never be redirected away from itself."""+ assert resolve_superseded("file_page:packages/core/pyproject.toml") is None++ def test_shipped_tables_are_internally_consistent(self):+ """Every retired id in the shipped tables resolves without raising.++ This is the guard that keeps a future entry from shipping a cycle or a+ malformed successor. It walks what is actually shipped, so it cannot+ drift from the tables the way a hand-written list would.+ """+ for retired_id in SUPERSEDED_IDS:+ assert resolve_superseded(retired_id) is not None+ for retired_type in SUPERSEDED_TYPES:+ assert resolve_superseded(f"{retired_type}:some-repo") is not None++ def test_no_retired_type_is_also_a_successor_of_itself(self):+ for retired_type, successor in SUPERSEDED_TYPES.items():+ assert retired_type != successordiff --git a/tests/unit/server/test_pages.py b/tests/unit/server/test_pages.pyindex 0471e628a..b18db5528 100644--- a/tests/unit/server/test_pages.py+++ b/tests/unit/server/test_pages.py@@ -330,3 +330,77 @@ async def test_regenerate_page_rejects_unknown_style(client: AsyncClient, app) -)assert resp.status_code == 400assert "style" in resp.json()["detail"].lower()++# ---------------------------------------------------------------------------+# Retired page ids+#+# Wiki pages are public and linkable. A page that stops being generated has to+# keep resolving, or every inbound link to it breaks silently on the next index.+# ---------------------------------------------------------------------------+++_REDIRECTS = "repowise.server.routers.pages.resolve_superseded"+++async def test_retired_page_id_serves_its_successor(client: AsyncClient, app) -> None:+ _, page_id = await _create_page(client, app.state.session_factory)+ with patch(_REDIRECTS, return_value=page_id):+ resp = await client.get("/api/pages/architecture_diagram:gone")+ assert resp.status_code == 200+ body = resp.json()+ # The reader gets the successor, and can see that they moved: the id in the+ # body is the successor's, not the one they asked for.+ assert body["id"] == page_id+ assert resp.headers["x-repowise-redirected-from"] == "architecture_diagram:gone"+++async def test_retired_page_id_redirects_on_lookup_too(client: AsyncClient, app) -> None:+ """The query-param form is the one the UI uses; it must behave the same."""+ _, page_id = await _create_page(client, app.state.session_factory)+ with patch(_REDIRECTS, return_value=page_id):+ resp = await client.get(+ "/api/pages/lookup", params={"page_id": "architecture_diagram:gone"}+ )+ assert resp.status_code == 200+ assert resp.json()["id"] == page_id+ assert resp.headers["x-repowise-redirected-from"] == "architecture_diagram:gone"+++async def test_live_page_is_not_redirected(client: AsyncClient, app) -> None:+ """A page that exists is served as itself and never consults the table."""+ _, page_id = await _create_page(client, app.state.session_factory)+ resp = await client.get(f"/api/pages/{page_id}")+ assert resp.status_code == 200+ assert resp.json()["id"] == page_id+ assert "x-repowise-redirected-from" not in resp.headers+++async def test_unknown_page_id_still_404s(client: AsyncClient, app) -> None:+ """Nothing in the redirect path may turn a genuine miss into a success."""+ await _create_page(client, app.state.session_factory)+ resp = await client.get("/api/pages/file_page:does/not/exist.py")+ assert resp.status_code == 404+++async def test_successor_that_does_not_exist_404s(client: AsyncClient, app) -> None:+ """A redirect pointing at a missing page is a miss, not a 500."""+ await _create_page(client, app.state.session_factory)+ with patch(_REDIRECTS, return_value="file_page:also/missing.py"):+ resp = await client.get("/api/pages/architecture_diagram:gone")+ assert resp.status_code == 404+++async def test_broken_redirect_table_does_not_500_the_reader(client: AsyncClient, app) -> None:+ """A cycle is a bug, but it must degrade to a 404 rather than a crash."""+ from repowise.core.generation.page_redirects import SupersededCycleError++ await _create_page(client, app.state.session_factory)+ with patch(_REDIRECTS, side_effect=SupersededCycleError("a -> b -> a")):+ resp = await client.get("/api/pages/architecture_diagram:gone")+ assert resp.status_code == 404