mustmatch

mustmatch provides two tightly coupled capabilities for executable documentation workflows. It asserts CLI output in shell pipelines, and it executes Markdown bash/python fences as pytest tests. The Rust core handles parsing, normalization, and comparison while Python keeps runtime orchestration.

Install

Use a normal Python virtual environment and install with pip. This snippet is documentation-only and intentionally skipped during executable doc runs.

pip install mustmatch

CLI Assertions

Pipe command output into mustmatch and compare against one expected value.

echo "hello" | mustmatch "hello"
echo "hello world" | mustmatch like "world"
echo "v1.2.3" | mustmatch "/^v[0-9]+[.][0-9]+[.][0-9]+$/"
echo '{"status":"ok","count":42}' | mustmatch like '{"status":"ok"}'

Executable Markdown

Markdown documents become test files under pytest collection. Tables can drive per-row Python checks with each_row.

# Math Behavior

## Double Values

| input | output |
|-------|--------|
| 2     | 4      |

```python each_row
doubled = row.input * 2
result = {"input": row.input, "output": doubled}
row_label = f"row-{row_index}"
```

Run docs as tests:

uv sync --extra dev --reinstall-package mustmatch
uv run python -m pytest docs/ -v

Quality Checks

Use mustmatch verify-matrix to confirm proof-matrix references stay inside the repo, and mustmatch lint to lint markdown specs without executing their fences.

• mustmatch verify-matrix .march/design-final.md --repo-root .
• mustmatch lint docs/02-cli-assertions.md

Documentation Map

The executable specification is in docs/:

1. docs/01-overview.md
2. docs/02-cli-assertions.md
3. docs/03-executable-documents.md
4. docs/04-fixtures-and-tables.md
5. docs/05-directives.md
6. docs/06-comparison-modes.md
7. docs/07-normalization.md
8. docs/08-configuration.md
9. docs/09-examples.md
10. docs/10-verify-matrix.md
11. docs/11-lint.md

CLI Bench Plan

Benchmark commands are tracked in bench/clibench-commands.txt so Python and Rust paths can be compared with the same tag set.

# Python baseline
CLIBENCH_PROJECT=mustmatch-cli uv run --script /home/ian/workspace/.codex/skills/clibench/clibench.py batch bench/clibench-commands.txt

# Compare prefixes
CLIBENCH_PROJECT=mustmatch-cli uv run --script /home/ian/workspace/.codex/skills/clibench/clibench.py compare python rust

License

MIT