From a7dff71e480cd79b11abb63537a5dfcfb3b97566 Mon Sep 17 00:00:00 2001 From: Ralf Anton Beier Date: Fri, 5 Jun 2026 11:23:34 +0200 Subject: [PATCH] docs(agents): add "Before You Push (Rust)" fmt/clippy guidance + file REQ-202 (minimal build) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses issue #438 (AI commits pass locally, fail CI Format/Clippy) via its own second suggestion: surface the exact CI gates where agents look. The git pre-commit hook (scripts/install-hooks.sh) already runs `cargo fmt --all -- check` on staged .rs since #438 was filed, but it requires manual install and does not cover clippy. The new AGENTS.md "Before You Push (Rust)" section gives the verbatim `cargo fmt --all -- --check` + `cargo clippy --all-targets -- -D warnings` one-liners and documents the three traps that bite agents (grep '^error' misses -D warnings; -p skips --all-targets test lints; the commit-msg hook rejects `Word:` body lines). Also files REQ-202 (draft) from issue #456: rivet-cli has no minimal build — `default = []` and axum/rmcp/lsp-server are unconditional deps, so every from-source build compiles the full serve+MCP+LSP stack even for the validate/list hot path. Proposed additive fix keeps features in `default` so the published binary is byte-for-byte unchanged; the feature set is a maintainer call, hence draft. Note: a stronger fix for #438 — a .claude/settings.json PostToolUse hook that auto-runs `cargo fmt --all` on every .rs edit — was attempted but is gated as self-modification of agent config and needs explicit maintainer authorization. Confirmed with: rivet validate PASS (257 warnings, 0 errors). Refs: REQ-202, REQ-007 --- AGENTS.md | 29 +++++++++++++++++++++ artifacts/requirements.yaml | 52 +++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 18feee23..61cd3bd0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -199,6 +199,35 @@ Exempt artifact types (no trailer required): `chore`, `style`, `ci`, `docs`, `bu To skip traceability for a commit, add: `Trace: skip` +## Before You Push (Rust) + +`Format` and `Clippy` are the two most common first-push CI failures, and +neither has a fast guard in the default agent workflow unless you have run +`./scripts/install-hooks.sh` (which installs a git `pre-commit` that runs +`cargo fmt --all -- --check` on staged `.rs` files). Even with the hook, +clippy is not checked per-commit (too slow). So before every push that +touches Rust, run the **exact CI gates** by hand: + +```sh +cargo fmt --all -- --check # CI "Format" gate (ci.yml) +cargo clippy --all-targets -- -D warnings # CI "Clippy" gate — note --all-targets and -D warnings +``` + +Pitfalls (verified against CI): +- `cargo clippy ... | grep '^error'` is **deceptive** — CI uses `-D warnings`, + so a *warning* (e.g. `doc_lazy_continuation`) fails CI while that grep reports + clean. Always run the full `-D warnings` form, no grep. +- `cargo clippy -p ` skips test code; CI runs `--all-targets`, which + lints tests too. Test-only lints pass locally but fail CI without + `--all-targets`. +- The commit-msg hook rejects body lines shaped like `Word:` as malformed + trailers — phrase verification prose as "Confirmed with …", and keep real + trailers (`Implements`/`Verifies`/`Refs`) in the final block. + +A one-shot `pre-commit install --install-hooks` also activates the +`.pre-commit-config.yaml` `cargo-fmt` + `cargo-clippy` hooks if you prefer the +pre-commit framework. See `docs/pre-commit.md`. + ## Commit Traceability This project enforces commit-to-artifact traceability. Every non-exempt diff --git a/artifacts/requirements.yaml b/artifacts/requirements.yaml index 913433fa..d5d1230c 100644 --- a/artifacts/requirements.yaml +++ b/artifacts/requirements.yaml @@ -6150,3 +6150,55 @@ artifacts: links: - type: traces-to target: REQ-196 + - id: REQ-202 + type: requirement + title: "rivet-cli must support a minimal `--no-default-features` build (validate/list/commit-msg-check) that excludes the serve+MCP+LSP stack" + status: draft + description: | + Finding (issue #456, AI-agent dogfooding, verified against + rivet-cli/Cargo.toml). `rivet validate` is the hook-critical and + CI-critical hot path, yet rivet-cli has NO way to build a minimal binary: + `[features]` is `default = []` (only `wasm` is non-trivial), and `axum`, + `tower-http`, `notify` (serve), `lsp-server`/`lsp-types` (LSP), and `rmcp` + (full streamable-HTTP MCP server) are UNCONDITIONAL dependencies. So every + from-source build — `cargo install rivet`, CI's compile step, and a local + build to test a one-line validate change — compiles the entire web/MCP/LSP + tree even though validate/list/commit-msg-check never use it. rivet-core + already gates its heavy deps (`wasm`, `reqwest`, `spar-*` are + `optional = true`); the coupling is specific to rivet-cli. + + Fix (additive, preserves published behavior): introduce cargo features and + KEEP them in `default`, so the released binary is byte-for-byte unchanged: + default = ["serve", "mcp", "lsp"] + serve = ["dep:axum", "dep:tower-http", "dep:notify"] + mcp = ["dep:rmcp", "dep:tokio"] + lsp = ["dep:lsp-server", "dep:lsp-types"] + …with `#[cfg(feature = ...)]` gating the corresponding command handlers and + `mod serve`/`mod mcp`/`mod lsp` declarations in main.rs. The code-side + gating across the serve/mcp/lsp command dispatch is the bulk of the work + and needs care so `--no-default-features` still compiles cleanly. The + default-feature set is a maintainer call (filed as draft). + + Acceptance: + - `rivet-cli/Cargo.toml` declares `serve`/`mcp`/`lsp` features, all in + `default`, with the corresponding deps marked `optional = true` + (`dep:` syntax). + - `cargo build -p rivet-cli --no-default-features` succeeds and the + resulting binary runs `validate`, `list`, and `commit-msg-check`. + - `cargo build -p rivet-cli --no-default-features` does NOT compile + `axum`, `rmcp`, or `lsp-server` (verify via + `cargo tree -p rivet-cli --no-default-features` absence). + - Default build (`cargo build -p rivet-cli`) is unchanged: serve, mcp, + and lsp subcommands all present. + - `rivet validate` on the rivet repo still PASS. + tags: [cli, build, cargo-features, minimal-build, friction, dogfooding] + fields: + priority: should + category: functional + links: + - type: traces-to + target: REQ-007 + provenance: + created-by: ai-assisted + model: claude-opus-4-8 + timestamp: 2026-06-05T09:23:14Z