gabriel / musehub public
test_doc_inf_registry.py python
189 lines 9.1 KB Hotspot
Raw
sha256:7513f245748d6667481e0ecef54e261ad11d4a664ba7128527060b240f4707bc docs(security): #260 Security Reference QA contract v2 — co… Sonnet 5.5 minor ⚠ breaking 7 days ago
1 """DOC_INF_02 (section registry + navigation) and DOC_INF_03 (internal links + anchors) — musehub#242.
2
3 ``ui_docs._PHASES`` is the single source of truth. Live-page checks render every /muse
4 route in-process (no lifespan, no database); known findings are strict-xfailed against the
5 page ticket that owns the fix, so closing that ticket flips the test to XPASS → failure
6 until the marker is removed. The ``TestCheckerDetects`` cases prove each check fires on a
7 real inconsistency.
8 """
9
10 from __future__ import annotations
11
12 import pytest
13
14 from musehub.api.routes.musehub import ui_docs
15 from musehub.api.routes.musehub.ui_docs import _PHASES
16 from musehub.main import app
17 from tests.docs_contract import registry_check as rc
18 from tests.docs_contract.pages import PAGES, SECTION_PAGES
19 from tests.docs_contract.pages import xfail_known as _xfail_known
20
21 # Known findings (2026-11-06, musehub dev 70e2deeb), each fixed under its page ticket.
22 _STALE_LABELS = set(map(rc.phase_path, ()))
23 _BROKEN_ANCHORS = set(map(rc.phase_path, (
24 "profiles", "security",
25 )))
26
27
28 @pytest.fixture(scope="module")
29 def parsed(rendered: dict[str, str]) -> dict[str, rc.ParsedPage]:
30 return {p: rc.parse_page(html) for p, html in rendered.items()}
31
32
33 @pytest.fixture(scope="module")
34 def anchor_problems(parsed: dict[str, rc.ParsedPage]) -> list[str]:
35 other = {r.path for r in app.routes if hasattr(r, "path")}
36 return rc.check_anchors(parsed, other_routes=other)
37
38
39 # ── DOC_INF_02: registry, routes, labels, landing, navigation ───────────────
40
41
42 def test_registry_is_well_formed() -> None:
43 assert rc.check_registry(_PHASES) == []
44
45
46 def test_every_section_has_a_route_and_every_route_a_section(rendered: dict[str, str]) -> None:
47 # ``rendered`` already asserts every registered path answers 200 through the app.
48 assert rc.check_route_coverage(_PHASES, {r.path for r in ui_docs.router.routes}) == []
49
50
51 @pytest.mark.parametrize("path", [_xfail_known(p, _STALE_LABELS, "stale section-number labels") for p in PAGES])
52 def test_section_labels_match_registry(path: str, parsed: dict[str, rc.ParsedPage]) -> None:
53 assert rc.check_section_labels(_PHASES, path, parsed[path]) == []
54
55
56 def test_landing_cards_and_section_count(rendered: dict[str, str], parsed: dict[str, rc.ParsedPage]) -> None:
57 assert rc.check_landing(_PHASES, rendered[rc.DOCS_ROOT], parsed[rc.DOCS_ROOT]) == []
58
59
60 def test_landing_has_one_card_per_section_in_order(rendered: dict[str, str], parsed: dict[str, rc.ParsedPage]) -> None:
61 problems = rc.check_landing(_PHASES, rendered[rc.DOCS_ROOT], parsed[rc.DOCS_ROOT])
62 assert [p for p in problems if "phase cards" in p] == []
63
64
65 @pytest.mark.parametrize("path", SECTION_PAGES)
66 def test_navigation_follows_registry(path: str, parsed: dict[str, rc.ParsedPage]) -> None:
67 current = path.removeprefix(rc.DOCS_ROOT + "/")
68 assert rc.check_navigation(_PHASES, current, path, parsed[path]) == []
69
70
71 # ── DOC_INF_03: internal links and anchors ──────────────────────────────────
72
73
74 @pytest.mark.parametrize("path", [_xfail_known(p, _BROKEN_ANCHORS, "in-page links without a target id") for p in PAGES])
75 def test_internal_links_and_anchors_resolve(path: str, anchor_problems: list[str]) -> None:
76 assert [p for p in anchor_problems if p.startswith(f"{path}: ")] == []
77
78
79 # ── The checker detects real inconsistencies ────────────────────────────────
80
81 _REG: list[rc.Phase] = [
82 ("alpha", "00", "Alpha Start", "a"),
83 ("beta", "01", "Beta Engine", "b"),
84 ("gamma", "02", "Gamma Reference", "c"),
85 ]
86
87
88 def _page(sidebar_active: str | None, prev: str | None, nxt: str, body: str = "") -> rc.ParsedPage:
89 side = "".join(
90 f'<a class="devdocs-nav-link devdocs-nav-link--phase{" devdocs-nav-link--active" if s == sidebar_active else ""}"'
91 f' href="/muse/{s}">{n} {t}</a>'
92 for s, n, t, _ in _REG
93 )
94 pager = (f'<a class="devdocs-phase-nav-btn" href="{prev}">prev</a>' if prev else "") + (
95 f'<a class="devdocs-phase-nav-btn devdocs-phase-nav-btn--next" href="{nxt}">next</a>'
96 )
97 return rc.parse_page(
98 f'<aside class="devdocs-sidebar"><nav class="devdocs-nav">{side}</nav></aside>'
99 f'<article>{body}<nav class="devdocs-phase-nav">{pager}</nav></article>'
100 )
101
102
103 class TestCheckerDetects:
104 def test_consistent_fixture_is_clean(self) -> None:
105 assert rc.check_registry(_REG) == []
106 assert rc.check_navigation(_REG, "beta", "beta", _page("beta", "/muse/alpha", "/muse/gamma")) == []
107 assert rc.check_navigation(_REG, "gamma", "gamma", _page("gamma", "/muse/beta", "/muse")) == []
108
109 def test_numbering_gap_and_order(self) -> None:
110 problems = rc.check_registry([_REG[0], ("beta", "02", "Beta Engine", "b"), _REG[2]])
111 assert problems == ["registry: 'beta' is numbered '02', expected '01' (position 1)"]
112
113 def test_duplicate_slug_and_title(self) -> None:
114 problems = rc.check_registry([_REG[0], ("alpha", "01", "Alpha Start", "b")])
115 assert "registry: duplicate slug 'alpha' (2×)" in problems
116 assert "registry: duplicate title 'Alpha Start' (2×)" in problems
117
118 def test_malformed_slug(self) -> None:
119 assert rc.check_registry([("Bad_Slug", "00", "T", "d")]) == [
120 "registry: slug 'Bad_Slug' is not a lowercase hyphenated path segment"
121 ]
122
123 def test_missing_and_orphan_routes(self) -> None:
124 problems = rc.check_route_coverage(_REG, {"/muse", "/muse/alpha", "/muse/beta", "/muse/delta"})
125 assert problems == [
126 "route: no route serves registered section /muse/gamma",
127 "route: /muse/delta is served but not in _PHASES",
128 ]
129
130 def test_stale_section_number_in_label(self) -> None:
131 page = rc.parse_page('<a href="/muse/gamma">01 Gamma Reference</a><a href="/muse/beta#x">01 Beta</a>')
132 assert rc.check_section_labels(_REG, "p", page) == [
133 "p: link to /muse/gamma labelled '01 Gamma Reference', but gamma is section 02"
134 ]
135
136 def test_every_label_format_is_checked(self) -> None:
137 page = rc.parse_page(
138 '<a href="/muse/beta">Phase 01: Beta Engine</a><a href="/muse/gamma">02 — Gamma Reference</a>'
139 '<a href="/muse/alpha">00 Alpha subsection</a>'
140 '<a href="/muse/beta">Phase 02: Beta</a><a href="/muse/gamma">01 — Gamma</a>'
141 )
142 assert rc.check_section_labels(_REG, "p", page) == [
143 "p: link to /muse/beta labelled 'Phase 02: Beta', but beta is section 01",
144 "p: link to /muse/gamma labelled '01 — Gamma', but gamma is section 02",
145 ]
146
147 def test_stale_section_count_and_missing_card(self) -> None:
148 html = (
149 '<span class="devdocs-stat-num">2</span><span class="devdocs-stat-label">doc sections</span>'
150 '<a class="devdocs-phase-card" href="/muse/alpha"></a><a class="devdocs-phase-card" href="/muse/beta"></a>'
151 )
152 problems = rc.check_landing(_REG, html, rc.parse_page(html))
153 assert len(problems) == 2
154 assert problems[0].startswith("landing: phase cards")
155 assert problems[1] == "landing: 'doc sections' stat shows ['2'], registry has 3"
156
157 def test_wrong_prev_next_and_active_state(self) -> None:
158 problems = rc.check_navigation(_REG, "beta", "beta", _page("alpha", "/muse/gamma", "/muse/alpha"))
159 assert problems == [
160 "beta: sidebar active entries ['/muse/alpha'], expected ['/muse/beta']",
161 "beta: previous-section link ['/muse/gamma'], expected ['/muse/alpha']",
162 "beta: next-section link ['/muse/alpha'], expected ['/muse/gamma']",
163 ]
164
165 def test_sidebar_missing_section(self) -> None:
166 page = rc.parse_page(
167 '<aside class="devdocs-sidebar"><a class="devdocs-nav-link--phase" href="/muse/alpha">00 Alpha</a></aside>'
168 )
169 assert rc.check_navigation(_REG, None, "idx", page) == [
170 "idx: sidebar sections ['/muse/alpha'] do not match registry order ['/muse/alpha', '/muse/beta', '/muse/gamma']"
171 ]
172
173 def test_broken_anchors_unknown_page_and_ambiguous_ids(self) -> None:
174 pages = {
175 "/muse/alpha": rc.parse_page(
176 '<h2 id="a1">A</h2><h2 id="a1">A</h2><symbol id="s"></symbol><symbol id="s"></symbol>'
177 '<a href="#nope">x</a><a href="#a1">dup</a><a href="#a1">dup</a>'
178 '<a href="/muse/beta#b1">ok</a><a href="/muse/beta#b9">x</a><a href="/muse/omega">x</a>'
179 '<a href="/muse/install.sh">route</a><a href="https://example.com/#z">ext</a>'
180 ),
181 "/muse/beta": rc.parse_page('<h2 id="b1">B</h2><a href="/muse/alpha#a1">dup</a>'),
182 }
183 assert rc.check_anchors(pages, other_routes={"/muse/install.sh"}) == [
184 "/muse/alpha: link '#nope' has no matching id on /muse/alpha",
185 "/muse/alpha: link '#a1' is ambiguous: id defined 2× on /muse/alpha",
186 "/muse/alpha: link '/muse/beta#b9' has no matching id on /muse/beta",
187 "/muse/alpha: link '/muse/omega' points at a docs page that is not served",
188 "/muse/beta: link '/muse/alpha#a1' is ambiguous: id defined 2× on /muse/alpha",
189 ]
File History 19 commits
sha256:7513f245748d6667481e0ecef54e261ad11d4a664ba7128527060b240f4707bc docs(security): #260 Security Reference QA contract v2 — co… Sonnet 5.5 minor ⚠ 7 days ago
sha256:4294c765f86bae7ca565b02af974c56bcd0e4288a71fcf1e3038231106f56ec1 docs(profiles): #256 Identity Profiles QA contract v2 (repl… Opus 5.5 minor ⚠ 9 days ago
sha256:417ffbc1d6761e3a4cd26ca5475d5a0b786ae8af936912b5ce31121e2e55c19a docs(mcp): #252 MCP Tooling QA contract v2 — correct /muse/… Opus 5.5 minor ⚠ 9 days ago
sha256:395afcc81bdadd355e87f50a1eb01b857ffdcce78f54635a77fe893ca7352528 docs(coordination): #251 Agent Coordination QA contract v2 … Opus 5.5 minor ⚠ 9 days ago
sha256:4c51ee348c9f4848b67c2553ad2375f244c210f999589abb2898c80f7b43a8ea docs(harmony): #250 Harmony QA contract v2 — correct /muse/… Opus 5.5 minor ⚠ 9 days ago
sha256:0914c802f6e5260fd54b28ecfb013b7815a76983780d5d2f854ef46c3ed36ab8 docs(merge): #249 Merge Engine QA contract v2 — correct /mu… Sonnet 5.5 minor ⚠ 9 days ago
sha256:e16f407d787df2320fb726a5ea8a5b5eb1d53e68135d8992373f0fd5b5319fa9 docs(intelligence): QA contract v2 — 148-claim audit, 20 co… Sonnet 5 minor ⚠ 9 days ago
sha256:7bef01440bfabe2977a6efa1a492091c4717e67d9ac79f5ebeb120d3fb87c3e0 docs(domains): QA contract v2 — executable minimal plugin, … Opus 5.5 minor ⚠ 9 days ago
sha256:634da27c5b4ea6e3cb5aa9cfb4e58dbf922b627caef67ffb0cb64bcaf70b7b9f Merge task/246-identity-qa-v2 (#246 Cryptographic Identity … Opus 5.5 minor ⚠ 9 days ago
sha256:2de1e96b7f547494958a8edace1860efc2c0de0933c4f00f777f2cc18abaf324 docs(identity): QA contract v2 for /muse/identity against m… Opus 5.5 minor ⚠ 9 days ago
sha256:56adfc888ae758960c3b8cf64dccb458d15a59a20505c0a97dc372867cd91404 Merge task/253-shelves-qa-v2 (#253 Shelves QA contract v2) … Opus 5.5 minor ⚠ 9 days ago
sha256:aba9127573acf011a1da39099eb32f7b3eeeeb98719df179f5ca39bf70b51e4e docs(shelves): QA contract v2 — engine-verified shelf contr… Opus 5.5 minor ⚠ 9 days ago
sha256:0d8df91e78d3fa8d14d82f9b35de2f6991462e104025f8f1d80174f55cd18fb6 docs(foundations): QA contract v2 — verified object model, … Opus 5.5 minor ⚠ 9 days ago
sha256:f7413c1abec6d6a8e5bdabcd4cc7ad5fcd059ce6a6f50f566e2b0118a0a8b578 tests: make tests/docs_contract/ database-free by directory… Opus 5.5 10 days ago
sha256:4414683727ea0547451795e9f87989be0031d71016b9595460967dcbb446ddc8 Merge dev (#243 landing) into task/244-docs-getting-started… Opus 5.5 patch 10 days ago
sha256:5745f056592123707326093fbe1c8fb6430304821fa6edf5263606624fc45883 docs(getting-started): teach a signed, verifiable first-run… Opus 5.5 minor ⚠ 10 days ago
sha256:4a670eb4493ce4626bb9b9380af6057d90cb61ac4af2800d4b03f3ec61ee70dc docs(landing): derive /muse stats and reading paths from th… Opus 5.5 patch 10 days ago
sha256:0e4f9453dfdeb2c10fb31581a5b195aa7af7d349f90e5904bd38e1c1f7d19cc0 test(docs): check every documented muse command against the… Opus 5.5 10 days ago
sha256:de2fd68a7904c36988c5b4cca0ab59979f72f385b701e9ac556d466c2725d64e test(docs): verify the /muse section registry, navigation a… Opus 5.5 minor ⚠ 10 days ago