gabriel / musehub public
test_shelves.py python
341 lines 14.9 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 uncommitted-work guard of
9 apply/pop (muse#156, fixed), 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_EXPIRY = "157" # --expires-in / expires_at / GC expiry not implemented
34 _T_DOMAIN = "159" # domain_state plugin hooks not implemented
35 _T_BUNDLE = "160" # bundles do not carry shelves
36 _T_BRANCH_INTENT_BUS = "151" # branch --intent/--resumable are local-only (#245)
37
38 _ENVELOPE = {"muse_version", "schema", "exit_code", "duration_ms", "timestamp", "warnings"}
39 _BASE = {
40 "README.md": "# demo\n",
41 "src/billing.py": "def compute_total(items):\n return sum(items)\n",
42 "src/invoice.py": "class Invoice:\n pass\n",
43 "docs/old.md": "old notes\n",
44 }
45 _SHELVED = {
46 "src/billing.py": "def compute_invoice_total(items):\n return sum(items)\n",
47 "src/invoice.py": "class Invoice:\n total = 0\n",
48 "src/new_helper.py": "HELPER = 1\n",
49 }
50 _LOCAL_EDIT = "# an uncommitted edit made after the shelf was saved\n"
51
52 Muse = Callable[..., dict]
53
54
55 @pytest.fixture(scope="module")
56 def html(rendered: dict[str, str]) -> str:
57 return rendered[PAGE].replace("'", "'").replace(""", '"').replace(""", '"')
58
59
60 def _text(fragment: str) -> str:
61 return html_lib.unescape(re.sub(r"<[^>]+>", "", fragment))
62
63
64 def _section(html: str, anchor: str) -> str:
65 rest = html.split(f'id="{anchor}"', 1)[1]
66 return " ".join(rest.split("</section>", 1)[0].split())
67
68
69 # ── Engine harness: the real CLI in a throwaway repository ──────────────────
70
71
72 def _engine(tmp: pathlib.Path) -> tuple[pathlib.Path, Muse]:
73 home = tmp / "home"
74 home.mkdir()
75 env = {k: v for k, v in os.environ.items() if not k.startswith(("MUSE_", "GIT_"))}
76 env.update(HOME=str(home), XDG_CONFIG_HOME=str(home / ".config"), MUSE_KEYCHAIN_BACKEND="disabled",
77 PYTHON_KEYRING_BACKEND="keyring.backends.fail.Keyring", NO_COLOR="1",
78 PYTHONPATH=os.pathsep.join(p for p in sys.path if p))
79 repo = tmp / "repo"
80 repo.mkdir()
81
82 def muse(*args: str, ok: bool = True) -> dict:
83 p = subprocess.run([sys.executable, "-c", "import sys; from muse.cli.app import main; main(sys.argv[1:])", *args],
84 cwd=repo, env=env, capture_output=True, text=True, timeout=120)
85 if ok:
86 assert p.returncode == 0, (args, p.stdout, p.stderr)
87 try:
88 out = json.loads(p.stdout)
89 except ValueError:
90 out = {}
91 return {"rc": p.returncode, "json": out, "stdout": p.stdout, "stderr": p.stderr}
92
93 muse("init")
94 assert "No remotes" in muse("remote", "-v")["stdout"] + muse("remote", "-v")["stderr"]
95 _write(repo, _BASE)
96 muse("commit", "-m", "base")
97 muse("checkout", "-b", "feat/billing")
98 return repo, muse
99
100
101 def _write(repo: pathlib.Path, files: dict[str, str]) -> None:
102 for rel, text in files.items():
103 (repo / rel).parent.mkdir(parents=True, exist_ok=True)
104 (repo / rel).write_text(text)
105
106
107 def _read(repo: pathlib.Path, rel: str) -> str | None:
108 p = repo / rel
109 return p.read_text() if p.exists() else None
110
111
112 def _save_wip(repo: pathlib.Path, muse: Muse) -> dict:
113 _write(repo, _SHELVED)
114 (repo / "docs/old.md").unlink()
115 return muse("shelf", "save", "wip", "--json")["json"]
116
117
118 @pytest.fixture(scope="module")
119 def engine(tmp_path_factory: pytest.TempPathFactory) -> dict:
120 """The figure's worked example, executed: save, set the documented pre-apply state, preview,
121 apply (refused: src/billing.py holds an uncommitted edit), then apply --force."""
122 repo, muse = _engine(tmp_path_factory.mktemp("shelf-engine"))
123 out: dict = {"save": _save_wip(repo, muse)}
124 out["list"] = muse("shelf", "list", "--json")["json"]
125 out["read"] = muse("shelf", "read", "wip", "--json")["json"]
126 _write(repo, {"src/invoice.py": _SHELVED["src/invoice.py"], "src/billing.py": _LOCAL_EDIT})
127 before = {p: _read(repo, p) for p in ("README.md", "src/invoice.py", "src/billing.py", "src/new_helper.py", "docs/old.md")}
128 out["before"] = before
129 out["diff"] = muse("shelf", "diff", "wip", "--json")["json"]
130 refused = muse("shelf", "apply", "wip", "--json", ok=False)
131 out["refusal_rc"] = refused["rc"]
132 out["refusal"] = refused["json"]
133 out["after_refusal"] = {p: _read(repo, p) for p in before}
134 out["apply"] = muse("shelf", "apply", "wip", "--force", "--json")["json"]
135 after = {p: _read(repo, p) for p in before}
136 outcome = {}
137 for path in before:
138 if before[path] is not None and after[path] is None:
139 outcome[path] = "deleted"
140 elif after[path] == before[path] and after[path] == _SHELVED.get(path):
141 outcome[path] = "already_current"
142 elif after[path] == before[path]:
143 outcome[path] = "skipped"
144 elif after[path] == _SHELVED.get(path):
145 outcome[path] = "restored"
146 else:
147 outcome[path] = f"unexpected: {after[path]!r}"
148 out["forced"] = dict(outcome)
149 for path in out["refusal"].get("files", []):
150 outcome[path] = "conflict"
151 out["outcome"] = outcome
152 out["pop"] = muse("shelf", "pop", "wip", "--json")["json"]
153 out["drop_empty"] = muse("shelf", "drop", "--json", ok=False)
154 return out
155
156
157 # ── DOC_SHL_04: apply/pop never destroy uncommitted work (muse#156) ──────────
158
159
160 def test_apply_never_destroys_uncommitted_edits(tmp_path: pathlib.Path) -> None:
161 repo, muse = _engine(tmp_path)
162 _save_wip(repo, muse)
163 _write(repo, {"src/billing.py": _LOCAL_EDIT})
164 r = muse("shelf", "apply", "wip", "--json", ok=False)
165 # Documented contract: apply is non-destructive. It refuses, and the edit survives.
166 assert _read(repo, "src/billing.py") == _LOCAL_EDIT, (r["rc"], r["json"])
167 assert r["rc"] == 1 and r["json"]["error"] == "dirty_workdir" and r["json"]["files"] == ["src/billing.py"]
168
169
170 def test_a_refused_pop_keeps_the_entry_and_force_discards_the_edit(tmp_path: pathlib.Path) -> None:
171 repo, muse = _engine(tmp_path)
172 _save_wip(repo, muse)
173 _write(repo, {"src/billing.py": _LOCAL_EDIT})
174 r = muse("shelf", "pop", "wip", "--json", ok=False)
175 assert r["rc"] == 1 and r["json"]["error"] == "dirty_workdir" and r["json"]["operation"] == "shelf pop"
176 assert [e["name"] for e in muse("shelf", "list", "--json")["json"]["entries"]] == ["wip"]
177 assert muse("shelf", "pop", "wip", "--force", "--json")["json"]["status"] == "popped"
178 assert _read(repo, "src/billing.py") == _SHELVED["src/billing.py"]
179 assert muse("shelf", "list", "--json")["json"]["entries"] == []
180
181
182 def test_a_symlinked_parent_is_refused_even_with_force(tmp_path: pathlib.Path) -> None:
183 repo, muse = _engine(tmp_path)
184 _write(repo, {"lib/extra.py": "EXTRA = 1\n"})
185 muse("shelf", "save", "lib", "--json")
186 assert _read(repo, "lib/extra.py") is None
187 outside = tmp_path / "outside"
188 outside.mkdir()
189 if (repo / "lib").exists():
190 (repo / "lib").rmdir()
191 (repo / "lib").symlink_to(outside, target_is_directory=True)
192 r = muse("shelf", "apply", "lib", "--force", "--json", ok=False)
193 assert r["rc"] == 1 and r["json"]["error"] == "unsafe_path" and r["json"]["files"] == ["lib/extra.py"]
194 assert list(outside.iterdir()) == []
195
196
197 # ── DOC_SHL_05: the decision figure shows what the engine does ──────────────
198
199
200 def _figure(html: str) -> str:
201 return html.split('id="apply-decision-figure"', 1)[1].split("</figure>", 1)[0]
202
203
204 def test_figure_example_matches_the_engine(html: str, engine: dict) -> None:
205 rows = dict(re.findall(r'<tr data-path="([^"]+)" data-outcome="([^"]+)">', _figure(html)))
206 assert rows == engine["outcome"]
207 # the refused apply changed nothing; --force restored every conflict path
208 assert engine["refusal_rc"] == 1
209 assert engine["after_refusal"] == engine["before"] and engine["before"]["src/billing.py"] == _LOCAL_EDIT
210 assert all(engine["forced"][p] == "restored" for p in engine["refusal"]["files"])
211 refusal = json.loads(_text(re.search(r"<code data-shelf-apply-refusal>(.*?)</code>", _figure(html)).group(1)))
212 assert refusal == {k: engine["refusal"][k] for k in refusal}
213 shown = json.loads(_text(re.search(r"<code data-shelf-apply-counts>(.*?)</code>", _figure(html)).group(1)))
214 assert shown == {k: engine["apply"][k] for k in shown}
215
216
217 def test_diff_previews_exactly_what_apply_does(engine: dict) -> None:
218 diff, outcome = engine["diff"], engine["outcome"]
219 assert diff["conflicts"] == engine["refusal"]["files"]
220 assert sorted(diff["would_restore"]) == sorted(p for p, o in engine["forced"].items() if o == "restored")
221 assert diff["already_current"] == [p for p, o in outcome.items() if o == "already_current"]
222 assert diff["would_delete"] == [p for p, o in outcome.items() if o == "deleted"]
223 # unchanged-at-save files are not listed as already_current (a whole-tree shelf lists only its changes)
224 assert "README.md" not in diff["already_current"] + diff["would_restore"]
225
226
227 def test_figure_rules_follow_the_engine_order(html: str) -> None:
228 fig = _figure(html)
229 assert re.findall(r'data-rule="(\w)"', fig) == ["1", "2", "3", "D"]
230 lanes = fig.split('class="shelfig__lanes"', 1)[1].split('class="shelfig__example"', 1)[0]
231 assert re.findall(r'class="shelfig__out[^"]*">(\w+)<', lanes) == [
232 "skipped", "already_current", "restored", "conflict", "deleted", "conflict"]
233 assert lanes.index("parent_commit") < lanes.index("already_current") # rule 1 compares with the save-time HEAD
234
235
236 def test_figure_renders_as_an_accessible_static_figure(html: str) -> None:
237 fig = _figure(html)
238 assert 'aria-labelledby="apply-decision-figure-title"' in html and 'id="apply-decision-figure-title"' in fig
239 assert "<figcaption" in fig and "<script" not in fig and "<svg" not in fig
240 assert fig.count("<ol") == 2 and "<caption>" in fig and fig.count('scope="col"') == 3 and fig.count('scope="row"') == 5
241 for lane in re.findall(r'<section class="shelfig__lane" aria-labelledby="([\w-]+)"', fig):
242 assert f'id="{lane}"' in fig
243
244
245 # ── DOC_SHL_06: documented JSON outputs have the engine's fields ────────────
246
247
248 def _documented_json(html: str) -> list[tuple[str, dict]]:
249 blocks = re.findall(r'data-shelf-json="(\w+)">\s*<pre>(.*?)</pre>', html, re.S)
250 return [(kind, json.loads(_text(body))) for kind, body in blocks]
251
252
253 def test_every_json_output_on_the_page_is_checked(html: str) -> None:
254 kinds = [k for k, _ in _documented_json(html)]
255 assert sorted(set(kinds)) == ["diff", "list", "pop", "read", "refusal", "save"] and len(kinds) == 8
256
257
258 def test_documented_json_keys_are_the_engine_keys(html: str, engine: dict) -> None:
259 for kind, doc in _documented_json(html):
260 real = engine[kind]
261 if kind == "list":
262 assert set(doc) == set(real) - _ENVELOPE == {"entries"}
263 for entry in doc["entries"]:
264 assert list(entry) == list(real["entries"][0]), "list entry fields, in engine order"
265 continue
266 assert [k for k in doc] == [k for k in real if k not in _ENVELOPE], kind
267 assert _ENVELOPE <= set(engine["save"]), "the omitted envelope fields exist"
268
269
270 def test_created_by_is_an_object(html: str, engine: dict) -> None:
271 assert engine["save"]["created_by"] == {"handle": "human", "kind": "human"}
272 for _, doc in _documented_json(html):
273 for entry in doc.get("entries", [doc]):
274 if "created_by" in entry:
275 assert set(entry["created_by"]) == {"handle", "kind"}
276
277
278 def test_save_reports_the_count_after_the_save(engine: dict) -> None:
279 # muse#162 (fixed in 0.2.2rc7): the page says "hence 1 for the first shelf".
280 assert engine["save"]["shelf_size"] == 1
281
282
283 def test_empty_shelf_exits_1(engine: dict) -> None:
284 assert engine["drop_empty"]["rc"] == 1
285
286
287 # ── DOC_SHL_07: corrected claims stay corrected; gaps stay linked ───────────
288
289
290 @pytest.mark.parametrize("stale", [
291 "does three things atomically",
292 "same content-addressed ID — deduplication is automatic",
293 "always produce the same ID",
294 ".msgpack ", # the storage tree no longer shows .msgpack entry files
295 "per-entry msgpack",
296 "-m / --message",
297 "--tags TAG",
298 "Phase 06",
299 "Files are staged and ready",
300 "removed from disk and staged",
301 "staging relevant files",
302 "compared to the current HEAD manifest",
303 "Shipped domain state examples",
304 "travels with the bundle",
305 "so no other agent modifies them",
306 "a delta against HEAD",
307 "entry_removed",
308 ])
309 def test_corrected_claims_stay_corrected(html: str, stale: str) -> None:
310 assert stale not in html
311
312
313 @pytest.mark.parametrize(("anchor", "issue"), [
314 ("entry", _T_EXPIRY),
315 ("save", _T_EXPIRY),
316 ("handoff", _T_EXPIRY),
317 ("entry", _T_DOMAIN),
318 ("domain-state", _T_DOMAIN),
319 ("storage", _T_BUNDLE),
320 ("branch-resumable", _T_BRANCH_INTENT_BUS),
321 ])
322 def test_known_gaps_link_their_tickets(html: str, anchor: str, issue: str) -> None:
323 assert f'href="{MUSE_ISSUES}{issue}"' in _section(html, anchor)
324
325
326 def test_contracts_are_kept_with_their_warnings(html: str) -> None:
327 restore = _section(html, "restore")
328 assert "Non-destructive and safe for inspection loops" in restore
329 assert "never overwrite uncommitted work" in restore and "--force" in restore
330 assert "Known defect" not in restore
331 inspect_ = _section(html, "inspect")
332 assert "previews exactly what <code>apply</code> will do" in inspect_ and "Known defect" not in inspect_
333 assert "Not implemented in muse 0.2.1rc20" in _section(html, "domain-state") and "shelf_state" in _section(html, "domain-state")
334 storage = _section(html, "storage")
335 assert "intended way to share a shelf" in storage and "Not available in muse 0.2.1rc20" in storage
336 assert "--tag" in _section(html, "inspect") and "every tag given" in _section(html, "inspect") # muse#158
337
338
339 def test_every_in_page_link_has_its_target(html: str) -> None:
340 for frag in set(re.findall(r'href="#([\w-]+)"', html)):
341 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