gabriel / musehub public
cli_check.py python
304 lines 12.3 KB
Raw
sha256:0e4f9453dfdeb2c10fb31581a5b195aa7af7d349f90e5904bd38e1c1f7d19cc0 test(docs): check every documented muse command against the… Opus 5.5 10 days ago
1 """Documented ``muse …`` command lines vs. the real muse argparse tree (musehub#242 W2.1, DOC_INF_01).
2
3 The CLI under test is the ``muse`` package importable next to musehub (the wheel bundled in
4 the image). ``capture_parser`` builds its real top-level parser by running
5 ``muse.cli.app.main`` up to its ``parse_args`` call and stopping there, so no command
6 handler, ``-C`` chdir or I/O ever runs. ``check_line`` then calls ``parse_args`` on each
7 documented line, with placeholders substituted, and classifies the argparse error.
8
9 Nothing documented is executed. Destructive examples are only classified, so a later
10 execution-based QA run (W4) knows to keep them out of any real repository.
11 """
12
13 from __future__ import annotations
14
15 import argparse
16 import contextlib
17 import io
18 import re
19 import shlex
20 from dataclasses import dataclass
21 from html.parser import HTMLParser
22 from unittest.mock import patch
23
24 # ── Parser capture ──────────────────────────────────────────────────────────
25
26
27 class _Captured(Exception):
28 def __init__(self, parser: argparse.ArgumentParser) -> None:
29 self.parser = parser
30
31
32 def capture_parser() -> argparse.ArgumentParser:
33 """The real ``muse`` top-level parser, captured at ``parse_args`` before any dispatch."""
34 from muse.cli import app as muse_app
35
36 def _stop(self: argparse.ArgumentParser, *args: object, **kwargs: object) -> None:
37 raise _Captured(self)
38
39 with patch.object(muse_app._MuseArgumentParser, "parse_args", _stop):
40 try:
41 muse_app.main(["--version"])
42 except _Captured as captured:
43 return captured.parser
44 raise RuntimeError("muse.cli.app.main returned without calling parse_args")
45
46
47 def cli_version() -> str:
48 from muse._version import __version__
49
50 return __version__
51
52
53 # ── Extraction ──────────────────────────────────────────────────────────────
54
55
56 @dataclass(frozen=True)
57 class DocCommand:
58 line: str
59 in_pre: bool # a runnable example block; inline <code> is a reference and may omit arguments
60
61
62 class _CodeParser(HTMLParser):
63 def __init__(self) -> None:
64 super().__init__(convert_charrefs=True)
65 self.blocks: list[tuple[str, bool]] = []
66 self._pre = 0
67 self._code = 0
68 self._buf: list[str] = []
69
70 def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
71 if tag == "pre":
72 if self._pre == 0:
73 self._buf = []
74 self._pre += 1
75 elif tag == "code" and self._pre == 0:
76 if self._code == 0:
77 self._buf = []
78 self._code += 1
79 elif tag == "br" and (self._pre or self._code):
80 self._buf.append("\n")
81
82 def handle_endtag(self, tag: str) -> None:
83 if tag == "pre" and self._pre:
84 self._pre -= 1
85 if self._pre == 0:
86 self.blocks.append(("".join(self._buf), True))
87 elif tag == "code" and self._code and self._pre == 0:
88 self._code -= 1
89 if self._code == 0:
90 self.blocks.append(("".join(self._buf), False))
91
92 def handle_data(self, data: str) -> None:
93 if self._pre or self._code:
94 self._buf.append(data)
95
96
97 # `muse <word>` where <word> is a whole command or flag token: excludes prose like "muse commit, muse push …".
98 _MUSE_LINE = re.compile(r"^muse\s+-{0,2}[A-Za-z][\w-]*(?=\s|$)")
99
100
101 def extract_commands(html: str) -> list[DocCommand]:
102 """Every ``muse …`` line in ``<pre>`` blocks and inline ``<code>``, with ``\\`` continuations joined."""
103 parser = _CodeParser()
104 parser.feed(html)
105 parser.close()
106 seen: dict[str, DocCommand] = {}
107 for text, in_pre in parser.blocks:
108 text = re.sub(r"\\[ \t]*\n[ \t]*", " ", text)
109 for raw in text.splitlines():
110 line = re.sub(r"^\s*(?:\$|>|#|%)\s+", "", raw).strip()
111 if _MUSE_LINE.match(line):
112 line = re.sub(r"\s+", " ", line)
113 prev = seen.get(line)
114 seen[line] = DocCommand(line, in_pre or (prev.in_pre if prev else False))
115 return list(seen.values())
116
117
118 # ── Tokenising ──────────────────────────────────────────────────────────────
119
120 _SHELL_STOP = {"|", "||", "&&", ";", "&", ">", ">>", "<", "2>", "2>&1", "&>", "|&"}
121 _PLACEHOLDER = re.compile(r"^(?:__PH\d+__|\$\{?[A-Za-z_][A-Za-z0-9_]*\}?|[A-Z][A-Z0-9_]{1,}|…|\.\.\.)$")
122
123
124 def tokenize(line: str) -> list[str] | None:
125 """argv after ``muse``: placeholders normalised, shell operators and comments cut. None if unparseable."""
126 n = 0
127
128 def _ph(_: re.Match[str]) -> str:
129 nonlocal n
130 n += 1
131 return f" __PH{n}__ "
132
133 line = re.sub(r"\$\([^()]*\)", _ph, line) # $(command substitution)
134 line = re.sub(r"<[^<>]+>", _ph, line) # <placeholder>, including "<commit id>"
135 try:
136 tokens = shlex.split(line, comments=True)
137 except ValueError:
138 # A quoted argument that continues on the next line, e.g. `muse … | python3 -c "`:
139 # the muse part ends at the first shell operator.
140 head = re.split(r"\s(?:\|\|?|&&|;)\s", line, maxsplit=1)[0]
141 try:
142 tokens = shlex.split(head, comments=True)
143 except ValueError:
144 return None
145 argv: list[str] = []
146 for t in tokens[1:]:
147 if t in _SHELL_STOP or t.startswith((">", "2>", "|")):
148 break
149 bracketed = t.startswith("[") or t.endswith("]")
150 t = t.strip("[]") # optional-argument synopsis: [--owner HANDLE] → --owner HANDLE
151 if not t or (bracketed and t.lower() in ("options", "flags", "args")):
152 continue
153 if "|" in t and not t.startswith("-"):
154 t = t.split("|", 1)[0] # alternatives synopsis: code|midi|identity → code
155 if t in ("...", "…"):
156 if argv and argv[-1].startswith("-") and "=" not in argv[-1]:
157 argv.append("x") # `--title ...` stands for a value
158 continue
159 argv.append(t)
160 return argv
161
162
163 def is_placeholder(token: str) -> bool:
164 return bool(_PLACEHOLDER.match(token))
165
166
167 # ── Classification ──────────────────────────────────────────────────────────
168
169 # Git verbs muse does not have as top-level commands, with the muse spelling. An unknown-command
170 # error on one of these is git muscle memory, and the diagnostic names the replacement.
171 GITISMS = {"add": "muse code add", "stash": "muse shelf save", "show": "muse read"}
172
173 # (subcommand path prefix, flags) that make an example destructive; an empty flag set means always.
174 _DESTRUCTIVE = [
175 (("reset",), {"--hard"}), (("branch",), {"-D", "--delete", "-d"}), (("rm",), set()),
176 (("push",), {"--force", "-f", "--delete"}), (("checkout",), {"--force", "-f", "--ours", "--theirs"}),
177 (("merge",), {"--abort"}), (("gc",), {"--prune"}), (("clean",), set()),
178 ]
179
180
181 @dataclass(frozen=True)
182 class CommandResult:
183 line: str
184 kind: str # ok | unknown-command | unsupported-flag | arity | invalid-value | unparseable
185 detail: str = ""
186 gitism: str | None = None # the muse spelling when the unknown command is a git verb
187 destructive: bool = False
188
189 @property
190 def ok(self) -> bool:
191 return self.kind == "ok"
192
193
194 def _subcommand_path(parser: argparse.ArgumentParser, argv: list[str]) -> tuple[str, ...]:
195 path: list[str] = []
196 node = parser
197 tokens = iter(argv)
198 for t in tokens:
199 if t.startswith("-"):
200 action = node._option_string_actions.get(t.split("=", 1)[0])
201 if action is not None and action.nargs != 0 and "=" not in t:
202 next(tokens, None) # the option's value, e.g. the DIR of `-C DIR`
203 continue
204 subs = [a for a in node._actions if isinstance(a, argparse._SubParsersAction)]
205 if not subs or t not in subs[0].choices:
206 break
207 path.append(t)
208 node = subs[0].choices[t]
209 return tuple(path)
210
211
212 def is_destructive(parser: argparse.ArgumentParser, argv: list[str]) -> bool:
213 path = _subcommand_path(parser, argv)
214 flags = {t.split("=", 1)[0] for t in argv if t.startswith("-")}
215 if "--force" in flags:
216 return True
217 return any(path[: len(prefix)] == prefix and (not need or flags & need) for prefix, need in _DESTRUCTIVE)
218
219
220 def _parse(parser: argparse.ArgumentParser, argv: list[str]) -> str | None:
221 """argparse's error message for ``argv``, or None when it parses. Never dispatches."""
222 err = io.StringIO()
223 with contextlib.redirect_stderr(err), contextlib.redirect_stdout(io.StringIO()):
224 try:
225 parser.parse_args(argv)
226 except SystemExit as exc:
227 if exc.code in (0, None):
228 return None # --help / --version
229 lines = err.getvalue().strip().splitlines()
230 start = next((i for i, ln in enumerate(lines) if ": error: " in ln), None)
231 if start is None:
232 return f"exit {exc.code}"
233 return " ".join(ln.strip() for ln in lines[start:]) # error line plus any "Did you mean" hint
234 return None
235
236
237 _ERR_VALUE = re.compile(r"argument (\S+?): invalid (?:int|float|\w+) value: '([^']*)'")
238 _ERR_CHOICE = re.compile(r"argument (\S+?): invalid choice: '([^']*)'")
239
240
241 def _substitute(parser: argparse.ArgumentParser, argv: list[str], message: str) -> list[str] | None:
242 """Replace a placeholder the parser rejected as a typed/choice value with a valid one."""
243 for rx in (_ERR_VALUE, _ERR_CHOICE):
244 m = rx.search(message)
245 if m and is_placeholder(m.group(2)) and m.group(2) in argv:
246 value = "1"
247 if rx is _ERR_CHOICE:
248 cm = re.search(r"\(choose from (.+)\)", message)
249 if not cm:
250 return None
251 value = cm.group(1).split(",")[0].strip().strip("'")
252 out = list(argv)
253 out[out.index(m.group(2))] = value
254 return out
255 return None
256
257
258 def _classify(message: str) -> str:
259 m = re.search(r"argument ([^:]+): invalid choice", message)
260 if m:
261 return "invalid-value" if m.group(1).startswith("-") else "unknown-command"
262 if "unrecognized arguments:" in message:
263 extra = message.split("unrecognized arguments:", 1)[1].split()
264 return "unsupported-flag" if any(t.startswith("-") for t in extra) else "arity"
265 if "the following arguments are required" in message or "expected one argument" in message:
266 return "arity"
267 return "invalid-value"
268
269
270 def check_line(parser: argparse.ArgumentParser, cmd: DocCommand) -> CommandResult:
271 argv = tokenize(cmd.line)
272 if argv is None:
273 return CommandResult(cmd.line, "unparseable", "unbalanced shell quoting")
274 destructive = is_destructive(parser, argv)
275 message = _parse(parser, argv)
276 for _ in range(8):
277 if message is None:
278 break
279 fixed = _substitute(parser, argv, message)
280 if fixed is None:
281 break
282 argv, message = fixed, _parse(parser, fixed)
283 if message is None:
284 return CommandResult(cmd.line, "ok", destructive=destructive)
285 kind = _classify(message)
286 if kind == "arity" and not cmd.in_pre and ("required" in message or "expected one argument" in message):
287 # Inline <code> names a command or flag (`muse merge --strategy`); only <pre> examples must be complete.
288 return CommandResult(cmd.line, "ok", destructive=destructive)
289 gitism = None
290 m = _ERR_CHOICE.search(message)
291 if kind == "unknown-command" and m and m.group(2) in GITISMS:
292 gitism = GITISMS[m.group(2)]
293 return CommandResult(cmd.line, kind, message.removeprefix("muse: error: ").split(": error: ")[-1], gitism, destructive)
294
295
296 def check_page(parser: argparse.ArgumentParser, page: str, html: str) -> tuple[list[CommandResult], list[str]]:
297 """All results for one page, plus one actionable diagnostic per failing command."""
298 results = [check_line(parser, c) for c in extract_commands(html)]
299 problems = []
300 for r in results:
301 if not r.ok:
302 hint = f" [git-ism → {r.gitism}]" if r.gitism else ""
303 problems.append(f"{page}: `{r.line}` → {r.kind}: {r.detail}{hint}")
304 return results, problems
File History 1 commit
sha256:0e4f9453dfdeb2c10fb31581a5b195aa7af7d349f90e5904bd38e1c1f7d19cc0 test(docs): check every documented muse command against the… Opus 5.5 10 days ago