Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
new file mode 100644
index 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.py
index 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, Response
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.generation.page_redirects import SupersededError, resolve_superseded
from repowise.core.persistence import crud
from repowise.core.persistence.models import _now_utc
from 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 a
page id that exists in another repo comes back as a 404 — so any caller
that 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.py
new file mode 100644
index 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 != successor
diff --git a/tests/unit/server/test_pages.py b/tests/unit/server/test_pages.py
index 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 == 400
assert "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