tempest-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{tempest_cli-0.5.0 → tempest_cli-0.6.0}/CHANGELOG.md

@@ -5,6 +5,58 @@ 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).
 
+## [Unreleased]
+
+## [0.6.0] — 2026-10-20
+
+### Changed
+
+- **`test` and `check` run the suite in parallel by default.** The
+  pytest-xdist run that needed `--fast` (`-n auto -p no:cacheprovider`) is
+  now what a bare `tempest-cli test` does; `--serial` opts out (for
+  `--lf` / `--ff`, or a debugger), and `--workers` tunes the default
+  without a flag. Measured on a FastAPI service suite of 1136 tests on a
+  12-CPU machine: 262 s serially, 37.6 s in parallel, same outcome.
+- **Without pytest-xdist the default degrades instead of failing.** When
+  the environment pytest runs in cannot import it, a bare `test` / `check`
+  prints a one-line notice naming the install command and runs the suite
+  serially (exit code is pytest's); an explicit `--fast` keeps the old
+  behavior — the fix is printed and the exit code is 127, nothing runs.
+  `run_pytest` / `run_full_check` take `require_xdist=` (default `True`,
+  the old library behavior) to pick between the two.
+- `--workers` with `--serial` is a usage error (exit 2), as `--workers`
+  without `--fast` used to be.
+
+## [0.5.1] — 2026-10-15
+
+### Fixed
+
+- **`fix` explains the E501 the formatter cannot resolve.** A line still
+  too long after `ruff format` is one the formatter has nowhere to break
+  — a dotted name (it never splits one, and drops parentheses that do not
+  make the line fit), a string literal, a comment — but the bare
+  `Line too long (94 > 79)` read as if `line-length` were being ignored.
+  `fix` now reads ruff's JSON report of the leftovers and names each such
+  line with the overflowing token, its kind and the action that does
+  resolve it, then splits the residual violations into those with no
+  autofix and those `fix --unsafe` would fix. The exit code is unchanged:
+  CI still fails on them. Closes #3.
+- **`fix` shortens the long comments and strings the formatter leaves
+  alone.** After `ruff format`, each E501 that is a comment is wrapped at
+  the limit (a trailing one moves above its line) and each that is a
+  plain string literal is split at its spaces into implicitly
+  concatenated parts inside parentheses; the touched files are formatted
+  again. Every edit is kept only when the file's AST is identical before
+  and after, so the program cannot change. Tool pragmas (`noqa`,
+  `type: ignore`, `fmt:`, …), f-strings, triple-quoted strings and words
+  longer than a line are left alone and explained instead. On by
+  default: neither rewrite changes behavior.
+- **`fix` reports on the formatted file.** The passes are now
+  `ruff check --fix-only`, `ruff format`, then `ruff check`; before, the
+  report and the exit code came from the lint pass that ran *before* the
+  formatter, so a violation the formatter went on to resolve still showed
+  up and still failed the command.
+
 ## [0.5.0] — 2026-10-13
 
 ### Added

{tempest_cli-0.5.0 → tempest_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.5.0
+Version: 0.6.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
@@ -70,12 +70,12 @@ remembered to pass.
 | Command | Runs |
 | --- | --- |
 | `tempest-cli lint` | `ruff check` |
-| `tempest-cli fix` | `ruff check --fix` then `ruff format` (`--unsafe` for the risky autofixes) |
+| `tempest-cli fix` | `ruff check --fix-only`, `ruff format`, wraps long comments and splits long strings the formatter leaves alone, then a final `ruff check` that explains what is left (`--unsafe` for the risky autofixes) |
 | `tempest-cli format` | `ruff format` (writes) |
 | `tempest-cli fmt-check` | `ruff format --check` (read-only) |
 | `tempest-cli type` | `mypy` |
-| `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; a host CLI can add steps between `mypy` and `pytest`) |
+| `tempest-cli test` | `pytest`, in parallel by default with pytest-xdist (`-n auto -p no:cacheprovider`, `-w N` to choose; serial with a notice when it is not installed; `--serial` opts out) |
+| `tempest-cli check` | all four, in order, stopping at the first failure (the test step in parallel as in `test`; a host CLI can add steps between `mypy` and `pytest`) |
 | `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
@@ -188,7 +188,8 @@ your suite. Add them yourself, or take the bundle:
 uv add --dev "tempest-cli[tools]"   # mypy + pytest + pytest-xdist
 ```
 
-`pytest-xdist` is what `test --fast` runs the suite with; its
+`pytest-xdist` is what `test` runs the suite in parallel with, by
+default (without it the suite runs serially, with a notice); 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

{tempest_cli-0.5.0 → tempest_cli-0.6.0}/README.md

@@ -38,12 +38,12 @@ remembered to pass.
 | Command | Runs |
 | --- | --- |
 | `tempest-cli lint` | `ruff check` |
-| `tempest-cli fix` | `ruff check --fix` then `ruff format` (`--unsafe` for the risky autofixes) |
+| `tempest-cli fix` | `ruff check --fix-only`, `ruff format`, wraps long comments and splits long strings the formatter leaves alone, then a final `ruff check` that explains what is left (`--unsafe` for the risky autofixes) |
 | `tempest-cli format` | `ruff format` (writes) |
 | `tempest-cli fmt-check` | `ruff format --check` (read-only) |
 | `tempest-cli type` | `mypy` |
-| `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; a host CLI can add steps between `mypy` and `pytest`) |
+| `tempest-cli test` | `pytest`, in parallel by default with pytest-xdist (`-n auto -p no:cacheprovider`, `-w N` to choose; serial with a notice when it is not installed; `--serial` opts out) |
+| `tempest-cli check` | all four, in order, stopping at the first failure (the test step in parallel as in `test`; a host CLI can add steps between `mypy` and `pytest`) |
 | `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
@@ -156,7 +156,8 @@ your suite. Add them yourself, or take the bundle:
 uv add --dev "tempest-cli[tools]"   # mypy + pytest + pytest-xdist
 ```
 
-`pytest-xdist` is what `test --fast` runs the suite with; its
+`pytest-xdist` is what `test` runs the suite in parallel with, by
+default (without it the suite runs serially, with a notice); 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

{tempest_cli-0.5.0 → tempest_cli-0.6.0}/docs/changelog.en.md

@@ -3,6 +3,41 @@
 The full history lives in the repository's
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md).
 
+## [0.6.0] — 2026-10-20
+
+### Changed
+
+- **`test` and `check` run the suite in parallel by default.** The
+  pytest-xdist `-n auto` run that needed `--fast` is now what a bare
+  `test` does; `--serial` opts out (for `--lf` / `--ff`, or a debugger).
+  Measured on a FastAPI suite of 1136 tests on 12 CPUs: 262 s serially,
+  37.6 s in parallel, same outcome.
+  [Details](commands.md#the-suite-in-parallel-the-default).
+- **Without pytest-xdist the default degrades to serial instead of
+  failing**, with a notice naming the install command; only an explicit
+  `--fast` still requires the plugin (exit code 127).
+- `--workers` with `--serial` is a usage error (exit code 2).
+
+## [0.5.1] — 2026-10-15
+
+### Fixed
+
+- **`fix` explains the E501 the formatter cannot resolve.** A line still
+  too long after `ruff format` (a dotted name, a string, a comment) comes
+  out with its token, its kind and the action that resolves it, and the
+  summary separates what has no autofix from what `--unsafe` would fix.
+  The exit code is unchanged.
+  [Details](commands.md#an-e501-ruff-format-cannot-fix).
+- **`fix` shortens the long comments and strings the formatter leaves
+  alone.** A comment is wrapped at the limit and a string is split into
+  concatenated parts; each edit is kept only when the file's AST is
+  identical before and after. Pragmas, f-strings, triple quotes and long
+  words are left out and explained. On by default.
+- **`fix` reports on the formatted file.** The passes are now
+  `ruff check --fix-only`, `ruff format` and `ruff check`; before, the
+  report and the exit code came from the pass that ran before the
+  formatter.
+
 ## [0.5.0] — 2026-10-13
 
 ### Added
@@ -26,7 +61,7 @@ The full history lives in the repository's
   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).
+  `fast/` folder. [Details](commands.md#the-suite-in-parallel-the-default).
 - **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

{tempest_cli-0.5.0 → tempest_cli-0.6.0}/docs/changelog.md

@@ -4,6 +4,39 @@ O histórico completo vive no
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md)
 do repositório.
 
+## [0.6.0] — 2026-10-20
+
+### Alterado
+
+- **O `test` e o `check` rodam a suíte em paralelo por padrão.** O
+  `-n auto` do pytest-xdist, que pedia `--fast`, agora é o que um
+  `test` puro faz; `--serial` desliga (para `--lf` / `--ff` ou depurador).
+  Medido numa suíte FastAPI de 1136 testes em 12 CPUs: 262 s em série,
+  37,6 s em paralelo, mesmo resultado.
+  [Detalhes](commands.md#a-suite-em-paralelo-o-padrao).
+- **Sem o pytest-xdist, o padrão cai para série em vez de falhar**, com um
+  aviso de como instalar; só o `--fast` explícito continua exigindo o
+  plugin (código de saída 127).
+- `--workers` com `--serial` é erro de uso (código de saída 2).
+
+## [0.5.1] — 2026-10-15
+
+### Corrigido
+
+- **O `fix` explica o E501 que o formatador não resolve.** Linha ainda
+  longa depois do `ruff format` (nome pontuado, string, comentário) sai
+  com o token, o tipo e a ação que resolve, e o resumo separa o que não
+  tem autofix do que o `--unsafe` resolveria. O código de saída não muda.
+  [Detalhes](commands.md#e501-que-o-ruff-format-nao-resolve).
+- **O `fix` encurta comentário e string longos que o formatador não
+  quebra.** Comentário é quebrado no limite e string é partida em pedaços
+  concatenados; cada edição só fica se a AST do arquivo for idêntica
+  antes e depois. Pragma, f-string, três aspas e palavra longa ficam de
+  fora e são explicados. Ligado por padrão.
+- **O `fix` relata sobre o arquivo formatado.** As passadas agora são
+  `ruff check --fix-only`, `ruff format` e `ruff check`; antes, o
+  relatório e o código de saída vinham da passada anterior ao formatador.
+
 ## [0.5.0] — 2026-10-13
 
 ### Adicionado
@@ -27,7 +60,7 @@ do repositório.
   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).
+  `fast/`. [Detalhes](commands.md#a-suite-em-paralelo-o-padrao).
 - **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-0.6.0/docs/commands.en.md

@@ -0,0 +1,303 @@
+# 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-only`, `ruff format`, shortens long comments/strings, then a final `ruff check` explaining what is left |
+| `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 (a CLI that mounts the gate can [add steps](library.md#adding-steps-to-check) between `mypy` and `pytest`) |
+| `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 four passes:
+
+1. `ruff check --fix-only` — sorts and dedupes imports, drops unused
+   ones, normalizes quotes.
+2. `ruff format` — indentation, line length, blank lines.
+3. Shortens the long lines the formatter cannot break, when that can be
+   done without changing the program: comments and strings (see below).
+4. `ruff check` — the report of what is left, on the final file.
+
+The exit code is the last pass's: anything left, `fix` exits with an
+error and CI fails.
+
+!!! 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.
+
+### An E501 `ruff format` cannot fix
+
+Sometimes `fix` ends like this, even with the right `line-length` in
+`pyproject.toml`:
+
+```python
+class AloController:
+    def template(self, kind: str) -> str:
+        match kind:
+            case "waiting":
+                user_template = notifications.NOTIFICATION_USER_BODY_ALO_STATUS_CHANGE_WAITING
+                return user_template
+        return ""
+```
+
+```text
+E501 Line too long (94 > 79)
+  --> controller.py:5:80
+```
+
+It is not a wrong setting — `fix` passes no `line-length` to ruff, the
+project's value already applies. It is a limit of the formatter: it
+**never splits a dotted name** (`a.b.C`), and the parentheses you put
+around it (`x = (\n    a.b.C\n)`) go away, because they do not make the
+line fit. 🤷
+
+#### What `fix` shortens on its own
+
+Two of these cases have a single right answer, and `fix` applies it:
+
+- a **comment** is wrapped at the limit; a trailing one moves above the
+  code it annotates;
+- a **string** is split at its spaces into concatenated parts inside
+  parentheses — Python joins them back into the same value.
+
+```python
+# before
+    text = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb"  # the text
+
+# after fix
+    # the text
+    text = (
+        "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa "
+        "bbbbbbbbbbbbbbbb"
+    )
+```
+
+```text
+shortened 1 long line(s) ruff format cannot break (comments wrapped, strings split into concatenated parts):
+  mod.py:2 [comment+string]
+```
+
+!!! check "Only what is proven equal goes in"
+    Before writing, `fix` compares the file's AST before and after.
+    Comments never reach the AST and the parser folds concatenated
+    strings into one constant, so a correct rewrite always passes.
+    Anything else — a `\N{...}` cut in half, a comment pushed into a
+    `\` continuation — changes the AST, and the line stays as it was.
+
+Left out on purpose: tool comments (`noqa`, `type: ignore`, `fmt:`,
+`pragma`…), which must stay on the line they govern; f-strings and
+triple-quoted strings; and a word longer than a line (a URL, say).
+
+#### What is left
+
+Dotted names, long names and expressions have no mechanical rewrite —
+and splitting them by hand is undone by the next `ruff format`. For
+those, `fix` explains each line right below ruff's report:
+
+```text
+1 line(s) still too long after ruff format — the line-length setting was applied; the formatter has nowhere to break these:
+  controller.py:5 [dotted-name] `notifications.NOTIFICATION_USER_BODY_ALO_STATUS_CHANGE_WAITING`
+    ruff format never splits a dotted name, and drops parentheses that do not make the line fit. Shorten the expression: import or alias the attribute, move the choice into a table or constant, or lower the indentation.
+1 residual violation(s): 1 with no autofix (edit by hand).
+```
+
+The bracketed label says what sits where the line crosses the limit:
+
+| Label | What it is | What resolves it |
+| --- | --- | --- |
+| `dotted-name` | a dotted name (`module.CONSTANT`) | an alias, a table/constant, less indentation |
+| `name` | one name that is too long on its own | rename it or indent less |
+| `string` | a string `fix` could not split (f-string, triple quotes, long word) | split it by hand into concatenated parts |
+| `comment` | a comment `fix` could not wrap (pragma, long word) | wrap it by hand or move it into the docstring |
+| `expression` | anything else | extract a variable or indent less |
+
+The last line separates what has **no autofix** from what `fix --unsafe`
+would resolve — without it, `Found 5 errors` does not say whether
+another run is worth it.
+
+!!! tip "Move the choice into a table"
+    In the example above, the indentation comes from the `match`.
+    Replacing it with a module-level dictionary removes four levels and
+    the line fits in exactly 79, without an alias:
+
+    ```python
+    import notifications
+
+    TEMPLATES: dict[str, str] = {
+        "waiting": notifications.NOTIFICATION_USER_BODY_ALO_STATUS_CHANGE_WAITING,
+    }
+
+
+    class AloController:
+        def template(self, kind: str) -> str:
+            return TEMPLATES.get(kind, "")
+    ```
+
+!!! note "What about `# noqa: E501`?"
+    It works, but hides the problem until the next refactor drops the
+    `noqa` — which is exactly how this case showed up. Prefer changing
+    the shape of the code.
+
+## 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 (the default)
+
+A suite whose tests are already isolated (a database per test, no global
+state) pays the serial time and buys nothing for it. That is why `test`
+and `check` spread the suite across cores with
+[pytest-xdist](https://pytest-xdist.readthedocs.io/) **without being
+asked**:
+
+```bash
+tempest-cli test                     # -n auto: one worker per core
+tempest-cli test -w 4                # four workers
+tempest-cli test tests/unit          # the target is still forwarded
+tempest-cli check                    # the full gate, with the test step in parallel
+tempest-cli test --serial            # a single process (for --lf / --ff, or a debugger)
+```
+
+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 are a `--serial` affair.
+
+On a FastAPI service suite of 1136 tests (an in-memory SQLite database
+per test), on a 12-CPU machine: **262 s** serially, **37.6 s** with
+`-n auto` — same outcome, 1136 passed.
+
+`--workers` (`-w`) takes what `pytest -n` takes: an integer, `auto` (the
+default) or `logical`. With `--serial` 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
+    6-core, 12-thread machine with `psutil` in the environment, `auto`
+    reported `created: 6/6 workers`. Want the 12 threads? `-w logical` or
+    `-w 12`.
+
+!!! note "Why a flag, and not `tempest-cli test serial`"
+    `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 that folder.
+
+### 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 another
+environment. When it is missing, it depends on who asked for parallel:
+
+- **Nobody (the default):** the suite runs serially, with a notice on
+  stderr naming what to install. `tempest-cli test` keeps working in a
+  project that never installed pytest-xdist — it is just slower.
+
+    ```console
+    $ tempest-cli test
+    note: pytest-xdist is not installed in the environment pytest runs in (.venv/bin/pytest), so the suite runs serially. 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]"' — to run it in parallel.
+    ```
+
+- **`--fast` by name:** parallel becomes a requirement. The message names
+  what to install and the exit code is **127**, with nothing run:
+
+    ```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 pass --serial to run the suite serially.
+    $ echo $?
+    127
+    ```
+
+Under `check` the probe happens **before** the first step: with `--fast`
+there is no point waiting for lint and mypy to finish only 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 with every core
+busy. Before treating the failure as a regression, run the test **alone
+and serially**:
+
+```bash
+tempest-cli test --serial "tests/test_scheduler.py::test_lease_expires"
+```
+
+- **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 `sleep`).
+- **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 an explicit `--fast` when pytest-xdist is not in
+pytest's environment; without the flag, its absence only makes the suite
+serial.
+
+## 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.
+- Long comments and strings `fix` shortens on its own, with the AST
+  proven equal. An E501 left after it has no mechanical rewrite: `fix`
+  names the token and the action — change the code's shape.
+- `test` and `check` run the suite in parallel by default, with
+  pytest-xdist (`-n auto`, `-w N` to choose); `--serial` turns it off.
+  Without pytest-xdist the default falls back to serial with a notice,
+  and an explicit `--fast` becomes exit 127. A test that fails only in
+  parallel is checked by running it alone, with `--serial`.
+- Exit codes are the tools'; 127 means a missing tool (or the
+  pytest-xdist an explicit `--fast` requires).