rust-style-clippy

Rust Style Formatting and Static Analysis

Based on the `rustfmt Book`, `Clippy Book`, `Edition Guide`, and `Error Code Index`.

Capability Boundaries

✅ Strengths

1. Stable rustfmt configuration (edition, maxwidth, tabspaces, usefieldinit_shorthand, etc.)
2. Clippy lint system — all 10 lint groups: correctness, suspicious, style, complexity, perf, pedantic, restriction, cargo, nursery, internal
3. clippy.toml configuration (msrv, arithmetic-side, cognitive-complexity-threshold, avoid-breaking-exported-api, etc.)
4. #[expect(...)] attribute (Rust 1.81+) for CI-enforced lint expectations
5. Lint priority ordering for layered policy
6. Production CI lint policy (deny/warn/allow decisions per group)
7. Edition migration (2015→2018→2021→2024, key changes per edition and cargo fix commands)
8. Compiler error code interpretation (rustc --explain, common error codes reference table)

⚠️ Prerequisites

1. Rust toolchain installed and configured

❌ Out of Scope

1. Rust syntax basics → Use rust-stable skill
2. Code review → Use rust-code-review skill
3. API shape design (naming, type/trait design, module layout) and the full ~100 C- API Guidelines checklist → Use the `rust-api-design` skill. This skill only maps the ~25 C- rules that Clippy can mechanically enforce; the rest are design decisions.

When to Use

• "Format Rust code"
• "Run Clippy"
• "Migrate to a new Edition"
• "What does compiler error E0xxx mean?"

I. rustfmt Configuration

# .rustfmt.toml
max_width = 100                    # Line width (default: 100)
tab_spaces = 4                     # Indentation spaces
edition = "2024"                   # Rust edition
merge_derives = true               # Merge derives
use_field_init_shorthand = true    # Field initialization shorthand
use_try_shorthand = true            # Use ? shorthand

cargo fmt                           # Format all files
cargo fmt --check                   # Check formatting (CI usage)
cargo fmt -- --config max_width=80  # Apply specific configuration

Options such as imports_granularity, group_imports, and reorder_impl_items may still require nightly rustfmt; do not include them in default configurations that must pass stable CI.

II. Clippy

cargo clippy                              # Default: correctness, suspicious, style, complexity, perf
cargo clippy -- -W clippy::pedantic       # Enable pedantic group
cargo clippy --fix                        # Auto-fix MachineApplicable lints
cargo clippy -- -A clippy::module_inception  # Allow a specific lint

All 10 lint groups

#[expect] attribute (Rust 1.81+) — better than #[allow]

// ✅ #[expect] — CI fails if the lint stops firing, surfacing dead expectations
#[expect(clippy::too_many_arguments, reason = "configurable builder has many options")]
fn build(name: &str, retries: u32, timeout: u32, /* 5 more */) { /* */ }

// ❌ #[allow] — silently becomes dead code if the lint stops firing
#[allow(clippy::too_many_arguments)]
fn build(/* */) { /* */ }

Prefer #[expect] for intentional suppressions; reserve #[allow] for transient reasons.

Lint priority — layering

// Higher priority wins. Use for layered policy.
#![warn(clippy::pedantic)]                       // enable pedantic (priority 0)
#![warn(priority = 1, clippy::module_name_repetitions)]  // re-enable a specific lint

clippy.toml configuration

# clippy.toml at workspace root
msrv = "1.85"                                  # Don't suggest APIs newer than MSRV
avoid-breaking-exported-api = false            # Suggest fixes that change public API
cognitive-complexity-threshold = 25            # Function complexity limit
arithmetic-side = "checked"                    # Prefer checked_* arithmetic
enum-variant-name-threshold = 1                # Trigger variant_name lint
single-char-binding-names-threshold = 3        # Allow `_a`, `_b`, but not 4+
too-many-arguments-threshold = 7
type-complexity-threshold = 250
disallowed-methods = [
    { path = "std::env::var", reason = "use our config::get instead" },
]
disallowed-types = [
    { path = "std::collections::LinkedList", reason = "almost never the right choice" },
]
disallowed-macros = [
    { path = "std::println", reason = "use tracing in libraries" },
]

See references/clippy-lint-policy.md for the full clippy.toml reference and production policies.

Production CI lint policy

Different projects need different strictness. See references/clippy-lint-policy.md for ready-to-paste configurations.

III. Edition Migration

# Check current edition
cargo metadata --format-version 1 | jq '.packages[0].edition'

# Migration steps (example: 2021 → 2024)
cargo fix --edition               # Auto-migrate code
cargo build                       # Verify compilation
cargo test                        # Validate functionality

# Update Cargo.toml
# edition = "2024"

Key changes per edition:

IV. Compiler Error Code Quick Reference

# View error details
rustc --explain E0277

V. API Guidelines ↔ Clippy Lints

The Rust API Guidelines checklist uses C-* rules (about 100 total). Clippy mechanically enforces roughly 25 of them; the remaining ~75 are design judgments (naming, type/trait shape, module layout) that belong to the rust-api-design skill, or require cargo-semver-checks for breaking-change detection. The table below lists the 12 highest-leverage mappings reviewers ask about most. The full crosswalk, including "lints not yet covered" guidance, lives in `references/api-guidelines-to-clippy.md`.

Many restriction and pedantic lints are off by default — enable them explicitly via #![warn(clippy::unwrap_used)] or in clippy.toml when enforcing a guideline in CI.

Workflow

1. Format code — cargo fmt ensures consistent style
2. Run Clippy — cargo clippy runs the 5 default groups (correctness, suspicious, style, complexity, perf); add -W clippy::pedantic for stricter
3. Decide policy — pick pedantic/restriction level by project type (see table above); paste the matching config from references/clippy-lint-policy.md
4. Configure clippy.toml — set msrv, disallowed-methods, and any project-specific thresholds
5. Use #[expect] for intentional suppressions — keeps CI honest about dead expectations
6. Check Edition — Confirm edition in Cargo.toml is up-to-date
7. CI integration — cargo fmt --check + cargo clippy -- -D warnings + cargo audit in CI

Gotchas

1. cargo clippy --fix only fixes lints at MachineApplicable level
2. rustfmt config file is named .rustfmt.toml, not rustfmt.toml
3. After edition migration, new warnings may appear — especially around unsafeopinunsafefn in 2024
4. cargo fix --edition does not fix all issues; manual review required after migration
5. Prefer let ... else for early exits and is_some_and/then_some for simple boolean mapping; avoid compressing complex control flows just to use modern syntax
6. saturating_*, checked_*, and regular arithmetic expressions have different business semantics regarding overflow strategy — decide first, then select API

On-Demand Resources

• Format and Clippy Examples
• Lint Group Quick Reference
• Clippy Lint Policy: Full clippy.toml reference, all 10 lint groups in depth, #[expect] patterns, priority layering, and ready-to-paste production CI configurations by project type.
• Production Rust Idioms: Review let-else, Option combinators, newtype patterns, non-exhaustive APIs, lock scopes, and overflow strategies when reviewing production code.
• API Guidelines ↔ Clippy Lints Crosswalk: Full mapping from Rust API Guidelines C-* rules to the Clippy lints that enforce them, plus the ~75 rules Clippy does not cover and where to review them.
• examples/golden-style/: Golden examples for CI passing rustfmt and Clippy

Official References

• rustfmt Book
• Clippy Book
• Edition Guide
• Compiler Error Index