ruff: format + lint as a first-class gate

Lands the ruff half of the Python toolchain (plan \xc2\xa7B2).

Config: [tool.ruff] in //:pyproject.toml \xe2\x80\x94 line-length 100, target py314,
src = [meta, tools], select E/F/I/B/UP/SIM/RUF/S. Per-file ignores carve
out S603/S607 for meta/scripts (subprocess calls to first-party tools by
name) and S101/S105/S106/S108/S311 for tests.

Where ruff runs:
- Pre-commit: ruff-check --fix then ruff-format (fix order matters; check
  re-sorts imports, format finishes).
- CI: new `ruff` job mirrors golangci-lint\xe2\x80\x99s shape, uses
  astral-sh/ruff-action with version pinned alongside the Dockerfile ARG.
  Added to build-and-test-per-target.needs to gate merge.
- Devcontainer: installed via uv tool install during image build.
  UV_TOOL_DIR is forced to /usr/local/share/uv-tools so the root-owned
  install is reachable by the vscode user.
- VS Code: charliermarsh.ruff in extensions.json + devcontainer.json;
  settings.json sets ruff as the default Python formatter with
  source.fixAll.ruff + source.organizeImports.ruff as save-time actions.

Renovate: new regex matcher for .github/workflows/*.yml picks up the
`version:` input under `# renovate: ...` (mirrors the Dockerfile pattern),
and a ruff packageRule groups both pins into one PR.

Existing meta/scripts/*.py reformatted by `ruff format` and the four real
findings fixed (SIM102 nested-if, two E501 long error messages, SIM115
NamedTemporaryFile-without-with). Test files\xe2\x80\x99 RUF005 fixed inline.

README: new ruff row in the CI checks table, ruff-check / ruff-format /
uv-lock-fresh rows in the pre-commit table, charliermarsh.ruff in the
recommended extensions, and a `ruff (diagnostics + format)` row in the
on-save table.

Author: Syndic

.devcontainer/Dockerfile

@@ -9,11 +9,23 @@ ARG BUILDIFIER_VERSION=v8.5.1
 # uv: the workspace's Python package manager. Single source of truth for the
 # uv.lock + requirements_lock.txt chain consumed by rules_python's pip.parse
 # and enforced by the `uv-lock-fresh` pre-commit hook. Installed first so
-# later PRs can layer `uv tool install ruff ty pre-commit` on top of it.
+# later layers can layer `uv tool install ruff ty pre-commit` on top of it.
 # Pinned tag bumped by Renovate's docker manager (matches the pattern used in
 # ~/.dotfiles/.devcontainer/Dockerfile).
 COPY --from=ghcr.io/astral-sh/uv:0.11.21 /uv /uvx /usr/local/bin/
 
+# ruff: format + lint. Installed via `uv tool install` so the binary lives in
+# /usr/local/bin and `ruff` is on PATH for the pre-commit hooks and the VS Code
+# extension. UV_TOOL_DIR is forced to a world-readable system location because
+# the install runs as root; the default ~/.local/share/uv would land under
+# /root (mode 700) and the vscode user could not follow the bin/ symlink.
+# Renovate's regex manager tracks RUFF_VERSION via the comment above the ARG.
+# renovate: datasource=pypi depName=ruff
+ARG RUFF_VERSION=0.15.17
+ENV UV_TOOL_BIN_DIR=/usr/local/bin \
+    UV_TOOL_DIR=/usr/local/share/uv-tools
+RUN uv tool install --no-cache "ruff==${RUFF_VERSION}"
+
 RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
         build-essential \
         ca-certificates \

.devcontainer/devcontainer.json

@@ -55,6 +55,7 @@
     "vscode": {
       "extensions": [
         "bazelbuild.vscode-bazel",
+        "charliermarsh.ruff",
         "cnshenj.vscode-task-manager",
         "esbenp.prettier-vscode",
         "github.vscode-github-actions",

.github/workflows/ci.yml

@@ -79,6 +79,21 @@ jobs:
         with:
           working-directory: ${{ matrix.module }}
 
+  # Python's sibling of golangci-lint. Format + lint in one job; config lives in
+  # `[tool.ruff]` in //:pyproject.toml. Renovate's regex manager tracks the
+  # version pin via the comment above (matches the Dockerfile pattern).
+  ruff:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/ruff-action@0ce1b0bf8b818ef400413f810f8a11cdbda0034b # v4.0.0
+        with:
+          # renovate: datasource=pypi depName=ruff
+          version: "0.15.17"
+          args: format --check
+      - run: ruff check
+
   # Build and test runs once per supported target platform, on a runner whose host matches
   # the target. (Running tests natively per platform is the only way (without an emulation
   # layer we do not have) to actually exercise platform-specific code paths and catch regressions
@@ -97,6 +112,7 @@ jobs:
       secrets-check,
       no-cgo-check,
       golangci-lint,
+      ruff,
     ]
     strategy:
       fail-fast: false

.pre-commit-config.yaml

@@ -18,6 +18,23 @@ repos:
         pass_filenames: false
         files: ^(pyproject\.toml|uv\.lock|requirements_lock\.txt)$
 
+      # ruff check first (with --fix), then ruff format — check's import
+      # sorting can produce output the formatter wants to retouch. Both fix in
+      # place; pre-commit re-flags modified files so the user re-stages.
+      - id: ruff-check
+        name: ruff check --fix
+        language: system
+        entry: ruff check --fix
+        pass_filenames: false
+        files: \.py$
+
+      - id: ruff-format
+        name: ruff format
+        language: system
+        entry: ruff format
+        pass_filenames: false
+        files: \.py$
+
       - id: gazelle
         name: gazelle
         language: system

.vscode/extensions.json

@@ -1,6 +1,7 @@
 {
   "recommendations": [
     "bazelbuild.vscode-bazel",
+    "charliermarsh.ruff",
     "esbenp.prettier-vscode",
     "github.vscode-github-actions",
     "golang.go",

.vscode/settings.json

@@ -18,6 +18,14 @@
   "prettier.proseWrap": "always",
   "prettier.trailingComma": "all",
   "python.languageServer": "Default",
+  "// Ruff format-on-save": "charliermarsh.ruff surfaces diagnostics inline; this block makes it the default Python formatter so `editor.formatOnSave` calls ruff format, and runs ruff check --fix + import-organize as save-time code actions. Config is read from `[tool.ruff]` in //:pyproject.toml — single source of truth shared with CI + pre-commit.",
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
   "// Task Manager favorites": "Pins the Bazel build/test tasks to the cnshenj.vscode-task-manager sidebar (recommended in the devcontainer; see devcontainer.json). Names must match the `label` fields in tasks.json. The `UnnaturalDesigns/Workspace/` prefix is Task Manager's own scoping convention.",
   "taskManager.favorites": [
     "UnnaturalDesigns/Workspace/Bazel Build all",

README.md

@@ -159,6 +159,7 @@ Two GitHub Actions workflows run on every push and pull request to `main`.
 | Secrets check                | Always - verifies the `secrets/` directory contains no committed files                             |
 | No-cgo policy check          | Always - rejects `import "C"` and transitive deps that compile C/C++/cgo/SWIG                      |
 | golangci-lint                | After module check passes - runs per Go module                                                     |
+| ruff                         | Always - `ruff format --check` and `ruff check` over all Python                                    |
 | Build and test               | After all checks above pass                                                                        |
 | Coverage                     | After build and test - `bazel coverage //...`, uploads merged lcov to Codecov                      |
 
@@ -181,23 +182,29 @@ each commit. To install:
 pre-commit install
 ```
 
-Only hooks that either fix the problem they detect (`bazel-mod-tidy`, `gazelle`) or prevent unsafe
-content from entering the repo (`check-secrets-dir`) run here. Verification-only checks live in the
-editor instead (see **Editor integration** below) so they can surface findings without blocking a
-commit when you want to switch contexts.
+Only hooks that either fix the problem they detect (`bazel-mod-tidy`, `gazelle`, `uv-lock-fresh`,
+`ruff-check`, `ruff-format`) or prevent unsafe content from entering the repo (`check-secrets-dir`)
+run here. Verification-only checks live in the editor instead (see **Editor integration** below) so
+they can surface findings without blocking a commit when you want to switch contexts.
 
-| Hook                | Triggers on                   |
-| ------------------- | ----------------------------- |
-| `bazel-mod-tidy`    | `go.mod`, `go.work`, `go.sum` |
-| `gazelle`           | `*.go` files                  |
-| `check-secrets-dir` | files under `secrets/`        |
+| Hook                | Triggers on                                  |
+| ------------------- | -------------------------------------------- |
+| `bazel-mod-tidy`    | `go.mod`, `go.work`, `go.sum`                |
+| `uv-lock-fresh`     | `pyproject.toml`, `uv.lock`, `requirements_lock.txt` |
+| `ruff-check`        | `*.py` files                                 |
+| `ruff-format`       | `*.py` files                                 |
+| `gazelle`           | `*.go` files                                 |
+| `check-secrets-dir` | files under `secrets/`                       |
 
 **Editor integration** (via `.vscode/`) - runs the non-fixing checks on save. Works in VS Code and
 VS Code-derived editors (e.g. Google Antigravity). Recommended extensions
 (`.vscode/extensions.json`):
 
 - [`golang.go`](https://marketplace.visualstudio.com/items?itemName=golang.go) - runs
   `golangci-lint` on save at package scope, surfacing inline findings that match what CI enforces.
+- [`charliermarsh.ruff`](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) -
+  surfaces `ruff check` diagnostics inline and applies `ruff format` on save, matching what the CI
+  `ruff` job and the pre-commit hooks enforce.
 - [`emeraldwalk.runonsave`](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave) -
   triggers the repo-health scripts on save.
 - [`ryanluker.vscode-coverage-gutters`](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) -
@@ -206,6 +213,7 @@ VS Code-derived editors (e.g. Google Antigravity). Recommended extensions
 | On-save check        | Triggers on                                |
 | -------------------- | ------------------------------------------ |
 | `golangci-lint`      | `*.go` files                               |
+| `ruff` (diagnostics + format) | `*.py` files                      |
 | `check-go-modules`   | `go.mod`, workflow `.yml`, `.golangci.yml` |
 | `check-go-work`      | `go.mod`, `go.work`                        |
 

meta/scripts/_workspace.py

@@ -14,7 +14,9 @@
 def workspace_root() -> Path:
     result = subprocess.run(
         ["git", "rev-parse", "--show-toplevel"],
-        capture_output=True, text=True, check=True,
+        capture_output=True,
+        text=True,
+        check=True,
     )
     return Path(result.stdout.strip())
 
@@ -27,8 +29,7 @@ def is_skipped(path: Path) -> bool:
     that should never contain repo-managed sources.
     """
     return any(
-        part in _SKIP_DIR_NAMES or part.startswith(_SKIP_DIR_PREFIXES)
-        for part in path.parts
+        part in _SKIP_DIR_NAMES or part.startswith(_SKIP_DIR_PREFIXES) for part in path.parts
     )
 
 
@@ -54,7 +55,7 @@ def col_range(file: Path, lineno: int, needle: str) -> tuple[int, int]:
         line = file.read_text().splitlines()[lineno - 1]
         start = line.index(needle) + 1
         return start, start + len(needle)
-    except (OSError, IndexError, ValueError):
+    except OSError, IndexError, ValueError:
         # bad path / past-EOF lineno / needle-not-on-line all collapse to the same fallback.
         return 1, 2
 

meta/scripts/check_go_modules.py

@@ -19,7 +19,7 @@
 # where rules_python already makes the import resolvable.
 sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 
-from meta.scripts._workspace import col_range, found_modules, workspace_root  # noqa: E402
+from meta.scripts._workspace import col_range, found_modules, workspace_root
 
 
 def workflow_module_lists(
@@ -52,7 +52,7 @@ def workflow_module_lists(
     text = workflow_file.read_text()
     result: list[tuple[str, int, dict[Path, int]]] = []
 
-    state = "scanning"   # scanning | in_matrix | in_module
+    state = "scanning"  # scanning | in_matrix | in_module
     matrix_indent = -1
     module_indent = -1
     module_key_line = -1
@@ -109,9 +109,8 @@ def workflow_module_lists(
                 module_key_line = lineno
                 current = {}
 
-        elif state == "in_module":
-            if stripped.startswith("- "):
-                current[Path(stripped[2:].strip())] = lineno
+        elif state == "in_module" and stripped.startswith("- "):
+            current[Path(stripped[2:].strip())] = lineno
 
     # End of file while still inside a module list.
     if state == "in_module" and current is not None:
@@ -146,7 +145,10 @@ def check_workflow_matrices(root: Path, modules: set[Path]) -> int:
             for mod in sorted(matrix_set - modules):
                 line = matrix_entries[mod]
                 start, end = col_range(wf_file, line, str(mod))
-                print(f"{rel}:{line}:{start}-{end}: [{job_name}] stale matrix entry ./{mod} (no go.mod)")
+                print(
+                    f"{rel}:{line}:{start}-{end}: "
+                    f"[{job_name}] stale matrix entry ./{mod} (no go.mod)"
+                )
                 errors += 1
 
     return errors
@@ -174,7 +176,10 @@ def check_golangci_configs(root: Path, modules: set[Path]) -> int:
             candidate = candidate.parent
         if not found:
             # Anchor on the module's go.mod — no specific token at fault.
-            print(f"{mod}/go.mod:1:1-2: no .golangci.yml reachable from ./{mod} (module dir or any parent up to repo root)")
+            print(
+                f"{mod}/go.mod:1:1-2: no .golangci.yml reachable from ./{mod} "
+                f"(module dir or any parent up to repo root)"
+            )
             errors += 1
     return errors
 

meta/scripts/check_go_work.py

@@ -16,7 +16,7 @@
 # where rules_python already makes the import resolvable.
 sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 
-from meta.scripts._workspace import (  # noqa: E402
+from meta.scripts._workspace import (
     col_range,
     found_modules,
     registered_modules,