test_doc_inf_registry.py
python
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