po4yka/rust-skills/rust-lints

Rust lints

A lint rejects a whole class of defect for every author. A written rule ("no unsafe", "no bare allow") is not enforcement until a lint level or a CI check carries it. Write down only the level that is actually deployed: a document that shows a target level as the current one makes reviewers stop checking what the compiler does not check either. Read references/triage.md when a clippy, cargo fmt, or cargo doc gate is red.

Where lint policy lives

Put every lint level in the workspace root Cargo.toml. Every member inherits it:

[lints]
workspace = true

Put no lint levels in a member manifest. A per-crate override is invisible to a reader of the root policy, and it drifts.

A crate attribute overrides the inherited level in both directions. A #![warn(lint)] in lib.rs lowers a workspace deny to warn for that crate (verified on 1.98.1). Only forbid cannot be lowered. Restate an inherited lint in source only at the same or a stricter level. To relax a lint in one crate, follow the order in Suppressions.

Verification

While you iterate, run the crate gate from Add a crate. Before a commit or a merge, run the workspace gate:

# --all-features only when the features are additive; see the first bullet below.
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --no-deps --document-private-items --all-features
cargo nextest run --locked --workspace --all-features  # without cargo-nextest: cargo test
cargo test --locked --workspace --all-features --doc   # nextest does not run doctests
cargo deny --config deny.toml --locked check  # when dependencies, Cargo.lock, or deny.toml change

What each check proves, and what it does not:

• --all-features is correct only when the features are additive. With mutually exclusive

features, run clippy once per supported feature set, or run cargo hack clippy --each-feature --workspace --all-targets --locked -- -D warnings when cargo-hack is installed. Give cargo doc and the tests the same feature sets as clippy. The cargo-workflows skill owns the feature matrix.

• Clippy does not run rustdoc lints. [workspace.lints.rustdoc] and

#![deny(rustdoc::broken_intra_doc_links)] act only under cargo doc. On 1.98.1 a broken intra-doc link passes clippy and cargo test --doc, and fails only cargo doc. Without --document-private-items, rustdoc does not resolve the links in the docs of private items (verified on 1.98.1). Without -D warnings, cargo doc also passes warn-level rustdoc lints such as private_intra_doc_links.

• A host run does not lint code behind #[cfg(target_os = "android")] or another target cfg.

Run cargo clippy --locked --workspace --target <triple> --all-targets -- -D warnings for each shipped target after rustup target add <triple>.

• -- -D warnings does not deny linker_messages (warn by default since 1.97, outside the

warnings group). Clippy does not link, so only cargo build or cargo test prints linker output. The default policy keeps linker_messages at warn, because linker output changes with the host linker. To fail CI on linker output, run the build or test step with CARGO_BUILD_WARNINGS=deny (1.97+).

• A green gate on one toolchain can go red on the next: a clippy release adds lints to

pedantic and nursery. Pin the toolchain, and re-run the gate after each bump.

• cargo fmt --all rewrites every file. When cargo fmt --all -- --check is red before your

change, run rustfmt --edition 2024 --config skip_children=true <file> on the changed files only: plain rustfmt <file> also formats each module the file declares (1.99.1). Run the tests again after formatting.

CARGO_BUILD_WARNINGS=deny (or build.warnings = "deny" in .cargo/config.toml) fails a local crate that has lint warnings. It does not change RUSTFLAGS, so the build cache survives; add --keep-going to see the warnings of every crate. It also fails on linker_messages and on cargo doc warnings (both verified on 1.98.1). Cargo older than 1.97 ignores it, and the gate passes silently. Use it only when the pinned toolchain is 1.97 or newer; keep -- -D warnings otherwise. Set CARGO_BUILD_WARNINGS=deny in the CI job environment, not in a checked-in .cargo/config.toml: the config key also turns every local warning into an error while a developer iterates. Do not use RUSTFLAGS=-Dwarnings: it rebuilds every dependency and replaces the rustflags from config files. RUSTDOCFLAGS also replaces build.rustdocflags from config (verified on 1.98.1); when the config sets rustdocflags, use CARGO_BUILD_WARNINGS=deny for the cargo doc line instead.

Audit suppressions after a lint change. Every hit needs reason = "...", and every // TODO(<owner>) needs a tracked follow-up:

rg '#!?\[(allow|expect)\(' --type rust -n
rg 'cfg_attr\([^)]*(allow|expect)\(' --type rust -n

The [workspace.lints] table

Read references/workspace-lints.md when you create or change the table. It holds the strict template for a new workspace and the pragmatic baseline for an existing one with a backlog. Climb from the baseline with Add or tighten a lint.

Read references/lint-catalog.md when you must justify a level, pick lints from restriction, add the optional pointer/FFI or async block, or read the binding-layer rules.

clippy.toml

# No msrv key. Clippy reads `rust-version` from each member's Cargo.toml; members inherit it
# with `rust-version.workspace = true`. Without it, clippy suggests APIs newer than the MSRV.
# Delete an existing msrv key: when it differs from `rust-version`, clippy warns and uses the
# clippy.toml value (verified on 1.98.1).
 
# Allow a known duplicate major version instead of letting clippy::multiple_crate_versions
# (the `cargo` group) fail the build. Name both consumers in a comment.
allowed-duplicate-crates = ["bitflags"]
 
# The default `true` holds back every lint whose fix changes an exported signature. Set
# `false` when no external crate consumes the API. Keep `true` for a crate on crates.io or a
# stable FFI or binding surface.
avoid-breaking-exported-api = false
 
# Test code may unwrap. Non-test code uses `?`, or `.expect("<invariant>")` for a real
# invariant (the `rust-discipline` skill owns that rule).
allow-unwrap-in-tests = true
allow-expect-in-tests = true
# Add the matching key only for a lint you enabled:
# allow-panic-in-tests            = true
# allow-print-in-tests            = true
# allow-dbg-in-tests              = true
# allow-indexing-slicing-in-tests = true
 
# Words clippy::doc_markdown must not ask you to backtick. ".." keeps clippy's default list
# (it already has SQLite, WebAssembly, GitHub, iOS, macOS) and appends yours.
doc-valid-idents = ["..", "UniFFI"]
 
stack-size-threshold         = 4096   # large_stack_frames fires above 4 KiB (default 512000)
future-size-threshold        = 16384  # default; large_futures fires above 16 KiB
enum-variant-size-threshold  = 200    # default; large_enum_variant compares the two largest variants
large-error-threshold        = 128    # default; result_large_err fires when Err reaches it
# large-error-ignored        = ["your_crate::RareBigError"]
type-complexity-threshold    = 250    # default; a higher value is debt
too-many-arguments-threshold = 6      # default 7; skips extern fns, see references/triage.md
 
# clippy::disallowed_methods turns each entry into a lint. The reason is printed in the
# diagnostic: write it for the person who hits the error.
disallowed-methods = [
  { path = "std::mem::forget",  reason = "use ManuallyDrop and document the Drop semantics" },
  { path = "std::env::set_var", reason = "not thread-safe; set it before threads start" },
  # Does not catch the `<*const T>::read` method.
  # `cast_ptr_alignment` catches the misaligned cast.
  { path = "std::ptr::read",    reason = "use ptr::read_unaligned for byte buffers from I/O or FFI" },
  # Catalog default, not a Rust rule (the `rust-code-style` skill): a `for` loop shows the effect.
  { path = "std::iter::Iterator::for_each", reason = "use a `for` loop for side effects" },
]

Run cargo clippy --locked --workspace --all-targets after you add a disallowed-methods or disallowed-types entry. Clippy matches the resolved function, not a same-named method on another type. It can ignore a path that it cannot resolve without a warning (<*const T>::read on 1.98.1). Check that the entry fires where you expect.

Keep one clippy.toml, beside the root manifest. Clippy reads only the nearest file: a member's own clippy.toml replaces the root file, and every root key, disallowed-methods included, stops applying to that member (verified on 1.98.1).

With allow-unwrap-in-tests = true, an #[expect(clippy::unwrap_used)] on test code is unfulfilled, and -D warnings fails on it (verified on 1.98.1). Do not add a per-test suppression that the key already covers. The keys cover only #[test] functions and #[cfg(test)] items: not a shared helper module under tests/, and not an examples/ file (see Suppressions).

rustfmt.toml

Use stable options only. A stable toolchain ignores an unstable option with a warning, so the file formats one way on nightly and another on stable, and cargo fmt --check splits the team.

edition = "2024"
style_edition = "2024"
max_width = 120
use_small_heuristics = "Max"

cargo fmt takes each crate's edition from Cargo.toml and ignores edition here. A direct rustfmt call (an editor, a pre-commit hook) reads it. Set edition and style_edition to the workspace steady-state edition, so that cargo fmt and a direct rustfmt sort imports the same way. Without either key, a direct rustfmt call uses style edition 2015. It then sorts use a::{u8x, U8} differently from cargo fmt on an edition-2024 crate, and CI fails on files that look formatted. edition alone also sets the style edition; set both so the intent is explicit. During a staged edition migration, keep both keys at the old edition until the last crate moves; the cargo-workflows skill owns that sequence. Verified on 1.98.1: stable rustfmt accepts style_edition without the unstable-option warning.

deny.toml

cargo deny --config deny.toml --locked check is the supply-chain part of the gate. The rust-security skill owns the deny.toml policy (licenses, advisories, bans, sources, ignore review) and the failure triage.

Crate-level attributes

Put #![forbid(unsafe_code)] in every crate that has no hand-written unsafe, including a crate that calls C through a safe wrapper crate. Set it per crate, never in [workspace.lints.rust]: a workspace forbid cannot be lowered by the one crate that owns unsafe.

#![forbid(unsafe_code)]