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