python-devkit 0.1.0__tar.gz → 0.1.2__tar.gz

python_devkit-0.1.2/.gitattributes

@@ -0,0 +1 @@
+ruff.base.toml -text

{python_devkit-0.1.0 → python_devkit-0.1.2}/.github/workflows/ci.yml

@@ -28,3 +28,6 @@ jobs:
 
       - name: Type check
         run: uv run basedpyright
+
+      - name: Ruff config drift
+        run: uv run sync-ruff --check

{python_devkit-0.1.0 → python_devkit-0.1.2}/.github/workflows/release.yml

@@ -22,4 +22,4 @@ jobs:
       - uses: astral-sh/setup-uv@v7
 
       - name: Publish
-        run: uvx --from release-devkit==0.1.0 publish-packages --config publish-config.json
+        run: uvx --from release-devkit==0.1.1 publish-packages --config publish-config.json

python_devkit-0.1.2/AGENTS.md

@@ -0,0 +1,33 @@
+# python-devkit
+
+The python repo-lifecycle devkit — workspace locking (`lock-python`), the preflight check runner, and the canonical ruff configuration with its sync verb and drift gate, per the tooling-consolidation program. Purely python-domain by charter: the CI runner floor (step wrapper, runner provisioning, git tags, OCI cache) lives in [`ci-devkit`](https://github.com/outernet-foundation/ci-devkit), which this package depends on (`ci-devkit>=0.1.0`).
+
+The package is `python_devkit` (src-layout under `src/python_devkit/`); all dependencies resolve from PyPI (`bashrun`, `ci-devkit`, `pydantic`, `typer`; git-source pins only in scratch branches testing unreleased changes).
+
+## Shape
+
+Entry point (`[project.scripts]`): `lock-python` → `lock_python.py:app`. The command function doubles as the library API — consumer preflights import `lock_python` and call `lock_python(check=True)` directly.
+
+`lock_python.py` regenerates a uv workspace's `uv.lock` plus per-service `pylock.toml` exports. Discovery: members of `[tool.uv.workspace]` in the root `pyproject.toml` that carry a `Dockerfile`; each gets `pylock.toml` (`--no-default-groups`) and one `pylock.<group>.toml` (`--only-group`) per non-`dev` dependency group. Redirect: a group matching a key of `[tool.python-devkit.lock-python] group-export-dirs` (glob → repo-relative directory) exports into that directory instead of the member's, once, deduplicated across members — the generalization of placeframe's neural-networks accelerator groups, which several members declare identically but only a non-member base image consumes. `--check` compares normalized exports against committed files and exits non-zero on any staleness.
+
+`preflight_runner.py` is the labeled-check runner consumer preflights thin into: `run_checks(checks)` executes a declarative list of `CommandCheck` (label + shell command under a `ci_step` group) and `GeneratedCheck` (label + generate command + pathspec + fix command — runs the generator, then fails on any `git status --porcelain` dirt under the paths, showing the diff and the fix command). Fail-fast; each check's duration lands in the Actions step summary via `ci_step`.
+
+`sync_ruff.py` writes the org-canonical ruff config (`src/python_devkit/ruff.base.toml`, shipped as package data) into a consuming repo's root as `ruff.base.toml`; `--check` is the drift gate (byte compare against the packaged canonical). The verb also validates the consuming repo's `ruff.toml` layer: it must set `extend = "ruff.base.toml"` and use only extend keys — plain `exclude`/`lint.select`/`lint.ignore`/`lint.per-file-ignores` in the layer replace the canonical settings under `extend` and fail the check. This repo consumes its own canonical the same way: root `ruff.base.toml` is a verb-written copy of the packaged one, root `ruff.toml` is the (currently empty) local layer.
+
+## Constraints
+
+- **The module surface is cross-repo Python API.** `python_devkit.lock_python.lock_python(check, root)` and `python_devkit.preflight_runner.run_checks(checks)` are contract: placeframe's preflight calls both in-process, the lock-python entry point is on CI's path, and the `[tool.python-devkit.lock-python]` table in consumer root pyprojects is its declarative config surface.
+- **The canonical ruff body is byte-stable contract.** Every consuming repo's `ruff.base.toml` is a verbatim copy compared byte-for-byte (after newline normalization); a cosmetic edit to the canonical ripples into every consumer's diff by design. Repo-local deltas never go here — they go in the consumer's `ruff.toml` extend layer.
+- **`group-export-dirs` is devkit-owned and `extra="forbid"`.** A typo'd key in that table fails validation loudly rather than silently dropping the redirect (the failure mode is per-group pylocks appearing in member directories).
+- **The redirect contract assumes identical group declarations.** Dedup is first-member-wins; members declaring the same redirected group differently get whichever member enumerates first, silently.
+- **Export commands are byte-stability load-bearing.** The exact `uv export` flag order must not churn — committed pylocks are compared byte-for-byte (after newline normalization), so a cosmetic flag change ripples into every consumer's diff.
+- **uv invocations run with `cwd=root`.** `--root` (default: current directory) exists so the verb and the library call work from anywhere; the uv commands themselves must execute inside the workspace root.
+
+## Release flow
+
+`release.yml` (workflow_run-gated on CI) publishes via release-devkit uvx-isolated under OIDC trusted publishing (publisher bound to `release.yml`, no environment); the first release is 0.1.0 on the fresh `python-devkit-v*` tag ledger. The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the tags are the version ledger. API-breaking changes ship with a manually bumped version — patch-auto assumes additive changes.
+
+## See also
+
+- `README.md` — human-facing overview.
+- [tooling-consolidation.md](https://github.com/outernet-foundation/placeframe/blob/dev/design/tooling-consolidation.md) — the program this repo belongs to.

python_devkit-0.1.2/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: python-devkit
+Version: 0.1.2
+Summary: Python repo-lifecycle tooling: workspace locking, preflight checks, canonical ruff configuration
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.13
+Requires-Dist: bashrun>=0.1.0
+Requires-Dist: ci-devkit>=0.1.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: typer>=0.17.4

python_devkit-0.1.2/README.md

@@ -0,0 +1,61 @@
+# python-devkit
+
+Python repo-lifecycle tooling shared across outernet-foundation repos: workspace locking (`lock-python`), the preflight check runner, and the canonical ruff configuration with its sync verb and drift gate. Sibling of `ci-devkit` (the CI runner floor it will depend on), `unity-devkit`, `docker-devkit`, and `release-devkit`.
+
+## lock-python
+
+Regenerates a uv workspace's `uv.lock` and the per-service `pylock.toml` exports consumed by service Dockerfiles:
+
+```bash
+uv run lock-python           # write: uv lock + every export
+uv run lock-python --check   # validate; exit 1 on any stale lock
+```
+
+For every workspace member that carries a `Dockerfile`, it exports `pylock.toml` (no default groups) plus one `pylock.<group>.toml` per non-`dev` dependency group. Dependency groups whose names match a pattern in the root `pyproject.toml`'s `[tool.python-devkit.lock-python] group-export-dirs` map export into the mapped directory instead, once, deduplicated across members — e.g. placeframe's accelerator groups:
+
+```toml
+[tool.python-devkit.lock-python]
+group-export-dirs = { "neural-networks-*" = "docker/neural-networks-base" }
+```
+
+## preflight runner
+
+Consumer preflights thin into a declarative check list over `run_checks`:
+
+```python
+from python_devkit.preflight_runner import CommandCheck, GeneratedCheck, run_checks
+
+run_checks([
+    CommandCheck(label="Lint", command="uv run ruff check ."),
+    GeneratedCheck(
+        label="Check client codegen",
+        generate_command="uv run generate-clients",
+        paths=[Path("packages/generated/")],
+        fix_command="uv run generate-clients",
+    ),
+])
+```
+
+`CommandCheck` wraps a shell command in a labeled CI step group; `GeneratedCheck` additionally guards the checked-in generator output with a git-status staleness check (diff shown, fix command named). Checks run fail-fast with per-step durations in the Actions step summary.
+
+## ruff canonical config
+
+`src/python_devkit/ruff.base.toml` is the org-canonical ruff configuration. Consuming repos carry it verbatim as `ruff.base.toml` at their root, with a hand-owned `ruff.toml` beside it layering repo-local deltas on top:
+
+```bash
+uvx --from python-devkit sync-ruff           # write/refresh ruff.base.toml
+uvx --from python-devkit sync-ruff --check   # drift gate: exit 1 on divergence
+```
+
+The consuming `ruff.toml` must set `extend = "ruff.base.toml"` and may only add via extend keys (`extend-exclude`, `lint.extend-ignore`, `lint.extend-per-file-ignores`) — plain `exclude`, `lint.select`, `lint.ignore`, and `lint.per-file-ignores` replace the canonical settings under `extend`, and `--check` fails on them. To change the canonical: edit it here, release, and run `sync-ruff` in every consuming repo.
+
+## Development
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+```

{python_devkit-0.1.0 → python_devkit-0.1.2}/pyproject.toml

@@ -1,14 +1,19 @@
 [project]
 name = "python-devkit"
-version = "0.1.0"
-description = "Python repo-lifecycle tooling: CI step wrapper, runner provisioning, workspace locking, preflight checks"
+version = "0.1.2"
+description = "Python repo-lifecycle tooling: workspace locking, preflight checks, canonical ruff configuration"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",
+    "ci-devkit>=0.1.0",
     "pydantic>=2.11.7",
-    "pydantic-settings>=2.9.1",
+    "typer>=0.17.4",
 ]
 
+[project.scripts]
+lock-python = "python_devkit.lock_python:app"
+sync-ruff = "python_devkit.sync_ruff:app"
+
 [dependency-groups]
 dev = ["basedpyright>=1.39.10", "ruff>=0.14.11"]
 
@@ -18,7 +23,7 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/python_devkit"]
-include = ["src/python_devkit/py.typed", "src/python_devkit/third-party/**"]
+include = ["src/python_devkit/py.typed", "src/python_devkit/ruff.base.toml"]
 
 [tool.uv.sources]
 

python_devkit-0.1.2/ruff.base.toml

@@ -0,0 +1,198 @@
+# Org-canonical ruff configuration, hosted in python-devkit.
+# Consuming repos carry this file verbatim as ruff.base.toml, written by the
+# sync-ruff verb (uvx --from python-devkit sync-ruff) and drift-gated in CI.
+# Never edit a synced copy: change this canonical, release python-devkit, and
+# re-run sync-ruff in each consuming repo.
+target-version = "py313"
+line-length = 120
+preview = true
+required-version = ">=0.14.11"
+
+[lint]
+select = ["ALL"]
+ignore = [
+    # ── Temporarily ignored (inline noqas exist for these rules but are redundant
+    # while the rules are globally ignored — RUF100 suppresses the "unused noqa" warning
+    # until we un-ignore each ticket's rules)
+    "RUF100",
+
+    # ── Permanently ignored ──────────────────────────────────────────────
+    # Type annotations — basedpyright strict mode handles this
+    "ANN",
+    # EM101 (string literal in exception) — the msg = ... indirection adds verbosity without benefit
+    "EM101",
+    # TRY003 (raise vanilla args) — requires custom exception class for every raise site;
+    # the real problem (interpolation) is caught by EM102/EM103
+    "TRY003",
+    # A003 (class attribute shadowing) — class attributes via self.x never conflict with builtins
+    "A003",
+    # Function complexity counting — C901 already covers structural complexity;
+    # these counting rules are largely redundant
+    "PLR0911",
+    "PLR0912",
+    "PLR0913",
+    "PLR0914",
+    "PLR0915",
+    "PLR0917",
+
+    # ── Temporarily ignored (will enable when conventions are established) ─
+    # Docstrings — project policy is "no docstrings" for now
+    "D",
+    # Copyright notices — not yet established
+    "CPY",
+    # Docstring formatting — blocked on D
+    "DOC",
+    # TODO/FIXME comment formatting
+    "TD",
+    "FIX",
+
+    # The "Ticket N" blocks below are the transitional cleanup slices tracked
+    # by PLE-248 (Enforce the deferred ruff rules):
+    #   https://linear.app/plerionplatforms/issue/PLE-248
+    # Ticket 3 (T201, print → logging) is tracked by PLE-336:
+    #   https://linear.app/plerionplatforms/issue/PLE-336
+    # Lifting a rule = remove it here in python-devkit's canonical config,
+    # release, and run sync-ruff in every consuming repo.
+
+    # ── Ticket 1: Auto-fix formatting & type modernization ───────────────
+    # Zero risk. Purely mechanical, all auto-fixable via ruff --fix.
+    "COM812",   # missing trailing commas
+    "I001",     # import sorting
+    "ISC003",   # explicit string concatenation
+    "RUF031",   # parenthesized tuple in subscript
+    "TC001",    # move import into TYPE_CHECKING block
+    "TC002",    # move third-party import into TYPE_CHECKING block
+    "TC003",    # move stdlib import into TYPE_CHECKING block
+    "TC006",    # move typing import into TYPE_CHECKING block (PEP 695)
+    "TC008",    # move import into TYPE_CHECKING block (quoted annotation)
+    "UP006",    # use X instead of typing.X
+    "UP007",    # use X | Y instead of Union
+    "UP011",    # unnecessary parentheses to functools.lru_cache
+    "UP015",    # unnecessary open mode parameters
+    "UP017",    # use datetime.UTC alias
+    "UP034",    # extraneous parentheses
+    "UP035",    # deprecated import (use collections.abc, etc.)
+    "UP040",    # use PEP 695 type alias
+    "UP042",    # use PEP 695 type parameters
+    "UP045",    # use X | None instead of Optional
+
+    # ── Ticket 2: Auto-fix code simplifications ──────────────────────────
+    # Very low risk. Auto-fixable with trivial semantic changes.
+    "C401",     # unnecessary generator — use set/dict comprehension
+    "C416",     # unnecessary comprehension — use list/dict
+    "ERA001",   # commented-out code
+    "FURB101",  # read-text can replace open+read
+    "FURB103",  # write-text can replace open+write
+    "FURB110",  # use ternary instead of try/except for default
+    "FURB113",  # use list.extend instead of repeated append
+    "FURB118",  # use operator module instead of lambda
+    "LOG004",   # use __name__ as logger name
+    "PERF401",  # use list comprehension instead of manual append
+    "PIE810",   # unnecessary spread of single-element starred
+    "PLC0207",  # use a single __all__ definition
+    "PLC1901",  # compare to empty string using falsy check
+    "PLR1711",  # useless return at end of function
+    "PLR6104",  # use augmented assignment
+    "PLR6201",  # use a set literal for membership test
+    "PLW1510",  # subprocess.run without explicit check= argument
+    "PLW1514",  # open without explicit encoding
+    "PT001",    # use @pytest.fixture over @pytest.fixture()
+    "PT018",    # composite assertion — split into multiple asserts
+    "PTH101",   # os.chmod → Path.chmod
+    "PTH111",   # os.path.expanduser → Path.expanduser
+    "PTH112",   # os.path.isdir → Path.is_dir
+    "PTH118",   # os.path.join → Path /
+    "PTH123",   # open() → Path.open()
+    "PTH201",   # pathlib.Path(".")
+    "RET501",   # unnecessary explicit return None
+    "RET504",   # unnecessary assignment before return
+    "RET505",   # unnecessary else after return
+    "RET506",   # unnecessary else after raise
+    "RET507",   # unnecessary else after continue
+    "RSE102",   # unnecessary parentheses on raised exception
+    "RUF005",   # consider spread operator instead of concatenation
+    "RUF010",   # use explicit conversion flag in f-string
+    "RUF015",   # prefer next() over single-element slice
+    "RUF029",   # function is declared async but has no await
+    "RUF052",   # local variable is assigned but never used (underscore prefix)
+    "RUF056",   # unnecessary default value for keyword argument
+    "SIM102",   # collapsible if statements
+    "SIM105",   # use contextlib.suppress instead of try/except/pass
+    "SIM115",   # use context manager for opening files
+    "SIM117",   # use single with statement for multiple context managers
+    "SIM118",   # use key in dict instead of key in dict.keys()
+    "TID252",   # prefer absolute imports over relative
+
+    # ── Ticket 3: print → logging ────────────────────────────────────────
+    # All code should use logging, including CLI scripts.
+    "T201",     # print found
+
+    # ── Ticket 4: Exception message interpolation ────────────────────────
+    # Remove f-strings from exception messages — use string literals.
+    "EM102",    # f-string in exception message
+
+    # ── Ticket 5: Missing __init__.py + shebangs ─────────────────────────
+    # Add __init__.py to installable packages; remove vestigial shebangs.
+    "INP001",   # implicit namespace package — add __init__.py
+    "EXE001",   # shebang present but file not executable
+
+    # ── Ticket 6: Type ignore specificity ────────────────────────────────
+    # Replace blanket type: ignore with specific error codes.
+    "PGH003",   # blanket type: ignore
+
+    # ── Ticket 7: Boolean trap refactoring ───────────────────────────────
+    # Change function signatures — callers must update too.
+    "FBT001",   # boolean positional argument
+    "FBT002",   # boolean default value in function definition
+    "FBT003",   # boolean positional value in call
+
+    # ── Ticket 8: Exception handling patterns ────────────────────────────
+    # Behavioral changes to error handling.
+    "B020",     # loop variable overwritten by except
+    "B903",     # generator should use yield from
+    "B904",     # raise without from inside except
+    "B905",     # zip() without strict= parameter
+    "BLE001",   # blind except Exception
+    "S101",     # assert outside tests
+    "TRY002",   # create custom exception class
+    "TRY300",   # try/except/return — move return into else
+
+    # ── Ticket 9: Complexity, naming & refactoring ───────────────────────
+    # Structural changes requiring judgment.
+    "A001",     # builtin shadowing (dir, bytes)
+    "ARG001",   # unused function argument
+    "ARG002",   # unused method argument
+    "C901",     # function too complex
+    "E501",     # line too long
+    "N802",     # function name should be lowercase
+    "N806",     # variable in function should be lowercase
+    "N815",     # mixed-case variable in class scope
+    "N818",     # exception name should end in Error
+    "PLC0415",  # import not at top level
+    "PLE0704",  # bare raise not inside except handler
+    "PLR1702",  # too many nested blocks
+    "PLR2004",  # magic value used in comparison
+    "PLR6301",  # method could be function or static method
+    "PLW0603",  # global statement
+    "PLW2901",  # loop variable overwritten
+    "RUF001",   # ambiguous unicode — replace with ASCII
+    "RUF003",   # ambiguous unicode in comment
+    "S106",     # possible hardcoded password
+    "S108",     # probable insecure temp file/dir usage
+    "S110",     # try/except/pass on broad exception
+    "S202",     # use of tarfile.extractall
+    # S404/S603: prerequisite — bash.py needs env, stderr=STDOUT merge, and no-raise-with-capture
+    # before context_sha.py, deptry_check.py, test_context_sha.py, list_debug_targets.py can migrate
+    "S404",     # suspicious subprocess import
+    "S603",     # subprocess call with non-literal
+    "S606",     # starting process without shell
+    "S607",     # starting process with partial path
+]
+
+[lint.per-file-ignores]
+# Tests use assert as the standard pytest mechanism; fixtures take arguments
+# that pytest consumes implicitly; pytest-style test classes need no self use
+"**/tests/**" = ["S101", "ARG001", "ARG002", "PLR6301"]
+
+[lint.flake8-builtins]
+ignorelist = ["id", "map"]

python_devkit-0.1.2/ruff.toml

@@ -0,0 +1 @@
+extend = "ruff.base.toml"

python_devkit-0.1.2/src/python_devkit/lock_python.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from fnmatch import fnmatch
+from pathlib import Path
+from tomllib import load
+from typing import Annotated, Any
+
+import typer
+from bashrun import bash, bash_check, bash_output
+from pydantic import BaseModel, ConfigDict, Field
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+
+class LockPythonConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    group_export_dirs: dict[str, Path] = Field(default_factory=dict, alias="group-export-dirs")
+
+
+class WorkspaceConfig(BaseModel):
+    members: list[str] = Field(default_factory=list)
+
+
+class ProjectConfig(BaseModel):
+    name: str
+
+
+class PackageConfig(BaseModel):
+    project: ProjectConfig
+    dependency_groups: dict[str, Any] = Field(default_factory=dict, alias="dependency-groups")
+
+
+@app.command()
+def lock_python(
+    check: Annotated[
+        bool, typer.Option("--check", help="Validate lock files without writing; exit non-zero if stale.")
+    ] = False,
+    root: Annotated[Path, typer.Option(help="uv workspace root; defaults to the current directory.")] = Path(),
+) -> None:
+    root = root.resolve()
+    stale = False
+
+    if check:
+        print("Checking uv.lock...")
+        if not bash_check("uv lock --check", cwd=root):
+            print("  STALE: uv.lock is out of date. Run 'uv run lock-python' to update.")
+            stale = True
+        else:
+            print("  OK")
+    else:
+        bash("uv lock", cwd=root)
+
+    with (root / "pyproject.toml").open("rb") as file:
+        workspace_toml = load(file)
+
+    tool = workspace_toml.get("tool", {})
+    workspace = WorkspaceConfig.model_validate(tool.get("uv", {}).get("workspace", {}))
+    config = LockPythonConfig.model_validate(tool.get("python-devkit", {}).get("lock-python", {}))
+
+    seen_redirected: set[str] = set()
+
+    for member in workspace.members:
+        member_dir = root / member
+
+        if not (member_dir / "Dockerfile").exists():
+            continue
+
+        with (member_dir / "pyproject.toml").open("rb") as file:
+            package = PackageConfig.model_validate(load(file))
+
+        stale |= _export_pylock(check, root, member_dir, package.project.name, group=None)
+
+        for group in package.dependency_groups:
+            if group == "dev":
+                continue
+            redirect = _redirect_dir(group, config, root)
+            if redirect is None:
+                stale |= _export_pylock(check, root, member_dir, package.project.name, group=group)
+                continue
+            if group in seen_redirected:
+                continue
+            seen_redirected.add(group)
+            stale |= _export_pylock(check, root, redirect, package.project.name, group=group)
+
+    if check and stale:
+        raise SystemExit(1)
+
+    if check:
+        print("\nAll Python lock files are up to date.")
+
+
+def _export_pylock(check: bool, root: Path, export_dir: Path, package_name: str, group: str | None) -> bool:
+    if group:
+        pylock = export_dir / f"pylock.{group}.toml"
+        group_flags = f"--only-group {group} "
+    else:
+        pylock = export_dir / "pylock.toml"
+        group_flags = "--no-default-groups "
+
+    export_command = (
+        f"uv export --format pylock.toml --no-header --package {package_name} {group_flags}--no-emit-local --frozen "
+    )
+
+    if check:
+        print(f"Checking {pylock}...")
+        exported = _normalize_line_endings(bash_output(export_command, cwd=root))
+        committed = _normalize_line_endings(pylock.read_text(encoding="utf-8")) if pylock.exists() else ""
+        if exported != committed:
+            print(f"  STALE: {pylock} is out of date.")
+            return True
+        print("  OK")
+        return False
+
+    bash(export_command + f"--output-file {pylock} ", cwd=root)
+    text = pylock.read_text(encoding="utf-8")
+    with pylock.open("w", encoding="utf-8", newline="\n") as file:
+        file.write(text)
+    return False
+
+
+def _normalize_line_endings(text: str) -> str:
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def _redirect_dir(group: str, config: LockPythonConfig, root: Path) -> Path | None:
+    for pattern, directory in config.group_export_dirs.items():
+        if fnmatch(group, pattern):
+            return root / directory
+    return None

python_devkit-0.1.2/src/python_devkit/preflight_runner.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from bashrun import bash, bash_output
+from ci_devkit.ci_step import ci_step
+from pydantic import BaseModel
+
+
+class CommandCheck(BaseModel):
+    label: str
+    command: str
+
+
+class GeneratedCheck(BaseModel):
+    label: str
+    generate_command: str
+    paths: list[Path]
+    fix_command: str
+
+
+def run_checks(checks: Sequence[CommandCheck | GeneratedCheck], *, cwd: Path | None = None) -> None:
+    for check in checks:
+        if isinstance(check, CommandCheck):
+            _run_command_check(check, cwd)
+        else:
+            _run_generated_check(check, cwd)
+
+
+def _run_command_check(check: CommandCheck, cwd: Path | None) -> None:
+    with ci_step(check.label):
+        bash(check.command, cwd=cwd)
+
+
+def _run_generated_check(check: GeneratedCheck, cwd: Path | None) -> None:
+    with ci_step(check.label):
+        bash(check.generate_command, cwd=cwd)
+        pathspec = " ".join(str(path) for path in check.paths)
+        staleness_output = bash_output(f"git status --porcelain -- {pathspec}", cwd=cwd)
+        if staleness_output.strip():
+            bash(f"git diff -- {pathspec}", cwd=cwd)
+            raise SystemExit(f"{check.label} output is stale. Run '{check.fix_command}' locally and commit the result.")