rust quality gates

Security Community

Skill notes

Step 1: Assess the repo before touching anything

Before writing or installing anything, understand the repo. Two outcomes are possible: a mature system already exists (stop and defer — Step 2), or it doesn't (proceed from Step 3). Gather in parallel: Cargo.toml (root and per-crate) / Cargo.lock — edition, MSRV (rust-version), workspace members, feature flags, existing [lints] table. rust-toolchain.toml / rust-toolchain — pinned compiler version, components (clippy, rustfmt, llvm-tools-preview), targets.

Features and target-cfg — detect once, use everywhere

Rust is simpler than JS here (one toolchain, one package manager), but Cargo features are the equivalent trap. cargo build with default features compiles a different subset than --all-features, and some feature combinations don't compile together at all. Running cargo clippy without --all-features (or without --each-feature for combinatorial coverage) produces silent no-ops for feature-gated code. Check for:

Step 2: Inventory existing gates and implement the delta

Most repos have some gates already (a cargo fmt --check in CI, a Makefile target running clippy, a half-finished [workspace.lints] table) but not the full set this skill installs. The default behavior is to fill in the missing gates, not to stop. Only defer the whole job when every row of the checklist below is already ✅ or when the existing orchestrator is genuinely incompatible with adding gates (rare — see end of step).

Step 3: Install dev tools

Rust dev tools come from two sources: rustup components (shipped with the toolchain) and cargo install for third-party tools. Prefer pinning third-party tool versions via rust-toolchain.toml components, or a tools/Cargo.toml workspace, or a cargo install --locked in a CI install step.

Core (every Rust project)

These ride the toolchain version. If rust-toolchain.toml pins a specific version (e.g. stable-1.85), clippy and rustfmt match — no version drift between developers. Pinning a specific stable version (rather than the floating stable channel) is what most production repos do; it eliminates "the lint that fired on my machine but not in CI" debugging.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Security
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Moderate
Setup complexity
Guided setup
External API key
Not required
Operating systems
Linux
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Assess the repo before touching anything

Before writing or installing anything, understand the repo. Two outcomes are possible: a mature system already exists (stop and defer — Step 2), or it doesn't (proceed from Step 3). Gather in parallel: `Cargo.toml` (root and per-crate) / `Cargo.lock` — edition, MSRV (`rust-version`), workspace members, feature flags, existing `[lints]` table. `rust-toolchain.toml` / `rust-toolchain` — pinned compiler version, components (`clippy`, `rustfmt`, `llvm-tools-preview`), targets.

02
Step 2: Inventory existing gates and implement the delta

Most repos have some gates already (a `cargo fmt --check` in CI, a Makefile target running clippy, a half-finished `[workspace.lints]` table) but not the full set this skill installs. The default behavior is to fill in the missing gates, not to stop. Only defer the whole job when every row of the checklist below is already ✅ or when the existing orchestrator is genuinely incompatible with adding gates (rare — see end of step).

03
Step 3: Install dev tools

Rust dev tools come from two sources: rustup components (shipped with the toolchain) and `cargo install` for third-party tools. Prefer pinning third-party tool versions via `rust-toolchain.toml` components, or a `tools/Cargo.toml` workspace, or a `cargo install --locked` in a CI install step.

04
Step 4: Check + build as the baseline

`cargo check --workspace --all-targets` and `cargo build --workspace --all-targets` are the floor. They require no config, catch real type errors, and `check` runs much faster than `build` because it skips codegen. If either fails on a clean checkout, stop and fix before adding further gates — there is no point layering linters on top of a repo that doesn't compile. `--all-targets` is critical: without it, `cargo check` does not compile `tests/`, `examples/`, or `benches/`, and those can rot silently.

05
Step 5: Clippy config

Clippy is to Rust what golangci-lint is to Go — one meta-linter that wraps the dozens of named lints you'd otherwise wire up individually. Since Cargo 1.74, lints can be configured via a `[lints]` table in `Cargo.toml` — an alternative to crate-level `#![warn(...)]` attributes in `lib.rs`, and the preferred form for workspaces because `[workspace.lints]` propagates to every member. Crate-level attributes still work and remain common; pick one form and stick with it.

06
Step 6: Formatting (rustfmt)

Rust has an unambiguous canonical format. There is no bikeshedding config (unlike Prettier). `rustfmt` is part of the toolchain — no install step beyond `rustup component add rustfmt`. If the repo wants a few customizations (the only ones worth setting on most projects), put them in `rustfmt.toml` at the repo root: If the repo's `rust-toolchain.toml` pins nightly, the `unstable_features` block is fair game; otherwise leave it commented. The trap to avoid: enabling unstable rustfmt options on a stable toolchain means `cargo fmt --check` returns success without applying them, and developer setups drift silently.

07
Step 7: Unused deps, dead code, duplication, complexity

These are cheap to run and catch things clippy alone misses.

08
Step 8: Create check.sh

A thin bash entry point that calls each gate sequentially. Fine for small/medium repos; see Step 12 for the parallel-orchestrator upgrade. Substitute `<CARGO_FEATURES>` and any toolchain env from Step 1. Do not leave the placeholders literal in the generated file. Intentionally not in this default template (to avoid double-gating or fragile behavior): `cargo audit` / `cargo deny` — network-dependent (fetches the RUSTSEC advisory DB) and can flake in air-gapped CI. Valuable but belongs on a scheduled CI run; see Step 12.

09
Step 9: Wire up prek

`prek` is the prescribed checker entry point — `.pre-commit-config.yaml` lets `prek` invoke `check.sh` from git hooks and from the command line under one stable interface. Even though `check.sh` runs fine on its own, route users through `prek` so the same gates fire on commit, on push, and on manual runs without three different invocations. Create `.pre-commit-config.yaml` at the repo root: `pass_filenames: false` and `always_run: true` matter: cargo gates are workspace-wide, not per-file, so we don't want `prek` to pass the staged file list to `check.sh` or skip the run when nothing Rust changed.

10
Step 10: Document (existing docs only)

If the repo already has `CLAUDE.md` or `AGENTS.md`, append a compact "Quality Gates" section: Do not create `CLAUDE.md` just to document the gates. That's agent-clutter the user didn't ask for; the `check.sh` header comment and `justfile`/`Makefile` are self-documenting.

11
Step 11: First run

Run `prek run --all-files` and fix anything that comes up. Expect: `prek: command not found` — install per Step 3 (`cargo install --locked prek` or `brew install prek`). Missing tools — `cargo-machete`, `cargo-nextest` not installed. Install with `cargo install --locked <tool>` from Step 3. `clippy` failures on a fresh setup — the default config is strict (`unwrap_used`, `expect_used`, `panic`). If the volume is large, either fix in batches or relax specific lints in `Cargo.toml` rather than disabling clippy wholesale. For test-only relaxations, put `#[cfg_attr(test, allow(clippy::unwrap_used))]` on the affected modules.

12
Step 12: Advanced patterns (propose for larger repos; don't apply unprompted)

These are proven production patterns for Rust workspaces and larger services. They cost setup time, so pitch them and get buy-in before applying.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.