tempest-cli 0.1.0__py3-none-any.whl

tempest_cli/__init__.py

@@ -0,0 +1,70 @@
+"""Framework-agnostic quality gate for Python projects.
+
+``tempest-cli`` runs ruff, mypy and pytest behind one command, with a
+typing-strictness dial read from ``[tool.tempest]`` in the project's
+``pyproject.toml`` — and a generator for the prompt that makes an AI fill
+a pull-request description from the branch's own diff.
+
+It knows nothing about any web framework. The only runtime dependency is
+``typer``; the tools themselves are invoked from the active environment,
+so a project pins the ruff and mypy versions it wants.
+
+```bash
+tempest-cli check                 # lint + fmt-check + type + test
+tempest-cli fix                   # every ruff autofix, then format
+tempest-cli type -s strict        # override the configured strictness
+tempest-cli pr-prompt | claude -p
+```
+
+Everything is importable too, for a project that would rather wire the
+gate into its own tooling:
+
+```python
+from tempest_cli import load_tempest_config, run_full_check
+
+config = load_tempest_config()
+exit_code = run_full_check(".", config=config)
+```
+
+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.
+"""
+
+from tempest_cli.config import DEFAULT_TYPING_STRICTNESS as DEFAULT_TYPING_STRICTNESS
+from tempest_cli.config import TempestConfig as TempestConfig
+from tempest_cli.config import TypingStrictness as TypingStrictness
+from tempest_cli.config import find_pyproject as find_pyproject
+from tempest_cli.config import load_tempest_config as load_tempest_config
+from tempest_cli.lint import resolve_tool as resolve_tool
+from tempest_cli.lint import run_full_check as run_full_check
+from tempest_cli.lint import run_mypy as run_mypy
+from tempest_cli.lint import run_pytest as run_pytest
+from tempest_cli.lint import run_ruff_check as run_ruff_check
+from tempest_cli.lint import run_ruff_fix as run_ruff_fix
+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
+
+__version__: str = "0.1.0"
+"""Installed package version."""
+
+__all__: list[str] = [
+    "DEFAULT_TYPING_STRICTNESS",
+    "GitError",
+    "PromptLanguage",
+    "TempestConfig",
+    "TypingStrictness",
+    "__version__",
+    "find_pyproject",
+    "generate_pr_prompt",
+    "load_tempest_config",
+    "resolve_tool",
+    "run_full_check",
+    "run_mypy",
+    "run_pytest",
+    "run_ruff_check",
+    "run_ruff_fix",
+    "run_ruff_format",
+]

tempest_cli/_templates/pull_request_template.en-US.md

@@ -0,0 +1,39 @@
+| Has Script? | New Env Vars |
+| :---------: | :----------: |
+| Yes/No      | Yes/No       |
+
+> :warning: **NOTE**
+> Use this section to highlight what the reviewer must not miss:
+> - Dependency on other PRs
+> - New environment variables
+> - Reasons for extra attention
+
+## Problem
+
+_What problem are you trying to solve?_
+
+## Solution
+
+_How did you solve it?_
+
+## Screenshots
+
+**Screenshot description**:
+[insert screenshot here]
+
+## Other changes
+
+(e.g. bugfixes, UI tweaks, improvements, refactors, etc)
+
+## Deploy notes
+
+_Notes about deploying these changes._
+
+**New Environment Variables**:
+- `ENV_VAR`: details
+
+**New Scripts and/or Background Tasks**:
+- `script`: details
+
+**New Dependencies**:
+- `dependency`: details

tempest_cli/_templates/pull_request_template.pt-BR.md

@@ -0,0 +1,39 @@
+| Tem Script? | Novas Env Vars |
+| :---------: | :------------: |
+| Sim/Não     | Sim/Não        |
+
+> :warning: **NOTA**
+> Use esta seção para destacar pontos importantes sobre o PR:
+> - Dependência de outros PRs
+> - Novas variáveis de ambiente
+> - Motivos para atenção especial
+
+## Problema
+
+_Qual é o problema que você está tentando resolver?_
+
+## Solução
+
+_Como você resolveu o problema?_
+
+## Screenshots
+
+**Descrição do Screenshot**:
+[insira o screenshot aqui]
+
+## Outras mudanças
+
+(e.g. bugfixes, alterações na UI, melhorias, refatorações, etc)
+
+## Notas sobre deploy
+
+_Notas sobre a implantação das alterações._
+
+**Novas Variáveis de Ambiente**:
+- `ENV_VAR`: detalhes
+
+**Novos Scripts e/ou Tarefas de Background**:
+- `script`: detalhes
+
+**Novas Dependências**:
+- `dependency`: detalhes

tempest_cli/config.py

@@ -0,0 +1,164 @@
+"""``[tool.tempest]`` configuration read from ``pyproject.toml``.
+
+The quality gates (``tempest-cli lint`` / ``fix`` / ``type`` / ``check``)
+let a project dial how strictly typing is enforced without editing the
+gate commands themselves. The single knob is ``typing_strictness`` under
+``[tool.tempest]``:
+
+```toml
+[tool.tempest]
+typing_strictness = "strict"  # lenient | standard | strict
+```
+
+Each level layers *additional* ruff and mypy flags on top of whatever
+``[tool.ruff]`` / ``[tool.mypy]`` already declares -- it never relaxes
+the project's own configuration. ``Any`` is always a valid annotation,
+so ANN401 is never enabled at any level: the levels enforce that things
+*are* annotated, never that they avoid ``Any``.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, get_args
+
+TypingStrictness = Literal["lenient", "standard", "strict"]
+"""Allowed values for ``[tool.tempest] typing_strictness``."""
+
+DEFAULT_TYPING_STRICTNESS: TypingStrictness = "standard"
+"""Level applied when the key is absent or no ``pyproject.toml`` is found."""
+
+# ANN rules layered onto ruff per level. ANN401 (Any) is intentionally
+# never included -- ``Any`` is a valid annotation. ANN002/ANN003
+# (``*args`` / ``**kwargs``) are also left out as noise.
+_RUFF_ANN_BY_LEVEL: dict[TypingStrictness, list[str]] = {
+    "lenient": [],
+    "standard": ["ANN001", "ANN201", "ANN202", "ANN205", "ANN206"],
+    "strict": [
+        "ANN001",
+        "ANN201",
+        "ANN202",
+        "ANN204",
+        "ANN205",
+        "ANN206",
+    ],
+}
+
+# mypy flags layered on per level (additive over [tool.mypy]).
+_MYPY_FLAGS_BY_LEVEL: dict[TypingStrictness, list[str]] = {
+    "lenient": [],
+    "standard": ["--disallow-untyped-defs", "--disallow-incomplete-defs"],
+    "strict": ["--strict"],
+}
+
+
+@dataclass(frozen=True)
+class TempestConfig:
+    """Resolved ``[tool.tempest]`` settings.
+
+    Attributes:
+        typing_strictness (TypingStrictness): How strictly the CLI gates
+            enforce typing. One of ``"lenient"``, ``"standard"``,
+            ``"strict"``.
+    """
+
+    typing_strictness: TypingStrictness = DEFAULT_TYPING_STRICTNESS
+
+    def ruff_ann_select(self) -> list[str]:
+        """Return the ANN rule codes to add to ruff for this level.
+
+        Returns:
+            list[str]: Rule codes for ``--extend-select`` (empty for
+            ``"lenient"``). ANN401 is never present.
+        """
+        return list(_RUFF_ANN_BY_LEVEL[self.typing_strictness])
+
+    def mypy_flags(self) -> list[str]:
+        """Return the extra mypy flags to add for this level.
+
+        Returns:
+            list[str]: Flags layered on top of the project's
+            ``[tool.mypy]`` config (empty for ``"lenient"``).
+        """
+        return list(_MYPY_FLAGS_BY_LEVEL[self.typing_strictness])
+
+
+def find_pyproject(start: Path | None = None) -> Path | None:
+    """Locate the nearest ``pyproject.toml`` walking up from ``start``.
+
+    Args:
+        start (Path | None): Directory to begin the search. Defaults to
+            the current working directory.
+
+    Returns:
+        Path | None: The path to the first ``pyproject.toml`` found in
+        ``start`` or an ancestor, or ``None`` when none exists.
+    """
+    current = (start or Path.cwd()).resolve()
+    for directory in (current, *current.parents):
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _coerce_strictness(value: object, *, source: str) -> TypingStrictness:
+    """Validate a raw ``typing_strictness`` value.
+
+    Args:
+        value (object): The raw value read from the TOML table.
+        source (str): Human-readable origin used in the error message.
+
+    Returns:
+        TypingStrictness: The validated level.
+
+    Raises:
+        ValueError: When ``value`` is not one of the allowed levels.
+    """
+    allowed = get_args(TypingStrictness)
+    if value not in allowed:
+        allowed_str = ", ".join(repr(level) for level in allowed)
+        raise ValueError(
+            f"{source}: invalid typing_strictness {value!r}; "
+            f"expected one of {allowed_str}."
+        )
+    return value  # type: ignore[return-value]
+
+
+def load_tempest_config(start: Path | None = None) -> TempestConfig:
+    """Load ``[tool.tempest]`` from the nearest ``pyproject.toml``.
+
+    Args:
+        start (Path | None): Directory to begin the search. Defaults to
+            the current working directory.
+
+    Returns:
+        TempestConfig: The resolved config. Falls back to defaults when
+        no ``pyproject.toml`` or no ``[tool.tempest]`` table is found.
+
+    Raises:
+        ValueError: When ``typing_strictness`` is present but invalid.
+    """
+    pyproject = find_pyproject(start)
+    if pyproject is None:
+        return TempestConfig()
+    with pyproject.open("rb") as handle:
+        data = tomllib.load(handle)
+    table = data.get("tool", {}).get("tempest", {})
+    strictness = (
+        _coerce_strictness(table["typing_strictness"], source=str(pyproject))
+        if "typing_strictness" in table
+        else DEFAULT_TYPING_STRICTNESS
+    )
+    return TempestConfig(typing_strictness=strictness)
+
+
+__all__: list[str] = [
+    "DEFAULT_TYPING_STRICTNESS",
+    "TempestConfig",
+    "TypingStrictness",
+    "find_pyproject",
+    "load_tempest_config",
+]

tempest_cli/lint.py

@@ -0,0 +1,238 @@
+"""Quality-gate helpers backing ``tempest lint``/``check``/etc."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+
+import typer
+
+from tempest_cli.config import TempestConfig
+
+
+def _ruff_ann_args(config: TempestConfig | None) -> list[str]:
+    """Build the ruff ``--extend-select`` args for ``config``'s level.
+
+    Args:
+        config (TempestConfig | None): The resolved config, or ``None``
+            to use the default level.
+
+    Returns:
+        list[str]: ``["--extend-select", "ANN001,..."]`` for a level that
+        adds ANN rules, or ``[]`` for the lenient level.
+    """
+    codes = (config or TempestConfig()).ruff_ann_select()
+    if not codes:
+        return []
+    return ["--extend-select", ",".join(codes)]
+
+
+def resolve_tool(executable: str) -> list[str] | None:
+    """Return an argv prefix invoking ``executable`` or ``None`` when absent.
+
+    Public because callers outside the gate need the same lookup — the
+    SDK's OpenAPI code generator formats what it emits with the project's
+    own ruff, and reimplementing the PATH/``uv run`` fallback there would
+    be a second answer to the same question.
+
+    Preference order:
+
+    1. ``executable`` available on ``PATH`` directly (already activated venv,
+       global install, etc.).
+    2. ``uv run <executable>`` when ``uv`` is on the ``PATH`` (handles
+       project-local virtualenvs without requiring activation).
+
+    Args:
+        executable (str): The command name (``ruff``/``mypy``/``pytest``).
+
+    Returns:
+        list[str] | None: argv prefix to extend with extra arguments, or
+        ``None`` when no runner could be found.
+    """
+    direct = shutil.which(executable)
+    if direct is not None:
+        return [direct]
+    uv = shutil.which("uv")
+    if uv is not None:
+        return [uv, "run", executable]
+    return None
+
+
+def _execute(executable: str, args: list[str]) -> int:
+    """Run ``executable args`` and return its exit code.
+
+    Args:
+        executable (str): The command to run.
+        args (list[str]): Extra arguments to forward.
+
+    Returns:
+        int: The child process exit code. Returns ``127`` when neither
+        the executable nor ``uv`` is available.
+    """
+    argv = resolve_tool(executable)
+    if argv is None:
+        typer.echo(
+            f"error: '{executable}' is not on PATH and 'uv' is unavailable. "
+            f"Install it (or activate the project venv) and retry.",
+            err=True,
+        )
+        return 127
+    return subprocess.call([*argv, *args])
+
+
+def run_ruff_check(target: str, *, config: TempestConfig | None = None) -> int:
+    """Invoke ``ruff check <target>`` with the configured ANN rules.
+
+    Args:
+        target (str): The path passed verbatim to ruff.
+        config (TempestConfig | None): Resolved ``[tool.tempest]`` config
+            controlling the typing-strictness ANN rules layered on. When
+            ``None`` the default level is used.
+
+    Returns:
+        int: The ruff exit code.
+    """
+    return _execute("ruff", ["check", *_ruff_ann_args(config), target])
+
+
+def run_ruff_fix(
+    target: str,
+    *,
+    unsafe: bool = False,
+    config: TempestConfig | None = None,
+) -> int:
+    """Apply every automatic fix ruff can perform, then format the target.
+
+    Runs in two passes so the second one sees the rewritten file:
+
+    1. ``ruff check --fix [--unsafe-fixes] <target>`` — autofix imports
+       (sort + dedupe), remove unused imports, normalize string quotes,
+       drop trailing whitespace, fix the rest of the lint rules that
+       have safe (or, with ``unsafe=True``, also unsafe) autofixers.
+    2. ``ruff format <target>`` — normalize indentation, line length,
+       blank lines and trailing newlines.
+
+    Both passes always run. ``ruff check --fix`` exits non-zero whenever
+    *any* residual violation remains that it cannot autofix (an
+    over-length string/comment, an undefined name, etc.) — even though
+    it already rewrote everything it could. Short-circuiting on that
+    exit code would skip ``ruff format`` entirely, leaving the file
+    un-wrapped and its extra blank lines intact. So the formatter runs
+    unconditionally; the lint exit code is surfaced afterwards so CI
+    still fails on the leftover issues.
+
+    Args:
+        target (str): The path passed verbatim to ruff.
+        unsafe (bool): When True, pass ``--unsafe-fixes`` so ruff also
+            applies the fixes it would otherwise leave alone.
+        config (TempestConfig | None): Resolved ``[tool.tempest]`` config
+            controlling the typing-strictness ANN rules layered onto the
+            fix pass. When ``None`` the default level is used.
+
+    Returns:
+        int: ``0`` when both passes succeed with nothing left to fix;
+        otherwise the lint pass exit code (residual violations), or the
+        format pass exit code when the lint pass was clean.
+    """
+    check_args = ["check", "--fix", *_ruff_ann_args(config)]
+    if unsafe:
+        check_args.append("--unsafe-fixes")
+    check_args.append(target)
+    check_code = _execute("ruff", check_args)
+    format_code = _execute("ruff", ["format", target])
+    return check_code or format_code
+
+
+def run_ruff_format(target: str, *, check: bool) -> int:
+    """Invoke ``ruff format`` (write or check-only).
+
+    Args:
+        target (str): The path passed verbatim to ruff.
+        check (bool): When True, run ``ruff format --check`` (read-only).
+
+    Returns:
+        int: The ruff exit code.
+    """
+    args = ["format"]
+    if check:
+        args.append("--check")
+    args.append(target)
+    return _execute("ruff", args)
+
+
+def run_mypy(target: str, *, config: TempestConfig | None = None) -> int:
+    """Invoke ``mypy <target>`` with the configured strictness flags.
+
+    Args:
+        target (str): The path passed verbatim to mypy.
+        config (TempestConfig | None): Resolved ``[tool.tempest]`` config
+            controlling the mypy strictness flags layered on top of the
+            project's ``[tool.mypy]``. When ``None`` the default level is
+            used.
+
+    Returns:
+        int: The mypy exit code.
+    """
+    flags = (config or TempestConfig()).mypy_flags()
+    return _execute("mypy", [*flags, target])
+
+
+def run_pytest(target: str | None) -> int:
+    """Invoke ``pytest`` with an optional target.
+
+    Args:
+        target (str | None): Optional pytest path filter. ``None`` runs
+            the default test suite.
+
+    Returns:
+        int: The pytest exit code.
+    """
+    args = [target] if target else []
+    return _execute("pytest", args)
+
+
+def run_full_check(target: str, *, config: TempestConfig | None = None) -> int:
+    """Run the entire quality gate sequentially.
+
+    Order: ``ruff check`` → ``ruff format --check`` → ``mypy`` → ``pytest``.
+    Stops at the first non-zero exit code so failures surface fast.
+
+    Args:
+        target (str): The path inspected by ruff/mypy. Pytest always runs
+            against the project's configured ``testpaths``.
+        config (TempestConfig | None): Resolved ``[tool.tempest]`` config
+            controlling the ANN rules and mypy flags layered onto the
+            ruff/mypy steps. When ``None`` the default level is used.
+
+    Returns:
+        int: The first non-zero exit code, or ``0`` when every gate passed.
+    """
+    resolved = config or TempestConfig()
+    steps: list[tuple[str, list[str]]] = [
+        ("ruff", ["check", *_ruff_ann_args(resolved), target]),
+        ("ruff", ["format", "--check", target]),
+        ("mypy", [*resolved.mypy_flags(), target]),
+        ("pytest", []),
+    ]
+    for executable, args in steps:
+        typer.echo(f"$ {executable} {' '.join(args)}", err=True)
+        code = _execute(executable, args)
+        if code != 0:
+            return code
+    return 0
+
+
+__all__: list[str] = [
+    "resolve_tool",
+    "run_full_check",
+    "run_mypy",
+    "run_pytest",
+    "run_ruff_check",
+    "run_ruff_fix",
+    "run_ruff_format",
+]
+
+
+if __name__ == "__main__":  # pragma: no cover - manual invocation only
+    sys.exit(run_full_check("."))