gabriel / musehub public
test_doc_inf_cli.py python
161 lines 7.3 KB Hotspot
Raw
sha256:27d91ce6191e753cb9f0dbd6b0b5d59dde18bc69fe10acc63bda269a0a0b238e docs(mists): #257 Mist Domain QA contract v2 (replay of 510… Opus 5.5 minor ⚠ breaking 8 days ago
1 """DOC_INF_01 — every documented ``muse …`` command parses against the real muse CLI (musehub#242 W2.1).
2
3 Each page's ``<pre>`` examples must parse completely; inline ``<code>`` references may omit
4 required arguments. Known findings are strict-xfailed against the page ticket that owns the
5 fix. The assertion message lists every offending command and the argparse reason.
6 ``TestCheckerDetects`` proves the checker reports each kind of defect, and
7 ``TestNeverExecutes`` proves that checking, destructive examples included, has no side effects.
8 """
9
10 from __future__ import annotations
11
12 import argparse
13 import os
14 import shutil
15 import subprocess
16 from collections.abc import Iterator
17 from unittest.mock import patch
18
19 import pytest
20
21 from tests.docs_contract import cli_check as cc
22 from tests.docs_contract.pages import PAGES, xfail_known
23
24 # Known findings (2026-11-06, musehub dev de2fd68a, muse dev 5becda10), each fixed under its page ticket.
25 _CLI_DEFECTS = {f"/muse/{s}" for s in (
26 "wire", "mists",
27 )}
28
29
30 @pytest.fixture(scope="module")
31 def parser() -> argparse.ArgumentParser:
32 return cc.capture_parser()
33
34
35 def _pre(line: str) -> cc.DocCommand:
36 return cc.DocCommand(line, in_pre=True)
37
38
39 # ── Live pages ──────────────────────────────────────────────────────────────
40
41
42 def test_extractor_finds_the_documented_commands(rendered: dict[str, str]) -> None:
43 counts = {p: len(cc.extract_commands(rendered[p])) for p in PAGES}
44 assert sum(counts.values()) > 400, counts # guards against the extractor silently matching nothing
45
46
47 @pytest.mark.parametrize("path", [xfail_known(p, _CLI_DEFECTS, "documented muse commands that do not parse") for p in PAGES])
48 def test_documented_commands_parse(path: str, parser: argparse.ArgumentParser, rendered: dict[str, str]) -> None:
49 _, problems = cc.check_page(parser, path, rendered[path])
50 assert problems == [], f"muse {cc.cli_version()}:\n" + "\n".join(problems)
51
52
53 # ── The checker detects real inconsistencies ────────────────────────────────
54
55
56 class TestCheckerDetects:
57 @pytest.mark.parametrize("line", [
58 'muse commit -m "msg" --agent-id claude-code --model-id m --sign',
59 "muse -C <repo> status --json | jq '.branch'",
60 "muse log --oneline 2>&1 > out.txt # trailing comment",
61 "muse init [--domain code|midi|identity]",
62 "muse coord enqueue <title> --queue q --priority <n> --json",
63 "muse hub issue read $ISSUE --json",
64 "muse read $(muse rev-parse HEAD) --json",
65 "muse --version",
66 "muse hub issue --help",
67 ])
68 def test_valid_commands_pass(self, parser: argparse.ArgumentParser, line: str) -> None:
69 assert cc.check_line(parser, _pre(line)).kind == "ok"
70
71 def test_unknown_command_and_subcommand(self, parser: argparse.ArgumentParser) -> None:
72 assert cc.check_line(parser, _pre("muse api-surface --json")).kind == "unknown-command"
73 r = cc.check_line(parser, _pre("muse harmony policies --json"))
74 assert r.kind == "unknown-command"
75 assert "policy-list" in r.detail # muse's own "did you mean" hint reaches the diagnostic
76
77 def test_unsupported_flag(self, parser: argparse.ArgumentParser) -> None:
78 r = cc.check_line(parser, _pre("muse shelf list --tags billing --json"))
79 assert (r.kind, r.detail) == ("unsupported-flag", "unrecognized arguments: --tags billing")
80
81 def test_positional_arity(self, parser: argparse.ArgumentParser) -> None:
82 assert cc.check_line(parser, _pre('muse code find-symbol "Name" --json')).kind == "arity"
83
84 def test_inline_reference_may_omit_arguments_but_pre_may_not(self, parser: argparse.ArgumentParser) -> None:
85 assert cc.check_line(parser, cc.DocCommand("muse merge --strategy", in_pre=False)).kind == "ok"
86 assert cc.check_line(parser, _pre("muse merge --strategy")).kind == "arity"
87
88 def test_invalid_choice_value(self, parser: argparse.ArgumentParser) -> None:
89 r = cc.check_line(parser, _pre("muse coord watch --kind reservation --json"))
90 assert r.kind == "invalid-value"
91 assert "reservations" in r.detail
92
93 @pytest.mark.parametrize(("line", "spelling"), [
94 ("muse add src/app.py", "muse code add"), ("muse stash", "muse shelf save"), ("muse show HEAD", "muse read"),
95 ])
96 def test_git_muscle_memory_is_named(self, parser: argparse.ArgumentParser, line: str, spelling: str) -> None:
97 r = cc.check_line(parser, _pre(line))
98 assert (r.kind, r.gitism) == ("unknown-command", spelling)
99
100 def test_diagnostic_names_page_and_command(self, parser: argparse.ArgumentParser) -> None:
101 html = "<pre>$ muse stash\n$ muse status</pre>"
102 _, problems = cc.check_page(parser, "/muse/x", html)
103 assert len(problems) == 1
104 assert problems[0].startswith("/muse/x: `muse stash` → unknown-command: ")
105 assert problems[0].endswith("[git-ism → muse shelf save]")
106
107 def test_extraction(self) -> None:
108 html = (
109 "<pre><span>$</span> muse status \\\n --json\n# output\nmuse 0.2.1\n</pre>"
110 "<p>Run <code>muse merge --strategy</code>; muse commit, muse push all sign.</p>"
111 "<code>muse commit, muse push</code><pre>&gt; muse log</pre>"
112 )
113 assert cc.extract_commands(html) == [
114 cc.DocCommand("muse status --json", in_pre=True),
115 cc.DocCommand("muse merge --strategy", in_pre=False),
116 cc.DocCommand("muse log", in_pre=True),
117 ]
118
119
120 # ── Checking never executes anything ────────────────────────────────────────
121
122 _DESTRUCTIVE = [
123 "muse reset --hard HEAD~3",
124 "muse branch -D feat/x",
125 "muse -C / rm src/app.py",
126 "muse push origin feat/x --delete",
127 "muse checkout --theirs config.py",
128 "muse auth keygen --force --destroy-mnemonic",
129 ]
130
131
132 @pytest.fixture
133 def no_side_effects() -> Iterator[None]:
134 def _forbidden(*_: object, **__: object) -> None:
135 raise AssertionError("the docs CLI checker must never execute, chdir or delete")
136
137 with (
138 patch.object(os, "chdir", _forbidden), patch.object(os, "remove", _forbidden),
139 patch.object(os, "unlink", _forbidden), patch.object(shutil, "rmtree", _forbidden),
140 patch.object(subprocess, "Popen", _forbidden),
141 ):
142 yield
143
144
145 class TestNeverExecutes:
146 def test_parser_capture_dispatches_nothing(self, no_side_effects: None) -> None:
147 captured = cc.capture_parser()
148 assert {"commit", "reset", "rm"} <= set(next(
149 a for a in captured._actions if isinstance(a, argparse._SubParsersAction)
150 ).choices)
151
152 @pytest.mark.parametrize("line", _DESTRUCTIVE)
153 def test_destructive_examples_are_classified_not_run(
154 self, parser: argparse.ArgumentParser, no_side_effects: None, line: str
155 ) -> None:
156 r = cc.check_line(parser, _pre(line))
157 assert r.destructive, line
158
159 @pytest.mark.parametrize("line", ["muse status", "muse branch feat/x", "muse push origin feat/x", "muse checkout -b feat/x"])
160 def test_safe_examples_are_not_flagged_destructive(self, parser: argparse.ArgumentParser, line: str) -> None:
161 assert not cc.check_line(parser, _pre(line)).destructive
File History 14 commits
sha256:27d91ce6191e753cb9f0dbd6b0b5d59dde18bc69fe10acc63bda269a0a0b238e docs(mists): #257 Mist Domain QA contract v2 (replay of 510… Opus 5.5 minor ⚠ 8 days ago
sha256:af8b93688057d89c35730de054ab1ce0648f4c405e3ebb884729a1a8b23fcd76 docs(wire): #254 Wire Protocol QA contract v2 (replay of c0… Opus 5.5 minor ⚠ 9 days ago
sha256:417ffbc1d6761e3a4cd26ca5475d5a0b786ae8af936912b5ce31121e2e55c19a docs(mcp): #252 MCP Tooling QA contract v2 — correct /muse/… Opus 5.5 minor ⚠ 9 days ago
sha256:395afcc81bdadd355e87f50a1eb01b857ffdcce78f54635a77fe893ca7352528 docs(coordination): #251 Agent Coordination QA contract v2 … Opus 5.5 minor ⚠ 9 days ago
sha256:4c51ee348c9f4848b67c2553ad2375f244c210f999589abb2898c80f7b43a8ea docs(harmony): #250 Harmony QA contract v2 — correct /muse/… Opus 5.5 minor ⚠ 9 days ago
sha256:0914c802f6e5260fd54b28ecfb013b7815a76983780d5d2f854ef46c3ed36ab8 docs(merge): #249 Merge Engine QA contract v2 — correct /mu… Sonnet 5.5 minor ⚠ 9 days ago
sha256:e16f407d787df2320fb726a5ea8a5b5eb1d53e68135d8992373f0fd5b5319fa9 docs(intelligence): QA contract v2 — 148-claim audit, 20 co… Sonnet 5 minor ⚠ 9 days ago
sha256:7bef01440bfabe2977a6efa1a492091c4717e67d9ac79f5ebeb120d3fb87c3e0 docs(domains): QA contract v2 — executable minimal plugin, … Opus 5.5 minor ⚠ 9 days ago
sha256:634da27c5b4ea6e3cb5aa9cfb4e58dbf922b627caef67ffb0cb64bcaf70b7b9f Merge task/246-identity-qa-v2 (#246 Cryptographic Identity … Opus 5.5 minor ⚠ 9 days ago
sha256:2de1e96b7f547494958a8edace1860efc2c0de0933c4f00f777f2cc18abaf324 docs(identity): QA contract v2 for /muse/identity against m… Opus 5.5 minor ⚠ 9 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
sha256:f7413c1abec6d6a8e5bdabcd4cc7ad5fcd059ce6a6f50f566e2b0118a0a8b578 tests: make tests/docs_contract/ database-free by directory… Opus 5.5 10 days ago
sha256:0e4f9453dfdeb2c10fb31581a5b195aa7af7d349f90e5904bd38e1c1f7d19cc0 test(docs): check every documented muse command against the… Opus 5.5 10 days ago