DEV: add Claude Code ruff hooks (auto-format on edit + pre-push lint guard) (#1046)

Recurring red on the Linters CI job (all ruff-format failures) motivated
two project-level Claude Code hooks, wired in .claude/settings.json:

- PostToolUse (Edit|Write|MultiEdit): ruff_on_edit.py runs `ruff format` +
  `ruff check --fix` on the edited .py file (~instant), keeping edits clean.
- PreToolUse (Bash): ruff_guard_push.py blocks `git push` when `ruff check`
  or `ruff format --check` would fail, before it turns CI red.

Both invoke ruff as `<python> -m ruff`, are cross-platform (pure Python, no
shell/OS-specific paths), and no-op when ruff is not installed. Pylint stays
in CI only (too slow per-file for an interactive guard). See
.claude/hooks/README.md.

Author: Gui-FernandesBR

.claude/hooks/README.md

@@ -0,0 +1,40 @@
+# Claude Code hooks
+
+Project-level [Claude Code hooks](https://docs.claude.com/en/docs/claude-code/hooks)
+that keep Claude's edits lint-clean and stop lint failures from reaching CI. They
+are wired up in [`.claude/settings.json`](../settings.json) and run automatically
+for anyone using Claude Code in this repo.
+
+Both hooks only run **ruff** (the fast linter/formatter, ~0.15s for the whole
+repo). Pylint is intentionally left to CI: on this codebase its per-file startup
+cost is seconds, too slow for an interactive guard. ruff is also what has actually
+been breaking the `Linters` job.
+
+## Hooks
+
+| Hook | Event | What it does |
+| --- | --- | --- |
+| [`ruff_on_edit.py`](ruff_on_edit.py) | `PostToolUse` on `Edit`/`Write`/`MultiEdit` | After Claude edits a `.py` file, runs `ruff format` then `ruff check --fix` on that one file. Surfaces any unfixable lint issues back to Claude. |
+| [`ruff_guard_push.py`](ruff_guard_push.py) | `PreToolUse` on `Bash` | Before a `git push`, runs `ruff check` + `ruff format --check` over the repo and **blocks the push** if either would fail (i.e. before it turns CI red). |
+
+## Design guarantees
+
+- **Cross-platform** (Windows / macOS / Linux): pure Python, no shell built-ins,
+  no OS-specific paths. ruff is invoked as `<current python> -m ruff` so it
+  resolves to the same environment the hook runs in.
+- **Never gets in the way**: if `ruff` is not installed, both hooks are a silent
+  no-op. The push guard only acts on actual `git push` commands.
+
+## Requirements
+
+A working `python` on `PATH` (an activated virtualenv is the normal setup) with
+`ruff` installed: `pip install ruff` — already included in `pip install .[tests]`.
+
+## Testing a hook manually
+
+Pipe a sample event payload to a hook on stdin:
+
+```bash
+printf '{"tool_input":{"file_path":"some_file.py"}}' | python .claude/hooks/ruff_on_edit.py
+printf '{"tool_input":{"command":"git push"}}'      | python .claude/hooks/ruff_guard_push.py
+```

.claude/hooks/ruff_guard_push.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Claude Code ``PreToolUse`` hook: block ``git push`` if ruff would fail in CI.
+
+Runs before every ``Bash`` command. If the command is a ``git push``, it runs the
+two fast ruff steps from the Linters CI job (``ruff check .`` and
+``ruff format --check .``) over the repo. If either would fail, the push is
+blocked (exit code 2) and the failure is reported back to Claude so it gets fixed
+*before* it turns the CI red.
+
+Only ruff runs here (both steps together are ~0.15s). Pylint is intentionally left
+to CI: on this repo pylint costs seconds-per-file of startup, which is too slow for
+an interactive guard. ruff is what has actually been breaking the Linters job.
+
+Design notes
+------------
+* ruff is invoked as ``<current python> -m ruff`` (see ``ruff_on_edit.py``).
+* Cross-platform: pure Python, no shell built-ins, no OS-specific paths.
+* Silent no-op when the command is not a push, or when ruff is not installed.
+"""
+
+import importlib.util
+import json
+import os
+import re
+import subprocess
+import sys
+
+# Match ``git push`` as a real command (start of line or after a shell
+# separator), tolerating global flags like ``git -C . push``. Avoids most
+# false positives from the substring "push" appearing elsewhere.
+_GIT_PUSH = re.compile(r"(?:^|[\s;&|(`])git(?:\s+-\S+|\s+--\S+)*\s+push\b")
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+
+    command = (payload.get("tool_input") or {}).get("command", "")
+    if not isinstance(command, str) or not _GIT_PUSH.search(command):
+        return 0
+
+    if importlib.util.find_spec("ruff") is None:
+        return 0  # ruff not installed: don't block pushes.
+
+    # Target the project root explicitly. ``CLAUDE_PROJECT_DIR`` is set by Claude
+    # Code to the native-format project root; passing it as a path argument (not
+    # as the subprocess ``cwd``) keeps this robust across platforms/shells. Falls
+    # back to ".", which resolves against the hook's working directory.
+    target = os.environ.get("CLAUDE_PROJECT_DIR") or "."
+    ruff = [sys.executable, "-m", "ruff"]
+    check = subprocess.run(ruff + ["check", target], capture_output=True, text=True)
+    fmt = subprocess.run(
+        ruff + ["format", "--check", target], capture_output=True, text=True
+    )
+    if check.returncode == 0 and fmt.returncode == 0:
+        return 0
+
+    out = [
+        "[ruff] Push blocked — this would fail the Linters CI job. "
+        "Fix the issues below, then push again.\n"
+    ]
+    if check.returncode != 0:
+        out.append("--- ruff check ---\n" + (check.stdout or "") + (check.stderr or ""))
+    if fmt.returncode != 0:
+        out.append(
+            "--- ruff format --check . ---\n"
+            + (fmt.stdout or "")
+            + (fmt.stderr or "")
+            + "\nFix formatting with:  python -m ruff format .\n"
+        )
+    sys.stderr.write("\n".join(out))
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.claude/hooks/ruff_on_edit.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Claude Code ``PostToolUse`` hook: auto-format + lint-fix edited Python files.
+
+Runs after every ``Edit``/``Write``/``MultiEdit``. Reads the hook payload from
+stdin, and if the touched file is a ``.py`` file, runs ``ruff format`` followed by
+``ruff check --fix`` on *just that one file*. ruff is ~instant per file, so this
+keeps Claude's edits continuously formatted and lint-clean without slowing the
+session down.
+
+Design notes
+------------
+* ruff is invoked as ``<current python> -m ruff`` so it always resolves to the
+  same environment the hook runs in (matches the ``python -m ruff`` convention
+  the repo already uses) instead of relying on a ``ruff`` binary being on PATH.
+* Cross-platform: pure Python, no shell built-ins, no OS-specific paths.
+* Degrades to a silent no-op when ruff is not installed, so it can never block
+  editing for a contributor who has not installed the linter yet.
+* Exit code 2 feeds any *unfixable* lint issues back to Claude so it fixes them;
+  the common case (format + autofix succeed) exits 0 silently.
+"""
+
+import importlib.util
+import json
+import subprocess
+import sys
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+
+    tool_input = payload.get("tool_input") or {}
+    file_path = tool_input.get("file_path")
+    if not isinstance(file_path, str) or not file_path.endswith(".py"):
+        return 0
+
+    if importlib.util.find_spec("ruff") is None:
+        # ruff not installed in this environment: never block the workflow.
+        return 0
+
+    ruff = [sys.executable, "-m", "ruff"]
+    subprocess.run(ruff + ["format", file_path], capture_output=True, text=True)
+    fix = subprocess.run(
+        ruff + ["check", "--fix", file_path], capture_output=True, text=True
+    )
+
+    if fix.returncode != 0:
+        sys.stderr.write(
+            f"[ruff] Lint issues ruff could not auto-fix in {file_path}:\n"
+            f"{fix.stdout}{fix.stderr}"
+        )
+        return 2
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.claude/settings.json

@@ -16,5 +16,31 @@
       "Bash(python -m pytest tests/unit/test_plots.py -k \"animate_trajectory or animate_rotate\" -p no:cacheprovider -q)",
       "Bash(python -m pytest tests/unit/test_plots.py -p no:cacheprovider -q)"
     ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .claude/hooks/ruff_on_edit.py",
+            "statusMessage": "ruff: formatting edited file"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .claude/hooks/ruff_guard_push.py",
+            "statusMessage": "ruff: pre-push lint guard"
+          }
+        ]
+      }
+    ]
   }
 }