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

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

@@ -5,6 +5,25 @@ 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.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.4.0
+Version: 0.5.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
@@ -75,7 +75,7 @@ remembered to pass.
 | `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.0}/README.md

@@ -43,7 +43,7 @@ remembered to pass.
 | `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.0}/docs/changelog.en.md

@@ -3,6 +3,19 @@
 The full history lives in the repository's
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md).
 
+## [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.0}/docs/changelog.md

@@ -4,6 +4,19 @@ O histórico completo vive no
 [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md)
 do repositório.
 
+## [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.0}/docs/commands.en.md

@@ -11,7 +11,7 @@ tool's exit code.
 | `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"

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

@@ -11,7 +11,7 @@ saída da ferramenta por baixo.
 | `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"

tempest_cli-0.5.0/docs/library.en.md

@@ -0,0 +1,193 @@
+# Use as a library
+
+Everything the CLI does is importable. Two situations are worth it.
+
+## Calling the runners from your code
+
+```python
+from tempest_cli import load_tempest_config, run_full_check
+
+config = load_tempest_config()
+exit_code = run_full_check(".", config=config)
+```
+
+Each step is callable on its own too, with the same exit-code contract:
+
+```python
+from tempest_cli import (
+    TempestConfig,
+    run_mypy,
+    run_pytest,
+    run_ruff_check,
+    run_ruff_fix,
+    run_ruff_format,
+)
+
+strict = TempestConfig(typing_strictness="strict")
+
+run_ruff_check("src", config=strict)      # ruff check + the level's ANN rules
+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)
+to the nearest `pyproject.toml` and returns the resolved
+`TempestConfig`. `find_pyproject` does the lookup alone, when you want
+the path.
+
+## Mounting the gate on your own CLI
+
+A tool that already has its own CLI can expose these commands under its
+own name — without copying a single command body:
+
+```python
+import typer
+
+from tempest_cli.main import register_commands
+
+cli: typer.Typer = typer.Typer(name="mytool")
+
+
+@cli.command("deploy")
+def deploy() -> None:
+    """A command the tool already had."""
+
+
+register_commands(cli)
+```
+
+Now `mytool check`, `mytool lint` and the rest exist, with the same
+behavior and the same `[tool.tempest]` reading.
+
+!!! info "This is exactly what `tempest-fastapi-sdk` does"
+    The SDK's `tempest check` is this `register_commands` called on its
+    app. That is why the two never diverge: there is one
+    implementation.
+
+## Adding steps to `check`
+
+`tempest-cli` knows nothing about any framework, on purpose. The
+framework does, though: "every service inherits `BaseService`" is a rule
+of whoever lays out the project, not of whoever runs ruff. `CheckStep`
+is the seam — you write the rule, `check` runs it.
+
+A `CheckStep` has two fields: `name`, the label `check` echoes as
+`$ <name>` on stderr, and `run`, a function that takes the `check`
+target (the path from the command line, `.` by default) and returns an
+exit code — `0` means it passed.
+
+```python
+from pathlib import Path
+
+import typer
+
+from tempest_cli import CheckStep
+from tempest_cli.main import register_commands
+
+
+def no_print(target: str) -> int:
+    """Fail when a module under ``target`` calls ``print``."""
+    offenders: list[str] = [
+        f"{path}:{number}: use logging instead of print()"
+        for path in sorted(Path(target).rglob("*.py"))
+        for number, line in enumerate(path.read_text().splitlines(), start=1)
+        if line.lstrip().startswith("print(")
+    ]
+    for offender in offenders:
+        typer.echo(offender, err=True)
+    return 1 if offenders else 0
+
+
+cli: typer.Typer = typer.Typer(name="mytool")
+
+
+@cli.command("deploy")
+def deploy() -> None:
+    """A command the tool already had."""
+
+
+register_commands(cli, extra_steps=[CheckStep(name="no-print", run=no_print)])
+
+if __name__ == "__main__":
+    cli()
+```
+
+With a module `pkg/a.py` that calls `print("x")`:
+
+```console
+$ python mytool.py check pkg
+$ ruff check --extend-select ANN001,ANN201,ANN202,ANN205,ANN206 pkg
+All checks passed!
+$ ruff format --check pkg
+1 file already formatted
+$ mypy --disallow-untyped-defs --disallow-incomplete-defs pkg
+Success: no issues found in 1 source file
+$ no-print
+pkg/a.py:2: use logging instead of print()
+$ echo $?
+1
+```
+
+The order is `ruff check` → `ruff format --check` → `mypy` → the extra
+steps, in list order → `pytest`. An extra step is a static check: it
+sits before the suite so it fails in a second, not after it. The
+contract is the built-in steps' — the first non-zero code stops the gate
+and becomes `check`'s exit code, with or without `--fast`.
+
+!!! tip "The message is yours"
+    `check` only echoes the name. What the step prints is what the user
+    reads, so name the file, the line and the fix — as `no-print` does
+    above.
+
+Without the CLI, the same holds for `run_full_check`:
+
+```python
+from tempest_cli import CheckStep, run_full_check
+
+
+def always_passes(target: str) -> int:
+    """A step that accepts any target."""
+    return 0
+
+
+exit_code: int = run_full_check(
+    ".", extra_steps=[CheckStep(name="always-passes", run=always_passes)]
+)
+```
+
+`extra_steps` is empty by default: without it, the gate is exactly what
+it was.
+
+## Generating the PR prompt without the CLI
+
+```python
+from pathlib import Path
+
+from tempest_cli import PromptLanguage, generate_pr_prompt
+
+prompt, context, template = generate_pr_prompt(
+    base="main",
+    head=None,
+    cwd=Path("."),
+    template=None,
+    language=PromptLanguage.EN_US,
+    max_files=20,
+    max_chars=8000,
+)
+print(len(context.commits), "commits;", template.source)
+```
+
+`generate_pr_prompt` raises `GitError` when git fails or a ref does not
+resolve.
+
+## Recap
+
+- Runners, config and the prompt generator are all importable.
+- `register_commands(app)` mounts the eight commands on any `Typer`.
+- `extra_steps=[CheckStep(...)]` puts your own rules in `check`, after
+  `mypy` and before `pytest`.
+- Exit codes are the tools', identical from the CLI and from a direct
+  call.

tempest_cli-0.5.0/docs/library.md

@@ -0,0 +1,192 @@
+# Usar como biblioteca
+
+Tudo que a CLI faz está importável. Duas situações valem a pena.
+
+## Chamar os runners do seu código
+
+```python
+from tempest_cli import load_tempest_config, run_full_check
+
+config = load_tempest_config()
+exit_code = run_full_check(".", config=config)
+```
+
+Cada etapa também é chamável isolada, com o mesmo contrato de código de
+saída:
+
+```python
+from tempest_cli import (
+    TempestConfig,
+    run_mypy,
+    run_pytest,
+    run_ruff_check,
+    run_ruff_fix,
+    run_ruff_format,
+)
+
+strict = TempestConfig(typing_strictness="strict")
+
+run_ruff_check("src", config=strict)      # ruff check + regras ANN do nível
+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
+subindo a partir de `start` (o cwd por padrão) e devolve o
+`TempestConfig` resolvido. `find_pyproject` faz só a busca, quando você
+quer o caminho.
+
+## Montar o gate na sua própria CLI
+
+Uma ferramenta que já tem CLI própria pode expor estes comandos sob o
+nome dela — sem copiar corpo de comando nenhum:
+
+```python
+import typer
+
+from tempest_cli.main import register_commands
+
+cli: typer.Typer = typer.Typer(name="minhaferramenta")
+
+
+@cli.command("deploy")
+def deploy() -> None:
+    """Um comando que a ferramenta já tinha."""
+
+
+register_commands(cli)
+```
+
+Agora `minhaferramenta check`, `minhaferramenta lint` e os demais
+existem, com o mesmo comportamento e a mesma leitura de
+`[tool.tempest]`.
+
+!!! info "É exatamente o que o `tempest-fastapi-sdk` faz"
+    O `tempest check` do SDK é este `register_commands` chamado no app
+    dele. Por isso os dois nunca divergem: há uma implementação só.
+
+## Acrescentar passos ao `check`
+
+O `tempest-cli` não sabe nada de framework, e é de propósito. Mas o
+framework sabe: "todo service herda `BaseService`" é regra de quem monta
+o projeto, não de quem roda o ruff. O `CheckStep` é a costura — você
+escreve a regra, o `check` roda.
+
+Um `CheckStep` tem dois campos: `name`, o rótulo que o `check` ecoa como
+`$ <name>` no stderr, e `run`, uma função que recebe o alvo do `check`
+(o caminho da linha de comando, `.` por padrão) e devolve um código de
+saída — `0` é passou.
+
+```python
+from pathlib import Path
+
+import typer
+
+from tempest_cli import CheckStep
+from tempest_cli.main import register_commands
+
+
+def no_print(target: str) -> int:
+    """Fail when a module under ``target`` calls ``print``."""
+    offenders: list[str] = [
+        f"{path}:{number}: use logging instead of print()"
+        for path in sorted(Path(target).rglob("*.py"))
+        for number, line in enumerate(path.read_text().splitlines(), start=1)
+        if line.lstrip().startswith("print(")
+    ]
+    for offender in offenders:
+        typer.echo(offender, err=True)
+    return 1 if offenders else 0
+
+
+cli: typer.Typer = typer.Typer(name="minhaferramenta")
+
+
+@cli.command("deploy")
+def deploy() -> None:
+    """Um comando que a ferramenta já tinha."""
+
+
+register_commands(cli, extra_steps=[CheckStep(name="no-print", run=no_print)])
+
+if __name__ == "__main__":
+    cli()
+```
+
+Com um módulo `pkg/a.py` que chama `print("x")`:
+
+```console
+$ python minhaferramenta.py check pkg
+$ ruff check --extend-select ANN001,ANN201,ANN202,ANN205,ANN206 pkg
+All checks passed!
+$ ruff format --check pkg
+1 file already formatted
+$ mypy --disallow-untyped-defs --disallow-incomplete-defs pkg
+Success: no issues found in 1 source file
+$ no-print
+pkg/a.py:2: use logging instead of print()
+$ echo $?
+1
+```
+
+A ordem é `ruff check` → `ruff format --check` → `mypy` → os passos
+extras, na ordem da lista → `pytest`. Passo extra é checagem estática:
+fica antes da suíte para falhar em um segundo, não depois dela. O
+contrato é o dos passos embutidos — o primeiro código diferente de `0`
+para o gate e vira o código de saída do `check`, com ou sem `--fast`.
+
+!!! tip "A mensagem é sua"
+    O `check` só ecoa o nome. O que o passo imprime é o que o usuário lê,
+    então diga arquivo, linha e a correção — como o `no-print` acima.
+
+Sem a CLI, o mesmo vale para `run_full_check`:
+
+```python
+from tempest_cli import CheckStep, run_full_check
+
+
+def always_passes(target: str) -> int:
+    """A step that accepts any target."""
+    return 0
+
+
+exit_code: int = run_full_check(
+    ".", extra_steps=[CheckStep(name="always-passes", run=always_passes)]
+)
+```
+
+`extra_steps` é vazio por padrão: sem ele, o gate é exatamente o de
+antes.
+
+## Gerar o prompt de PR sem a CLI
+
+```python
+from pathlib import Path
+
+from tempest_cli import PromptLanguage, generate_pr_prompt
+
+prompt, context, template = generate_pr_prompt(
+    base="main",
+    head=None,
+    cwd=Path("."),
+    template=None,
+    language=PromptLanguage.PT_BR,
+    max_files=20,
+    max_chars=8000,
+)
+print(len(context.commits), "commits;", template.source)
+```
+
+`generate_pr_prompt` levanta `GitError` quando o git falha ou uma ref não
+resolve.
+
+## Recap
+
+- Runners, config e o gerador de prompt são todos importáveis.
+- `register_commands(app)` monta os oito comandos em qualquer `Typer`.
+- `extra_steps=[CheckStep(...)]` põe regras suas no `check`, depois do
+  `mypy` e antes do `pytest`.
+- Código de saída é o da ferramenta, igual na CLI e na chamada direta.

{tempest_cli-0.4.0 → tempest_cli-0.5.0}/docs/reference.md

@@ -35,6 +35,12 @@ Gerada a partir das docstrings do pacote via
 
 ---
 
+## Passos extras
+
+::: tempest_cli.steps.CheckStep
+
+---
+
 ## Prompt de PR
 
 ::: tempest_cli.pr_prompt.generate_pr_prompt

{tempest_cli-0.4.0 → tempest_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Framework-agnostic quality gate for Python projects: ruff + mypy + pytest behind one command, with a typing-strictness dial and a PR-description prompt generator."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_cli-0.4.0 → tempest_cli-0.5.0}/tempest_cli/__init__.py

@@ -30,6 +30,11 @@ config = load_tempest_config()
 exit_code = run_full_check(".", config=config)
 ```
 
+A framework that wants its own rules in ``check`` passes them as
+:class:`tempest_cli.CheckStep` values — ``extra_steps`` on
+:func:`run_full_check` and on :func:`tempest_cli.main.register_commands`
+— and they run after ``mypy``, before ``pytest``.
+
 And :func:`tempest_cli.main.register_commands` mounts the whole gate onto
 an existing :class:`typer.Typer`, so another CLI can expose these
 commands under its own name without copying them.
@@ -50,12 +55,14 @@ from tempest_cli.lint import run_ruff_format as run_ruff_format
 from tempest_cli.pr_prompt import GitError as GitError
 from tempest_cli.pr_prompt import PromptLanguage as PromptLanguage
 from tempest_cli.pr_prompt import generate_pr_prompt as generate_pr_prompt
+from tempest_cli.steps import CheckStep as CheckStep
 
-__version__: str = "0.4.0"
+__version__: str = "0.5.0"
 """Installed package version."""
 
 __all__: list[str] = [
     "DEFAULT_TYPING_STRICTNESS",
+    "CheckStep",
     "GitError",
     "PromptLanguage",
     "TempestConfig",