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

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

@@ -5,6 +5,59 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.3.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
@@ -26,6 +26,7 @@ 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'
 Description-Content-Type: text/markdown
 
@@ -73,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
@@ -104,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
@@ -155,9 +163,12 @@ 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:
 

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

@@ -42,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
@@ -73,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
@@ -124,9 +131,12 @@ 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:
 

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

@@ -3,6 +3,31 @@
 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

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

@@ -4,6 +4,30 @@ 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

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).

tempest_cli-0.4.0/docs/commands.md

@@ -0,0 +1,156 @@
+# Comandos
+
+Oito comandos. Todos aceitam um caminho opcional e devolvem o código de
+saída da ferramenta por baixo.
+
+| Comando | Roda |
+| --- | --- |
+| `lint` | `ruff check` |
+| `fix` | `ruff check --fix` e depois `ruff format` |
+| `format` | `ruff format` (escreve) |
+| `fmt-check` | `ruff format --check` (só leitura) |
+| `type` | `mypy` |
+| `test` | `pytest` |
+| `check` | os quatro acima, em ordem, parando na primeira falha |
+| `pr-prompt` | monta o prompt da descrição do PR — [página própria](pr-prompt.md) |
+
+!!! tip "`tc` é a forma curta"
+    O pacote instala `tempest-cli` e `tc` apontando para o mesmo
+    programa. Os exemplos usam o nome longo; `tc check`, `tc fix` e
+    `tc type -s strict` funcionam igual.
+
+## O gate completo
+
+```bash
+tempest-cli check              # o projeto todo
+tempest-cli check src/         # só um caminho
+tempest-cli check -s strict    # com rigor de tipagem elevado nesta execução
+```
+
+A ordem é deliberada: **lint → formatação → tipos → testes**. O que falha
+mais rápido e é mais barato de corrigir vem primeiro, e a execução para
+na primeira falha — não adianta rodar a suíte inteira se o import está
+desordenado.
+
+## Corrigindo o que dá para corrigir
+
+```bash
+tempest-cli fix                # autofixes seguros + formatação
+tempest-cli fix --unsafe       # inclui os autofixes de risco do ruff
+```
+
+O `fix` faz duas passadas: `ruff check --fix` (ordena e deduplica
+imports, remove imports não usados, normaliza aspas) e depois `ruff
+format` (indentação, comprimento de linha, linhas em branco).
+
+!!! warning "`--unsafe` muda comportamento"
+    Os autofixes "unsafe" do ruff são os que podem alterar semântica.
+    Ficam desligados por padrão. Ligou? Leia o `git diff` antes de
+    commitar.
+
+## Um comando por vez
+
+```bash
+tempest-cli lint src/
+tempest-cli fmt-check
+tempest-cli type meupacote
+tempest-cli test tests/unit
+```
+
+`test` repassa o caminho ao pytest como filtro; sem argumento, roda a
+suíte inteira.
+
+## A suíte em paralelo: `--fast`
+
+Suíte cujos testes já são isolados (banco por teste, nada de estado
+global) paga o tempo serial sem comprar nada. `--fast` espalha a suíte
+pelos núcleos com o [pytest-xdist](https://pytest-xdist.readthedocs.io/):
+
+```bash
+tempest-cli test --fast              # -n auto: um worker por núcleo
+tempest-cli test --fast -w 4         # quatro workers
+tempest-cli test tests/unit --fast   # o alvo continua sendo repassado
+tempest-cli check --fast             # o gate completo, com o passo de teste em paralelo
+```
+
+Por baixo, vira `pytest -n <workers> -p no:cacheprovider [alvo]`. O
+`-p no:cacheprovider` existe porque vários workers escrevendo
+`.pytest_cache` ao mesmo tempo é corrida à toa — e é esse cache que o
+`--lf` / `--ff` leem, então esses dois continuam sendo coisa de execução
+serial.
+
+`--workers` (`-w`) aceita o que o `pytest -n` aceita: um inteiro, `auto`
+(o padrão) ou `logical`. Sem `--fast` ele é erro de uso (saída 2), em vez
+de ser ignorado em silêncio.
+
+!!! info "`auto` conta núcleo físico quando o `psutil` está instalado"
+    É o pytest-xdist que decide: com `psutil` importável, `auto` é o número
+    de núcleos **físicos**; sem ele, o de CPUs lógicas. Numa máquina de 6
+    núcleos e 12 threads, com `psutil` no ambiente, `auto` subiu
+    `created: 6/6 workers`. Quer as 12 threads? `-w logical` ou `-w 12`.
+
+!!! note "Por que flag, e não `tempest-cli test fast`"
+    `test` já recebe um caminho posicional. `test fast` continua
+    significando "rode o pytest na pasta `fast/`" — um subcomando com esse
+    nome quebraria quem tem essa pasta.
+
+### Sem o pytest-xdist
+
+Antes de rodar qualquer coisa, a CLI pergunta ao **mesmo interpretador
+que vai rodar o pytest** se ele importa o `xdist` — não ao interpretador
+da própria CLI, que sob `uv tool install` ou pipx mora em outro ambiente.
+Faltou, a mensagem diz o que instalar e a saída é **127**, sem 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
+```
+
+No `check --fast` essa checagem acontece **antes** do primeiro passo:
+não adianta esperar lint e mypy terminarem para descobrir que o teste
+não vai rodar.
+
+### Teste que só falha em paralelo
+
+O paralelismo expõe teste que depende de ordem ou de máquina ociosa:
+dois testes escrevendo o mesmo arquivo, a mesma porta, um global de
+módulo, um `sleep` fixo esperando algo que, com os núcleos ocupados,
+demora mais. Antes de tratar a falha como regressão, rode o teste
+**sozinho e em série**:
+
+```bash
+tempest-cli test "tests/test_scheduler.py::test_lease_expires"
+```
+
+- **Passou sozinho**: o defeito é o isolamento do teste, não a mudança
+  em revisão. Conserte o teste (arquivo em `tmp_path`, porta livre,
+  espera por condição em vez de `sleep`).
+- **Falhou sozinho também**: é regressão de verdade.
+
+## O que cada um devolve
+
+O código de saída é o da ferramenta, sem tradução:
+
+```bash
+tempest-cli lint; echo "saiu $?"
+```
+
+Só há um código próprio: **127**, quando a ferramenta não está em nenhum
+dos lugares onde a CLI procura — ambiente da execução, `PATH`, `uv run
+--with` — e aí a mensagem diz qual faltou e como instalá-la. A ordem de
+busca está em [Instalação](installation.md#de-onde-vem-o-ruff-o-mypy-e-o-pytest).
+O mesmo 127 sai do `--fast` quando o pytest-xdist não está no ambiente do
+pytest.
+
+## Recap
+
+- `check` é lint + fmt-check + type + test, nessa ordem, parando na
+  primeira falha.
+- `fix` é a passada que conserta; `--unsafe` só quando você for revisar.
+- `test --fast` / `check --fast` rodam a suíte com pytest-xdist
+  (`-n auto`, `-w N` para escolher); teste que só falha em paralelo se
+  confere rodando-o sozinho.
+- Código de saída é o da ferramenta; 127 significa ferramenta (ou o
+  pytest-xdist do `--fast`) ausente.

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/configuration.en.md

@@ -36,6 +36,12 @@ The level **adds** flags on top of what you already configured in
     `ANN002` / `ANN003` (`*args` / `**kwargs`) are left out too: on a
     passthrough wrapper they are noise carrying no information.
 
+!!! tip "And the rules themselves?"
+    This knob only moves typing. Turning any other rule on, off or down
+    — including silencing mypy's complaints about untyped libraries,
+    the ones that make the first run look alarming — belongs to
+    **[Tuning the rules](rules.md)**.
+
 ## Per-run override
 
 ```bash

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/configuration.md

@@ -35,6 +35,12 @@ O nível **soma** flags ao que você já configurou em `[tool.ruff]` e
     `ANN002` / `ANN003` (`*args` / `**kwargs`) também ficam de fora: em
     wrapper de passagem viram ruído sem informação.
 
+!!! tip "E as regras em si?"
+    Este knob só mexe em tipagem. Ligar, desligar e afrouxar qualquer
+    outra regra — inclusive calar as reclamações do mypy sobre
+    bibliotecas sem tipos, que assustam na primeira execução — é
+    assunto de **[Ajustando as regras](rules.md)**.
+
 ## Override por execução
 
 ```bash

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/index.en.md

@@ -55,6 +55,9 @@ into a versioned value rather than a flag someone remembered to pass.
 - **[Commands »](commands.md)** — all eight, what each runs and returns.
 - **[Typing strictness »](configuration.md)** — the three levels, what
   each adds, and why `ANN401` is never enabled.
+- **[Tuning the rules »](rules.md)** — turning rules on, off and down
+  from `pyproject.toml`; the recipe that makes a legacy Django project
+  green.
 - **[PR descriptions »](pr-prompt.md)** — the prompt that makes an AI
   write the PR description from the branch's own diff.
 - **[Use as a library »](library.md)** — calling the runners from your

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/index.md

@@ -56,6 +56,9 @@ cobra" num valor versionado, não numa flag que alguém lembrou de passar.
   devolve.
 - **[Rigor de tipagem »](configuration.md)** — os três níveis, o que
   cada um acrescenta e por que `ANN401` nunca entra.
+- **[Ajustando as regras »](rules.md)** — ligar, desligar e afrouxar
+  regra pelo `pyproject.toml`; a receita que deixa um Django legado
+  verde.
 - **[Descrições de PR »](pr-prompt.md)** — o prompt que faz uma IA
   escrever a descrição do PR a partir do diff da branch.
 - **[Usar como biblioteca »](library.md)** — chamar os runners do seu

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/installation.en.md

@@ -42,9 +42,14 @@ suite — those versions are the project's call. Add them yourself, or
 take the bundle:
 
 ```bash
-uv add --dev "tempest-cli[tools]"   # mypy + pytest
+uv add --dev "tempest-cli[tools]"   # mypy + pytest + pytest-xdist
 ```
 
+`pytest-xdist` is what [`test --fast`](commands.md#the-suite-in-parallel-fast)
+uses to run the suite in parallel. Its `requires-dist` (`execnet>=2.1`,
+`pytest>=7.0.0`) carries no upper bound, so it tightens nobody's
+resolution.
+
 !!! question "Why ruff is a dependency and the other two are not"
     Six of the eight commands are ruff — a `tempest-cli` without ruff is
     a gate that cannot run. And it costs nothing: ruff is a static

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/installation.md

@@ -43,9 +43,14 @@ e a sua suíte — versão dessas duas é decisão do projeto. Adicione você
 mesmo, ou pegue o pacote pronto:
 
 ```bash
-uv add --dev "tempest-cli[tools]"   # mypy + pytest
+uv add --dev "tempest-cli[tools]"   # mypy + pytest + pytest-xdist
 ```
 
+O `pytest-xdist` é o que o [`test --fast`](commands.md#a-suite-em-paralelo-fast)
+usa para rodar a suíte em paralelo. O `requires-dist` dele
+(`execnet>=2.1`, `pytest>=7.0.0`) não tem teto nenhum, então ele não
+aperta a resolução de ninguém.
+
 !!! question "Por que o ruff é dependência e as outras duas não"
     Seis dos oito comandos são ruff — um `tempest-cli` sem ruff é um
     gate que não roda. E o custo é zero: o ruff é um binário estático,

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/library.en.md

@@ -30,6 +30,7 @@ run_ruff_fix("src", unsafe=False, config=strict)
 run_ruff_format("src", check=True)        # --check: writes nothing
 run_mypy("src", config=strict)
 run_pytest("tests/unit")
+run_pytest("tests/unit", fast=True, workers="4")   # pytest-xdist: -n 4
 ```
 
 `load_tempest_config(start)` walks up from `start` (the cwd by default)

{tempest_cli-0.3.0 → tempest_cli-0.4.0}/docs/library.md

@@ -31,6 +31,7 @@ run_ruff_fix("src", unsafe=False, config=strict)
 run_ruff_format("src", check=True)        # --check: não escreve
 run_mypy("src", config=strict)
 run_pytest("tests/unit")
+run_pytest("tests/unit", fast=True, workers="4")   # pytest-xdist: -n 4
 ```
 
 `load_tempest_config(start)` procura o `pyproject.toml` mais próximo