gabriel / musehub public
registry_check.py python
234 lines 10.3 KB
Raw
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