tempest-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{tempest_cli-0.2.0 → tempest_cli-0.4.0}/CHANGELOG.md

@@ -5,6 +5,82 @@ All notable changes to **tempest-cli** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] — 2026-09-27
+
+### Added
+
+- **`test --fast` and `check --fast`: the suite in parallel.** `--fast`
+  runs pytest as `pytest -n <workers> -p no:cacheprovider [target]`, with
+  pytest-xdist spreading the suite across the cores; `--workers` / `-w`
+  takes what `pytest -n` takes (an integer, `auto` — the default — or
+  `logical`) and is a usage error (exit 2) without `--fast`. The cache
+  plugin is off because several workers writing `.pytest_cache` at once
+  is a race that buys nothing. The target is forwarded and pytest's exit
+  code comes straight back, as in the serial run. It is a flag rather
+  than a `test fast` subcommand because `test` already takes a
+  positional path: `test fast` keeps meaning the `fast/` folder.
+  Requested in mauriciobenjamin700/tempest-fastapi-sdk#328.
+
+  Measured on a machine with 6 physical cores / 12 threads. On this
+  package's own suite (100 tests, warm environment, three runs each)
+  `tempest-cli test` took 2.2 s and `tempest-cli test --fast` 1.6–1.7 s
+  (12 workers: no `psutil` here, so `auto` counts logical CPUs) — worker
+  start-up is most of the fast run at this size. On the
+  tempest-fastapi-sdk suite (10 218 tests, one run each, same
+  invocation), pytest reported 2127 s serial and 411 s with `--fast`
+  (`auto` → 6 workers, since `psutil` is installed there), about 5.2x;
+  both runs ended with the same 10 failures, all from `ruff` being a dead
+  pyenv shim on that `PATH`.
+
+  `auto` is pytest-xdist's rule, not ours: physical cores when `psutil`
+  is importable, logical CPUs otherwise. `-w logical` asks for the
+  threads explicitly.
+
+- **A missing pytest-xdist is a sentence, not `unrecognized arguments:
+  -n`.** Before spawning, `--fast` asks the interpreter pytest will run
+  under — read from the pytest script's shebang, its sibling `python`,
+  or the same `uv run --with pytest` overlay — whether it can import
+  `xdist`. When it cannot, the message names `pytest-xdist`,
+  `tempest-cli[tools]` and `tempest-fastapi-sdk[tests]`, and the exit code
+  is 127, with no traceback. `check --fast` makes that check before its
+  first step. A probe that cannot run at all is not taken as "missing":
+  the run proceeds and pytest reports for itself.
+
+- **`run_pytest(..., fast=, workers=)` and `run_full_check(..., fast=,
+  workers=)`** for library callers — keyword-only, defaulting to the
+  serial run, so every existing call is unchanged. `DEFAULT_FAST_WORKERS`,
+  `XDIST_MODULE` and `MISSING_TOOL_EXIT_CODE` are exported from
+  `tempest_cli.lint`.
+
+### Changed
+
+- **`[tools]` now carries `pytest-xdist>=3.8.0`** next to mypy and pytest,
+  so the bundle is enough for `--fast`. Its `requires-dist`
+  (`execnet>=2.1`, `pytest>=7.0.0`) has no upper bound.
+
+## [0.3.0] — 2026-08-15
+
+### Changed
+
+- **`ruff` now ships with the package.** It moved from the `[tools]`
+  extra into the runtime dependencies, so `uv add --dev tempest-cli` is
+  enough for `lint`, `fix`, `format` and `fmt-check` to run — no second
+  install, and no dependency on `uv` being around to fetch one. The cost
+  is nil: ruff is a static binary wheel with no Python dependencies of
+  its own, so no bound of its reaches a consumer's resolution.
+
+  `mypy` and `pytest` stay out on purpose. A mypy bump changes which
+  errors a codebase reports and pytest has to match the suite and its
+  plugins — those are the project's call. `[tools]` now installs exactly
+  those two.
+
+- **The project's environment is searched before the CLI's own.** With
+  ruff bundled, the CLI's environment always has one; looking there
+  first would silently override a version the project pinned whenever
+  `tempest-cli` is installed apart from it (`uv tool install`, pipx).
+  The order is now `$VIRTUAL_ENV` → nearest `.venv` → the CLI's own
+  environment → `PATH` → `uv run --with`.
+
 ## [0.2.0] — 2026-08-15
 
 ### Added

{tempest_cli-0.2.0 → tempest_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Framework-agnostic quality gate for Python projects: ruff + mypy + pytest behind one command, with a typing-strictness dial and a PR-description prompt generator.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-cli
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-cli
@@ -22,11 +22,12 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: ruff>=0.8.0
 Requires-Dist: typer>=0.12.0
 Provides-Extra: tools
 Requires-Dist: mypy>=1.13.0; extra == 'tools'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'tools'
 Requires-Dist: pytest>=8.3.3; extra == 'tools'
-Requires-Dist: ruff>=0.8.0; extra == 'tools'
 Description-Content-Type: text/markdown
 
 # tempest-cli
@@ -42,7 +43,8 @@ One command for the quality gate of any Python project — `ruff` +
 `pyproject.toml` instead of in four different Makefile targets.
 
 Framework-agnostic on purpose: Django, Flask, Litestar, FastAPI, a
-library, a script. The only runtime dependency is `typer`.
+library, a script. It brings `ruff` along, so the gate runs the moment
+you install it; `typer` is the only other runtime dependency.
 
 ```bash
 uv add --dev tempest-cli
@@ -72,8 +74,8 @@ remembered to pass.
 | `tempest-cli format` | `ruff format` (writes) |
 | `tempest-cli fmt-check` | `ruff format --check` (read-only) |
 | `tempest-cli type` | `mypy` |
-| `tempest-cli test` | `pytest` |
-| `tempest-cli check` | all four, in order, stopping at the first failure |
+| `tempest-cli test` | `pytest` (`--fast` spreads it across cores with pytest-xdist: `-n auto -p no:cacheprovider`, `-w N` to choose) |
+| `tempest-cli check` | all four, in order, stopping at the first failure (`--fast` runs the test step in parallel) |
 | `tempest-cli pr-prompt` | builds the prompt that makes an AI write this branch's PR description |
 
 Every command takes an optional path (`tempest-cli lint src/`) and
@@ -103,6 +105,13 @@ they avoid `Any`.
 Override per run with `--strictness` / `-s`. Absent config means
 `standard`.
 
+Everything that is *not* typing — silencing an untyped library, skipping
+generated code, dropping a rule that does not fit your framework — is
+ordinary `[tool.ruff]` / `[tool.mypy]` configuration. The recipes,
+including the one that takes a legacy Django project to a green gate,
+are in **[Tuning the rules](https://mauriciobenjamin700.github.io/tempest-cli/rules/)**
+([EN](https://mauriciobenjamin700.github.io/tempest-cli/en/rules/)).
+
 ## PR descriptions from the branch itself
 
 ```bash
@@ -141,24 +150,36 @@ cli: typer.Typer = typer.Typer(name="mytool")
 register_commands(cli)
 ```
 
-## Installing the tools
-
-`tempest-cli` shells out to whatever `ruff`, `mypy` and `pytest` it
-finds — it does not pin them, so your project chooses the versions. The
-lookup runs in this order:
+## Where the tools come from
 
-1. the environments of the run — the interpreter's own directory, then
-   `$VIRTUAL_ENV`, then the nearest `.venv` up the tree;
-2. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
-   that answers `pyenv: ruff: command not found`);
-3. `uv run --with <tool> <tool>`, when `uv` is available.
+**`ruff` comes with the package** — six of the eight commands are ruff,
+so `lint`, `fix`, `format` and `fmt-check` work straight after
+`uv add --dev tempest-cli`, with nothing else to install. It is a static
+binary wheel with no Python dependencies of its own, so nothing of its
+propagates into your resolution.
 
-To install the three alongside it:
+`mypy` and `pytest` are deliberately left to you — a mypy bump changes
+which errors your code reports, and pytest has to match your plugins and
+your suite. Add them yourself, or take the bundle:
 
 ```bash
-uv add --dev "tempest-cli[tools]"
+uv add --dev "tempest-cli[tools]"   # mypy + pytest + pytest-xdist
 ```
 
+`pytest-xdist` is what `test --fast` runs the suite with; its
+`requires-dist` (`execnet>=2.1`, `pytest>=7.0.0`) carries no upper bound.
+
+Whatever you pin wins over the bundled ruff. The lookup runs in this
+order:
+
+1. the project's environment — `$VIRTUAL_ENV`, then the nearest `.venv`
+   up the tree;
+2. the environment `tempest-cli` itself runs from (where the bundled
+   ruff lives);
+3. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
+   that answers `pyenv: ruff: command not found`);
+4. `uv run --with <tool> <tool>`, when `uv` is available.
+
 ## Relationship with tempest-fastapi-sdk
 
 This package was extracted from

{tempest_cli-0.2.0 → tempest_cli-0.4.0}/README.md

@@ -11,7 +11,8 @@ One command for the quality gate of any Python project — `ruff` +
 `pyproject.toml` instead of in four different Makefile targets.
 
 Framework-agnostic on purpose: Django, Flask, Litestar, FastAPI, a
-library, a script. The only runtime dependency is `typer`.
+library, a script. It brings `ruff` along, so the gate runs the moment
+you install it; `typer` is the only other runtime dependency.
 
 ```bash
 uv add --dev tempest-cli
@@ -41,8 +42,8 @@ remembered to pass.
 | `tempest-cli format` | `ruff format` (writes) |
 | `tempest-cli fmt-check` | `ruff format --check` (read-only) |
 | `tempest-cli type` | `mypy` |
-| `tempest-cli test` | `pytest` |
-| `tempest-cli check` | all four, in order, stopping at the first failure |
+| `tempest-cli test` | `pytest` (`--fast` spreads it across cores with pytest-xdist: `-n auto -p no:cacheprovider`, `-w N` to choose) |
+| `tempest-cli check` | all four, in order, stopping at the first failure (`--fast` runs the test step in parallel) |
 | `tempest-cli pr-prompt` | builds the prompt that makes an AI write this branch's PR description |
 
 Every command takes an optional path (`tempest-cli lint src/`) and
@@ -72,6 +73,13 @@ they avoid `Any`.
 Override per run with `--strictness` / `-s`. Absent config means
 `standard`.
 
+Everything that is *not* typing — silencing an untyped library, skipping
+generated code, dropping a rule that does not fit your framework — is
+ordinary `[tool.ruff]` / `[tool.mypy]` configuration. The recipes,
+including the one that takes a legacy Django project to a green gate,
+are in **[Tuning the rules](https://mauriciobenjamin700.github.io/tempest-cli/rules/)**
+([EN](https://mauriciobenjamin700.github.io/tempest-cli/en/rules/)).
+
 ## PR descriptions from the branch itself
 
 ```bash
@@ -110,24 +118,36 @@ cli: typer.Typer = typer.Typer(name="mytool")
 register_commands(cli)
 ```
 
-## Installing the tools
-
-`tempest-cli` shells out to whatever `ruff`, `mypy` and `pytest` it
-finds — it does not pin them, so your project chooses the versions. The
-lookup runs in this order:
+## Where the tools come from
 
-1. the environments of the run — the interpreter's own directory, then
-   `$VIRTUAL_ENV`, then the nearest `.venv` up the tree;
-2. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
-   that answers `pyenv: ruff: command not found`);
-3. `uv run --with <tool> <tool>`, when `uv` is available.
+**`ruff` comes with the package** — six of the eight commands are ruff,
+so `lint`, `fix`, `format` and `fmt-check` work straight after
+`uv add --dev tempest-cli`, with nothing else to install. It is a static
+binary wheel with no Python dependencies of its own, so nothing of its
+propagates into your resolution.
 
-To install the three alongside it:
+`mypy` and `pytest` are deliberately left to you — a mypy bump changes
+which errors your code reports, and pytest has to match your plugins and
+your suite. Add them yourself, or take the bundle:
 
 ```bash
-uv add --dev "tempest-cli[tools]"
+uv add --dev "tempest-cli[tools]"   # mypy + pytest + pytest-xdist
 ```
 
+`pytest-xdist` is what `test --fast` runs the suite with; its
+`requires-dist` (`execnet>=2.1`, `pytest>=7.0.0`) carries no upper bound.
+
+Whatever you pin wins over the bundled ruff. The lookup runs in this
+order:
+
+1. the project's environment — `$VIRTUAL_ENV`, then the nearest `.venv`
+   up the tree;
+2. the environment `tempest-cli` itself runs from (where the bundled
+   ruff lives);
+3. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
+   that answers `pyenv: ruff: command not found`);
+4. `uv run --with <tool> <tool>`, when `uv` is available.
+
 ## Relationship with tempest-fastapi-sdk
 
 This package was extracted from

{tempest_cli-0.2.0 → tempest_cli-0.4.0}/docs/changelog.en.md

@@ -3,6 +3,48 @@
 The full history lives in the repository's
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md).
 
+## [0.4.0] — 2026-09-27
+
+### Added
+
+- **`test --fast` and `check --fast`: the suite in parallel.** Runs
+  `pytest -n <workers> -p no:cacheprovider [target]` with pytest-xdist;
+  `--workers` / `-w` takes what `pytest -n` takes (an integer, `auto` —
+  the default — or `logical`) and is a usage error without `--fast`. The
+  target is forwarded and pytest's exit code comes back untranslated. It
+  is a flag, not a subcommand, because `test fast` keeps meaning the
+  `fast/` folder. [Details](commands.md#the-suite-in-parallel-fast).
+- **A missing pytest-xdist is a sentence, not `unrecognized arguments:
+  -n`.** `--fast` asks the interpreter that will run pytest whether it
+  can import `xdist`; when it cannot, the message names the package and
+  the extras (`tempest-cli[tools]`, `tempest-fastapi-sdk[tests]`) and the
+  exit code is 127, with no traceback. Under `check --fast` the check
+  comes before the first step.
+- **`run_pytest` / `run_full_check` gain `fast=` and `workers=`**,
+  keyword-only, serial by default.
+
+### Changed
+
+- **`[tools]` now carries `pytest-xdist>=3.8.0`.** No upper bound in its
+  `requires-dist` (`execnet>=2.1`, `pytest>=7.0.0`).
+
+## [0.3.0] — 2026-08-15
+
+### Changed
+
+- **`ruff` now ships with the package.** It left the `[tools]` extra for
+  the runtime dependencies, so `uv add --dev tempest-cli` is enough for
+  `lint`, `fix`, `format` and `fmt-check` to run. The cost is nil: ruff
+  is a static binary wheel with no Python dependencies of its own, so no
+  bound of its reaches a consumer's resolution. `mypy` and `pytest` stay
+  out on purpose; `[tools]` now installs exactly those two.
+- **The project's environment is searched before the CLI's own.** With
+  ruff bundled, the CLI's environment always has one — looking there
+  first would silently override a version the project pinned whenever
+  `tempest-cli` lives apart from it (`uv tool install`, pipx). The order
+  is now `$VIRTUAL_ENV` → nearest `.venv` → the CLI's environment →
+  `PATH` → `uv run --with`.
+
 ## [0.2.0] — 2026-08-15
 
 ### Added

{tempest_cli-0.2.0 → tempest_cli-0.4.0}/docs/changelog.md

@@ -4,6 +4,47 @@ O histórico completo vive no
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md)
 do repositório.
 
+## [0.4.0] — 2026-09-27
+
+### Adicionado
+
+- **`test --fast` e `check --fast`: a suíte em paralelo.** Roda
+  `pytest -n <workers> -p no:cacheprovider [alvo]` com o pytest-xdist;
+  `--workers` / `-w` aceita o que o `pytest -n` aceita (inteiro, `auto` —
+  o padrão — ou `logical`) e é erro de uso sem `--fast`. O alvo é
+  repassado e o código de saída do pytest volta sem tradução. É flag, e
+  não subcomando, porque `test fast` continua significando a pasta
+  `fast/`. [Detalhes](commands.md#a-suite-em-paralelo-fast).
+- **pytest-xdist ausente vira frase, não `unrecognized arguments: -n`.**
+  O `--fast` pergunta ao interpretador que vai rodar o pytest se ele
+  importa o `xdist`; faltando, a mensagem nomeia o pacote e os extras
+  (`tempest-cli[tools]`, `tempest-fastapi-sdk[tests]`) e a saída é 127,
+  sem traceback. No `check --fast` a checagem vem antes do primeiro passo.
+- **`run_pytest` / `run_full_check` ganham `fast=` e `workers=`**
+  keyword-only, com default serial.
+
+### Mudado
+
+- **O `[tools]` agora leva `pytest-xdist>=3.8.0`.** Sem teto no
+  `requires-dist` (`execnet>=2.1`, `pytest>=7.0.0`).
+
+## [0.3.0] — 2026-08-15
+
+### Mudado
+
+- **O `ruff` agora vem junto com o pacote.** Saiu do extra `[tools]` e
+  virou dependência: `uv add --dev tempest-cli` já basta para `lint`,
+  `fix`, `format` e `fmt-check` rodarem. Custo zero — o ruff é binário
+  estático, sem dependência Python, então nenhum limite dele entra na
+  resolução de quem instala. `mypy` e `pytest` continuam de fora de
+  propósito; `[tools]` agora instala exatamente esses dois.
+- **O ambiente do projeto passa a ser procurado antes do da CLI.** Com o
+  ruff embutido, o ambiente da CLI sempre tem um — procurar ali primeiro
+  sobrescreveria em silêncio a versão que o projeto fixou quando o
+  `tempest-cli` mora fora dele (`uv tool install`, pipx). A ordem agora é
+  `$VIRTUAL_ENV` → `.venv` mais próximo → ambiente da CLI → `PATH` →
+  `uv run --with`.
+
 ## [0.2.0] — 2026-08-15
 
 ### Adicionado

tempest_cli-0.4.0/docs/commands.en.md

@@ -0,0 +1,159 @@
+# Commands
+
+Eight commands. All take an optional path and return the underlying
+tool's exit code.
+
+| Command | Runs |
+| --- | --- |
+| `lint` | `ruff check` |
+| `fix` | `ruff check --fix` then `ruff format` |
+| `format` | `ruff format` (writes) |
+| `fmt-check` | `ruff format --check` (read-only) |
+| `type` | `mypy` |
+| `test` | `pytest` |
+| `check` | the four above, in order, stopping at the first failure |
+| `pr-prompt` | builds the PR-description prompt — [its own page](pr-prompt.md) |
+
+!!! tip "`tc` is the short form"
+    The package installs `tempest-cli` and `tc` pointing at the same
+    program. The examples use the long name; `tc check`, `tc fix` and
+    `tc type -s strict` work exactly the same.
+
+## The full gate
+
+```bash
+tempest-cli check              # the whole project
+tempest-cli check src/         # a single path
+tempest-cli check -s strict    # with raised typing strictness for this run
+```
+
+The order is deliberate: **lint → formatting → types → tests**. What
+fails fastest and is cheapest to fix comes first, and the run stops at
+the first failure — there is no point running the whole suite when the
+imports are unsorted.
+
+## Fixing what can be fixed
+
+```bash
+tempest-cli fix                # safe autofixes + formatting
+tempest-cli fix --unsafe       # also ruff's risky autofixes
+```
+
+`fix` makes two passes: `ruff check --fix` (sorts and dedupes imports,
+drops unused ones, normalizes quotes) and then `ruff format`
+(indentation, line length, blank lines).
+
+!!! warning "`--unsafe` can change behavior"
+    Ruff's "unsafe" autofixes are the ones that may alter semantics.
+    They are off by default. Turned them on? Read the `git diff` before
+    committing.
+
+## One at a time
+
+```bash
+tempest-cli lint src/
+tempest-cli fmt-check
+tempest-cli type mypackage
+tempest-cli test tests/unit
+```
+
+`test` forwards the path to pytest as a filter; with no argument it runs
+the whole suite.
+
+## The suite in parallel: `--fast`
+
+A suite whose tests are already isolated (a database per test, no global
+state) pays the serial time and buys nothing for it. `--fast` spreads the
+suite across the cores with
+[pytest-xdist](https://pytest-xdist.readthedocs.io/):
+
+```bash
+tempest-cli test --fast              # -n auto: one worker per core
+tempest-cli test --fast -w 4         # four workers
+tempest-cli test tests/unit --fast   # the target is still forwarded
+tempest-cli check --fast             # the full gate, with the test step in parallel
+```
+
+Underneath it becomes `pytest -n <workers> -p no:cacheprovider [target]`.
+`-p no:cacheprovider` is there because several workers writing
+`.pytest_cache` at once is a race that buys nothing — and that cache is
+what `--lf` / `--ff` read, so those two remain a serial-run affair.
+
+`--workers` (`-w`) takes what `pytest -n` takes: an integer, `auto` (the
+default) or `logical`. Without `--fast` it is a usage error (exit 2)
+instead of being silently ignored.
+
+!!! info "`auto` counts physical cores when `psutil` is installed"
+    pytest-xdist decides: with `psutil` importable, `auto` is the number of
+    **physical** cores; without it, the number of logical CPUs. On a machine
+    with 6 cores and 12 threads, with `psutil` in the environment, `auto`
+    started `created: 6/6 workers`. Want the 12 threads? `-w logical` or
+    `-w 12`.
+
+!!! note "Why a flag, not `tempest-cli test fast`"
+    `test` already takes a positional path. `test fast` keeps meaning
+    "run pytest on the `fast/` folder" — a subcommand by that name would
+    break anyone who has one.
+
+### Without pytest-xdist
+
+Before running anything, the CLI asks **the very interpreter that will
+run pytest** whether it can import `xdist` — not the CLI's own
+interpreter, which under `uv tool install` or pipx lives in a different
+environment. When it is missing, the message names what to install and
+the exit code is **127**, with no traceback:
+
+```console
+$ tempest-cli test --fast
+error: --fast needs pytest-xdist, which is not installed in the environment pytest runs in (.venv/bin/pytest). Install it with 'uv add --dev pytest-xdist' — or a bundle that carries it, 'uv add --dev "tempest-cli[tools]"' or 'uv add --dev "tempest-fastapi-sdk[tests]"' — and retry, or drop --fast to run the suite serially.
+$ echo $?
+127
+```
+
+Under `check --fast` the check happens **before** the first step: there
+is no point waiting for lint and mypy to finish to learn the tests will
+not run.
+
+### A test that fails only in parallel
+
+Parallelism exposes tests that depend on order or on an idle machine:
+two tests writing the same file, the same port, a module-level global, a
+fixed `sleep` waiting for something that takes longer once every core is
+busy. Before treating the failure as a regression, run the test **alone
+and serially**:
+
+```bash
+tempest-cli test "tests/test_scheduler.py::test_lease_expires"
+```
+
+- **It passes alone**: the defect is the test's isolation, not the change
+  under review. Fix the test (a file under `tmp_path`, a free port, wait
+  on a condition instead of a `sleep`).
+- **It fails alone too**: it is a real regression.
+
+## What each returns
+
+The exit code is the tool's own, untranslated:
+
+```bash
+tempest-cli lint; echo "exited $?"
+```
+
+There is exactly one code of its own: **127**, when the tool is in none
+of the places the CLI looks — the run's environment, `PATH`, `uv run
+--with` — and the message then names what was missing and how to install
+it. The lookup order is in
+[Installation](installation.md#where-ruff-mypy-and-pytest-come-from).
+The same 127 comes out of `--fast` when pytest-xdist is not in pytest's
+environment.
+
+## Recap
+
+- `check` is lint + fmt-check + type + test, in order, stopping at the
+  first failure.
+- `fix` is the pass that repairs; `--unsafe` only when you will review.
+- `test --fast` / `check --fast` run the suite with pytest-xdist
+  (`-n auto`, `-w N` to choose); a test that fails only in parallel is
+  checked by running it alone.
+- Exit codes are the tools'; 127 means a missing tool (or the
+  pytest-xdist `--fast` needs).