rhiza-task 0.1.1__py3-none-any.whl

rhiza_task/__init__.py

@@ -0,0 +1,26 @@
+"""The rhiza developer tasks, as a pinned CLI instead of a synced make layer.
+
+What this replaces, per consumer repository: ``.rhiza/rhiza.mk`` (200 lines) and the ten
+fragments in ``.rhiza/make.d/`` (823 lines), synced at a template tag and excluded,
+shadowed or patched wherever a project disagreed with them. Here they are a dependency
+pin -- ``uvx rhiza-task@0.1.1 test`` -- so there is nothing to copy, nothing to exclude in
+``template.yml``, and nothing to drift.
+
+Sibling to ``pytest-rhiza``, which did the same for ``.rhiza/tests``.
+
+Layout:
+
+* :mod:`rhiza_task.spec` -- the task model: ``Task``, ``Guard``, ``Skip``/``Failed``, and
+  the registry that replaces make's double-colon rules.
+* :mod:`rhiza_task.config` -- five-layer settings resolution, replacing ``?=`` and ``+=``.
+* :mod:`rhiza_task.uv` -- the three ways rhiza reaches a tool.
+* :mod:`rhiza_task.runner` -- prerequisite dedup, guard evaluation, outcome bookkeeping.
+* :mod:`rhiza_task.cli` -- the Typer app, generated from the registry.
+* :mod:`rhiza_task.tasks` -- the task modules themselves, loaded by entry point.
+"""
+
+__all__ = ["__version__"]
+
+# Kept in step with [project].version by bump-my-version, which needs a [[files]] entry
+# for this file but not for pyproject.toml itself.
+__version__ = "0.1.1"

rhiza_task/__main__.py

@@ -0,0 +1,6 @@
+"""Support ``python -m rhiza_task``, for a checkout without the console script installed."""
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover - trivial delegation
+    main()

rhiza_task/cli.py

@@ -0,0 +1,163 @@
+"""The command line, generated from the registry rather than hand-maintained.
+
+rhiza.mk builds its help by running awk over ``$(MAKEFILE_LIST)`` looking for ``##`` and
+``##@`` comments -- a parser for a documentation convention that exists only because make
+has no notion of a task description. Typer has one, so help text, sections, per-task help
+and the "unknown task" error all come from the same registry the runner uses, and cannot
+drift from it.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from importlib.metadata import entry_points
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__, runner
+from .config import Config
+from .runner import Status
+from .spec import REGISTRY
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="rhiza developer tasks. Run `rhiza-task list` to see what is available.",
+)
+console = Console()
+err = Console(stderr=True)
+
+STATUS_COLOUR = {
+    Status.OK: "green",
+    Status.SKIPPED: "yellow",
+    Status.FAILED: "red",
+    Status.BLOCKED: "red",
+}
+
+RESERVED = frozenset({"list", "print", "run", "ci-os-matrix", "shim", "version"})
+"""Subcommand names, so the bare-task shorthand in :func:`main` can tell them apart."""
+
+
+def load_tasks() -> None:
+    """Import every module registered under the ``rhiza_task.tasks`` entry-point group.
+
+    Failures are reported and skipped rather than fatal: a broken third-party task module
+    should not take the built-in gates down with it.
+    """
+    for entry in entry_points(group="rhiza_task.tasks"):
+        try:
+            entry.load()
+        except Exception as exc:  # noqa: BLE001 - a plugin must not break the runner
+            err.print(f"[yellow]could not load task module {entry.name}: {exc}[/yellow]")
+
+
+@app.command("list")
+def list_tasks() -> None:
+    """Show every available task, grouped by section."""
+    table = Table("task", "section", "needs", "does", box=None, header_style="bold")
+    for name, spec in sorted(REGISTRY.items(), key=lambda kv: (kv[1].section, kv[0])):
+        if not spec.hidden:
+            table.add_row(name, spec.section, " ".join(spec.needs), spec.help)
+    console.print(table)
+
+
+@app.command("print")
+def print_setting(name: str) -> None:
+    """Print one resolved setting, replacing make's ``print-%`` pattern rule.
+
+    Args:
+        name: A config field, spelled either way -- ``source_folder`` or ``SOURCE_FOLDER``.
+
+    Raises:
+        typer.Exit: With status 2 when the setting does not exist.
+    """
+    cfg = Config.load()
+    field = name.removeprefix("RHIZA_").lower().replace("-", "_")
+    if not hasattr(cfg, field):
+        err.print(f"[red]unknown setting: {name}[/red]")
+        raise typer.Exit(2)
+    value = getattr(cfg, field)
+    console.print(" ".join(map(str, value)) if isinstance(value, tuple) else str(value))
+
+
+@app.command("ci-os-matrix")
+def ci_os_matrix() -> None:
+    """Emit the CI OS matrix as a JSON array, for a GitHub Actions matrix input."""
+    print(json.dumps(list(Config.load().ci_os_matrix)))
+
+
+@app.command("shim")
+def shim() -> None:
+    """Print the Makefile that forwards to this CLI.
+
+    ``uvx rhiza-task shim > Makefile`` is the whole migration for a consumer repository:
+    it is what replaces ``.rhiza/rhiza.mk`` and the ten fragments in ``.rhiza/make.d/``.
+    Generated rather than synced, so it cannot drift from the version that produced it.
+    """
+    template = Path(__file__).parent / "templates" / "Makefile"
+    # sys.stdout, not the rich Console: Console word-wraps to the terminal width and
+    # expands tabs, and a Makefile survives neither. A wrapped comment is merely ugly, but
+    # a wrapped recipe line is a syntax error and a tab expanded to spaces stops make
+    # recognising the line as a recipe at all -- so `rhiza-task shim > Makefile` would
+    # write a broken file.
+    sys.stdout.write(template.read_text())
+
+
+@app.command("version")
+def version() -> None:
+    """Print the rhiza-task version."""
+    console.print(__version__)
+
+
+@app.command("run", no_args_is_help=True)
+def run_tasks(
+    names: list[str] = typer.Argument(..., help="Tasks to run, in order"),
+    strict: bool = typer.Option(False, "--strict", help="Treat a skipped gate as a failure"),
+    root: Path | None = typer.Option(None, "--root", help="Repository to operate on"),
+) -> None:
+    """Run one or more tasks, with their prerequisites.
+
+    Args:
+        names: Task names.
+        strict: Fail rather than skip when a gate has nothing to measure.
+        root: Repository root; defaults to the current directory.
+
+    Raises:
+        typer.Exit: With 0 when everything passed, 1 on failure, 2 on a usage error.
+    """
+    try:
+        cfg = Config.load(root=root, strict=strict or None)
+    except ValueError as exc:  # invalid configuration, e.g. typechecker=tpye
+        err.print(f"[red]{exc}[/red]")
+        raise typer.Exit(2) from exc
+
+    try:
+        state = runner.run(names, cfg)
+    except KeyError as exc:
+        err.print(f"[red]{exc.args[0]}[/red]  (try `rhiza-task list`)")
+        raise typer.Exit(2) from exc
+
+    console.print()
+    for result in state.results:
+        colour = STATUS_COLOUR[result.status]
+        detail = f"  [dim]{result.detail}[/dim]" if result.detail else ""
+        console.print(f"[{colour}]{result.status.value:>8}[/{colour}]  {result.name}{detail}")
+    raise typer.Exit(state.exit_code())
+
+
+def main() -> None:
+    """Entry point. A bare ``rhiza-task <task>`` is shorthand for ``rhiza-task run <task>``.
+
+    Not sugar -- it is the compatibility contract. The reusable workflows and the Makefile
+    shim both invoke ``rhiza-task test``, and a consumer's muscle memory is ``make test``.
+    Requiring ``run`` would put a word between the two for no gain.
+    """
+    load_tasks()
+    argv = sys.argv[1:]
+    if argv and argv[0] not in RESERVED and not argv[0].startswith("-"):
+        sys.argv = [sys.argv[0], "run", *argv]
+    app()

rhiza_task/config.py

@@ -0,0 +1,248 @@
+"""Configuration, and the resolution order that replaces make's ``?=`` and ``+=``.
+
+The make layer builds its settings from three overlapping mechanisms: ``?=`` defaults in
+the fragment that owns a setting, ``+=`` accumulation from other fragments
+(``DEPTRY_FOLDERS``, ``LICENSE_IGNORE_PACKAGES``, ``RHIZA_CHECKS``), and a repo-owned
+Makefile or ``local.mk`` assigning over the top. The precedence is a consequence of
+include order, which is why rhiza.mk has to explain that ``-include .rhiza/make.d/*.mk``
+comes last and ``-include local.mk`` last of all.
+
+Here the order is explicit and testable, lowest precedence first:
+
+1. The dataclass defaults below.
+2. ``.rhiza/.env`` -- kept unchanged, because it is already the file consumers edit and
+   the reusable workflows read it too.
+3. ``[tool.rhiza-task]`` in ``pyproject.toml`` -- the new home for what used to require
+   editing a synced ``.mk`` file or shadowing a target.
+4. ``RHIZA_*`` (or bare make-style) environment variables.
+5. Command-line flags.
+
+The ``+=`` accumulators do not survive as a mechanism, and do not need to: every one of
+them was a bundle contributing something it owned, which the task body can now *derive*
+by asking whether the contributing task is registered. See ``tasks/python.py``'s ``deps``
+and ``license``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+from dotenv import dotenv_values
+
+TYPECHECKERS = ("ty", "mypy", "both")
+
+DEFAULT_RHIZA_CHECKS = (
+    "pytest_rhiza.checks.test_readme",
+    "pytest_rhiza.checks.test_release_tags",
+    "pytest_rhiza.checks.test_pyproject",
+    "pytest_rhiza.checks.test_docstrings",
+    "pytest_rhiza.checks.test_readme_validation",
+)
+"""The Python check set, enumerated rather than globbed.
+
+pytest-rhiza ships the Rust and Go modules (``test_cargo_toml``, ``test_go_module``) in
+the same distribution, so ``--pyargs pytest_rhiza.checks`` would collect checks that
+cannot pass here. This is jointview's ``RHIZA_CHECKS`` list, promoted from a shadowed make
+variable to a default: the 60-line override in its Makefile exists only because the make
+layer had nowhere else to put it.
+"""
+
+
+@dataclass
+class Config:
+    """Resolved settings for one repository.
+
+    Field names are the lowercased make variables, so the mapping to what a consumer
+    already knows stays one-to-one and greppable.
+    """
+
+    source_folder: str = "src"
+    tests_folder: str = "tests"
+    marimo_folder: str = "docs/notebooks"
+    book_output: str = "_book"
+    python_version: str = "3.13"
+
+    coverage_fail_under: int = 90
+
+    # ty | mypy | both. python.mk documents that ``both`` masks ty's exit status behind
+    # mypy's, and jointview sets ``ty`` in .rhiza/.env for that reason. The shell ``case``
+    # whose fourth branch validated this is replaced by __post_init__, so a typo now fails
+    # before any tool is provisioned rather than after.
+    typechecker: str = "ty"
+
+    # Matched as substrings -- see ``--partial-match`` in the ``license`` task.
+    license_fail_on: tuple[str, ...] = ("GPL", "LGPL", "AGPL")
+    license_ignore_packages: tuple[str, ...] = ()
+
+    deptry_ignore: tuple[str, ...] = ()
+    mkdocs_extra_packages: tuple[str, ...] = ()
+    zensical_version: str = ">=0.0.36"
+    uv_sync_args: tuple[str, ...] = ("--all-extras", "--all-groups")
+    ci_os_matrix: tuple[str, ...] = ("ubuntu-latest",)
+
+    # Pinned to a tag rather than a branch: a gate that moves under you is not a gate.
+    pytest_rhiza: str = "pytest-rhiza @ git+https://github.com/Jebel-Quant/pytest-rhiza@v0.2.0"
+    rhiza_checks: tuple[str, ...] = DEFAULT_RHIZA_CHECKS
+
+    # Turns Skip into failure. The answer to jointview's own complaint about "a green gate
+    # measuring nothing": set it in CI and a missing folder is a red build rather than a
+    # yellow line nobody reads.
+    strict: bool = False
+
+    root: Path = field(default_factory=Path.cwd)
+
+    def __post_init__(self) -> None:
+        """Validate the enumerated and numeric fields.
+
+        Raises:
+            ValueError: When ``typechecker`` is not one of ty, mypy, both, or
+                ``coverage_fail_under`` is outside 0-100.
+        """
+        if self.typechecker not in TYPECHECKERS:
+            msg = f"typechecker must be one of {', '.join(TYPECHECKERS)} (got {self.typechecker!r})"
+            raise ValueError(msg)
+        if not 0 <= int(self.coverage_fail_under) <= 100:
+            msg = f"coverage_fail_under must be a percentage (got {self.coverage_fail_under!r})"
+            raise ValueError(msg)
+
+    @property
+    def folders(self) -> dict[str, str]:
+        """Return the folder settings, for :meth:`~rhiza_task.spec.Guard.check`.
+
+        Returns:
+            Mapping of field name to configured relative path.
+        """
+        return {f.name: getattr(self, f.name) for f in fields(self) if f.name.endswith("_folder")}
+
+    def path(self, folder_field: str) -> Path:
+        """Resolve a folder field to an absolute path.
+
+        Args:
+            folder_field: A field name such as ``source_folder``.
+
+        Returns:
+            The absolute path.
+        """
+        return self.root / getattr(self, folder_field)
+
+    @classmethod
+    def load(cls, root: Path | None = None, **overrides: Any) -> Config:
+        """Build a config by walking the five layers in order.
+
+        Args:
+            root: Repository root; defaults to the current directory.
+            **overrides: Layer 5, the command-line flags. ``None`` values are ignored so
+                an unset flag does not shadow a configured value.
+
+        Returns:
+            The resolved config.
+        """
+        root = (root or Path.cwd()).absolute()
+        raw: dict[str, Any] = {}
+        raw.update(_from_env_file(root / ".rhiza" / ".env"))
+        raw.update(_from_pyproject(root / "pyproject.toml"))
+        raw.update(_from_environ(os.environ))
+        raw.update({k: v for k, v in overrides.items() if v is not None})
+
+        # .python-version wins over a configured python_version for the reason python.mk
+        # reads it: it is what uv itself honours, so a second source of truth could only
+        # ever disagree.
+        pv = root / ".python-version"
+        if pv.is_file() and (text := pv.read_text().strip()):
+            raw["python_version"] = text
+
+        known = {f.name for f in fields(cls)} - {"root"}
+        return cls(root=root, **{k: v for k, v in raw.items() if k in known})
+
+
+def _from_env_file(path: Path) -> dict[str, Any]:
+    """Read ``.rhiza/.env``.
+
+    Args:
+        path: Path to the dotenv file.
+
+    Returns:
+        Parsed settings; empty when the file is absent.
+    """
+    if not path.is_file():
+        return {}
+    return {_key(k): _coerce(v) for k, v in dotenv_values(path).items() if v is not None}
+
+
+def _from_pyproject(path: Path) -> dict[str, Any]:
+    """Read ``[tool.rhiza-task]``.
+
+    Values here are already typed by TOML, so they bypass :func:`_coerce` -- a TOML array
+    arrives as a list and is tupled, nothing is parsed out of a string.
+
+    Args:
+        path: Path to pyproject.toml.
+
+    Returns:
+        Parsed settings; empty when the file or the table is absent.
+    """
+    if not path.is_file():
+        return {}
+    table = tomllib.loads(path.read_text()).get("tool", {}).get("rhiza-task", {})
+    return {k.replace("-", "_"): tuple(v) if isinstance(v, list) else v for k, v in table.items()}
+
+
+def _from_environ(environ: Mapping[str, str]) -> dict[str, Any]:
+    """Read settings from the process environment.
+
+    Both ``RHIZA_CI_OS_MATRIX`` and bare ``SOURCE_FOLDER`` are accepted, because the
+    reusable workflows currently pass bare make-style names on the command line and those
+    jobs must keep working through the transition.
+
+    Args:
+        environ: The environment mapping.
+
+    Returns:
+        Parsed settings.
+
+    """
+    known = {f.name for f in fields(Config)}
+    return {_key(k): _coerce(v) for k, v in environ.items() if _key(k) in known}
+
+
+def _key(name: str) -> str:
+    """Normalise a make-style variable name to a field name.
+
+    Args:
+        name: e.g. ``RHIZA_CI_OS_MATRIX`` or ``SOURCE_FOLDER``.
+
+    Returns:
+        e.g. ``ci_os_matrix``, ``source_folder``.
+    """
+    return name.removeprefix("RHIZA_").lower()
+
+
+def _coerce(value: str) -> Any:
+    """Turn a string setting into the field's type.
+
+    Three shapes exist in ``.rhiza/.env`` today and all must keep parsing: a JSON array
+    (``RHIZA_CI_OS_MATRIX=["ubuntu-latest","macos-latest"]``), a semicolon-separated list
+    (``LICENSE_FAIL_ON=GPL;LGPL;AGPL``), and a plain scalar.
+
+    Args:
+        value: The raw string.
+
+    Returns:
+        A ``str``, ``int``, ``bool`` or ``tuple[str, ...]``.
+    """
+    value = value.strip()
+    if value.startswith("["):
+        return tuple(json.loads(value))
+    if ";" in value:
+        return tuple(p for p in value.split(";") if p)
+    if value.lower() in {"true", "false"}:
+        return value.lower() == "true"
+    if value.lstrip("-").isdigit():
+        return int(value)
+    return value

rhiza_task/runner.py

@@ -0,0 +1,149 @@
+"""Prerequisite resolution, guard evaluation, and outcome bookkeeping.
+
+Small on purpose. make gave four behaviours for free, and this module is what buys them
+back; nothing else belongs here.
+
+1. **Dedup within one invocation.** Eleven tasks name ``install`` as a prerequisite and
+   ``all`` names eight of those. Without a seen-set, ``rhiza-task all`` would sync the
+   environment eight times.
+2. **Depth-first ordering.** ``book`` needs ``test``, which needs ``install``.
+3. **A failed prerequisite stops its dependents.** As make does, rather than running a
+   gate against a half-built environment.
+4. **A missing prerequisite is not an error.** book.mk declares ``test:: ; @:`` no-op
+   stubs so ``book`` can depend on gates that may not have been synced; here a
+   prerequisite absent from the registry is simply not run, and the stubs are gone.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from .config import Config
+from .spec import REGISTRY, Failed, Skip
+
+
+class Status(StrEnum):
+    """The four outcomes a task can have."""
+
+    OK = "ok"
+    SKIPPED = "skipped"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+
+
+@dataclass(frozen=True)
+class Result:
+    """What happened to one task.
+
+    Attributes:
+        name: The task name.
+        status: Its outcome.
+        detail: Why, for anything other than :attr:`Status.OK`.
+    """
+
+    name: str
+    status: Status
+    detail: str = ""
+
+
+@dataclass
+class Run:
+    """One invocation: the results so far, and the tasks already attempted."""
+
+    results: list[Result] = field(default_factory=list)
+    seen: set[str] = field(default_factory=set)
+
+    @property
+    def failed(self) -> bool:
+        """Whether any task failed or was blocked.
+
+        Returns:
+            True when the invocation should exit non-zero.
+        """
+        return any(r.status in {Status.FAILED, Status.BLOCKED} for r in self.results)
+
+    def status_of(self, name: str) -> Status | None:
+        """Return the recorded status of a task, if it ran.
+
+        Args:
+            name: Task name.
+
+        Returns:
+            The status, or None when the task was not attempted.
+        """
+        return next((r.status for r in self.results if r.name == name), None)
+
+    def exit_code(self) -> int:
+        """Return the aggregate exit status.
+
+        The first real failure's own code is propagated where there is one, so a caller
+        can still distinguish e.g. pytest's exit codes. Blocked-only runs exit 1.
+
+        Returns:
+            0 when nothing failed, else the failing task's exit status.
+        """
+        return 1 if self.failed else 0
+
+
+def run(names: list[str], cfg: Config) -> Run:
+    """Run the named tasks and their prerequisites, in order.
+
+    Args:
+        names: Task names, as typed on the command line.
+        cfg: The resolved config.
+
+    Returns:
+        The completed :class:`Run`.
+
+    Raises:
+        KeyError: When an explicitly requested task does not exist. Only for requested
+            names -- an unknown *prerequisite* is skipped, whereas an unknown request is a
+            typo and should say so.
+    """
+    unknown = [n for n in names if n not in REGISTRY]
+    if unknown:
+        msg = f"unknown task{'s' if len(unknown) > 1 else ''}: {', '.join(unknown)}"
+        raise KeyError(msg)
+
+    run_state = Run()
+    for name in names:
+        _run_one(name, cfg, run_state)
+    return run_state
+
+
+def _run_one(name: str, cfg: Config, state: Run) -> None:
+    """Run one task after its prerequisites, recording the outcome.
+
+    Args:
+        name: Task name.
+        cfg: The resolved config.
+        state: The invocation state, appended to in place.
+    """
+    if name in state.seen or name not in REGISTRY:
+        return
+    state.seen.add(name)
+    spec = REGISTRY[name]
+
+    for need in spec.needs:
+        _run_one(need, cfg, state)
+    blocked = [n for n in spec.needs if state.status_of(n) in {Status.FAILED, Status.BLOCKED}]
+    if blocked:
+        state.results.append(Result(name, Status.BLOCKED, f"prerequisite failed: {', '.join(blocked)}"))
+        return
+
+    try:
+        for guard in spec.guards:
+            guard.check(cfg.root, cfg.folders)
+        spec.run(cfg)
+    except Skip as exc:
+        # The strict switch is the whole reason Skip is a distinct outcome rather than a
+        # warning printed on the way to exit 0.
+        if cfg.strict:
+            state.results.append(Result(name, Status.FAILED, f"skipped under --strict: {exc}"))
+        else:
+            state.results.append(Result(name, Status.SKIPPED, str(exc)))
+    except Failed as exc:
+        state.results.append(Result(name, Status.FAILED, str(exc)))
+    else:
+        state.results.append(Result(name, Status.OK))