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

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

@@ -5,6 +5,55 @@ 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.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
+
+- **`extra_steps`: a framework's own rules inside `check`.** The new
+  `CheckStep(name, run)` (frozen dataclass, exported from `tempest_cli`)
+  is a step `check` runs after `mypy` and before `pytest`: `run` receives
+  the `check` target and returns an exit code. `run_full_check(...,
+  extra_steps=)` and `register_commands(app, *, extra_steps=)` take a
+  sequence of them — keyword-only, empty by default, so every existing
+  call runs the same four steps as before. Each extra step is echoed as
+  `$ <name>` on stderr, runs in list order, and the first non-zero code
+  stops the gate and becomes its exit code, with or without `--fast`.
+  They sit before `pytest` because they are static checks that should
+  fail in a second, not after the suite. Requested in
+  mauriciobenjamin700/tempest-fastapi-sdk#520, where the SDK adds its
+  service-layer rules to `tempest check` without this package learning
+  about any framework.
+
 ## [0.4.0] — 2026-09-27
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.4.0
+Version: 0.5.1
 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) |
+| `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 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
@@ -150,6 +150,28 @@ cli: typer.Typer = typer.Typer(name="mytool")
 register_commands(cli)
 ```
 
+A framework that wants its own rules in `check` passes them as
+`CheckStep`s — they run after `mypy` and before `pytest`, and the first
+non-zero exit code stops the gate:
+
+```python
+import typer
+
+from tempest_cli import CheckStep
+from tempest_cli.main import register_commands
+
+
+def layers(target: str) -> int:
+    """Return 0 when every module under ``target`` follows the layering."""
+    return 0
+
+
+cli: typer.Typer = typer.Typer(name="mytool")
+register_commands(cli, extra_steps=[CheckStep(name="layers", run=layers)])
+```
+
+`run_full_check(".", extra_steps=[...])` takes the same list.
+
 ## Where the tools come from
 
 **`ruff` comes with the package** — six of the eight commands are ruff,

{tempest_cli-0.4.0 → tempest_cli-0.5.1}/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) |
+| `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 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
@@ -118,6 +118,28 @@ cli: typer.Typer = typer.Typer(name="mytool")
 register_commands(cli)
 ```
 
+A framework that wants its own rules in `check` passes them as
+`CheckStep`s — they run after `mypy` and before `pytest`, and the first
+non-zero exit code stops the gate:
+
+```python
+import typer
+
+from tempest_cli import CheckStep
+from tempest_cli.main import register_commands
+
+
+def layers(target: str) -> int:
+    """Return 0 when every module under ``target`` follows the layering."""
+    return 0
+
+
+cli: typer.Typer = typer.Typer(name="mytool")
+register_commands(cli, extra_steps=[CheckStep(name="layers", run=layers)])
+```
+
+`run_full_check(".", extra_steps=[...])` takes the same list.
+
 ## Where the tools come from
 
 **`ruff` comes with the package** — six of the eight commands are ruff,

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

@@ -3,6 +3,39 @@
 The full history lives in the repository's
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md).
 
+## [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
+
+- **`extra_steps`: a framework's own rules inside `check`.** The new
+  `CheckStep(name, run)` is a step `check` runs after `mypy` and before
+  `pytest`; `run` receives the target and returns an exit code.
+  `run_full_check(..., extra_steps=)` and
+  `register_commands(app, *, extra_steps=)` take the list — empty by
+  default, so nothing changes for a caller that does not pass one. The
+  first non-zero code stops the gate, with or without `--fast`.
+  [Details](library.md#adding-steps-to-check).
+
 ## [0.4.0] — 2026-09-27
 
 ### Added

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

@@ -4,6 +4,37 @@ O histórico completo vive no
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md)
 do repositório.
 
+## [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
+
+- **`extra_steps`: regras do framework dentro do `check`.** O novo
+  `CheckStep(name, run)` é um passo que o `check` roda depois do `mypy` e
+  antes do `pytest`; `run` recebe o alvo e devolve um código de saída.
+  `run_full_check(..., extra_steps=)` e
+  `register_commands(app, *, extra_steps=)` aceitam a lista — vazia por
+  padrão, então nada muda para quem não passa. O primeiro código diferente
+  de `0` para o gate, com ou sem `--fast`.
+  [Detalhes](library.md#acrescentar-passos-ao-check).
+
 ## [0.4.0] — 2026-09-27
 
 ### Adicionado

{tempest_cli-0.4.0 → tempest_cli-0.5.1}/docs/commands.en.md

@@ -6,12 +6,12 @@ tool's exit code.
 | Command | Runs |
 | --- | --- |
 | `lint` | `ruff check` |
-| `fix` | `ruff check --fix` then `ruff format` |
+| `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 |
+| `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"
@@ -39,15 +39,136 @@ 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).
+`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
@@ -152,6 +273,9 @@ environment.
 - `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 --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.

{tempest_cli-0.4.0 → tempest_cli-0.5.1}/docs/commands.md

@@ -6,12 +6,12 @@ saída da ferramenta por baixo.
 | Comando | Roda |
 | --- | --- |
 | `lint` | `ruff check` |
-| `fix` | `ruff check --fix` e depois `ruff format` |
+| `fix` | `ruff check --fix-only`, `ruff format`, encurta comentário/string longos e um `ruff check` final que explica o que sobrou |
 | `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 |
+| `check` | os quatro acima, em ordem, parando na primeira falha (uma CLI que monta o gate pode [acrescentar passos](library.md#acrescentar-passos-ao-check) entre o `mypy` e o `pytest`) |
 | `pr-prompt` | monta o prompt da descrição do PR — [página própria](pr-prompt.md) |
 
 !!! tip "`tc` é a forma curta"
@@ -39,15 +39,136 @@ 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).
+O `fix` faz quatro passadas:
+
+1. `ruff check --fix-only` — ordena e deduplica imports, remove imports
+   não usados, normaliza aspas.
+2. `ruff format` — indentação, comprimento de linha, linhas em branco.
+3. Encurta as linhas longas que o formatador não quebra, quando dá para
+   fazer isso sem mudar o programa: comentários e strings (veja abaixo).
+4. `ruff check` — o relatório do que sobrou, já sobre o arquivo final.
+
+O código de saída é o da última passada: sobrou violação, o `fix` sai
+com erro e o CI falha.
 
 !!! 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.
 
+### E501 que o `ruff format` não resolve
+
+Às vezes o `fix` termina assim, mesmo com o `line-length` certo no
+`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
+```
+
+Não é configuração errada — o `fix` não passa `line-length` nenhum ao
+ruff, o valor do projeto já vale. É limite do formatador: ele **não
+divide um nome pontuado** (`a.b.C`), e o parêntese que você pôs em volta
+(`x = (\n    a.b.C\n)`) some, porque não faz a linha caber. 🤷
+
+#### O que o `fix` encurta sozinho
+
+Dois desses casos têm uma única resposta certa, e o `fix` aplica:
+
+- **comentário** é quebrado no limite; comentário no fim da linha sobe
+  para cima do código que ele comenta;
+- **string** é partida nos espaços em pedaços concatenados entre
+  parênteses — o Python junta tudo de volta no mesmo valor.
+
+```python
+# antes
+    text = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbb"  # o texto
+
+# depois do fix
+    # o texto
+    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 "Só entra o que é provado igual"
+    Antes de gravar, o `fix` compara a AST do arquivo antes e depois.
+    Comentário não entra na AST e o parser junta string concatenada numa
+    constante só, então uma reescrita certa sempre passa. Qualquer outra
+    coisa — um `\N{...}` cortado no meio, comentário empurrado para
+    dentro de uma continuação com `\` — muda a AST, e a linha fica como
+    estava.
+
+Fica de fora, de propósito: comentário de ferramenta (`noqa`,
+`type: ignore`, `fmt:`, `pragma`…), que precisa ficar na linha que
+governa; f-string e string com três aspas; e palavra mais longa que uma
+linha (URL, por exemplo).
+
+#### O que sobra
+
+Nome pontuado, nome longo e expressão não têm reescrita mecânica — e
+quebrá-los à mão é desfeito pelo próximo `ruff format`. Para esses, o
+`fix` explica cada linha logo abaixo do relatório do ruff:
+
+```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).
+```
+
+O rótulo entre colchetes diz o que está no ponto onde a linha estoura:
+
+| Rótulo | O que é | O que resolve |
+| --- | --- | --- |
+| `dotted-name` | nome pontuado (`modulo.CONSTANTE`) | alias, tabela/constante, indentação menor |
+| `name` | um nome sozinho longo demais | renomear ou indentar menos |
+| `string` | string que o `fix` não pôde partir (f-string, três aspas, palavra longa) | partir à mão em pedaços concatenados |
+| `comment` | comentário que o `fix` não pôde quebrar (pragma, palavra longa) | quebrar à mão ou levar para a docstring |
+| `expression` | qualquer outra coisa | extrair variável ou indentar menos |
+
+A última linha separa o que **não tem autofix** do que o `fix --unsafe`
+resolveria — sem ela, `Found 5 errors` não diz se vale rodar de novo.
+
+!!! tip "Leve a escolha para uma tabela"
+    No exemplo acima, a indentação vem do `match`. Trocar o `match` por
+    um dicionário no nível do módulo tira quatro níveis e a linha cabe
+    exatamente em 79, sem 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 "E o `# noqa: E501`?"
+    Funciona, mas esconde o problema até o próximo refactor tirar o
+    `noqa` — que foi exatamente como esse caso apareceu. Prefira mudar a
+    forma do código.
+
 ## Um comando por vez
 
 ```bash
@@ -149,6 +270,9 @@ pytest.
 - `check` é lint + fmt-check + type + test, nessa ordem, parando na
   primeira falha.
 - `fix` é a passada que conserta; `--unsafe` só quando você for revisar.
+- Comentário e string longos o `fix` encurta sozinho, com a AST provada
+  igual. O E501 que sobra é linha sem reescrita mecânica: o `fix` diz o
+  token e a ação — mude a forma do código.
 - `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.