From c676aafa68f06736ac14adc18097ecd323f8fb12 Mon Sep 17 00:00:00 2001
From: leynos <leynos@rohga>
Date: Wed, 8 Jul 2026 12:54:01 +0200
Subject: [PATCH] Align Whitaker lint wiring with the estate rollout
 conventions

Cuprum already runs the Whitaker Dylint suite in `make lint` and in the
CI lint-test job. This change brings the wiring in line with the
conventions used across the estate rollout (see leynos/netsuke#410):

- Introduce a `WHITAKER ?= whitaker` tool variable in the Makefile and
  use it in the lint recipe, so the binary can be overridden like the
  other tools.
- Run Whitaker with `RUSTFLAGS="$(RUST_FLAGS)"` so warnings are denied
  during the lint build, matching the Clippy and test invocations, and
  mention Whitaker in the lint target's help text.
- Add a binstall-or-build fallback to the CI install step: runners
  whose Rust setup does not provide `cargo binstall` now fall back to
  `cargo install --locked whitaker-installer` instead of failing.
- Document a rationale for the existing `no_std_fs_operations`
  exclusion in rust/dylint.toml: the extension crate only wraps raw
  file descriptors and handles received from Python in std::fs::File
  and never opens filesystem paths itself.
- Sync the `make lint` command listing in AGENTS.md with the new
  Whitaker invocation.
---
 .github/workflows/ci.yml | 14 ++++++++++----
 AGENTS.md                |  2 +-
 Makefile                 |  7 ++++---
 rust/dylint.toml         |  3 +++
 4 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c203c4e4..0bdde7b3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -53,10 +53,16 @@ jobs:
       - name: Install Whitaker
         run: |
           if [ "${{ steps.cache-whitaker.outputs.cache-hit }}" != "true" ]; then
-            cargo binstall --no-confirm --locked \
-              --git https://github.com/leynos/whitaker \
-              --version "${WHITAKER_INSTALLER_VERSION}" \
-              whitaker-installer
+            if cargo binstall --version >/dev/null 2>&1; then
+              cargo binstall --no-confirm --locked \
+                --git https://github.com/leynos/whitaker \
+                --version "${WHITAKER_INSTALLER_VERSION}" \
+                whitaker-installer
+            else
+              echo "cargo-binstall unavailable; building whitaker-installer from crates.io"
+              cargo install --locked whitaker-installer \
+                --version "${WHITAKER_INSTALLER_VERSION}"
+            fi
           fi
           whitaker-installer --cranelift
 
diff --git a/AGENTS.md b/AGENTS.md
index c595403e..68a473e5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -168,7 +168,7 @@ working on the Rust portions of the project:
     ```sh
     RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
     cargo clippy --all-targets --all-features -- -D warnings
-    whitaker --all -- --all-targets --all-features
+    RUSTFLAGS="-D warnings" whitaker --all -- --all-targets --all-features
     ```
 
     linting every target with all features enabled and denying all Clippy
diff --git a/Makefile b/Makefile
index 6c89760f..1d7fe987 100644
--- a/Makefile
+++ b/Makefile
@@ -5,6 +5,7 @@ TOOLS = $(MDFORMAT_ALL) $(MDLINT) uv
 VENV_TOOLS = pytest ruff
 RUST_DIR ?= rust
 CARGO ?= cargo
+WHITAKER ?= whitaker
 BUILD_JOBS ?=
 RUST_FLAGS ?= -D warnings
 RUSTDOC_FLAGS ?= -D warnings
@@ -88,17 +89,17 @@ check-fmt: ruff ## Verify formatting
 	cd $(RUST_DIR) && $(CARGO) fmt --all -- --check
 	# mdformat-all doesn't currently do checking
 
-lint: ruff uv ## Run linters
+lint: ruff uv ## Run linters (Ruff, pylint, Clippy, Whitaker)
 	$(RUFF) check
 	$(UV_RUN_ENV) uv run interrogate --fail-under 100 cuprum
 	$(PYLINT) $(PYLINT_TARGETS)
 	cd $(RUST_DIR) && RUSTDOCFLAGS="$(RUSTDOC_FLAGS)" $(CARGO) doc --no-deps
 	cd $(RUST_DIR) && $(CARGO) clippy $(CLIPPY_FLAGS)
-	@if ! $(LOCAL_TOOL_ENV) command -v whitaker >/dev/null 2>&1; then \
+	@if ! $(LOCAL_TOOL_ENV) command -v $(WHITAKER) >/dev/null 2>&1; then \
 	  echo "whitaker is required for linting. Install it before running this target." >&2; \
 	  exit 1; \
 	fi
-	cd $(RUST_DIR) && $(LOCAL_TOOL_ENV) whitaker --all -- $(CARGO_FLAGS)
+	cd $(RUST_DIR) && $(LOCAL_TOOL_ENV) RUSTFLAGS="$(RUST_FLAGS)" $(WHITAKER) --all -- $(CARGO_FLAGS)
 
 typecheck: build ## Run typechecking
 	$(UV_RUN_ENV) uv sync --group dev
diff --git a/rust/dylint.toml b/rust/dylint.toml
index 670af4ef..575fe853 100644
--- a/rust/dylint.toml
+++ b/rust/dylint.toml
@@ -1,2 +1,5 @@
 [no_std_fs_operations]
+# _rust_backend_native never opens filesystem paths itself; it wraps raw file
+# descriptors and handles received from the Python caller in std::fs::File, so
+# capability-based alternatives such as cap-std do not apply here.
 excluded_crates = ["_rust_backend_native"]