registry_check.py
python
sha256:de2fd68a7904c36988c5b4cca0ab59979f72f385b701e9ac556d466c2725d64e
test(docs): verify the /muse section registry, navigation a…
Opus 5.5
minor
⚠ breaking
10 days ago
| 1 | """Section-registry, navigation and internal-anchor checks for the /muse docs (musehub#242 W2.2, W2.3). |
| 2 | |
| 3 | ``ui_docs._PHASES`` is the single source of truth for section slugs, numbers and titles. |
| 4 | Every function here is pure: it takes the registry plus rendered HTML (or route paths) and |
| 5 | returns a list of human-readable problems, empty when consistent. The tests in |
| 6 | ``test_doc_inf_registry.py`` feed it both the live pages and deliberately broken inputs. |
| 7 | """ |
| 8 | |
| 9 | from __future__ import annotations |
| 10 | |
| 11 | import re |
| 12 | from collections import Counter |
| 13 | from collections.abc import Collection, Iterable, Mapping, Sequence |
| 14 | from dataclasses import dataclass, field |
| 15 | from html.parser import HTMLParser |
| 16 | |
| 17 | DOCS_ROOT = "/muse" |
| 18 | |
| 19 | Phase = tuple[str, str, str, str] # (slug, num, title, desc), the shape of ui_docs._PHASES |
| 20 | |
| 21 | _SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$") |
| 22 | # "05 Harmony", "Phase 01: Foundations", "15 — CRDT Primitives" |
| 23 | _LABEL_RE = re.compile(r"^(?:Phase\s+)?(\d{2})(?:\s*[:—–-])?\s+(\S.*)$") |
| 24 | |
| 25 | |
| 26 | @dataclass |
| 27 | class Anchor: |
| 28 | href: str |
| 29 | classes: frozenset[str] |
| 30 | text: str |
| 31 | in_sidebar: bool |
| 32 | in_pager: bool |
| 33 | |
| 34 | |
| 35 | @dataclass |
| 36 | class ParsedPage: |
| 37 | ids: list[str] = field(default_factory=list) |
| 38 | anchors: list[Anchor] = field(default_factory=list) |
| 39 | |
| 40 | |
| 41 | class _DocsParser(HTMLParser): |
| 42 | def __init__(self) -> None: |
| 43 | super().__init__(convert_charrefs=True) |
| 44 | self.page = ParsedPage() |
| 45 | self._aside_depth = 0 |
| 46 | self._sidebar_at: int | None = None |
| 47 | self._nav_depth = 0 |
| 48 | self._pager_at: int | None = None |
| 49 | self._open: dict[str, object] | None = None |
| 50 | |
| 51 | def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: |
| 52 | a = {k: v or "" for k, v in attrs} |
| 53 | classes = frozenset(a.get("class", "").split()) |
| 54 | if "id" in a: |
| 55 | self.page.ids.append(a["id"]) |
| 56 | if tag == "aside": |
| 57 | self._aside_depth += 1 |
| 58 | if "devdocs-sidebar" in classes and self._sidebar_at is None: |
| 59 | self._sidebar_at = self._aside_depth |
| 60 | elif tag == "nav": |
| 61 | self._nav_depth += 1 |
| 62 | if "devdocs-phase-nav" in classes and self._pager_at is None: |
| 63 | self._pager_at = self._nav_depth |
| 64 | elif tag == "a" and "href" in a: |
| 65 | self._open = {"href": a["href"], "classes": classes, "text": []} |
| 66 | |
| 67 | def handle_endtag(self, tag: str) -> None: |
| 68 | if tag == "aside": |
| 69 | if self._sidebar_at == self._aside_depth: |
| 70 | self._sidebar_at = None |
| 71 | self._aside_depth -= 1 |
| 72 | elif tag == "nav": |
| 73 | if self._pager_at == self._nav_depth: |
| 74 | self._pager_at = None |
| 75 | self._nav_depth -= 1 |
| 76 | elif tag == "a" and self._open is not None: |
| 77 | text = " ".join("".join(self._open["text"]).split()) # type: ignore[arg-type] |
| 78 | self.page.anchors.append(Anchor( |
| 79 | href=str(self._open["href"]), |
| 80 | classes=self._open["classes"], # type: ignore[arg-type] |
| 81 | text=text, |
| 82 | in_sidebar=self._sidebar_at is not None, |
| 83 | in_pager=self._pager_at is not None, |
| 84 | )) |
| 85 | self._open = None |
| 86 | |
| 87 | def handle_data(self, data: str) -> None: |
| 88 | if self._open is not None: |
| 89 | self._open["text"].append(data) # type: ignore[union-attr] |
| 90 | |
| 91 | |
| 92 | def parse_page(html: str) -> ParsedPage: |
| 93 | parser = _DocsParser() |
| 94 | parser.feed(html) |
| 95 | parser.close() |
| 96 | return parser.page |
| 97 | |
| 98 | |
| 99 | def phase_path(slug: str) -> str: |
| 100 | return f"{DOCS_ROOT}/{slug}" |
| 101 | |
| 102 | |
| 103 | def _split(href: str) -> tuple[str, str]: |
| 104 | path, _, frag = href.partition("#") |
| 105 | return path, frag |
| 106 | |
| 107 | |
| 108 | # ── Registry ──────────────────────────────────────────────────────────────── |
| 109 | |
| 110 | |
| 111 | def check_registry(phases: Sequence[Phase]) -> list[str]: |
| 112 | """Numbers are two-digit, contiguous from 00, in order; slugs and titles are unique and well-formed.""" |
| 113 | problems: list[str] = [] |
| 114 | for i, (slug, num, title, desc) in enumerate(phases): |
| 115 | expected = f"{i:02d}" |
| 116 | if num != expected: |
| 117 | problems.append(f"registry: '{slug}' is numbered {num!r}, expected {expected!r} (position {i})") |
| 118 | if not _SLUG_RE.match(slug): |
| 119 | problems.append(f"registry: slug {slug!r} is not a lowercase hyphenated path segment") |
| 120 | if not title.strip() or not desc.strip(): |
| 121 | problems.append(f"registry: '{slug}' has an empty title or description") |
| 122 | for kind, values in (("slug", [p[0] for p in phases]), ("title", [p[2] for p in phases])): |
| 123 | for value, n in Counter(values).items(): |
| 124 | if n > 1: |
| 125 | problems.append(f"registry: duplicate {kind} {value!r} ({n}×)") |
| 126 | return problems |
| 127 | |
| 128 | |
| 129 | def check_route_coverage(phases: Sequence[Phase], docs_route_paths: Iterable[str]) -> list[str]: |
| 130 | """Every registered slug has a docs route, and every docs route (other than the index) is registered.""" |
| 131 | routes = set(docs_route_paths) |
| 132 | registered = {phase_path(p[0]) for p in phases} |
| 133 | problems = [f"route: no route serves registered section {path}" for path in sorted(registered - routes)] |
| 134 | problems += [f"route: {path} is served but not in _PHASES" for path in sorted(routes - registered - {DOCS_ROOT})] |
| 135 | return problems |
| 136 | |
| 137 | |
| 138 | # ── Rendered pages ────────────────────────────────────────────────────────── |
| 139 | |
| 140 | |
| 141 | def check_section_labels(phases: Sequence[Phase], page: str, parsed: ParsedPage) -> list[str]: |
| 142 | """Every link to a section whose text carries an "NN …" label uses the registry's number. |
| 143 | |
| 144 | Only the number is compared: link text legitimately abbreviates the title or names a |
| 145 | subsection ("13 Mists", "Phase 06 — Reservations"). |
| 146 | """ |
| 147 | by_path = {phase_path(p[0]): p for p in phases} |
| 148 | problems: list[str] = [] |
| 149 | for a in parsed.anchors: |
| 150 | if "devdocs-phase-card" in a.classes: |
| 151 | continue # cards are rendered from _PHASES; covered by check_landing |
| 152 | phase = by_path.get(_split(a.href)[0]) |
| 153 | m = _LABEL_RE.match(a.text) |
| 154 | if phase is None or m is None: |
| 155 | continue |
| 156 | slug, want_num = phase[0], phase[1] |
| 157 | if m.group(1) != want_num: |
| 158 | problems.append(f"{page}: link to /muse/{slug} labelled {a.text!r}, but {slug} is section {want_num}") |
| 159 | return problems |
| 160 | |
| 161 | |
| 162 | def check_landing(phases: Sequence[Phase], html: str, parsed: ParsedPage) -> list[str]: |
| 163 | """The index links one card per section and its "doc sections" stat equals the registry size.""" |
| 164 | problems: list[str] = [] |
| 165 | cards = [_split(a.href)[0] for a in parsed.anchors if "devdocs-phase-card" in a.classes] |
| 166 | want = [phase_path(p[0]) for p in phases] |
| 167 | if cards != want: |
| 168 | problems.append(f"landing: phase cards {cards} do not match registry order {want}") |
| 169 | stats = re.findall( |
| 170 | r'class="devdocs-stat-num">\s*([^<]*?)\s*</span>\s*<span class="devdocs-stat-label">\s*([^<]*?)\s*</span>', |
| 171 | html, |
| 172 | ) |
| 173 | sections = [n for n, label in stats if label.lower() == "doc sections"] |
| 174 | if sections != [str(len(phases))]: |
| 175 | problems.append(f"landing: 'doc sections' stat shows {sections}, registry has {len(phases)}") |
| 176 | return problems |
| 177 | |
| 178 | |
| 179 | def check_navigation(phases: Sequence[Phase], current: str | None, page: str, parsed: ParsedPage) -> list[str]: |
| 180 | """Sidebar lists every section in registry order with exactly ``current`` active; prev/next follow the registry.""" |
| 181 | problems: list[str] = [] |
| 182 | side = [a for a in parsed.anchors if a.in_sidebar and "devdocs-nav-link--phase" in a.classes] |
| 183 | want = [phase_path(p[0]) for p in phases] |
| 184 | got = [_split(a.href)[0] for a in side] |
| 185 | if got != want: |
| 186 | problems.append(f"{page}: sidebar sections {got} do not match registry order {want}") |
| 187 | active = [_split(a.href)[0] for a in side if "devdocs-nav-link--active" in a.classes] |
| 188 | want_active = [] if current is None else [phase_path(current)] |
| 189 | if active != want_active: |
| 190 | problems.append(f"{page}: sidebar active entries {active}, expected {want_active}") |
| 191 | if current is None: |
| 192 | return problems |
| 193 | |
| 194 | slugs = [p[0] for p in phases] |
| 195 | i = slugs.index(current) |
| 196 | pager = [a for a in parsed.anchors if a.in_pager] |
| 197 | nexts = [a for a in pager if "devdocs-phase-nav-btn--next" in a.classes] |
| 198 | prevs = [a for a in pager if "devdocs-phase-nav-btn--next" not in a.classes] |
| 199 | want_prev = [phase_path(slugs[i - 1])] if i > 0 else [] |
| 200 | want_next = [phase_path(slugs[i + 1])] if i + 1 < len(slugs) else [DOCS_ROOT] |
| 201 | got_prev = [_split(a.href)[0] for a in prevs if _split(a.href)[0] != DOCS_ROOT] |
| 202 | got_next = [_split(a.href)[0] for a in nexts] |
| 203 | if got_prev != want_prev: |
| 204 | problems.append(f"{page}: previous-section link {got_prev}, expected {want_prev}") |
| 205 | if got_next != want_next: |
| 206 | problems.append(f"{page}: next-section link {got_next}, expected {want_next}") |
| 207 | return problems |
| 208 | |
| 209 | |
| 210 | def check_anchors(pages: Mapping[str, ParsedPage], other_routes: Collection[str] = ()) -> list[str]: |
| 211 | """Every same-page ``#frag`` and every ``/muse...`` link resolves to a page and to exactly one id there. |
| 212 | |
| 213 | ``other_routes`` are served non-docs paths under /muse (e.g. ``/muse/install.sh``): valid targets |
| 214 | whose fragments are not checked. Duplicate ids are reported only when a link targets them |
| 215 | (shared SVG sprite symbol ids are not anchors). |
| 216 | """ |
| 217 | problems: list[str] = [] |
| 218 | counts = {path: Counter(parsed.ids) for path, parsed in pages.items()} |
| 219 | for path, parsed in pages.items(): |
| 220 | for a in parsed.anchors: |
| 221 | target, frag = _split(a.href) |
| 222 | if target == "": |
| 223 | target = path |
| 224 | elif target != DOCS_ROOT and not target.startswith(DOCS_ROOT + "/"): |
| 225 | continue # external or non-docs link: out of scope (no network in unit tests) |
| 226 | if target not in pages: |
| 227 | if target in other_routes: |
| 228 | continue |
| 229 | problems.append(f"{path}: link {a.href!r} points at a docs page that is not served") |
| 230 | elif frag and frag not in pages[target].ids: |
| 231 | problems.append(f"{path}: link {a.href!r} has no matching id on {target}") |
| 232 | elif frag and counts[target][frag] > 1: |
| 233 | problems.append(f"{path}: link {a.href!r} is ambiguous: id defined {counts[target][frag]}× on {target}") |
| 234 | return list(dict.fromkeys(problems)) |
File History
1 commit
sha256:de2fd68a7904c36988c5b4cca0ab59979f72f385b701e9ac556d466c2725d64e
test(docs): verify the /muse section registry, navigation a…
Opus 5.5
minor
⚠
10 days ago