gabriel / musehub public
test_doc_inf_registry.py python
187 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
25
26 @pytest.fixture(scope="module")
27 def parsed(rendered: dict[str, str]) -> dict[str, rc.ParsedPage]:
28 return {p: rc.parse_page(html) for p, html in rendered.items()}
29
30
31 @pytest.fixture(scope="module")
32 def anchor_problems(parsed: dict[str, rc.ParsedPage]) -> list[str]:
33 other = {r.path for r in app.routes if hasattr(r, "path")}
34 return rc.check_anchors(parsed, other_routes=other)
35
36
37 # ── DOC_INF_02: registry, routes, labels, landing, navigation ───────────────
38
39
40 def test_registry_is_well_formed() -> None:
41 assert rc.check_registry(_PHASES) == []
42
43
44 def test_every_section_has_a_route_and_every_route_a_section(rendered: dict[str, str]) -> None:
45 # ``rendered`` already asserts every registered path answers 200 through the app.
46 assert rc.check_route_coverage(_PHASES, {r.path for r in ui_docs.router.routes}) == []
47
48
49 @pytest.mark.parametrize("path", [_xfail_known(p, _STALE_LABELS, "stale section-number labels") for p in PAGES])
50 def test_section_labels_match_registry(path: str, parsed: dict[str, rc.ParsedPage]) -> None:
51 assert rc.check_section_labels(_PHASES, path, parsed[path]) == []
52
53
54 def test_landing_cards_and_section_count(rendered: dict[str, str], parsed: dict[str, rc.ParsedPage]) -> None:
55 assert rc.check_landing(_PHASES, rendered[rc.DOCS_ROOT], parsed[rc.DOCS_ROOT]) == []
56
57
58 def test_landing_has_one_card_per_section_in_order(rendered: dict[str, str], parsed: dict[str, rc.ParsedPage]) -> None:
59 problems = rc.check_landing(_PHASES, rendered[rc.DOCS_ROOT], parsed[rc.DOCS_ROOT])
60 assert [p for p in problems if "phase cards" in p] == []
61
62
63 @pytest.mark.parametrize("path", SECTION_PAGES)
64 def test_navigation_follows_registry(path: str, parsed: dict[str, rc.ParsedPage]) -> None:
65 current = path.removeprefix(rc.DOCS_ROOT + "/")
66 assert rc.check_navigation(_PHASES, current, path, parsed[path]) == []
67
68
69 # ── DOC_INF_03: internal links and anchors ──────────────────────────────────
70
71
72 @pytest.mark.parametrize("path", [_xfail_known(p, _BROKEN_ANCHORS, "in-page links without a target id") for p in PAGES])
73 def test_internal_links_and_anchors_resolve(path: str, anchor_problems: list[str]) -> None:
74 assert [p for p in anchor_problems if p.startswith(f"{path}: ")] == []
75
76
77 # ── The checker detects real inconsistencies ────────────────────────────────
78
79 _REG: list[rc.Phase] = [
80 ("alpha", "00", "Alpha Start", "a"),
81 ("beta", "01", "Beta Engine", "b"),
82 ("gamma", "02", "Gamma Reference", "c"),
83 ]
84
85
86 def _page(sidebar_active: str | None, prev: str | None, nxt: str, body: str = "") -> rc.ParsedPage:
87 side = "".join(
88 f'<a class="devdocs-nav-link devdocs-nav-link--phase{" devdocs-nav-link--active" if s == sidebar_active else ""}"'
89 f' href="/muse/{s}">{n} {t}</a>'
90 for s, n, t, _ in _REG
91 )
92 pager = (f'<a class="devdocs-phase-nav-btn" href="{prev}">prev</a>' if prev else "") + (
93 f'<a class="devdocs-phase-nav-btn devdocs-phase-nav-btn--next" href="{nxt}">next</a>'
94 )
95 return rc.parse_page(
96 f'<aside class="devdocs-sidebar"><nav class="devdocs-nav">{side}</nav></aside>'
97 f'<article>{body}<nav class="devdocs-phase-nav">{pager}</nav></article>'
98 )
99
100
101 class TestCheckerDetects:
102 def test_consistent_fixture_is_clean(self) -> None:
103 assert rc.check_registry(_REG) == []
104 assert rc.check_navigation(_REG, "beta", "beta", _page("beta", "/muse/alpha", "/muse/gamma")) == []
105 assert rc.check_navigation(_REG, "gamma", "gamma", _page("gamma", "/muse/beta", "/muse")) == []
106
107 def test_numbering_gap_and_order(self) -> None:
108 problems = rc.check_registry([_REG[0], ("beta", "02", "Beta Engine", "b"), _REG[2]])
109 assert problems == ["registry: 'beta' is numbered '02', expected '01' (position 1)"]
110
111 def test_duplicate_slug_and_title(self) -> None:
112 problems = rc.check_registry([_REG[0], ("alpha", "01", "Alpha Start", "b")])
113 assert "registry: duplicate slug 'alpha' (2×)" in problems
114 assert "registry: duplicate title 'Alpha Start' (2×)" in problems
115
116 def test_malformed_slug(self) -> None:
117 assert rc.check_registry([("Bad_Slug", "00", "T", "d")]) == [
118 "registry: slug 'Bad_Slug' is not a lowercase hyphenated path segment"
119 ]
120
121 def test_missing_and_orphan_routes(self) -> None:
122 problems = rc.check_route_coverage(_REG, {"/muse", "/muse/alpha", "/muse/beta", "/muse/delta"})
123 assert problems == [
124 "route: no route serves registered section /muse/gamma",
125 "route: /muse/delta is served but not in _PHASES",
126 ]
127
128 def test_stale_section_number_in_label(self) -> None:
129 page = rc.parse_page('<a href="/muse/gamma">01 Gamma Reference</a><a href="/muse/beta#x">01 Beta</a>')
130 assert rc.check_section_labels(_REG, "p", page) == [
131 "p: link to /muse/gamma labelled '01 Gamma Reference', but gamma is section 02"
132 ]
133
134 def test_every_label_format_is_checked(self) -> None:
135 page = rc.parse_page(
136 '<a href="/muse/beta">Phase 01: Beta Engine</a><a href="/muse/gamma">02 — Gamma Reference</a>'
137 '<a href="/muse/alpha">00 Alpha subsection</a>'
138 '<a href="/muse/beta">Phase 02: Beta</a><a href="/muse/gamma">01 — Gamma</a>'
139 )
140 assert rc.check_section_labels(_REG, "p", page) == [
141 "p: link to /muse/beta labelled 'Phase 02: Beta', but beta is section 01",
142 "p: link to /muse/gamma labelled '01 — Gamma', but gamma is section 02",
143 ]
144
145 def test_stale_section_count_and_missing_card(self) -> None:
146 html = (
147 '<span class="devdocs-stat-num">2</span><span class="devdocs-stat-label">doc sections</span>'
148 '<a class="devdocs-phase-card" href="/muse/alpha"></a><a class="devdocs-phase-card" href="/muse/beta"></a>'
149 )
150 problems = rc.check_landing(_REG, html, rc.parse_page(html))
151 assert len(problems) == 2
152 assert problems[0].startswith("landing: phase cards")
153 assert problems[1] == "landing: 'doc sections' stat shows ['2'], registry has 3"
154
155 def test_wrong_prev_next_and_active_state(self) -> None:
156 problems = rc.check_navigation(_REG, "beta", "beta", _page("alpha", "/muse/gamma", "/muse/alpha"))
157 assert problems == [
158 "beta: sidebar active entries ['/muse/alpha'], expected ['/muse/beta']",
159 "beta: previous-section link ['/muse/gamma'], expected ['/muse/alpha']",
160 "beta: next-section link ['/muse/alpha'], expected ['/muse/gamma']",
161 ]
162
163 def test_sidebar_missing_section(self) -> None:
164 page = rc.parse_page(
165 '<aside class="devdocs-sidebar"><a class="devdocs-nav-link--phase" href="/muse/alpha">00 Alpha</a></aside>'
166 )
167 assert rc.check_navigation(_REG, None, "idx", page) == [
168 "idx: sidebar sections ['/muse/alpha'] do not match registry order ['/muse/alpha', '/muse/beta', '/muse/gamma']"
169 ]
170
171 def test_broken_anchors_unknown_page_and_ambiguous_ids(self) -> None:
172 pages = {
173 "/muse/alpha": rc.parse_page(
174 '<h2 id="a1">A</h2><h2 id="a1">A</h2><symbol id="s"></symbol><symbol id="s"></symbol>'
175 '<a href="#nope">x</a><a href="#a1">dup</a><a href="#a1">dup</a>'
176 '<a href="/muse/beta#b1">ok</a><a href="/muse/beta#b9">x</a><a href="/muse/omega">x</a>'
177 '<a href="/muse/install.sh">route</a><a href="https://example.com/#z">ext</a>'
178 ),
179 "/muse/beta": rc.parse_page('<h2 id="b1">B</h2><a href="/muse/alpha#a1">dup</a>'),
180 }
181 assert rc.check_anchors(pages, other_routes={"/muse/install.sh"}) == [
182 "/muse/alpha: link '#nope' has no matching id on /muse/alpha",
183 "/muse/alpha: link '#a1' is ambiguous: id defined 2× on /muse/alpha",
184 "/muse/alpha: link '/muse/beta#b9' has no matching id on /muse/beta",
185 "/muse/alpha: link '/muse/omega' points at a docs page that is not served",
186 "/muse/beta: link '/muse/alpha#a1' is ambiguous: id defined 2× on /muse/alpha",
187 ]
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