gabriel / musehub public
test_domains.py python
323 lines 17.0 KB
Raw
sha256:580949619fa19ce11fb2e0fd9ebd2e95707a8db352a8586382e0707b2a4a78a9 docs: follow Muse 0.2.2rc7 — shelf list --tag, shelf_size a… Opus 5.5 minor ⚠ breaking 1 day ago
1 """DOC_DOM — /muse/domains contract (musehub#247, 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 execute the page's minimal plugin verbatim through the real CLI, recompute the
6 capability matrix, the HD integers, the strategy tables and the algorithm figures from the
7 installed muse, and fail when either side drifts. Known product defects stay documented as
8 contract plus warning (#241 defect-preservation rule): DOC_DOM_10 pins the contract as a strict
9 xfail against its product ticket; DOC_DOM_11 (muse#166) and the CRDT routing (musehub#204) were
10 fixed in Muse batch 1 and now pin the fixed behaviour. Rendering is the shared in-process fixture (no
11 database); the CLI runs offline in a temporary HOME with no identity and no remotes.
12 """
13
14 from __future__ import annotations
15
16 import html as html_lib
17 import json
18 import os
19 import pathlib
20 import re
21 import subprocess
22 import sys
23
24 import pytest
25
26 from tests.docs_contract import registry_check as rc
27
28 PAGE = rc.phase_path("domains")
29 MUSE_ISSUES = "https://staging.musehub.ai/gabriel/muse/issues/"
30 HUB_ISSUES = "https://staging.musehub.ai/gabriel/musehub/issues/"
31
32 # Product tickets the page's known-defect and not-available notes link to (filed under #247).
33 _T_ATTR = "166" # fixed: .museattributes file-level rules apply at merge in every domain
34 _T_FP = "167" # identity fingerprint not timestamp-invariant; protocol asks for bare hex
35 _T_ALGO = "168" # myers/patience, zhang_shasha/gumtree, map value_schema are labels only
36 _T_OVL = "170" # merge --strategy=overlay reports 'theirs'
37 _T_CRDT = "204" # musehub, fixed: muse merge joins a CRDTPlugin that declares merge_mode "crdt"
38
39 _PROTOCOLS = ("AddressedMergePlugin", "HarmonyPlugin", "CRDTPlugin", "StagePlugin", "StrictCommitDomain")
40
41
42 @pytest.fixture(scope="module")
43 def html(rendered: dict[str, str]) -> str:
44 return rendered[PAGE].replace("'", "'").replace(""", '"').replace(""", '"')
45
46
47 def _text(fragment: str) -> str:
48 return html_lib.unescape(re.sub(r"<[^>]+>", "", fragment))
49
50
51 def _section(html: str, anchor: str) -> str:
52 rest = html.split(f'id="{anchor}"', 1)[1]
53 return " ".join(_text(rest.split("</section>", 1)[0]).split())
54
55
56 def _env(tmp: pathlib.Path) -> dict[str, str]:
57 home = tmp / "home"
58 home.mkdir(exist_ok=True)
59 env = {k: v for k, v in os.environ.items() if not k.startswith(("MUSE_", "GIT_"))}
60 env.update(HOME=str(home), XDG_CONFIG_HOME=str(home / ".config"), MUSE_KEYCHAIN_BACKEND="disabled",
61 PYTHON_KEYRING_BACKEND="keyring.backends.fail.Keyring", NO_COLOR="1",
62 PYTHONPATH=os.pathsep.join(p for p in sys.path if p))
63 return env
64
65
66 # The page's plugin, registered at runtime in the CLI process only (the registry file is never edited).
67 _RUN_WITH_PLUGIN = (
68 "import sys; ns = {}; exec(compile(open(sys.argv[1]).read(), 'my_domain/plugin.py', 'exec'), ns); "
69 "from muse.plugins import registry; registry._REGISTRY[ns['DOMAIN']] = ns['JsonDocPlugin'](); "
70 "from muse.cli.app import main; main(sys.argv[2:])"
71 )
72
73
74 def _cli(repo: pathlib.Path, env: dict[str, str], args: tuple[str, ...], plugin: pathlib.Path | None = None) -> dict:
75 cmd = [sys.executable, "-c", _RUN_WITH_PLUGIN, str(plugin)] if plugin else \
76 [sys.executable, "-c", "import sys; from muse.cli.app import main; main(sys.argv[1:])"]
77 p = subprocess.run([*cmd, *args], cwd=repo, env=env, capture_output=True, text=True, timeout=120)
78 return {"rc": p.returncode, "out": p.stdout + p.stderr}
79
80
81 # ── DOC_DOM_04: the minimal plugin is executed verbatim ─────────────────────
82
83
84 @pytest.fixture(scope="module")
85 def plugin_source(html: str) -> str:
86 m = re.search(r'id="minimal-plugin-code">.*?<pre><code>(.*?)</code></pre>', html, re.S)
87 assert m, "minimal plugin listing not found"
88 return _text(m.group(1))
89
90
91 def test_dom_04_minimal_plugin_satisfies_the_protocol(plugin_source: str) -> None:
92 from muse.domain import MergeResult, MuseDomainPlugin, SnapshotManifest
93 ns: dict = {}
94 exec(compile(plugin_source, "my_domain/plugin.py", "exec"), ns)
95 plugin = ns["JsonDocPlugin"]()
96 assert isinstance(plugin, MuseDomainPlugin)
97 assert len(plugin_source.splitlines()) < 80 # "six methods, under 80 lines"
98 schema = plugin.schema()
99 from muse.core.schema import DomainSchema, DimensionSpec
100 assert set(DomainSchema.__annotations__) <= set(schema)
101 assert set(DimensionSpec.__annotations__) <= set(schema["dimensions"][0])
102 snap = lambda h: SnapshotManifest(files={"a.json": "sha256:" + h * 64}, domain="json-docs", directories=[])
103 result = plugin.merge(snap("0"), snap("1"), snap("2"))
104 assert isinstance(result, MergeResult) and result.conflicts == ["a.json"] and not result.is_clean
105
106
107 def test_dom_04_minimal_plugin_runs_through_the_cli(plugin_source: str, tmp_path: pathlib.Path) -> None:
108 src = tmp_path / "plugin.py"
109 src.write_text(plugin_source)
110 repo = tmp_path / "repo"
111 repo.mkdir()
112 env = _env(tmp_path)
113 run = lambda *a: _cli(repo, env, a, plugin=src)
114 steps = [("init", "--domain", "json-docs")]
115 assert run(*steps[0])["rc"] == 0
116 (repo / "app.json").write_text('{"MAX_CONNECTIONS": 10}\n')
117 (repo / "other.json").write_text('{"x": 1}\n')
118 for args, edit in [
119 (("commit", "-m", "base"), None),
120 (("checkout", "-b", "feat/a"), {"app.json": '{"MAX_CONNECTIONS": 20}\n'}),
121 (("commit", "-m", "a"), None), (("checkout", "main"), None),
122 (("checkout", "-b", "feat/b"), {"app.json": '{"MAX_CONNECTIONS": 50}\n', "new.json": '{"y": 2}\n'}),
123 (("commit", "-m", "b"), None), (("checkout", "main"), None),
124 (("checkout", "-b", "feat/c"), {"other.json": '{"x": 2}\n'}),
125 (("commit", "-m", "c"), None), (("checkout", "main"), None),
126 (("merge", "feat/a"), None), (("merge", "feat/c"), None),
127 ]:
128 r = run(*args)
129 assert r["rc"] == 0, (args, r["out"])
130 for rel, text in (edit or {}).items():
131 (repo / rel).write_text(text)
132 assert "Merge made by the three-way strategy" in r["out"]
133 assert (repo / "other.json").read_text() == '{"x": 2}\n'
134 conflict = run("merge", "feat/b")
135 assert conflict["rc"] == 1 and "CONFLICT (both modified): app.json" in conflict["out"], conflict["out"]
136 assert (repo / "new.json").read_text() == '{"y": 2}\n' # the non-conflicting side of feat/b merged
137
138
139 # ── DOC_DOM_05: capability matrix = runtime isinstance + schema() ───────────
140
141
142 def test_dom_05_capability_matrix_matches_the_engine(html: str) -> None:
143 import muse.domain as D
144 from muse.plugins import registry
145 body = html.split('id="capability-matrix-figure"', 1)[1].split("</figure>", 1)[0]
146 rows = dict(re.findall(r'<tr data-domain="([a-z_]+)">(.*?)</tr>', body, re.S))
147 shipped = set(registry._REGISTRY) - {"midi"} # midi registers only behind an opt-in flag
148 assert shipped <= set(rows), sorted(shipped - set(rows))
149 from muse.plugins.midi.plugin import MidiPlugin
150 plugins = {**{k: registry._REGISTRY[k] for k in shipped}, "midi": MidiPlugin()}
151 assert set(rows) == set(plugins)
152 for name, plugin in plugins.items():
153 cells = [_text(c).strip() for c in re.findall(r"<td[^>]*>(.*?)</td>", rows[name], re.S)]
154 want = ["Yes" if isinstance(plugin, getattr(D, p)) else "—" for p in _PROTOCOLS]
155 schema = plugin.schema()
156 want += [schema["top_level"]["kind"], str(len(schema["dimensions"]))]
157 assert cells == want, (name, cells, want)
158 assert schema["merge_mode"] == "three_way"
159
160
161 # ── DOC_DOM_06: HD domain integers and the muse domain CLI ──────────────────
162
163
164 def test_dom_06_domain_integers(html: str) -> None:
165 from muse.core.hdkeys import domain_index
166 table = html.split('id="domain-integers"', 1)[1].split("</table>", 1)[0]
167 pairs = re.findall(r"<td><code>(muse/[a-z]+)</code></td><td><code>(\d+)</code></td>", table)
168 assert len(pairs) == 8
169 for name, value in pairs:
170 assert domain_index(name) == int(value), name
171
172
173 def test_dom_06_domain_cli_examples(tmp_path: pathlib.Path) -> None:
174 env = _env(tmp_path)
175 run = lambda *a: _cli(tmp_path, env, a)
176 idx = run("domain", "index", "muse/identity", "--json")
177 assert json.loads(idx["out"])["index"] == 1660078172
178 assert json.loads(run("domain", "lookup", "--index", "1660078172", "--json")["out"])["name"] == "muse/identity"
179 assert run("domain", "check", "muse/identity", "--json")["rc"] == 0
180 mist = run("domain", "check", "muse/mist", "--json") # muse#169: seeded since 0.2.2rc7
181 assert mist["rc"] == 0 and json.loads(mist["out"])["exit_code"] == 0
182
183
184 # ── DOC_DOM_07: .museattributes example and strategy table ──────────────────
185
186
187 def test_dom_07_museattributes_example_validates(html: str, tmp_path: pathlib.Path) -> None:
188 from muse.core.attributes import VALID_STRATEGIES
189 sec = html.split('id="museattributes"', 1)[1].split("</section>", 1)[0]
190 toml = _text(re.search(r'<span class="devdocs-code-lang">toml</span>.*?<pre><code>(.*?)</code></pre>', sec, re.S).group(1))
191 repo = tmp_path / "repo"
192 repo.mkdir()
193 env = _env(tmp_path)
194 assert _cli(repo, env, ("init", "--domain", "code"))["rc"] == 0
195 (repo / ".museattributes").write_text(toml)
196 out = _cli(repo, env, ("attributes", "validate", "--json"))
197 assert out["rc"] == 0 and json.loads(out["out"])["rule_count"] == 3, out["out"]
198 check = json.loads(_cli(repo, env, ("check-attr", "tracks/master.mid", "--json"))["out"])
199 assert check["results"][0]["strategy"] == "theirs"
200 table = sec.split("<tbody>", 1)[1].split("</tbody>", 1)[0]
201 assert set(re.findall(r"<tr><td><code>([a-z]+)</code>", table)) == set(VALID_STRATEGIES)
202 (repo / ".museattributes").write_text("*.lock merge=ours\n") # the gitattributes form
203 assert _cli(repo, env, ("attributes", "validate", "--json"))["rc"] == 1
204
205
206 # ── DOC_DOM_08: strategy table, algorithm figures, op shapes ────────────────
207
208
209 def test_dom_08_merge_strategy_table_matches_strategy_map(html: str) -> None:
210 from muse.core.merge_engine import STRATEGY_MAP
211 table = html.split('id="merge-strategies"', 1)[1].split("</table>", 1)[0]
212 rows = re.findall(r"<td><code>(\w+)</code>(?: <em>\(default\)</em>)?</td>\s*<td><code>(\w+)</code></td>\s*<td><code>(\w+)</code></td>", table)
213 assert {name: (unit, res) for name, unit, res in rows} == {
214 name: (e.diff_unit, e.resolution) for name, e in STRATEGY_MAP.items()}
215
216
217 def test_dom_08_sequence_and_tree_figures_match_the_algorithms(html: str) -> None:
218 from muse.core.diff_algorithms import lcs
219 from muse.core.diff_algorithms.tree_edit import TreeNode, diff as tree_diff
220 seq = html.split('domains-seq-vis', 1)[1].split('domains-da-note', 1)[0]
221 rows = re.findall(r'<div class="domains-seq-row">(.*?)</div>\s*<div class="domains-seq-ops-row">(.*?)</div>\s*(?=<div class="domains-seq-row|<div class="domains-seq-row-lbl">after)', seq, re.S)
222 before = re.findall(r'domains-seq-hash">(\w+)<', rows[0][0])
223 after = re.findall(r'domains-seq-hash">(\w+)<', rows[1][0])
224 spec = {"kind": "sequence", "element_type": "note", "identity": "by_id", "diff_algorithm": "lcs", "alphabet": None}
225 ops = sorted(o["op"] for o in lcs.diff(spec, before, after, domain="t")["ops"])
226 figure_ops = sorted(re.findall(r"(DeleteOp|InsertOp|MoveOp)", rows[0][1] + rows[1][1]))
227 assert [o.replace("Op", "").lower() for o in figure_ops] == ops
228 assert [o["op"] for o in lcs.diff(spec, ["A", "B", "C"], ["C", "A", "B"], domain="t")["ops"]] == ["move"]
229 n = lambda label, *kids: TreeNode(id=label, label=label, content_id="cid-" + label, children=tuple(kids))
230 tops = tree_diff({"kind": "tree", "node_type": "n", "diff_algorithm": "zhang_shasha"},
231 n("session", n("intro", n("C4"), n("E4")), n("verse", n("G4"))),
232 n("session", n("intro", n("C4"), n("E4"), n("G4")), n("verse", n("A4"))), domain="t")["ops"]
233 assert sorted(o["op"] for o in tops) == ["delete", "insert", "insert"]
234 assert "DeleteOp + 2 × InsertOp" in html
235
236
237 def test_dom_08_op_shapes_match_the_typed_dicts(html: str) -> None:
238 import muse.domain as D
239 block = _text(html.split("muse.domain — DomainOp variants", 1)[1].split("</pre>", 1)[0])
240 for name in ("InsertOp", "DeleteOp", "AddressedInsertOp", "AddressedDeleteOp", "MoveOp", "ReplaceOp", "MutateOp", "PatchOp", "RenameOp"):
241 decl = re.search(rf"^{name}\s*=\s*\{{(.*?)\}}\s*(?:#.*)?$", block, re.S | re.M).group(1)
242 keys = set(re.findall(r'"(\w+)":', decl))
243 assert keys == set(getattr(D, name).__annotations__), (name, keys)
244
245
246 def test_dom_08_tensor_emits_replace_ops() -> None:
247 from muse.core.diff_algorithms import numerical
248 for mode in ("sparse", "block", "full"):
249 d = numerical.diff({"kind": "tensor", "dtype": "float32", "rank": 1, "epsilon": 0.01, "diff_mode": mode},
250 [0.0, 1.0, 2.0], [0.0, 1.5, 2.5], domain="t")
251 assert {o["op"] for o in d["ops"]} == {"replace"}
252
253
254 # ── DOC_DOM_09: corrected claims stay corrected; warnings link their tickets ─
255
256
257 def test_dom_09_corrected_claims(html: str) -> None:
258 text = " ".join(_text(html).split())
259 for stale in ("Two optional extension protocols", "ignore_filter(", "muse drift", "gitattributes-style",
260 "merge=domain", "Zhang-Shasha / GumTree", "Myers / LCS", "collision-resistant",
261 "domain_int", "muse api-surface", "muse domain check muse/identity 1660078172",
262 "muse domain lookup 1660078172", "conditional on an optional dependency", "11 languages",
263 "Phase 12: Mist Domain", "→ PatchOp", "Recursive key-by-key"):
264 assert stale not in text, stale
265 for ticket in (_T_ATTR, _T_FP, _T_ALGO, _T_OVL, "155", "108"):
266 assert f'href="{MUSE_ISSUES}{ticket}"' in html, ticket
267 for ticket in (_T_CRDT, "214"):
268 assert f'href="{HUB_ISSUES}{ticket}"' in html, ticket
269 assert "from muse.domain import DomainSchema" not in text
270 with pytest.raises(ImportError):
271 exec("from muse.domain import DomainSchema", {})
272
273
274 def test_dom_09_tree_svg_is_accessible_and_themed(html: str) -> None:
275 svg = html.split('<svg class="domains-tree-svg"', 1)[1].split("</svg>", 1)[0]
276 assert 'role="img"' in svg and 'aria-labelledby="tree-diff-svg-title tree-diff-svg-desc"' in svg
277 assert '<title id="tree-diff-svg-title">' in svg and '<desc id="tree-diff-svg-desc">' in svg
278 assert not re.search(r'(fill|stroke)="(#|rgb)', svg)
279
280
281 # ── Known product defects: the contract is kept, pinned as strict xfails ────
282
283
284 @pytest.mark.xfail(strict=True, raises=AssertionError, reason=f"gabriel/muse#{_T_FP}: identity fingerprint hashes blob IDs")
285 def test_dom_10_identity_fingerprint_ignores_timestamps(tmp_path: pathlib.Path) -> None:
286 from muse.core.types import blob_id
287 from muse.plugins.identity.plugin import IdentityPlugin
288 p = IdentityPlugin()
289 path = "relationships/gabriel--delegates--claude-code.json"
290 rec = lambda ts, sig: blob_id(json.dumps({"from": "gabriel", "edge_type": "delegates", "to": "claude-code",
291 "authorized_at": ts, "sig": sig}).encode())
292 f1 = p.conflict_fingerprint(path, rec("2026-11-01T00:00:00Z", "s1"), rec("2026-11-01T00:00:00Z", "s2"), tmp_path)
293 f2 = p.conflict_fingerprint(path, rec("2026-11-02T00:00:00Z", "s3"), rec("2026-11-02T00:00:00Z", "s4"), tmp_path)
294 assert f1 == f2
295
296
297 def test_dom_11_museattributes_rule_applies_in_every_domain(tmp_path: pathlib.Path) -> None:
298 repo = tmp_path / "repo"
299 repo.mkdir()
300 env = _env(tmp_path)
301 run = lambda *a: _cli(repo, env, a)
302 assert run("init", "--domain", "chess")["rc"] == 0
303 (repo / "game.moves").write_text("e4\ne5\n")
304 (repo / ".museattributes").write_text('[[rules]]\npath = "game.moves"\ndimension = "*"\nstrategy = "ours"\n')
305 for args, moves in [(("commit", "-m", "base"), None), (("checkout", "-b", "a"), "e4\ne5\nNf3\n"),
306 (("commit", "-m", "a"), None), (("checkout", "main"), None),
307 (("checkout", "-b", "b"), "e4\ne5\nBc4\n"), (("commit", "-m", "b"), None),
308 (("checkout", "main"), None), (("merge", "a"), None)]:
309 r = run(*args)
310 if r["rc"] != 0:
311 pytest.fail(f"setup step {args} failed: {r['out']}")
312 if moves:
313 (repo / "game.moves").write_text(moves)
314 merged = run("merge", "b")
315 assert merged["rc"] == 0 and (repo / "game.moves").read_text() == "e4\ne5\nNf3\n", merged["out"]
316
317
318 def test_dom_11_the_page_says_museattributes_and_crdt_routing_apply(html: str) -> None:
319 text = " ".join(re.sub(r"<[^>]+>", " ", html).split())
320 assert "applies at merge in every domain" in text and "Every domain applies it" in text
321 assert "routes muse merge to the convergent join" in text
322 for stale in ("only the code and midi plugins apply", "does not change how muse merge merges", "Not wired into"):
323 assert stale not in text, stale
File History 5 commits
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:af59de7b8c8e9eaa86759e00caf5ee286439cf1dfc7730b6fb144cb29dd4a09f docs(domains,crdt,landing): .museattributes in every domain… 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:7bef01440bfabe2977a6efa1a492091c4717e67d9ac79f5ebeb120d3fb87c3e0 docs(domains): QA contract v2 — executable minimal plugin, … Opus 5.5 minor ⚠ 9 days ago