gabriel / musehub public
test_shelves.py python
298 lines 12.5 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_SHL — /muse/shelves contract (musehub#253, QA contract v2).
2
3 Every claim on the page was checked against muse 0.2.1rc20 (muse ``dev`` 5becda10) in a
4 disposable sandbox on 2026-11-07. These tests keep the corrected page honest in both
5 directions: they run the real ``muse shelf`` commands in a throwaway repository (offline, a
6 temporary HOME, no identity, no remotes) and compare the engine's behaviour with what the page
7 shows, so a change to either side fails here. Known product defects stay documented as contract
8 plus warning (#241 defect-preservation rule): DOC_SHL_04 pins the contract as a strict xfail
9 against its product ticket, and DOC_SHL_05 pins the figure to the behaviour the engine has today.
10 Rendering is the shared in-process fixture (no database).
11 """
12
13 from __future__ import annotations
14
15 import html as html_lib
16 import json
17 import os
18 import pathlib
19 import re
20 import subprocess
21 import sys
22 from collections.abc import Callable
23
24 import pytest
25
26 from tests.docs_contract import registry_check as rc
27
28 PAGE = rc.phase_path("shelves")
29 MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/"
30
31 # Product tickets the page's known-defect and not-available warnings link to (filed under
32 # #253, assigned to gabriel).
33 _T_APPLY = "156" # apply/pop overwrite uncommitted edits; diff does not predict apply
34 _T_EXPIRY = "157" # --expires-in / expires_at / GC expiry not implemented
35 _T_TAGS = "158" # shelf list has no tag filter
36 _T_DOMAIN = "159" # domain_state plugin hooks not implemented
37 _T_BUNDLE = "160" # bundles do not carry shelves
38 _T_INVALID = "161" # corrupt entry stops gc; oversized entries are written
39 _T_COUNTS = "162" # save shelf_size, workspace shelf_count, autoshelf message
40 _T_BRANCH_INTENT_BUS = "151" # branch --intent/--resumable are local-only (#245)
41
42 _ENVELOPE = {"muse_version", "schema", "exit_code", "duration_ms", "timestamp", "warnings"}
43 _BASE = {
44 "README.md": "# demo\n",
45 "src/billing.py": "def compute_total(items):\n return sum(items)\n",
46 "src/invoice.py": "class Invoice:\n pass\n",
47 "docs/old.md": "old notes\n",
48 }
49 _SHELVED = {
50 "src/billing.py": "def compute_invoice_total(items):\n return sum(items)\n",
51 "src/invoice.py": "class Invoice:\n total = 0\n",
52 "src/new_helper.py": "HELPER = 1\n",
53 }
54 _LOCAL_EDIT = "# an uncommitted edit made after the shelf was saved\n"
55
56 Muse = Callable[..., dict]
57
58
59 @pytest.fixture(scope="module")
60 def html(rendered: dict[str, str]) -> str:
61 return rendered[PAGE].replace("'", "'").replace(""", '"').replace(""", '"')
62
63
64 def _text(fragment: str) -> str:
65 return html_lib.unescape(re.sub(r"<[^>]+>", "", fragment))
66
67
68 def _section(html: str, anchor: str) -> str:
69 rest = html.split(f'id="{anchor}"', 1)[1]
70 return " ".join(rest.split("</section>", 1)[0].split())
71
72
73 # ── Engine harness: the real CLI in a throwaway repository ──────────────────
74
75
76 def _engine(tmp: pathlib.Path) -> tuple[pathlib.Path, Muse]:
77 home = tmp / "home"
78 home.mkdir()
79 env = {k: v for k, v in os.environ.items() if not k.startswith(("MUSE_", "GIT_"))}
80 env.update(HOME=str(home), XDG_CONFIG_HOME=str(home / ".config"), MUSE_KEYCHAIN_BACKEND="disabled",
81 PYTHON_KEYRING_BACKEND="keyring.backends.fail.Keyring", NO_COLOR="1",
82 PYTHONPATH=os.pathsep.join(p for p in sys.path if p))
83 repo = tmp / "repo"
84 repo.mkdir()
85
86 def muse(*args: str, ok: bool = True) -> dict:
87 p = subprocess.run([sys.executable, "-c", "import sys; from muse.cli.app import main; main(sys.argv[1:])", *args],
88 cwd=repo, env=env, capture_output=True, text=True, timeout=120)
89 if ok:
90 assert p.returncode == 0, (args, p.stdout, p.stderr)
91 try:
92 out = json.loads(p.stdout)
93 except ValueError:
94 out = {}
95 return {"rc": p.returncode, "json": out, "stdout": p.stdout, "stderr": p.stderr}
96
97 muse("init")
98 assert "No remotes" in muse("remote", "-v")["stdout"] + muse("remote", "-v")["stderr"]
99 _write(repo, _BASE)
100 muse("commit", "-m", "base")
101 muse("checkout", "-b", "feat/billing")
102 return repo, muse
103
104
105 def _write(repo: pathlib.Path, files: dict[str, str]) -> None:
106 for rel, text in files.items():
107 (repo / rel).parent.mkdir(parents=True, exist_ok=True)
108 (repo / rel).write_text(text)
109
110
111 def _read(repo: pathlib.Path, rel: str) -> str | None:
112 p = repo / rel
113 return p.read_text() if p.exists() else None
114
115
116 def _save_wip(repo: pathlib.Path, muse: Muse) -> dict:
117 _write(repo, _SHELVED)
118 (repo / "docs/old.md").unlink()
119 return muse("shelf", "save", "wip", "--json")["json"]
120
121
122 @pytest.fixture(scope="module")
123 def engine(tmp_path_factory: pytest.TempPathFactory) -> dict:
124 """The figure's worked example, executed: save, set the documented pre-apply state, apply."""
125 repo, muse = _engine(tmp_path_factory.mktemp("shelf-engine"))
126 out: dict = {"save": _save_wip(repo, muse)}
127 out["list"] = muse("shelf", "list", "--json")["json"]
128 out["read"] = muse("shelf", "read", "wip", "--json")["json"]
129 out["diff"] = muse("shelf", "diff", "wip", "--json")["json"]
130 _write(repo, {"src/invoice.py": _SHELVED["src/invoice.py"], "src/billing.py": _LOCAL_EDIT})
131 before = {p: _read(repo, p) for p in ("README.md", "src/invoice.py", "src/billing.py", "src/new_helper.py", "docs/old.md")}
132 out["apply"] = muse("shelf", "apply", "wip", "--json")["json"]
133 after = {p: _read(repo, p) for p in before}
134 outcome = {}
135 for path in before:
136 if before[path] is not None and after[path] is None:
137 outcome[path] = "deleted"
138 elif after[path] == before[path] and after[path] == _SHELVED.get(path):
139 outcome[path] = "already_current"
140 elif after[path] == before[path]:
141 outcome[path] = "skipped"
142 elif after[path] == _SHELVED.get(path):
143 outcome[path] = "restored"
144 else:
145 outcome[path] = f"unexpected: {after[path]!r}"
146 out["outcome"] = outcome
147 out["pop"] = muse("shelf", "pop", "wip", "--json")["json"]
148 out["drop_empty"] = muse("shelf", "drop", "--json", ok=False)
149 return out
150
151
152 # ── DOC_SHL_04: apply/pop must not destroy uncommitted work (contract; muse ticket) ─
153
154
155 @pytest.mark.xfail(strict=True, raises=AssertionError,
156 reason=f"muse#{_T_APPLY}: shelf apply/pop overwrite uncommitted edits without a check")
157 def test_apply_never_destroys_uncommitted_edits(tmp_path: pathlib.Path) -> None:
158 repo, muse = _engine(tmp_path)
159 _save_wip(repo, muse)
160 _write(repo, {"src/billing.py": _LOCAL_EDIT})
161 r = muse("shelf", "apply", "wip", "--json", ok=False)
162 # Documented contract: apply is non-destructive. Either it refuses, or the edit survives.
163 assert _read(repo, "src/billing.py") == _LOCAL_EDIT, (r["rc"], r["json"])
164
165
166 # ── DOC_SHL_05: the decision figure shows what the engine does ──────────────
167
168
169 def _figure(html: str) -> str:
170 return html.split('id="apply-decision-figure"', 1)[1].split("</figure>", 1)[0]
171
172
173 def test_figure_example_matches_the_engine(html: str, engine: dict) -> None:
174 rows = dict(re.findall(r'<tr data-path="([^"]+)" data-outcome="([^"]+)">', _figure(html)))
175 assert rows == engine["outcome"]
176 shown = json.loads(_text(re.search(r"<code data-shelf-apply-counts>(.*?)</code>", _figure(html)).group(1)))
177 assert shown == {k: engine["apply"][k] for k in shown}
178
179
180 def test_figure_rules_follow_the_engine_order(html: str) -> None:
181 fig = _figure(html)
182 assert re.findall(r'data-rule="(\w)"', fig) == ["1", "2", "3", "D"]
183 lanes = fig.split('class="shelfig__lanes"', 1)[1].split('class="shelfig__example"', 1)[0]
184 assert re.findall(r'class="shelfig__out[^"]*">(\w+)<', lanes) == ["skipped", "already_current", "restored", "deleted"]
185 assert lanes.index("parent_commit") < lanes.index("already_current") # rule 1 compares with the save-time HEAD
186
187
188 def test_figure_renders_as_an_accessible_static_figure(html: str) -> None:
189 fig = _figure(html)
190 assert 'aria-labelledby="apply-decision-figure-title"' in html and 'id="apply-decision-figure-title"' in fig
191 assert "<figcaption" in fig and "<script" not in fig and "<svg" not in fig
192 assert fig.count("<ol") == 2 and "<caption>" in fig and fig.count('scope="col"') == 3 and fig.count('scope="row"') == 5
193 for lane in re.findall(r'<section class="shelfig__lane" aria-labelledby="([\w-]+)"', fig):
194 assert f'id="{lane}"' in fig
195
196
197 # ── DOC_SHL_06: documented JSON outputs have the engine's fields ────────────
198
199
200 def _documented_json(html: str) -> list[tuple[str, dict]]:
201 blocks = re.findall(r'data-shelf-json="(\w+)">\s*<pre>(.*?)</pre>', html, re.S)
202 return [(kind, json.loads(_text(body))) for kind, body in blocks]
203
204
205 def test_every_json_output_on_the_page_is_checked(html: str) -> None:
206 kinds = [k for k, _ in _documented_json(html)]
207 assert sorted(set(kinds)) == ["diff", "list", "pop", "read", "save"] and len(kinds) == 7
208
209
210 def test_documented_json_keys_are_the_engine_keys(html: str, engine: dict) -> None:
211 for kind, doc in _documented_json(html):
212 real = engine[kind]
213 if kind == "list":
214 assert set(doc) == set(real) - _ENVELOPE == {"entries"}
215 for entry in doc["entries"]:
216 assert list(entry) == list(real["entries"][0]), "list entry fields, in engine order"
217 continue
218 assert [k for k in doc] == [k for k in real if k not in _ENVELOPE], kind
219 assert _ENVELOPE <= set(engine["save"]), "the omitted envelope fields exist"
220
221
222 def test_created_by_is_an_object(html: str, engine: dict) -> None:
223 assert engine["save"]["created_by"] == {"handle": "human", "kind": "human"}
224 for _, doc in _documented_json(html):
225 for entry in doc.get("entries", [doc]):
226 if "created_by" in entry:
227 assert set(entry["created_by"]) == {"handle", "kind"}
228
229
230 def test_save_reports_the_pre_save_count_until_fixed(engine: dict) -> None:
231 # The page documents the actual value with a warning (muse#162); when the count is
232 # fixed this fails, and the page's "hence 0 for the first shelf" sentence must change with it.
233 assert engine["save"]["shelf_size"] == 0
234
235
236 def test_empty_shelf_exits_1(engine: dict) -> None:
237 assert engine["drop_empty"]["rc"] == 1
238
239
240 # ── DOC_SHL_07: corrected claims stay corrected; gaps stay linked ───────────
241
242
243 @pytest.mark.parametrize("stale", [
244 "does three things atomically",
245 "same content-addressed ID — deduplication is automatic",
246 "always produce the same ID",
247 ".msgpack ", # the storage tree no longer shows .msgpack entry files
248 "per-entry msgpack",
249 "-m / --message",
250 "--tags TAG",
251 "Phase 06",
252 "Files are staged and ready",
253 "removed from disk and staged",
254 "staging relevant files",
255 "compared to the current HEAD manifest",
256 "Shipped domain state examples",
257 "travels with the bundle",
258 "so no other agent modifies them",
259 "a delta against HEAD",
260 "entry_removed",
261 ])
262 def test_corrected_claims_stay_corrected(html: str, stale: str) -> None:
263 assert stale not in html
264
265
266 @pytest.mark.parametrize(("anchor", "issue"), [
267 ("restore", _T_APPLY),
268 ("inspect", _T_APPLY),
269 ("entry", _T_EXPIRY),
270 ("save", _T_EXPIRY),
271 ("handoff", _T_EXPIRY),
272 ("inspect", _T_TAGS),
273 ("handoff", _T_TAGS),
274 ("entry", _T_DOMAIN),
275 ("domain-state", _T_DOMAIN),
276 ("storage", _T_BUNDLE),
277 ("storage", _T_INVALID),
278 ("save", _T_COUNTS),
279 ("branch-resumable", _T_BRANCH_INTENT_BUS),
280 ])
281 def test_known_gaps_link_their_tickets(html: str, anchor: str, issue: str) -> None:
282 assert f'href="{MUSE_ISSUES}{issue}"' in _section(html, anchor)
283
284
285 def test_contracts_are_kept_with_their_warnings(html: str) -> None:
286 restore = _section(html, "restore")
287 assert "Intended to be non-destructive and safe for inspection loops" in restore
288 assert "Known defect in muse 0.2.1rc20: apply and pop can destroy uncommitted work" in restore
289 assert "meant to preview exactly what <code>apply</code> will do" in _section(html, "inspect")
290 assert "Not implemented in muse 0.2.1rc20" in _section(html, "domain-state") and "shelf_state" in _section(html, "domain-state")
291 storage = _section(html, "storage")
292 assert "intended way to share a shelf" in storage and "Not available in muse 0.2.1rc20" in storage
293 assert "Tags are meant to be filterable" in _section(html, "inspect")
294
295
296 def test_every_in_page_link_has_its_target(html: str) -> None:
297 for frag in set(re.findall(r'href="#([\w-]+)"', html)):
298 assert f'id="{frag}"' in html, frag
File History 6 commits
sha256:16d33f5988942b0ea6160933bdd2ac8e5c97aa4a0816c1d4be03abdfc73da2f4 docs: follow Muse 0.2.2rc8 — fixed defects leave the pages Opus 5.5 minor ⚠ 1 day ago
sha256:580949619fa19ce11fb2e0fd9ebd2e95707a8db352a8586382e0707b2a4a78a9 docs: follow Muse 0.2.2rc7 — shelf list --tag, shelf_size a… 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:1066c93310e49f5b655d8f4b1cc7b08206c8d745bf565175cc6e53ae37835553 docs(shelves): apply/pop refuse to overwrite uncommitted wo… Opus 5.5 minor ⚠ 2 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