防锈质量门
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 安全
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Linux
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
在编写或安装任何内容之前,请先了解存储库。可能有两种结果:成熟的系统已经存在(停止并推迟 - 步骤 2),或者不存在(从步骤 3 继续)。并行收集:`Cargo.toml`(根和每个板条箱)/`Cargo.lock` — 版本、MSRV (`rust-version`)、工作区成员、功能标志、现有 `[lints]` 表。 `rust-toolchain.toml` / `rust-toolchain` — 固定编译器版本、组件(`clippy`、`rustfmt`、`llvm-tools-preview`)、目标。
大多数存储库已经有一些门(CI 中的 `cargo fmt --check`、运行 Clippy 的 Makefile 目标、半完成的 `[workspace.lints]` 表),但不是此技能安装的全套。默认行为是填补缺失的门,而不是停止。仅当下面清单的每一行都已经是 ✅ 或现有编排器确实与添加门不兼容时才推迟整个工作(罕见 - 请参阅步骤结束)。
Rust 开发工具有两个来源:rustup 组件(随工具链一起提供)和用于第三方工具的`cargo install`。更喜欢通过 CI 安装步骤中的 `rust-toolchain.toml` 组件、`tools/Cargo.toml` 工作区或 `cargo install --locked` 固定第三方工具版本。
`cargo check --workspace --all-targets`和`cargo build --workspace --all-targets`是地板。它们不需要配置,捕获真实类型错误,并且`check`比`build`运行得快得多,因为它跳过了代码生成。如果在干净的检查中失败,请在添加更多门之前停止并修复 - 在无法编译的存储库之上分层 linter 是没有意义的。 `--all-targets` 至关重要:没有它,`cargo check` 就无法编译 `tests/`、`examples/` 或 `benches/`,而且它们会默默地腐烂。
Clippy 之于 Rust 就像 golangci-lint 之于 Go — 一种元 linter,它包装了数十个命名的 lint,否则您需要单独连接。从 Cargo 1.74 开始,lint 可以通过 `Cargo.toml` 中的 `[lints]` 表进行配置——这是 `lib.rs` 中板条箱级 `#![warn(...)]` 属性的替代方案,也是工作区的首选形式,因为 `[workspace.lints]` 会传播到每个成员。板条箱级别的属性仍然有效并且仍然很常见;选择一种形式并坚持下去。
Rust 具有明确的规范格式。没有 bikeshedding 配置(与 Prettier 不同)。 `rustfmt` 是工具链的一部分 — 除了`rustup component add rustfmt` 之外没有安装步骤。如果存储库需要一些自定义(唯一值得在大多数项目上设置的自定义项),请将它们放在存储库根目录的`rustfmt.toml`中:如果存储库的`rust-toolchain.toml`每晚固定,则`unstable_features`块是公平的游戏;否则请留下评论。要避免的陷阱:在稳定的工具链上启用不稳定的 rustfmt 选项意味着`cargo fmt --check` 会在不应用它们的情况下返回成功,并且开发人员设置会悄无声息地发生变化。
这些运行起来很便宜,并且可以捕捉到单独错过的东西。
一个按顺序调用每个门的精简 bash 入口点。适合小型/中型回购;请参阅步骤 12 了解并行协调器升级。替换步骤 1 中的 `<CARGO_FEATURES>` 和任何工具链环境。不要在生成的文件中保留占位符文字。故意不在这个默认模板中(以避免双重门控或脆弱行为): `cargo audit` / `cargo deny` - 网络相关(获取 RUSTSEC 咨询数据库)并且可能在气隙 CI 中分层。有价值但属于预定的 CI 运行;请参阅步骤 12。
# Rust Quality Gates Setup
Set up a quality gate system for a Rust project. The prescribed checker command is `prek run --all-files`. The deliverables are a `.pre-commit-config.yaml` that points `prek` at a `check.sh` orchestrator, a `clippy.toml` / `rustfmt.toml` pair (plus a `[lints]` table in `Cargo.toml`), and any extra tool configs (`deny.toml`, `cargo-machete` ignore lists) — wired to the repo's actual workspace layout and feature matrix. For larger repos, Step 12 describes the upgrades that production setups use.
## 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:
1. `Cargo.toml` (root and per-crate) / `Cargo.lock` — edition, MSRV (`rust-version`), workspace members, feature flags, existing `[lints]` table.
2. `rust-toolchain.toml` / `rust-toolchain` — pinned compiler version, components (`clippy`, `rustfmt`, `llvm-tools-preview`), targets.
3. Existing config files: `clippy.toml`, `rustfmt.toml` / `.rustfmt.toml`, `deny.toml`, `.cargo/config.toml`, `.cargo/audit.toml`, `.pre-commit-config.yaml`, any `scripts/check*.sh` / `scripts/lint*.sh` / `justfile` / `Makefile` targets (`make check`, `just lint`, `make ci`).
4. `CLAUDE.md` / `AGENTS.md` — canonical commands already documented.
5. Source layout: top-level `src/`, `crates/`, `examples/`, `tests/`, `benches/`, workspace members in `[workspace.members]`, `build.rs` scripts, generated files (`OUT_DIR`, `tonic-build`, `prost-build`).
6. Native / FFI deps — look for `build.rs`, `*-sys` crates, `bindgen`, `cc`, `cxx`, or `[target.'cfg(...)'.dependencies]`; these change how every gate must be invoked (system libs, target triple, cross-compilation).
### 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:
- Crates with many features in `Cargo.toml` `[features]` (more than 2–3 non-trivial features = a real matrix).
- Mutually exclusive features (e.g. `tls-rustls` vs `tls-openssl`) — `--all-features` will fail; needs `cargo hack` or per-combo invocation.
- `[target.'cfg(...)']` sections — platform-specific code that only compiles on certain targets.
- `no_std` crates or `#![no_std]` directives — the host-tools default toolchain may not even build them without `--target`.
- Existing pre-push hooks (`.githooks/pre-push`, `.husky/`) that already set `CARGO_TARGET_DIR`, `RUSTFLAGS`, `--features`, etc.
Throughout this skill, `<CARGO_FEATURES>` means whatever feature/target combination the repo already uses (commonly `--workspace --all-features` for libraries, `--workspace` for binaries, or a `cargo hack --feature-powerset` for crates with mutually-exclusive features). If the detected setup is ambiguous or has mutually-exclusive features, ask before generating.
## 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).
Walk this checklist before writing anything. For each gate, check the listed signal; mark ✅ if present and working, ❌ if missing or broken on disk.
| Gate | Detection signal | Where to add if ❌ |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `cargo check` / `cargo build` baseline | Always available in a Rust repo with a valid `Cargo.toml` | Step 4 invocation |
| rustfmt config | `rustfmt.toml` exists, OR rustfmt defaults are explicitly fine for the project | Step 6 |
| Clippy `[workspace.lints]` policy | Root `Cargo.toml` has a non-trivial `[workspace.lints.clippy]` AND every workspace member has `[lints] workspace = true` | Step 5 |
| `clippy.toml` thresholds + test escape hatches | `clippy.toml` exists with at least `allow-unwrap-in-tests`/`allow-expect-in-tests`/`allow-panic-in-tests` configured | Step 5 |
| Strict doc gate | `[workspace.lints.rustdoc] broken_intra_doc_links = "deny"` set, OR existing orchestrator invokes `cargo doc` with `-D warnings` | Step 7 |
| `cargo-machete` unused-deps gate | Tool installed AND invoked by an existing orchestrator | Step 7 + check.sh |
| Test gate | Existing orchestrator runs `cargo test` / `cargo nextest run` over the workspace | Step 8 |
| `check.sh` orchestrator | `check.sh` (or equivalent `justfile`/`Makefile` target) runs the full gate sequentially | Step 8 |
| `.pre-commit-config.yaml` + `prek` wiring | File exists and wires `check.sh` (or per-gate hooks) for `prek`/`pre-commit` | Step 9 |
Run the existing orchestrator once (`just check`, `make ci`, `./check.sh`, `cargo xtask check`) before counting any ✅. A passing run earns it; a failing run means the gate is broken regardless of config presence — treat as ❌ and fix or replace.
Then report a short table to the user and **proceed to implement every ❌ row** without asking permission per row. Two modes:
- **No existing orchestrator** — create `check.sh` and `.pre-commit-config.yaml` per Steps 8–9; add only the gates the inventory marked ❌.
- **Existing orchestrator present** — **extend it** rather than replacing. Add new targets to the `justfile`/`Makefile`, append gate invocations to the existing `check.sh`, or register new hooks in `.pre-commit-config.yaml`. Keep the user's entry point name. Only mention replacement if the orchestrator is structurally hostile to new gates (see below).
Two cases where you stop or ask first:
1. **Everything is ✅** — every gate is present and the orchestrator passes cleanly. Report "all gates already in place" and stop. Nothing to do.
2. **Incompatible orchestrator** — Bazel rules, Nx executors with custom runners, a vendored CI script that forbids local invocation, or a `clippy::all` set via `lib.rs` crate attributes that conflicts with the `[lints]` table this skill writes. Ask whether to (a) wire missing gates into that system using its native idiom, or (b) add `check.sh` + `prek` alongside as a developer-facing fast path (some duplication, stable second entry point). Don't auto-replace.
Conflict cases that need a one-line confirmation before proceeding (not a "stop entirely"):
- Legacy `#![deny(clippy::all)]` in `lib.rs` plus a partial `[lints]` table — Step 5 prefers `[lints]`; ask which form to remove.
- `nightly` pinned `rust-toolchain.toml` enabling `unstable_features` in `rustfmt.toml` — the recommended config assumes stable; confirm before changing the pin.
- Existing `clippy.toml` with `msrv` that mismatches `Cargo.toml`'s `rust-version` — ask which is canonical before overwriting either.
## 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)
```text
rustup component add clippy rustfmt # meta-linter + formatter, shipped with the toolchain
```
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.
### Recommended add-ons
```text
# Prefer a prebuilt binary — building prek from source via cargo install takes minutes:
brew install prek # or: pipx install prek, uv tool install prek, cargo binstall prek
# Cargo-installed tools (slower first install, but no extra package manager required):
cargo install --locked cargo-machete # unused dependencies (fast, stable, no nightly)
cargo install --locked cargo-deny # licenses, advisories, banned crates, source policy
cargo install --locked cargo-audit # RUSTSEC CVE scanning (subset of cargo-deny)
cargo install --locked cargo-nextest # faster test runner with better output
cargo install --locked cargo-hack # feature-matrix testing (each-feature, feature-powerset)
```
`prek` (<https://github.com/j178/prek>) is the user-facing entry point: it reads `.pre-commit-config.yaml`, installs git hooks, and runs the gate. The `check.sh` orchestrator (Step 8) does the actual work; `prek` just wraps it.
Optional (nightly-only or niche):
```text
cargo install --locked cargo-udeps # unused deps via compiler internals (needs nightly, more accurate than machete)
cargo install --locked cargo-llvm-cov # coverage via llvm-cov (also needs `llvm-tools-preview` component)
cargo install --locked cargo-mutants # mutation testing
cargo install --locked cargo-semver-checks # public API drift for library crates
```
If the repo already has a `rust-toolchain.toml`, add `clippy`, `rustfmt`, and `llvm-tools-preview` (if using coverage) to its `components` list so every developer and every CI runner gets the same versions automatically.
`cargo check`, `cargo build`, `cargo test`, `cargo doc` are part of cargo — nothing to install.
## 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.
`--all-features` is the next layer up. For libraries it's almost always what you want; for binaries with mutually-exclusive feature groups, you need `cargo hack --feature-powerset check` instead. Record the exact invocation in `check.sh`:
```bash
# Library or binary with compatible features:
cargo check --workspace --all-targets --all-features
# Crate with mutually-exclusive features (needs cargo-hack):
cargo hack check --workspace --feature-powerset --depth 2 --all-targets
```
## 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.
In the workspace root `Cargo.toml`:
```toml
[workspace.lints.rust]
# Compiler lints — these come from rustc itself, not clippy
unsafe_code = "warn" # downgrade to "allow" only in crates that genuinely need it
unused_imports = "warn"
unused_must_use = "warn"
unreachable_pub = "warn"
missing_debug_implementations = "warn"
# missing_docs = "warn" # enable when public API docs are a priority
[workspace.lints.clippy]
# Lint groups (the big knobs). `priority = -1` is required so individual
# lints below (at default priority 0) can override the group level —
# without it, group entries and individual entries collide ambiguously.
# `pedantic` is opt-in by design and very noisy — enable individually if at all.
# `nursery` is unstable; expect false positives.
# `correctness` is already deny-by-default in clippy; listing it here is
# documentation, not hardening.
all = { level = "warn", priority = -1 } # the default-warn set
suspicious = { level = "warn", priority = -1 }
complexity = { level = "warn", priority = -1 }
perf = { level = "warn", priority = -1 }
style = { level = "warn", priority = -1 }
# Individual lints worth enabling beyond the defaults
unwrap_used = "warn" # forces explicit error handling at boundaries
expect_used = "warn" # same, but for `.expect("…")`
panic = "warn" # flag `panic!()` in library code
todo = "warn" # `todo!()` shouldn't ship
dbg_macro = "warn" # `dbg!()` shouldn't ship either
print_stdout = "warn" # use `tracing` / `log` instead
print_stderr = "warn"
# Frequently-fired pedantic lints that are usually worth the noise
needless_pass_by_value = "warn"
redundant_clone = "warn"
inefficient_to_string = "warn"
# Deliberate opt-outs — these fire on legitimate patterns and aren't worth the friction
module_name_repetitions = "allow" # naming convention, not a bug
must_use_candidate = "allow" # noisy on internal helpers
missing_errors_doc = "allow" # enable when missing_docs is enabled
missing_panics_doc = "allow"
```
Then in **each crate**'s `Cargo.toml`, opt in to the workspace policy:
```toml
[lints]
workspace = true
```
Without that opt-in line, `[workspace.lints]` does nothing for that crate. This trips up newcomers — every workspace member needs the `[lints]` table.
For per-threshold tuning, also create `clippy.toml` at the repo root:
```toml
# clippy.toml — thresholds and behavior tweaks that aren't expressible as lint levels
cognitive-complexity-threshold = 25 # default 25; bump for unavoidably-complex code
too-many-arguments-threshold = 8 # default 7; raise if many builder patterns
type-complexity-threshold = 250 # default 250
msrv = "1.85" # match Cargo.toml rust-version; clippy uses this for "won't compile on MSRV" lints
# These flip off the unwrap/expect/panic lints inside `#[cfg(test)]` modules
# and `tests/` integration tests — the canonical escape hatch, much cleaner
# than scattering `#[allow(clippy::unwrap_used)]` attributes per module.
allow-unwrap-in-tests = true
allow-expect-in-tests = true
allow-panic-in-tests = true
```
Notes on deliberate omissions:
- **`clippy::pedantic` is off by default** — it includes ~80 lints, most of which fire on idiomatic code (`module_name_repetitions`, `must_use_candidate`, `missing_errors_doc`). Enable individually, not as a group, after the core gate stabilizes.
- **`clippy::restriction` is off, on purpose** — by design it contains _mutually incompatible_ lints (`else_if_without_else` vs `redundant_else`). Never enable as a group.
- **`clippy::nursery` is off** — unstable lints with frequent false positives.
## 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:
```toml
# rustfmt.toml — keep this minimal; rustfmt's defaults are good
edition = "2021" # match Cargo.toml — rustfmt formats differently per edition
max_width = 100 # default 100; many style guides prefer 100 or 120
# Anything below requires the nightly rustfmt and is gated behind `unstable_features = true`.
# Do not enable on a stable toolchain — `cargo fmt --check` will silently ignore them and
# CI will pass while local pre-commit fails (or vice versa).
# unstable_features = true
# group_imports = "StdExternalCrate"
# imports_granularity = "Crate"
# wrap_comments = true
```
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.
The `check.sh` script below runs `cargo fmt --all -- --check` for verification and `cargo fmt --all` for the `--fix` path.
## Step 7: Unused deps, dead code, duplication, complexity
These are cheap to run and catch things clippy alone misses.
### cargo-machete (unused dependencies)
```bash
cargo machete
```
Detects deps listed in `Cargo.toml` but never `use`d. Fast, stable, no false negatives on most codebases. Has known false positives for crates referenced only via macro expansion (`serde` derive macros, etc.) — silence those with a `package.metadata.cargo-machete.ignored` list. This block lives in the **member crate's** `Cargo.toml` (the one with `[package]`), **not** in the workspace root — pasting it under `[workspace]` is a silent no-op:
```toml
# crates/foo/Cargo.toml — note this is per-crate, not workspace-root
[package.metadata.cargo-machete]
ignored = ["serde"] # used via #[derive(Serialize)] but not directly imported
```
Prefer `cargo-machete` over `cargo-udeps` for the default gate. Two reasons, in order: machete is dramatically faster (it parses `Cargo.toml` and greps source, no compilation; `udeps` runs as a rustc plugin and needs a full compile), and machete works on stable while `udeps` requires nightly. Add `udeps` in Step 12 if the user wants the higher accuracy and is willing to pay the time + nightly cost.
### dead_code (intra-crate, via rustc) — weaker than it looks
Rust's `dead_code` lint is enabled by default at warn level and catches functions/types/fields with no internal callers. Two important caveats that bite people coming from the Go ecosystem:
1. **It only checks reachability within a crate.** Cross-crate dead-code analysis is fundamentally hard in Rust because `pub` items can be consumed by code the compiler doesn't see.
2. **It exempts `pub` items entirely.** Anything marked `pub` is assumed to be external API and never flagged — so on a library crate, `dead_code` is largely silent regardless of internal use.
There is no widely-deployed Rust equivalent to Go's `deadcode` reachability walker that starts from `main` and finds unreachable `pub` items. For binary crates, `unreachable_pub` (set to `warn` in the rustc lints above) helps surface `pub` items that aren't actually exported. For libraries, accept the limitation; `cargo-machete` (which finds unused _deps_, not unused _items_) is the closest practical signal. Make sure `[workspace.lints.rust] dead_code = "warn"` (or `deny`) is set so the gate at least catches private-only dead code. No separate tool needed.
### Duplication — deliberately omitted
Unlike Go (`dupl`) or JS (`jscpd`), there isn't a widely-adopted Rust-native duplication detector. The available tools (`simian`, generic `pmd-cpd`) are language-agnostic, ignore Rust semantics (macros, generics), and produce noisy results. Skip the duplication gate for the default setup. If the user specifically asks, recommend running `jscpd --languages rust --min-tokens 50` against the workspace and triaging manually — but don't put it in `check.sh`.
### Complexity (reporting via clippy thresholds)
Clippy already has `cognitive_complexity`, `too_many_arguments`, `type_complexity`, and `too_many_lines` lints — all configurable via `clippy.toml` thresholds (Step 5). There's no separate tool to install. Use the thresholds as soft signals; raising them per-crate via `#[allow(clippy::cognitive_complexity)]` on a specific function is the standard escape hatch. Step 12 shows how to track these as metrics rather than hard gates.
### Doc build (catches broken intra-doc links)
The modern (Rust 1.74+) idiom is to declare doc-lint policy in the same `[workspace.lints]` table as everything else, so the gate doesn't depend on an env var being set:
```toml
[workspace.lints.rustdoc]
broken_intra_doc_links = "deny"
bare_urls = "warn"
```
Then the gate is just:
```bash
cargo doc --workspace --no-deps --all-features
```
`--no-deps` is what makes a strict policy safe — it skips rendering dependency docs, so deprecation warnings or doctest issues in third-party crates don't fail your build. The older pattern, `RUSTDOCFLAGS="-D warnings -D rustdoc::broken_intra_doc_links" cargo doc ...`, still works and is what you'll see in older codebases; both produce the same result. Prefer the `[lints.rustdoc]` form for new setups so the policy lives alongside the rest of the lint config.
Cheap (runs in seconds for most workspaces) and catches `[Foo]`-style doc links that fail to resolve after a rename. Treat as a hard gate.
## 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.
```bash
#!/usr/bin/env bash
# Code quality gates — run before pushing.
# Usage: ./check.sh [--fix]
set -euo pipefail
FIX="${1:-}"
ROOT="$(cd "$(dirname "$0")" && pwd)"
cd "$ROOT"
# Adapt these to the repo's detected build setup (Step 1).
# For mutually-exclusive feature crates, replace --all-features with the right combo
# or switch to `cargo hack --feature-powerset`.
CARGO_FEATURES="--workspace --all-targets --all-features"
echo "══════════════════════════════════════"
echo " Rust Quality Gates"
echo "══════════════════════════════════════"
FAILED=()
run_gate() {
local name="$1"; shift
echo ""
echo "▶ $name"
if "$@"; then
return 0
else
FAILED+=("$name")
return 1
fi
}
# Formatting — rustfmt has a canonical style; no config debate
if [ "$FIX" = "--fix" ]; then
run_gate "rustfmt (write)" cargo fmt --all
else
run_gate "rustfmt (check)" cargo fmt --all -- --check
fi
# Type check — fastest signal, catches most real bugs before clippy or build
run_gate "cargo check" bash -c "cargo check $CARGO_FEATURES"
# Clippy — the meta-linter. `-D warnings` turns every warn into a hard fail.
# Use `--no-deps` to avoid lint noise from dependencies (we can't fix those).
if [ "$FIX" = "--fix" ]; then
run_gate "clippy" bash -c "cargo clippy $CARGO_FEATURES --no-deps --fix --allow-dirty --allow-staged -- -D warnings"
else
run_gate "clippy" bash -c "cargo clippy $CARGO_FEATURES --no-deps -- -D warnings"
fi
# Build — full codegen. Catches things `check` misses (link errors, build.rs failures).
run_gate "cargo build" bash -c "cargo build $CARGO_FEATURES"
# Doc build — catches broken intra-doc links and warnings
run_gate "cargo doc" bash -c '
RUSTDOCFLAGS="-D warnings -D rustdoc::broken_intra_doc_links" \
cargo doc --workspace --no-deps --all-features
'
# Unused dependencies — cargo-machete is fast and stable
if command -v cargo-machete >/dev/null 2>&1; then
run_gate "cargo-machete" cargo machete
fi
# Tests — only if there are tests. nextest is faster + better output if installed.
if find . -path ./target -prune -o \( -name '*_test.rs' -o -name 'tests' -type d \) -print 2>/dev/null | grep -q . \
|| grep -qE '#\[(cfg\(test\)|test)\]' -r --include='*.rs' --exclude-dir=target . 2>/dev/null; then
if command -v cargo-nextest >/dev/null 2>&1; then
run_gate "cargo nextest" bash -c "cargo nextest run $CARGO_FEATURES"
# Doc tests don't run under nextest yet — run them separately
run_gate "cargo test --doc" bash -c "cargo test --doc --workspace --all-features"
else
run_gate "cargo test" bash -c "cargo test $CARGO_FEATURES"
fi
fi
# Summary
echo ""
echo "══════════════════════════════════════"
if [ "${#FAILED[@]}" -eq 0 ]; then
echo " All checks passed"
else
echo " ${#FAILED[@]} check(s) failed:"
for name in "${FAILED[@]}"; do
echo " - $name"
done
exit 1
fi
echo "══════════════════════════════════════"
```
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.
- **Coverage gate** — needs `cargo llvm-cov` and a threshold-checker. Making it conditional on a file silently no-ops; see Step 12 for the reliable pattern.
- **`cargo test --release`** — much slower than debug tests and rarely catches additional bugs unless the code has `cfg(debug_assertions)` or release-only optimizations. Add explicitly if needed.
- **MSRV verification (`cargo-msrv`)** — slow (builds against multiple toolchains). Run in CI matrix, not on every push.
- **`miri`** — invaluable for `unsafe` code but slow (10–100× test time) and only available on nightly. Add as a separate `miri.sh` script for crates that need it.
- **Bash file-length loop** — file size is a weak signal in Rust; most large files are generated code or large `enum` definitions. Track it as a metric (Step 12) rather than a hard gate.
- **Auto-creating `CLAUDE.md`** — an agent shouldn't fabricate agent docs the user didn't ask for.
Make the file executable: `chmod +x check.sh`.
## 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:
```yaml
repos:
- repo: local
hooks:
- id: quality-gates
name: Rust quality gates
entry: ./check.sh
language: system
pass_filenames: false
always_run: true
stages: [pre-commit, pre-push, manual]
```
`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.
Wire to git hooks once per checkout:
```bash
prek install # both pre-commit and pre-push by default
# or, if pre-commit is too slow for the full gate, push-only:
prek install --hook-type pre-push
```
Daily invocation — `prek run --all-files` is the prescribed command:
```bash
prek run --all-files # full sweep — the canonical entry point
prek run # staged files only (fast pre-commit path)
./check.sh # still works; prek is just calling this
./check.sh --fix # auto-fix path — call check.sh directly since prek doesn't pass flags
```
For per-gate granularity (each tool as its own hook with its own file-type filter, plus separate fast and full stages), see Step 12.
## Step 10: Document (existing docs only)
If the repo already has `CLAUDE.md` or `AGENTS.md`, append a compact "Quality Gates" section:
```markdown
## Quality Gates
- `prek run --all-files` — runs all gates (~60s on a warm `target/`; first-run cold build can be 3–5 min on a medium workspace) — prescribed entry point
- `./check.sh --fix` — auto-fix path (prek doesn't pass flags through)
- `prek install` — wire up git hooks (one-time per checkout)
Gates: rustfmt · cargo check · clippy · cargo build · cargo doc · cargo-machete (+ cargo test / nextest if present).
```
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.
## 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.
- Workspace members missing `[lints] workspace = true` — `[workspace.lints]` is opt-in per crate. Add the table to each member's `Cargo.toml`.
- `cargo doc` failing on intra-doc links — usually `[Foo]` references to renamed/removed items. Fix by adjusting the link or removing the doc.
- `cargo-machete` flagging crates used only via proc macros (`serde`, `tracing`, `async-trait`) — add to `[package.metadata.cargo-machete] ignored = [...]`.
- Build failures from mutually-exclusive features — drop `--all-features`, or switch the gate to `cargo hack --feature-powerset` (Step 12).
- Stale `Cargo.lock` after first run — commit the changes; this is normal when adding new dev tools.
## 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.
### Parallel orchestrator instead of sequential bash
A sequential `check.sh` with 6+ gates commonly hits 2–4 min wall time. A Rust orchestrator (or `cargo make`, or `just` with `parallel` flags) that fans gates out compresses that to the slowest single gate (usually tests). The simplest pure-Rust orchestrator:
```rust
// xtask/src/main.rs — invoke via `cargo xtask check`
// Requires the standard `xtask` pattern: add an `xtask` crate to the workspace
// and an alias in `.cargo/config.toml`: `[alias] xtask = "run --package xtask --"`
use std::process::{Command, Stdio};
use std::sync::mpsc;
use std::thread;
use std::time::Duration;
struct Gate {
name: &'static str,
argv: Vec<&'static str>,
}
fn main() -> std::io::Result<()> {
let gates = vec![
Gate { name: "fmt", argv: vec!["cargo", "fmt", "--all", "--", "--check"] },
Gate { name: "check", argv: vec!["cargo", "check", "--workspace", "--all-targets", "--all-features"] },
Gate { name: "clippy", argv: vec!["cargo", "clippy", "--workspace", "--all-targets", "--all-features", "--no-deps", "--", "-D", "warnings"] },
Gate { name: "doc", argv: vec!["cargo", "doc", "--workspace", "--no-deps", "--all-features"] },
Gate { name: "machete", argv: vec!["cargo", "machete"] },
Gate { name: "test", argv: vec!["cargo", "nextest", "run", "--workspace", "--all-features"] },
];
let (tx, rx) = mpsc::channel();
let n = gates.len();
for g in gates {
let tx = tx.clone();
thread::spawn(move || {
let out = Command::new(g.argv[0])
.args(&g.argv[1..])
.env("RUSTDOCFLAGS", "-D warnings -D rustdoc::broken_intra_doc_links")
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.output();
let _ = tx.send((g.name, out));
});
}
drop(tx);
// Collect with a global deadline — a hung gate can't pin the whole run.
let mut failed = Vec::new();
for _ in 0..n {
let (name, out) = rx.recv_timeout(Duration::from_secs(600))
.expect("gate timed out (>10 min)");
match out {
Ok(o) => {
println!("── {name} ──");
std::io::Write::write_all(&mut std::io::stdout(), &o.stdout)?;
std::io::Write::write_all(&mut std::io::stderr(), &o.stderr)?;
if !o.status.success() {
failed.push(name);
}
}
Err(e) => {
eprintln!("── {name} ── failed to spawn: {e}");
failed.push(name);
}
}
}
if !failed.is_empty() {
for n in &failed { eprintln!("FAIL: {n}"); }
std::process::exit(1);
}
Ok(())
}
```
Note: for a more polished experience, wrap each gate's stdout/stderr in a per-gate `Write` that prefixes every line with `[name]` and streams live; that's worth the complexity once the orchestrator is your daily driver. The version above is the minimal correct shape — parallel, bounded, deterministic output.
Keep `check.sh` as a thin wrapper that calls `cargo xtask check` so external consumers (CI, IDEs, hooks) still see a stable entry point.
### Feature-matrix testing with `cargo-hack`
Crates with several optional features have a combinatorial test space. `--all-features` only proves the all-on combination compiles; it says nothing about the all-off, default-only, or pairwise combinations. `cargo hack` solves this:
```bash
# Every feature individually, plus none — catches most issues, fast
cargo hack check --workspace --feature-powerset --depth 1 --all-targets
# Pairwise combinations — much slower but catches feature interactions
cargo hack check --workspace --feature-powerset --depth 2 --all-targets
```
Run `--depth 1` on every push; reserve `--depth 2+` for nightly CI. Cost grows quadratically — for a crate with N features, depth-2 builds roughly N + C(N,2) combinations. That's manageable at 6–8 features (~30 builds) but punishing at 15 (~120 builds). Above ~8 features, restrict depth-2 to scheduled runs only.
### `cargo-deny` for supply chain
`cargo-deny` is a strict superset of `cargo-audit`: licenses, security advisories, banned crates, source policy (only crates.io, only certain git remotes). Add `deny.toml`:
```toml
[advisories]
db-urls = ["https://github.com/rustsec/advisory-db"]
yanked = "deny"
unmaintained = "warn"
[licenses]
allow = ["MIT", "Apache-2.0", "Apache-2.0 WITH LLVM-exception", "BSD-3-Clause", "ISC", "Unicode-DFS-2016"]
confidence-threshold = 0.93
[bans]
multiple-versions = "warn" # several copies of `syn`, `hashbrown`, etc. is normal but worth eyeballing
wildcards = "deny" # `*` version requirements are a footgun
[sources]
unknown-registry = "deny"
unknown-git = "deny"
```
Run `cargo deny check` in CI on every push for everything except advisories; run advisories on a daily schedule so an upstream CVE disclosure doesn't fail every PR until you bump.
### MSRV verification with `cargo-msrv`
If the crate publishes a `rust-version = "1.X"` in `Cargo.toml`, verify it actually builds against that version. `cargo-msrv verify` does this. Slow (downloads a toolchain), so run nightly in CI, not on every push.
### Coverage the reliable way
```bash
cargo llvm-cov --workspace --all-features --lcov --output-path lcov.info
cargo llvm-cov report --fail-under-lines 80 # tune the threshold per repo
```
Make generating `lcov.info` part of the gate, not conditional on its presence. Per-crate thresholds (via `cargo-llvm-cov`'s `--fail-under` per-package or a follow-up script) prevent one well-tested crate from masking the rest.
### Public-API drift for libraries (`cargo-semver-checks`)
For library crates published to crates.io, accidental breaking changes are a real cost. Add `cargo semver-checks check-release` as a release-gate (not every-push) — it diffs the current crate against the latest published version and fails on undeclared breaking changes.
### `miri` for unsafe-heavy crates
If the crate has `unsafe` blocks, run the test suite under `miri` to catch undefined behavior:
```bash
cargo +nightly miri test --workspace
```
Slow (10–100× normal test time). Run as a separate `miri.sh` script invoked nightly in CI, not in `check.sh`.
### Pre-commit / pre-push split
Pre-commit must be <15s or developers start using `--no-verify`. Split:
- **pre-commit (~10s)**: `cargo fmt --check` on staged files, `cargo clippy --workspace --no-deps -- -D warnings` scoped to changed crates only (`cargo clippy -p <changed-crate>`).
- **pre-push (~60–180s)**: the full orchestrator — fmt, check, clippy, build, doc, machete, tests.
`cargo check` and `cargo clippy` benefit massively from a warm target dir, so set `CARGO_TARGET_DIR=$HOME/.cache/cargo-target-shared` in the dev profile if it isn't already.
### Project-specific gates belong in the orchestrator
Mature Rust repos often need custom checks the template doesn't cover: schema migration freshness, protobuf regen, OpenAPI contract drift, generated bindings (`bindgen`, `tonic-build`), cross-compile smoke (`cargo check --target aarch64-unknown-linux-gnu` on an x86 dev box), license header presence. Add them as additional gates in the `xtask` orchestrator — don't try to cram them into `check.sh`.
## Customization options
Ask the user if they want to adjust:
- **Lint strictness** — `unwrap_used`/`expect_used`/`panic` are on by default; relax to `allow` for binary crates or research code where pragmatic panics are common.
- **Complexity thresholds** — defaults in `clippy.toml` are 25 cognitive, 7 args, 250 type-complexity; tune per repo.
- **Feature matrix depth** — none / `--all-features` / `cargo hack --depth 1` / `cargo hack --depth 2`.
- **Test runner** — `cargo test` (stdlib) vs `cargo nextest` (faster, better output, retry support).
- **Coverage minimum** — only if adopting Step 12's coverage pattern.
- **Additional gates** — `cargo audit` / `cargo deny`, `miri`, `cargo-mutants`, `cargo-semver-checks`, MSRV verification.
- **Workspace vs single crate** — single-crate repos don't need `[workspace.lints]`; put lints directly in the crate's `Cargo.toml [lints]` table.
- **Stable vs nightly toolchain** — nightly unlocks `udeps`, unstable rustfmt options, and `miri` but adds churn from compiler regressions.
---
> Source: [CaliLuke/skills](https://github.com/CaliLuke/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
按说明文件中的顺序排列。
第 1 步:在接触任何内容之前评估存储库
功能和 target-cfg — 检测一次,随处使用
第 2 步:清点现有登机口并实施增量
第三步:安装开发工具
核心(每个 Rust 项目)
文件/命令 -> prek run --all-files · .pre-commit-config.yaml · prek · check.sh · clippy.toml · rustfmt.toml · [lints] · Cargo.toml
内容校验值 -> 7bc3fe12727a
当前原文的自动摘译,尚未人工审校。
功能和 target-cfg — 检测一次,随处使用
Rust 比 JS 更简单(一个工具链,一个包管理器),但 Cargo 功能是等效的陷阱。具有默认功能的
cargo build编译的子集与--all-features不同,并且某些功能组合根本不能一起编译。在没有--all-features的情况下运行cargo clippy(或者在没有--each-feature的情况下进行组合覆盖)会为功能门控代码产生静默无操作。检查:核心(每个 Rust 项目)
这些使用工具链版本。如果
rust-toolchain.toml固定特定版本(例如stable-1.85),clippy和rustfmt匹配 - 开发人员之间没有版本漂移。大多数生产存储库都会固定特定的稳定版本(而不是浮动的stable通道);它消除了“在我的机器上触发但不在 CI 中触发的 lint”调试。