gabriel / musehub public
test_foundations.py python
319 lines 15.2 KB
Raw
sha256:16d33f5988942b0ea6160933bdd2ac8e5c97aa4a0816c1d4be03abdfc73da2f4 docs: follow Muse 0.2.2rc8 — fixed defects leave the pages Opus 5.5 minor ⚠ breaking 1 day ago
1 """DOC_FND — /muse/foundations contract (musehub#245, QA contract v2).
2
3 Every claim below was checked against muse 0.2.1rc20 (muse ``dev`` 5becda10) in a disposable
4 sandbox on 2026-11-07: IDs were recomputed from stored bytes, the stored records were read
5 back, and the documented commands were run. The figures' data is computed by muse's own
6 functions (``ui_docs._FND_*``); these tests re-derive it from the formulas the page documents,
7 so a change to either the engine or the page fails here. Known product defects stay documented
8 as contract plus warning (#241 defect-preservation rule): the tests pin both halves. Rendering
9 is the shared in-process fixture (no database).
10 """
11
12 from __future__ import annotations
13
14 import base64
15 import dataclasses
16 import hashlib
17 import re
18 import typing
19
20 import pytest
21
22 from musehub.api.routes.musehub import ui_docs
23 from tests.docs_contract import registry_check as rc
24
25 PAGE = rc.phase_path("foundations")
26 MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/"
27 MUSEHUB_ISSUES = "https://staging.musehub.ai/gabriel/musehub/issues/"
28
29 # Product tickets the page's known-defect warnings link to (filed under #245, assigned to gabriel).
30 _T_EXCLUSION_POLICY = 154 # [force_track] inert in code repos; check-ignore layers; dot-directories
31 _T_PATTERN_SEMANTICS = 145 # unanchored dir/ matches at the root only; * crosses /
32 _T_ADD_AFTER_RM_CACHED = 146
33 _T_FETCH_FSYNC = 148
34 _T_BRANCH_INTENT_BUS = 151
35
36
37 @pytest.fixture(scope="module")
38 def html(rendered: dict[str, str]) -> str:
39 return rendered[PAGE].replace("'", "'").replace(""", '"').replace(""", '"')
40
41
42 def _section(html: str, anchor: str) -> str:
43 """From ``id="<anchor>"`` to the next subsection or section, whitespace-collapsed."""
44 rest = html.split(f'id="{anchor}"', 1)[1]
45 end = min(i for i in (rest.find('class="devdocs-subsection-title"'), rest.find("</section>")) if i >= 0)
46 return " ".join(rest[:end].split())
47
48
49 def _text(fragment: str) -> str:
50 return re.sub(r"<[^>]+>", "", fragment).replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
51
52
53 def _code_after(html: str, anchor: str, label: str = "") -> str:
54 """Text of the first ``<pre>`` after ``anchor`` (and after ``label``, when given)."""
55 rest = html.split(f'id="{anchor}"', 1)[1]
56 if label:
57 rest = rest.split(label, 1)[1]
58 return _text(rest.split("<pre>", 1)[1].split("</pre>", 1)[0])
59
60
61 # ── DOC_FND_04: the documented ID formulas reproduce muse's IDs (V1, V3) ─────
62
63
64 def _sha(data: bytes) -> str:
65 return "sha256:" + hashlib.sha256(data).hexdigest()
66
67
68 def _doc_blob(data: bytes) -> str:
69 return _sha(f"blob {len(data)}\0".encode() + data)
70
71
72 def _doc_snapshot(manifest: dict[str, str], directories: list[str]) -> str:
73 parts = sorted(f"{p}\0{oid.split(':', 1)[1]}" for p, oid in manifest.items())
74 parts += [f"dir\0{d}" for d in sorted(directories)]
75 canon = "\0".join(parts).encode()
76 return _sha(f"snapshot {len(canon)}\0".encode() + canon)
77
78
79 def _doc_commit(parents: list[str], snapshot: str, message: str, at: str, author: str, signer: str) -> str:
80 fields = ["\0".join(sorted(p.split(":", 1)[1] for p in parents)), snapshot.split(":", 1)[1], message, at, author, signer]
81 canon = "\0".join(fields).encode()
82 return _sha(f"commit {len(canon)}\0".encode() + canon)
83
84
85 def test_figure_ids_follow_the_documented_formulas() -> None:
86 cards = {c.kind: c for c in ui_docs._FND_ID_CARDS}
87 blobs = {p: _doc_blob(b) for p, b in ui_docs._FND_FILES.items()}
88 assert cards["blob"].result == blobs["README.md"]
89 snapshot = _doc_snapshot(blobs, ui_docs._FND_DIRS)
90 assert cards["snapshot"].result == snapshot
91 commit = _doc_commit([], snapshot, ui_docs._FND_MESSAGE, ui_docs._FND_AT, ui_docs._FND_AUTHOR, ui_docs._FND_SIGNER)
92 assert cards["commit"].result == commit
93 agent, model = ui_docs._FND_AGENT
94 payload = "muse-provenance-v2\n" + "\0".join([commit, ui_docs._FND_AUTHOR, agent, model, "", "", ui_docs._FND_AT])
95 assert cards["signature"].result == hashlib.sha256(payload.encode()).hexdigest()
96
97
98 def test_a_blob_id_is_the_sha256_of_its_object_file() -> None:
99 data = ui_docs._FND_FILES["README.md"]
100 stored = f"blob {len(data)}\0".encode() + data # the on-disk object file
101 assert _sha(stored) == ui_docs._FND_ID_CARDS[0].result
102 assert _sha(data) != ui_docs._FND_ID_CARDS[0].result, "not the SHA-256 of the raw bytes"
103
104
105 def test_figure_signer_key_is_the_public_key_of_the_documented_seed() -> None:
106 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
107 from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
108
109 raw = Ed25519PrivateKey.from_private_bytes(bytes(range(32))).public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
110 assert ui_docs._FND_SIGNER == "ed25519:" + base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
111
112
113 def test_one_changed_byte_changes_every_id_above_it() -> None:
114 rows = {name: (before, after) for name, before, after in ui_docs._FND_PROPAGATION}
115 assert rows["src/app.py blob"][0] == rows["src/app.py blob"][1]
116 for name in ("README.md blob", "snapshot", "commit"):
117 assert rows[name][0] != rows[name][1], name
118
119
120 def test_dag_ids_follow_the_documented_formulas_and_share_blobs() -> None:
121 by_label = {c.label: c for c in ui_docs._FND_DAG}
122 assert by_label["A"].commit_id == ui_docs._FND_ID_CARDS[2].result, "A is the V1 commit"
123 assert by_label["M"].parents == ["B", "C"] and by_label["B"].parents == by_label["C"].parents == ["A"]
124 for c in ui_docs._FND_DAG:
125 parents = [by_label[p].commit_id for p in c.parents]
126 snap = _doc_snapshot(c.manifest, ui_docs._FND_DIRS)
127 at = {"A": "09:00", "B": "09:10", "C": "09:20", "M": "09:30"}[c.label]
128 assert c.commit_id == _doc_commit(parents, snap, c.message, f"2026-11-07T{at}:00+00:00", ui_docs._FND_AUTHOR, ui_docs._FND_SIGNER)
129 app = {c.manifest["src/app.py"] for c in ui_docs._FND_DAG}
130 assert len(app) == 1, "an unchanged file keeps one blob across every snapshot"
131 # M keeps dev's README.md (B) and adds task's new file (C).
132 assert by_label["M"].manifest == {**by_label["C"].manifest, **by_label["B"].manifest}
133
134
135 def test_page_states_the_formulas_the_figures_use(html: str) -> None:
136 formulas = _code_after(html, "object-store", "muse.core.ids")
137 for part in ('"blob <size>\\0" + data', '"snapshot <size>\\0"', '"dir\\0<directory>"', '"commit <size>\\0"', "signer_public_key"):
138 assert part in formulas, part
139
140
141 @pytest.mark.parametrize("figure", ["id-derivation", "object-graph-figure"])
142 def test_figures_render_as_accessible_static_figures(html: str, figure: str) -> None:
143 fig = html.split(f'id="{figure}"', 1)[1].split("</figure>", 1)[0]
144 assert f'aria-labelledby="{figure}-title"' in html and f'id="{figure}-title"' in fig
145 assert "<figcaption" in fig and "<script" not in fig and "<svg" not in fig
146 for table in re.findall(r"<table.*?</table>", fig, re.S):
147 named = "<caption>" in table or re.search(r'aria-labelledby="([\w-]+)"', table)
148 assert named and 'scope="col"' in table
149 if "<caption>" not in table:
150 assert f'id="{named.group(1)}"' in fig, "the table's label is in the figure"
151 for region in re.findall(r'<div class="dagfig__scroll"[^>]*>', fig):
152 assert 'tabindex="0"' in region and 'role="region"' in region and "aria-labelledby=" in region
153
154
155 def test_figures_show_the_computed_ids(html: str) -> None:
156 for card in ui_docs._FND_ID_CARDS[:3]:
157 assert ui_docs._short(card.result) in html
158 for c in ui_docs._FND_DAG:
159 assert ui_docs._short(c.commit_id) in html
160 assert html.count('class="idfig__card') == len(ui_docs._FND_ID_CARDS)
161
162
163 # ── DOC_FND_05: documented shapes equal muse's own types ─────────────────────
164
165
166 def _keys(block: str) -> list[str]:
167 return re.findall(r'"(\w+)"\s*:', block)
168
169
170 def test_status_json_keys_are_the_status_schema(html: str) -> None:
171 from muse.cli.commands.status import _StatusJson
172
173 assert set(_keys(_code_after(html, "cli-json-shape"))) == set(typing.get_type_hints(_StatusJson))
174
175
176 def test_branch_json_keys_are_the_branch_entry_schema(html: str) -> None:
177 from muse.cli.commands.branch import _BranchEntryJson, _CreatedByJson
178
179 keys = set(_keys(_code_after(html, "resumable-branches", "muse branch --json")))
180 nested = set(typing.get_type_hints(_CreatedByJson))
181 assert keys - nested == set(typing.get_type_hints(_BranchEntryJson)) and nested <= keys
182
183
184 def test_commit_record_fields_are_the_dataclass_fields_in_order(html: str) -> None:
185 from muse.core.commits import CommitRecord
186
187 documented = re.findall(r"^\s{4}(\w+):", _code_after(html, "commit-record", "CommitRecord"), re.M)
188 assert documented == [f.name for f in dataclasses.fields(CommitRecord)]
189
190
191 def test_stored_commit_record_lists_exactly_the_dataclass_fields(html: str) -> None:
192 from muse.core.commits import CommitRecord
193
194 stored = _code_after(html, "stored-records", 'devdocs-code-block--output')
195 assert _keys(stored) == [f.name for f in dataclasses.fields(CommitRecord)]
196
197
198 def test_never_tracked_directories_are_the_engine_list(html: str) -> None:
199 from muse.core.exclusion import ALWAYS_PRUNE_DIRS
200
201 para = html.split("Some directories are never tracked", 1)[1].split("says:", 1)[1].split("</p>", 1)[0]
202 assert set(re.findall(r"<code>([^<]+)</code>", para)) == set(ALWAYS_PRUNE_DIRS)
203
204
205 # ── DOC_FND_06: corrected claims stay corrected ──────────────────────────────
206
207
208 @pytest.mark.parametrize("stale", [
209 "serialized with <strong>msgpack</strong>", # storage is JSON behind a typed header (muse#12)
210 "3–6×", # unsupported benchmark
211 "msgpack.unpackb", # the decode recipe fails on a stored record
212 "/data/repos", # the hub keeps no per-repo directory
213 "POST /{owner}/{slug}/push<", # no such route
214 "branches/{name}/repair", # no such route; repair is POST …/repair-object|snapshot|commit
215 "WireMPack", # unused server model
216 "≥32 chars", # IDs are exactly sha256:<64-hex>
217 "zero, one, or two parent", # N-way merges exist (muse#105)
218 "format_version", # not a CommitRecord field
219 '"repo_id": "sha256:0000genesis', # not a CommitRecord field (muse#9)
220 "claude-sonnet-4-6", # dated example model ID
221 "midi|identity", # init --domain list: midi is not generally available
222 "SHA-256 of raw bytes", # blob IDs hash a typed header
223 "preimage attack", # replacing an object needs a second-preimage attack
224 "no index file", # .muse/code/stage.json is the staging index
225 "└── agent.md", # agent rules are .museagent.md at the repo root (muse#78)
226 "Muse automatically blocks certain file types", # replaced by the owner-approved wording above
227 ])
228 def test_corrected_claims_stay_corrected(html: str, stale: str) -> None:
229 if stale == "preimage attack":
230 assert "second-preimage attack" in html and "a SHA-256 preimage attack" not in html
231 return
232 assert stale not in html
233
234
235 def test_tag_and_label_examples_use_the_current_commands(html: str) -> None:
236 cli = _section(html, "cli-basics")
237 assert re.search(r"muse tag add v\d+\.\d+\.\d+", cli) and "muse label add" in cli
238 assert 'muse tag add "label"' not in cli
239
240
241 def test_branch_lifecycle_creates_dev_and_signs_the_merge(html: str) -> None:
242 lifecycle = _code_after(html, "branch-dag", "branch lifecycle")
243 assert lifecycle.index("muse branch dev") < lifecycle.index("muse checkout dev")
244 merge = lifecycle.split("muse merge", 1)[1].split("muse branch -d", 1)[0]
245 assert "--agent-id" in merge and "--model-id" in merge and "--sign" in merge
246
247
248 def test_every_subsection_link_has_its_target(html: str) -> None:
249 for frag in set(re.findall(r'href="#([\w-]+)"', html)):
250 assert f'id="{frag}"' in html, frag
251
252
253 # ── DOC_FND_07: known product defects stay documented as contract + warning ─
254
255
256 def _warning_links(html: str, anchor: str, issue: int, base: str = MUSE_ISSUES) -> bool:
257 return f'href="{base}{issue}"' in _section(html, anchor)
258
259
260 def test_exclusion_contract_is_kept_and_its_defect_is_linked(html: str) -> None:
261 force = _section(html, "museignore-force-track")
262 # Owner-approved wording (gabriel, 2026-11-07): the default exclusions are stated, with review guidance.
263 assert "Muse provides default exclusions for certain file types" in force
264 assert "not a substitute for reviewing the contents of a commit" in force
265 assert "verify what will be committed before sharing a repository" in force
266 assert "Known defect in muse 0.2.1rc20" in force and _warning_links(html, "museignore-force-track", _T_EXCLUSION_POLICY)
267 assert _warning_links(html, "cli-basics", _T_EXCLUSION_POLICY), "code add . skips dot-directories"
268
269
270 def test_pattern_semantics_contract_is_kept_and_its_defects_are_linked(html: str) -> None:
271 patterns = _section(html, "museignore-patterns")
272 assert "Any directory named" in patterns and "excludes <code>/</code>" in patterns
273 assert "mirroring gitignore semantics" in patterns
274 # muse#145 shipped in 0.2.2rc8: the page states the semantics, no defect warning, no ticket link.
275 assert "Since muse 0.2.2rc8 these rules hold exactly" in patterns and "at any depth" in patterns
276 assert f"{MUSE_ISSUES}{_T_PATTERN_SEMANTICS}\"" not in html
277
278
279 @pytest.mark.parametrize(("anchor", "issue", "base"), [
280 ("resumable-branches", _T_BRANCH_INTENT_BUS, MUSE_ISSUES),
281 ("push-flow", 171, MUSEHUB_ISSUES), # pushed_at is never updated
282 ])
283 def test_known_defects_link_their_tickets(html: str, anchor: str, issue: int, base: str) -> None:
284 assert _warning_links(html, anchor, issue, base)
285
286
287 def test_init_refuses_an_unregistered_domain(html: str) -> None:
288 # muse#147 is fixed: the page states the refusal, not the old defect.
289 cli = " ".join(_section(html, "cli-basics").split())
290 assert "accepts only a registered domain" in cli and "unknown_domain" in cli
291 assert "accepts a name that is not a registered domain" not in cli
292
293
294 def test_resumable_metadata_keeps_its_documented_purpose(html: str) -> None:
295 resumable = _section(html, "resumable-branches")
296 assert "orchestrators can assign" in resumable and "Not yet implemented in muse 0.2.1rc20" in resumable
297
298
299 def test_fsync_contract_is_kept_with_its_caveat(html: str) -> None:
300 graph = _section(html, "object-graph")
301 assert "mkstemp → write → fsync → os.replace" in graph
302 # muse#148 shipped in 0.2.2rc8; muse#146 in 0.2.2rc7: no defect text, no ticket links.
303 assert "before\n any branch moves" in graph or "before any branch moves" in " ".join(graph.split())
304 for fixed in (_T_FETCH_FSYNC, _T_ADD_AFTER_RM_CACHED):
305 assert f"{MUSE_ISSUES}{fixed}\"" not in html, fixed
306
307
308 def test_unused_server_storage_model_is_gone() -> None:
309 """musehub#282: no repos dir, no stale wire models or repair route in code or type contracts."""
310 import pathlib
311 import musehub.api.routes.musehub.repos as repos
312 import musehub.models.wire as wire_models
313 from musehub.config import settings
314
315 assert not hasattr(settings, "musehub_repos_dir")
316 assert not hasattr(wire_models, "WireMPack") and not hasattr(wire_models, "WireObject")
317 assert "branches/{name}/repair" not in (repos.__doc__ or "")
318 contracts = (pathlib.Path(__file__).resolve().parents[2] / "docs/reference/type-contracts.md").read_text()
319 assert "WireMPack" not in contracts and "WireObject" not in contracts
File History 7 commits
sha256:16d33f5988942b0ea6160933bdd2ac8e5c97aa4a0816c1d4be03abdfc73da2f4 docs: follow Muse 0.2.2rc8 — fixed defects leave the pages Opus 5.5 minor ⚠ 1 day ago
sha256:4f1496efd3bb9b1e764c31d3d9ae8218a550c06f78e351b15fe58409e4223282 fix(releases,wire): the rc channel is accepted like Muse's … Opus 5.5 minor ⚠ 1 day ago
sha256:e1629e5f328982dbf6e535d3f253993c78ff225dfee4ebb0e0a15fc1db69046b merge: rc25 — docs and docs-contract tests match Muse batch… Opus 5.5 minor ⚠ 2 days ago
sha256:dbbf615be725b5889e300e2fe88a603841d6f3c315236e35a5426796bfcdcb65 docs(vision,foundations,domains): init refuses an unregiste… Opus 5.5 patch 2 days ago
sha256:369f691c7aaec3ca84a864ad1d099d5409045ddc12d185a922b3c84b9e2a1bad merge: 100% passing, parallelized MuseHub test suite (task/… Sonnet 5.5 patch 3 days ago
sha256:8166b51ae53275831023a7ce334228b3ccc8237b55d68a35172389db9ff46ad5 test: 100% passing MuseHub suite, parallelized (xdist, one … Sonnet 5.5 patch 3 days ago
sha256:0d8df91e78d3fa8d14d82f9b35de2f6991462e104025f8f1d80174f55cd18fb6 docs(foundations): QA contract v2 — verified object model, … Opus 5.5 minor ⚠ 9 days ago