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