rhiza_tools.cli

  1"""CLI commands for Rhiza Tools.
  2
  3This module defines the main Typer application and all command-line interface
  4commands for rhiza-tools. It provides commands for version bumping, coverage
  5badge generation, release management, and README updates.
  6
  7The CLI can be used either as a standalone tool (`rhiza-tools`) or as a
  8subcommand of the rhiza CLI (`rhiza tools`).
  9
 10Example:
 11    Bump version to a specific version::
 12
 13        $ rhiza-tools bump 1.2.3
 14        $ rhiza tools bump 1.2.3
 15
 16    Bump version interactively::
 17
 18        $ rhiza-tools bump
 19
 20    Generate a coverage badge::
 21
 22        $ rhiza-tools generate-coverage-badge --coverage-json _tests/coverage.json
 23
 24    Update README with make help output::
 25
 26        $ rhiza-tools update-readme
 27"""
 28
 29from pathlib import Path
 30from typing import Annotated
 31
 32import typer
 33
 34from rhiza_tools import __version__, console
 35from rhiza_tools.console import configure as configure_console
 36
 37from .commands.analyze_benchmarks import analyze_benchmarks_command
 38from .commands.bump import bump_command
 39from .commands.generate_badge import generate_coverage_badge_command
 40from .commands.release import release_command
 41from .commands.rollback import rollback_command
 42from .commands.update_readme import update_readme_command
 43from .commands.version_matrix import version_matrix_command
 44
 45
 46def version_callback(value: bool) -> None:
 47    """Display the version and exit."""
 48    if value:
 49        typer.echo(f"rhiza-tools version {__version__}")
 50        raise typer.Exit()
 51
 52
 53app = typer.Typer(help="Rhiza Tools - Extra utilities for Rhiza.")
 54
 55# Shared option so --verbose / -v works both before and after the subcommand.
 56VERBOSE_OPTION = typer.Option(False, "--verbose", "-v", help="Show verbose debug output.")
 57
 58
 59def _apply_verbose(verbose: bool) -> None:
 60    """Enable verbose output if the flag was passed on the subcommand."""
 61    if verbose:
 62        configure_console(verbose=True)
 63
 64
 65@app.callback()
 66def main(
 67    version: bool = typer.Option(
 68        None,
 69        "--version",
 70        help="Show the version and exit.",
 71        callback=version_callback,
 72        is_eager=True,
 73    ),
 74    verbose: bool = VERBOSE_OPTION,
 75) -> None:
 76    """Rhiza Tools - Extra utilities for Rhiza."""
 77    configure_console(verbose=verbose)
 78
 79
 80@app.command()
 81def bump(
 82    version: str | None = typer.Argument(None, help="The version to bump to (e.g., 1.0.1, major, minor, patch, etc)"),
 83    language: str | None = typer.Option(
 84        None, "--language", "-l", help="Programming language (python or go). Auto-detected if not specified."
 85    ),
 86    dry_run: bool = typer.Option(False, "--dry-run", help="Print what would happen without doing it."),
 87    commit: bool = typer.Option(False, "--commit", help="Commit the changes to git."),
 88    push: bool = typer.Option(False, "--push", help="Push changes to remote after commit (implies --commit)."),
 89    branch: str | None = typer.Option(
 90        None, "--branch", help="Branch to perform the bump on (default: current branch)."
 91    ),
 92    allow_dirty: bool = typer.Option(
 93        False, "--allow-dirty", help="Allow bumping even if the working directory is dirty."
 94    ),
 95    verbose: bool = VERBOSE_OPTION,
 96) -> None:
 97    """Bump the version of the project.
 98
 99    This command updates the version for Python (pyproject.toml) or Go (VERSION file)
100    projects using semantic versioning. You can provide an explicit version number,
101    a bump type (patch, minor, major), or leave it blank for an interactive prompt.
102
103    Args:
104        version: The version to bump to. Can be an explicit version (e.g., "1.2.3"),
105            a bump type ("patch", "minor", "major"), a prerelease type
106            ("alpha", "beta", "rc", "dev"), or None for interactive selection.
107        language: Programming language (python or go). Auto-detected if not specified.
108        dry_run: If True, show what would change without actually changing anything.
109        commit: If True, automatically commit the version change to git.
110        push: If True, push changes to remote after commit (implies --commit).
111        branch: Branch to perform the bump on (default: current branch).
112        allow_dirty: If True, allow bumping even with uncommitted changes.
113        verbose: If True, enable verbose debug output.
114
115    Example:
116        Bump to a specific version::
117
118            $ rhiza-tools bump 2.0.0
119
120        Bump patch version (1.2.3 -> 1.2.4)::
121
122            $ rhiza-tools bump patch
123
124        Bump a Go project explicitly::
125
126            $ rhiza-tools bump minor --language go
127
128        Preview changes without applying them::
129
130            $ rhiza-tools bump minor --dry-run
131
132        Interactive version selection::
133
134            $ rhiza-tools bump
135
136        Bump and push to remote::
137
138            $ rhiza-tools bump minor --push
139    """
140    _apply_verbose(verbose)
141    from rhiza_tools.commands.bump import BumpOptions, Language
142
143    # Parse language if provided
144    lang_enum = None
145    if language:
146        try:
147            lang_enum = Language(language.lower())
148        except ValueError:
149            console.error(f"Invalid language: {language}")
150            console.error("Supported languages: python, go")
151            raise typer.Exit(code=1) from None
152
153    options = BumpOptions(
154        version=version,
155        dry_run=dry_run,
156        commit=commit,
157        push=push,
158        branch=branch,
159        allow_dirty=allow_dirty,
160        language=lang_enum,
161    )
162    bump_command(options)
163
164
165@app.command()
166def generate_coverage_badge(
167    coverage_json: Annotated[
168        Path,
169        typer.Option(
170            "--coverage-json",
171            help="Path to coverage.json file",
172        ),
173    ] = Path("_tests/coverage.json"),
174    output: Annotated[
175        Path,
176        typer.Option(
177            help="Path to output badge JSON",
178        ),
179    ] = Path("_book/tests/coverage-badge.json"),
180    verbose: bool = VERBOSE_OPTION,
181) -> None:
182    """Generate a coverage badge for the project.
183
184    Reads a coverage report JSON file and creates a shields.io endpoint JSON file
185    for displaying a coverage badge. The badge color automatically adjusts based
186    on the coverage percentage.
187
188    Args:
189        coverage_json: Path to the coverage.json file generated by pytest-cov.
190        output: Path where the badge JSON file should be written.
191        verbose: If True, enable verbose debug output.
192
193    Example:
194        Generate badge with default paths::
195
196            $ rhiza-tools generate-coverage-badge
197
198        Generate badge with custom paths::
199
200            $ rhiza-tools generate-coverage-badge \
201                --coverage-json tests/coverage.json \
202                --output assets/badge.json
203    """
204    _apply_verbose(verbose)
205    generate_coverage_badge_command(coverage_json_path=coverage_json, output_path=output)
206
207
208@app.command()
209def release(
210    bump: str | None = typer.Option(None, "--bump", help="Bump type (MAJOR, MINOR, PATCH) before release."),
211    with_bump: bool = typer.Option(
212        False,
213        "--with-bump",
214        help="Interactively select bump type before release (works with --dry-run).",
215    ),
216    push: bool = typer.Option(False, "--push", help="Push changes to remote (default: prompt in interactive mode)."),
217    dry_run: bool = typer.Option(False, "--dry-run", help="Print what would happen without doing it."),
218    non_interactive: bool = typer.Option(False, "--non-interactive", "-y", help="Skip all confirmation prompts."),
219    language: str | None = typer.Option(
220        None, "--language", "-l", help="Programming language (python or go). Auto-detected if not specified."
221    ),
222    verbose: bool = VERBOSE_OPTION,
223) -> None:
224    """Push a release tag to remote to trigger the release workflow.
225
226    This command validates the repository state and pushes the git tag for the
227    current version to the remote repository, which triggers the automated release
228    workflow. Supports Python projects (pyproject.toml) and Go projects
229    (go.mod + VERSION file). The project language is auto-detected when not
230    explicitly specified.
231
232    Args:
233        bump: Bump type (MAJOR, MINOR, PATCH) to apply before release.
234        with_bump: If True, interactively select bump type before release.
235        push: If True, push changes without prompting (implies non-interactive for push).
236        dry_run: If True, show what would happen without actually pushing the tag.
237        non_interactive: If True, skip all confirmation prompts (useful for CI/CD).
238        language: Programming language (python or go). Auto-detected if not specified.
239        verbose: If True, enable verbose debug output.
240
241    Example:
242        Push a release tag (with prompts)::
243
244            $ rhiza-tools release
245
246        Preview what would happen::
247
248            $ rhiza-tools release --dry-run
249
250        Non-interactive mode (for CI/CD)::
251
252            $ rhiza-tools release --non-interactive
253
254        Bump version and release::
255
256            $ rhiza-tools release --bump MINOR --push
257
258        Interactive bump with dry-run preview::
259
260            $ rhiza-tools release --with-bump --push --dry-run
261
262        Release a Go project::
263
264            $ rhiza-tools release --language go
265    """
266    _apply_verbose(verbose)
267    from rhiza_tools.commands.bump import Language
268
269    lang_enum = None
270    if language:
271        try:
272            lang_enum = Language(language.lower())
273        except ValueError:
274            console.error(f"Invalid language: {language}")
275            console.error("Supported languages: python, go")
276            raise typer.Exit(code=1) from None
277
278    release_command(bump, push, dry_run, non_interactive, with_bump, lang_enum)
279
280
281@app.command()
282def rollback(
283    tag: str | None = typer.Argument(None, help="Tag to rollback (e.g., v1.2.3). Interactive if omitted."),
284    revert_bump: bool = typer.Option(False, "--revert-bump", help="Also revert the version bump commit."),
285    dry_run: bool = typer.Option(False, "--dry-run", help="Print what would happen without doing it."),
286    non_interactive: bool = typer.Option(False, "--non-interactive", "-y", help="Skip all confirmation prompts."),
287    verbose: bool = VERBOSE_OPTION,
288) -> None:
289    """Rollback a release and/or version bump.
290
291    This command safely reverses release and bump operations by deleting
292    the release tag from local and remote repositories, and optionally
293    reverting the version bump commit.
294
295    It uses ``git revert`` rather than ``git reset``, making it safe
296    even when changes have already been pushed to remote.
297
298    Args:
299        tag: The tag to rollback (e.g., "v1.2.3"). If omitted, an interactive
300            menu shows recent tags to choose from.
301        revert_bump: If True, also revert the version bump commit associated
302            with the tag.
303        dry_run: If True, show what would happen without actually making changes.
304        non_interactive: If True, skip all confirmation prompts (useful for CI/CD).
305        verbose: If True, enable verbose debug output.
306
307    Example:
308        Rollback the most recent release interactively::
309
310            $ rhiza-tools rollback
311
312        Preview rollback of a specific tag::
313
314            $ rhiza-tools rollback v1.2.3 --dry-run
315
316        Fully rollback including the bump commit::
317
318            $ rhiza-tools rollback v1.2.3 --revert-bump
319
320        Non-interactive rollback (for CI/CD)::
321
322            $ rhiza-tools rollback v1.2.3 --revert-bump -y
323    """
324    _apply_verbose(verbose)
325    from rhiza_tools.commands.rollback import RollbackOptions
326
327    options = RollbackOptions(
328        tag=tag,
329        revert_bump=revert_bump,
330        dry_run=dry_run,
331        non_interactive=non_interactive,
332    )
333    rollback_command(options)
334
335
336@app.command(name="update-readme")
337def update_readme(
338    dry_run: bool = typer.Option(False, "--dry-run", help="Print what would happen without doing it."),
339    verbose: bool = VERBOSE_OPTION,
340) -> None:
341    """Update README.md with the current output from `make help`.
342
343    This command runs `make help` and updates the README.md file with the current
344    help output, keeping the documentation in sync with available Make targets.
345
346    Args:
347        dry_run: If True, show the help output that would be inserted without
348            actually modifying README.md.
349        verbose: If True, enable verbose debug output.
350
351    Example:
352        Update README with make help output::
353
354            $ rhiza-tools update-readme
355
356        Preview changes without modifying README::
357
358            $ rhiza-tools update-readme --dry-run
359    """
360    _apply_verbose(verbose)
361    update_readme_command(dry_run)
362
363
364@app.command(name="version-matrix")
365def version_matrix(
366    pyproject: Annotated[
367        Path,
368        typer.Option(
369            "--pyproject",
370            help="Path to pyproject.toml file",
371        ),
372    ] = Path("pyproject.toml"),
373    candidates: Annotated[
374        str | None,
375        typer.Option(
376            "--candidates",
377            help="Comma-separated list of candidate Python versions (e.g., '3.11,3.12,3.13')",
378        ),
379    ] = None,
380    verbose: bool = VERBOSE_OPTION,
381) -> None:
382    """Emit supported Python versions from pyproject.toml as JSON.
383
384    This command reads the requires-python field from pyproject.toml and outputs
385    a JSON array of Python versions that satisfy the constraint. This is primarily
386    used in GitHub Actions to compute the test matrix.
387
388    Args:
389        pyproject: Path to the pyproject.toml file.
390        candidates: Comma-separated list of candidate Python versions to evaluate.
391            Defaults to "3.11,3.12,3.13,3.14".
392        verbose: If True, enable verbose debug output.
393
394    Example:
395        Get supported versions with defaults::
396
397            $ rhiza-tools version-matrix
398            ["3.11", "3.12"]
399
400        Use custom pyproject.toml path::
401
402            $ rhiza-tools version-matrix --pyproject /path/to/pyproject.toml
403
404        Use custom candidates::
405
406            $ rhiza-tools version-matrix --candidates "3.10,3.11,3.12"
407    """
408    _apply_verbose(verbose)
409    candidates_list = None
410    if candidates:
411        candidates_list = [v.strip() for v in candidates.split(",")]
412
413    version_matrix_command(pyproject_path=pyproject, candidates=candidates_list)
414
415
416@app.command(name="analyze-benchmarks")
417def analyze_benchmarks(
418    benchmarks_json: Annotated[
419        Path,
420        typer.Option(
421            "--benchmarks-json",
422            help="Path to benchmarks.json file",
423        ),
424    ] = Path("_benchmarks/benchmarks.json"),
425    output_html: Annotated[
426        Path,
427        typer.Option(
428            "--output-html",
429            help="Path to save HTML visualization",
430        ),
431    ] = Path("_benchmarks/benchmarks.html"),
432    verbose: bool = VERBOSE_OPTION,
433) -> None:
434    """Analyze pytest-benchmark results and visualize them.
435
436    This command reads a benchmarks.json file produced by pytest-benchmark,
437    prints a table with benchmark name, mean milliseconds, and operations per
438    second, and generates an interactive Plotly bar chart of mean runtimes.
439
440    Note: This command requires pandas and plotly. Install with:
441    uv pip install -e '.[dev]' or pip install 'rhiza-tools[dev]'
442
443    Args:
444        benchmarks_json: Path to the benchmarks.json file.
445        output_html: Path where the HTML visualization should be saved.
446        verbose: If True, enable verbose debug output.
447
448    Example:
449        Analyze benchmarks with default paths::
450
451            $ rhiza-tools analyze-benchmarks
452
453        Use custom paths::
454
455            $ rhiza-tools analyze-benchmarks \
456                --benchmarks-json tests/benchmarks.json \
457                --output-html reports/benchmarks.html
458    """
459    _apply_verbose(verbose)
460    analyze_benchmarks_command(benchmarks_json=benchmarks_json, output_html=output_html)