perfectionist lints

perfectionist::allow_attributes↑ top

active#[allow] for a deterministically-firing lint should be removed or be #[expect]

What it does

Flags #[allow(<lints>)] when every named lint fires deterministically — a built-in rustc lint (not on the exempt list), a clippy::* / rustdoc::* lint, or a tool-namespaced lint such as perfectionist::*. Such a suppression can be resolved two ways:

1. Remove it — when the lint can no longer fire at the site (a dead suppression, e.g. clippy::too_many_arguments left on a function that has since shed its arguments).
2. Replace it with #[expect] — when the lint still fires and you want the suppression to report itself the moment it stops.

If the attribute also names a lint the rule leaves alone (an exempt or unknown lint), only the deterministic names are resolved; the rest stay under #[allow].

Crate- and module-level scopes (#![allow(...)], and outer #[allow(...)] on a mod item) are left alone by default, because a cfg-conditional body inside the scope may fire the lint in one configuration and not another — set apply_to_outer_scopes = true to opt in.

Why restrict this?

This is a stylistic preference, not a correctness issue. A suppression often outlives the problem it suppressed. #[allow] stays silent forever, including after the underlying issue is resolved, so a project accumulates stale #[allow] attributes that no longer apply. #[expect] emits unfulfilled_lint_expectations the moment the named lint stops triggering at the site — exactly when the suppression becomes dead — so routine compilation tells the author to remove it. Every #[expect] is also a self-test that the lint does fire at the site, so a future refactor that inadvertently fixes the issue is observed rather than hidden.

Interaction with Clippy

clippy::allow_attributes (restriction, off by default) also pushes #[allow] towards #[expect], but rewrites every #[allow] indiscriminately, and only towards #[expect]. This rule flags only the lints that fire deterministically, leaving lint groups and conditionally-firing lints under #[allow]. Crucially, it does not assume #[expect] is always the answer: a deterministic #[allow] may already be dead, in which case #[expect] would be unfulfilled and removal is the right fix, so the rule offers both. Reach for this rule for that precision, or clippy::allow_attributes for a blunt crate-wide sweep.

Example

Avoid:

#[allow(clippy::too_many_arguments, reason = "matches pnpm's signature")]
fn build_fetcher(/* ... */) {}

Prefer:

#[expect(clippy::too_many_arguments, reason = "matches pnpm's signature")]
fn build_fetcher(/* ... */) {}

Source: src/rules/allow_attributes.rs

perfectionist::allow_attributes_without_reason↑ top

active#[allow] / #[expect] attribute lacks an explanatory reason = "..." field

What it does

Requires every #[allow(<lints>)] and #[expect(<lints>)] attribute to carry an explanatory reason = "..." field. #[allow] and #[expect] are the two levels that fully silence a lint's output; the project's record of suppressions needs to know why each one exists.

The check is purely local — the attribute itself — and does not depend on any inherited or ambient lint level.

Why restrict this?

This is a stylistic preference, not a correctness issue. Suppressions outlive the conditions that justify them. A bare #[allow(clippy::too_many_arguments)] told the original author to ignore a complaint; six months later, no one knows whether the rationale was "matches upstream signature", "intentional over-engineering", or "we'll fix it in the next refactor". The reason field records intent at the moment of suppression, and rustc renders it back in unfulfilled_lint_expectations notes when a stale #[expect] is encountered.

Interaction with Clippy

clippy::allow_attributes_without_reason (restriction, off by default) flags a missing reason = "..." on the same two levels this rule does — #[allow] and #[expect] — and only those, so the trigger overlaps. This rule adds a quality floor Clippy lacks: min_reason_length (default 3) flags a content-free reason = "ok" that Clippy accepts, and a blank reason = "" is treated as missing. It also takes a per-lint exempt_lints list and fires regardless of the crate's MSRV, where Clippy's is gated on the lint_reasons stabilisation. For the bare presence check alone, the Clippy lint is equivalent.

Example

Avoid:

#[allow(clippy::too_many_arguments)]
fn build_fetcher(/* ... */) {}

Prefer:

#[allow(clippy::too_many_arguments, reason = "matches upstream signature")]
fn build_fetcher(/* ... */) {}

Source: src/rules/allow_attributes_without_reason.rs

perfectionist::avoidable_string_escapes↑ top

activestring literal contains only raw-expressible escapes; prefer the raw-string form

What it does

Forbids regular string literals whose only backslash escapes are ones a raw string would express verbatim — \", \\, and \'. The autofix rewrites the literal to the raw form r"..." / r#"..."#, picking the smallest hash count that avoids a delimiter collision.

Literals inside macro invocations are covered too: every string literal in a macro call, whatever its position — including a format!-family template that contains a {...} placeholder. The rewrite is value-preserving (a raw string still parses placeholders, and {{ / }} survive verbatim), so the literal's role doesn't matter. Suppress a site where the regular form is deliberately preferred.

That includes literals a macro uses for their source spelling rather than their value, such as stringify! and dbg!, where the raw form has the same value but a different reflected text. This is intentional: code whose behaviour depends on a literal's exact spelling instead of its value is rare and a code smell; suppress it per site with #[expect(perfectionist::avoidable_string_escapes)].

Pattern-position literals in ordinary code (e.g. match s { "C:\\path" => ... }) are out of scope; only expression-position literals are rewritten. A literal written as a pattern inside a macro call (e.g. matches!(s, "C:\\path")) is rewritten anyway, since a literal's position isn't distinguished inside a macro.

Whitespace and control-character escapes (\n, \t, \r, \0) and Unicode escapes (\x.., \u{..}) are exempt — a raw string cannot express them, and the regular form is the only choice. A literal that mixes eliminable and inexpressible escapes is also left alone; the rewrite would force the author to split the literal or fall back to concat!, which loses more than it gains.

Why restrict this?

This is a stylistic preference, not a correctness issue. The rule trades one noise source (interior backslash escapes) for a slightly more elaborate string syntax. The benefit is highest in strings full of file paths, regex patterns, JSON snippets, or embedded source code — all of which would otherwise be a sea of \\ and \".

Example

Avoid:

let json = "{\"name\":\"foo\"}";
let path = "C:\\Users\\foo\\bar";

Prefer:

let json = r#"{"name":"foo"}"#;
let path = r"C:\Users\foo\bar";

Source: src/rules/avoidable_string_escapes.rs

perfectionist::bare_email↑ top

activebare email address in comment or doc comment; wrap in <...> or prefix with mailto:

What it does

Flags bare email addresses (user@example.com) in doc comments (///, //!) and regular comments (//, /* */). Wrapping in <...>, prefixing with mailto:, or both turns the address into an explicit autolink across CommonMark, GitHub-flavored markdown, and rustdoc.

A forbid style is available for projects that prefer to keep contact information out of source entirely.

Why restrict this?

This is a stylistic preference, not a correctness issue. Bare email addresses rely on the renderer's autolinkification, which is inconsistent across markdown engines. The <email> / mailto:email forms make the autolink intent explicit.

Example

Avoid:

/// Report security issues to security@example.com.

Prefer:

/// Report security issues to <security@example.com>.

Source: src/rules/bare_email.rs

perfectionist::bare_identifier_reference↑ top

activebackticked identifier in a doc comment that resolves in scope should be an intra-doc link

What it does

Flags a backticked identifier in a doc comment (`Foo`) that resolves as a Rust path in the documented item's scope but is not written as a rustdoc intra-doc link ([`Foo`]).

Only bare single identifiers whose name resolves to an item in the enclosing module's scope are flagged; a backticked word that names nothing in scope is left alone.

A publicly-reachable item that mentions a private (not publicly-reachable) item is also left alone: turning that mention into a link would make rustdoc's rustdoc::private_intra_doc_links fire under a plain cargo doc, and a public item leaning on a private one is a separate concern from this rule's.

Why restrict this?

This is a stylistic preference, not a correctness issue. Both `Foo` and [`Foo`] render as monospaced text, so the page looks the same at a glance. The link form additionally turns the mention into a clickable cross-reference and lets rustdoc's rustdoc::broken_intra_doc_links lint catch the day a rename leaves the prose pointing at a type that no longer exists. Spelling every in-scope mention as a link keeps the documentation navigable and the references checked.

Example

Avoid:

/// Installs the package described by `PackageManifest` into `Store`.
pub fn install(manifest: &PackageManifest, store: &Store) {}

Prefer:

/// Installs the package described by [`PackageManifest`] into [`Store`].
pub fn install(manifest: &PackageManifest, store: &Store) {}

Caveat: linking is not always correct

When a backticked word names a foreign symbol that merely shares its name with an in-scope item, rewriting `Foo` to [`Foo`] links to the local item — a wrong reference that still compiles. The rule therefore only suggests the link rather than applying it automatically. For an external target, write an explicit reference link instead: [`Foo`][foo-ext] plus a [foo-ext]: <url> definition.

Source: src/rules/bare_identifier_reference.rs

perfectionist::bare_issue_reference↑ top

activeambiguous bare #NNN issue / PR reference in comment

What it does

Flags bare #NNN issue / pull-request references in doc comments (///, //!) — and, when opted in, in plain // line comments. The autofix rewrites the reference; the doc_comment_form knob selects the shape (inline [#123](URL), reference [#123], a bare URL, or a <URL> autolink).

A bare #NNN is deeply ambiguous: it might be an issue, a pull request, a colour like #123, or any other numbered item, so no suggestion is ever MachineApplicable. The suggest_issue_url / suggest_pr_url knobs choose which link target(s) the autofix offers — each MaybeIncorrect — and with neither enabled the lint is help-only. The author can also resolve the ambiguity by enclosing the token in backticks (so it reads as code) or by using a spelling without a leading #.

Why restrict this?

This is a stylistic preference, not a correctness issue. A bare #123 renders as literal text in CommonMark; only GitHub's markdown flavour autolinks the token, and only when the rendering surface is itself within a GitHub repository view. The link form renders portably across rustdoc, GitHub, and any other markdown engine.

Example

Avoid:

/// Closes #123 and supersedes #124.

Prefer: (with repository = "https://github.com/owner/repo" — forge is detected from the host), picking the issue link for one and the pull-request link for the other:

/// Closes [#123](https://github.com/owner/repo/issues/123) and
/// supersedes [#124](https://github.com/owner/repo/pull/124).

Source: src/rules/bare_issue_reference.rs

perfectionist::bare_url↑ top

activebare URL in comment or doc comment; wrap in <...> or use a labelled markdown link

What it does

Flags bare http:// and https:// URLs in doc comments (///, //!) and regular comments (//, /* */). Wrapping the URL in <...> (or using the labelled [text](url) form) is the portable rendering across CommonMark, GitHub-flavored markdown, and rustdoc.

Why restrict this?

This is a stylistic preference, not a correctness issue. Bare URLs rely on the renderer's autolinkification: rustdoc renders them, GitHub renders them, but plain CommonMark does not. The <...> form is the explicit, portable spelling.

Example

Avoid:

/// See https://example.com for details.

Prefer:

/// See <https://example.com> for details.

Source: src/rules/bare_url.rs

perfectionist::clap_help_markdown↑ top

activemarkdown construct in a clap-derived doc comment leaks into --help output

What it does

Forbids markdown-specific constructs in a doc comment that clap's derive macros consume as --help text — HTML tags, inline / reference / intra-doc links, code blocks, code spans, and headings. The rule fires on the doc comment of a struct or enum deriving clap::Parser, Args, Subcommand, ValueEnum, or CommandFactory, and on the doc comments of their fields and variants.

A ValueEnum's own type-level doc comment is left alone: unlike its variant docs — clap's per-value help — it never reaches --help.

Bold, italics, and lists are not flagged by default — clap renders them as their literal characters, which usually reads cleanly — but are available through the extra_constructs knob.

The lint stays silent on a node that overrides its help text with a plain string (#[arg(help = "...")], #[command(about = "...")], ...), because the doc comment is then no longer the source of truth for --help. A node marked #[clap(verbatim_doc_comment)] instead gets a softer note that the markdown will appear verbatim in the terminal.

A project that never wants a doc comment to become --help text at all — preferring an explicit override on every command, argument, and value — can opt into the stricter require_help_override mode. It flags every clap-derived doc comment that reaches --help without such an override, markdown or not, and reports each as a single missing-override finding rather than per markdown construct. A node with no doc comment is still left alone. This mode is off by default.

Why is this bad?

By default, clap does not render doc comments through a markdown processor. The raw text is shown verbatim in the terminal --help output. Writing [`PathBuf`] produces a docs.rs link in HTML output but shows literally as [`PathBuf`] in the terminal — a classic two-audience leak. The doc comment serves both cargo doc readers and --help readers, and markdown that helps the former actively degrades the latter.

The escape hatch is to override the help text with a plain string, keeping the rich doc comment for cargo doc:

/// Builds the lockfile by walking [`Dependency`] graphs.
#[arg(help = "Builds the lockfile by walking dependency graphs.")]
pub deps: PathBuf,

Example

Avoid:

#[derive(clap::Parser)]
struct Cli {
    /// Path to the [`PackageManifest`].
    ///
    /// See [the manifest format](https://example.com/manifest).
    manifest: PathBuf,
}

Prefer: (no markdown in the help text)

#[derive(clap::Parser)]
struct Cli {
    /// Path to the package manifest.
    manifest: PathBuf,
}

Source: src/rules/clap_help_markdown.rs

perfectionist::excessive_inline_tests↑ top

activeinline test code should be extracted to a separate file

What it does

Caps how much inline unit-test code a production file may carry. Inline test code — #[cfg(test)] mod X { ... } blocks, #[test] fns, #[cfg(test)] fn helpers, and any other #[cfg(test)] item — is summed per file. The default external_when_long style flags a file once its inline-test footprint crosses inline_max_lines (or the optional inline_max_fraction_of_file); external_only flags every inline test item regardless of length. A file whose top-level items are entirely test code is exempt — it is itself a valid extraction target.

An external #[cfg(test)] mod <name>; (its body in a separate file) is neutral: it is already extracted, so it neither charges the footprint nor is otherwise checked. A test module gated by a compound predicate that still implies test — #[cfg(all(test, unix))], #[cfg(all(test, feature = "..."))] — is recognised the same as a bare #[cfg(test)], so its external file is not re-flagged as inline test code in a production file.

Only the library or binary crate is checked. Integration tests (tests/), benchmarks (benches/), and examples (examples/) are separate targets, not the library or binary whose unit-test footprint this rule governs; for those compiled under cfg(test) their top-level #[test] functions are the target rather than unit tests misplaced in a production file, so they are left untouched.

Why restrict this?

This is a stylistic preference, not a correctness issue. Both source projects keep large test suites out of the production file, so the file an editor tab, a grep hit, or a diff shows is production code rather than a wall of fixtures. The threshold is deliberately configurable because the exact budget varies by project.

Example

Avoid:

// File: foo.rs
#[cfg(test)]
mod tests {
    /* ... 200 lines of test code ... */
}

Prefer:

// File: foo.rs
mod tests;

// File: foo/tests.rs
/* ... 200 lines of test code ... */

Source: src/rules/excessive_inline_tests.rs

perfectionist::exhaustive_error_enums↑ top

inactiveerror-shaped type is missing #[non_exhaustive]

What it does

Flags publicly-exposed error enums that lack a #[non_exhaustive] attribute. An enum is treated as an error enum when its name ends in Error (configurable) or it implements std::error::Error. Publicly-exposed sum-like structs (a single field whose type is itself an enum) follow the same rule.

"Publicly-exposed" defaults to pub items; pub(crate) and the whole-crate "every item" sweep are configurable.

Why restrict this?

This is a stylistic preference, not a correctness issue. Adding a variant to an error enum is one of the most common reasons to publish a new minor version of an error-producing library, and #[non_exhaustive] is the standard way to make that addition not a SemVer break for downstream pattern matches. Applying it up front means future variants land without a coordinated major release across the dependents that exhaustively match on the enum.

The opinion is opt-in: some projects deliberately use exhaustive error enums to force downstream consumers to handle every new variant, and binary crates have no SemVer surface to protect. The rule is therefore inactive by default — enable it per crate by adding to dylint.toml:

[perfectionist]
enable = ["exhaustive_error_enums"]

Interaction with Clippy

clippy::exhaustive_enums and clippy::exhaustive_structs (restriction, off by default) require #[non_exhaustive] on every exported enum / struct. This rule scopes that same requirement to error types — those whose name ends in Error or that implement std::error::Error — because adding a variant to an error type downstream code matches on is the breaking change #[non_exhaustive] exists to absorb, while demanding it on all exported types is usually too broad. Enable the Clippy lints instead if you do want that blanket policy.

Example

Avoid:

#[derive(Debug)]
pub enum RuntimeError {
    SerializationFailure,
}

Prefer:

#[derive(Debug)]
#[non_exhaustive]
pub enum RuntimeError {
    SerializationFailure,
}

Source: src/rules/exhaustive_error_enums.rs

perfectionist::import_granularity_mismatch↑ top

activeimport granularity does not match the configured import_granularity_mismatch.style

What it does

Enforces a single project-wide import-granularity style, chosen via style:

• crate — one use per crate root, with every shared prefix collapsed into nested braces (use std::{collections::HashMap, io::Read};).
• module (default) — one use per leaf module; items from the same module are merged into one braced list while sibling modules sit on their own lines (use std::collections::{BTreeMap, HashMap};).
• item — one use per leaf path (use std::collections::BTreeMap;).

The names map one-to-one onto rustfmt's unstable imports_granularity (Crate / Module / Item). Only use statements that sit next to each other in a module body, share a visibility, and carry matching attributes are merged; the three respect_* knobs tighten or loosen that grouping.

Under crate style a name that is both an item and a module (use crate::thing; next to use crate::thing::T;) has two valid one-use shapes — the self-fold crate::thing::{self, T} and the sibling-split crate::{thing, thing::T} — that bind different namespaces. By default neither single-statement form is flagged and both are offered when a merge is forced; the optional self_merge knob (fold / split) picks one and enforces it.

Globs (use foo::*) are governed by perfectionist::wildcard_imports, not by this rule: a top-level glob is left alone under item.

Why restrict this?

This is a stylistic preference, not a correctness issue. None of the three shapes is wrong in the abstract — the violation is a mismatch with the project's configured style. Enforcing one keeps use blocks scanning uniformly and makes import diffs predictable. rustfmt can enforce the same shape, but only on the nightly channel; this lint gives stable-toolchain projects a hard CI check instead of a silent reformat.

Example

Style: Module (default)

Avoid:

use std::collections::HashMap;
use std::collections::BTreeMap;

Prefer:

use std::collections::{BTreeMap, HashMap};

Style: Crate

Avoid:

use std::collections::{BTreeMap, HashMap};
use std::io::Read;

Prefer:

use std::{collections::{BTreeMap, HashMap}, io::Read};

Style: Item

Avoid:

use std::collections::{BTreeMap, HashMap};

Prefer:

use std::collections::BTreeMap;
use std::collections::HashMap;

Source: src/rules/import_granularity_mismatch.rs

perfectionist::import_grouping_mismatch↑ top

inactiveimport grouping does not match the configured import_grouping_mismatch.style

What it does

Enforces a single project-wide grouping style for the run of use statements at the top of a module body. The rule is inactive by default; a project opts in and sets style to one of:

• single_block — every use sits in one contiguous block with no blank lines between imports, except that #[cfg(...)]-gated imports are carved into their own trailing block (one blank line below the rest). Set cfg_block_handling = "merge" to keep them in the one block.
• multi_block — imports are partitioned into ordered groups separated by exactly one blank line. The group set, in order, is std (std / core / alloc / proc_macro / test), internal (crate / super / self), then third-party (every other crate). A bare-path import of a first-party submodule (mod error; use error::Foo;) is classified as internal, not third-party: a bare first segment that names a mod declared in the same module scope is recognised as first-party. The order and cfg_block_handling knobs tune the partition; the inner ordering within each group is left to cargo fmt.

Orthogonally to style, the reexports knob controls pub re-exports — any use with an explicit visibility. Like style it is mandatory once the rule is enabled, and is one of: grouped, which pulls every re-export into one contiguous leading block above the private imports, visibility outranking path and cfg gating; split, which breaks that block into two — submodule re-exports (pub use child::Item;, a multi-segment path) above alias re-exports (pub use Item; / pub use Item as Alias;, a single-segment path); or by_path, which gives re-exports no dedicated block, classifying each by its path like a private import.

This rule only governs the partitioning of imports into blocks. Whether items within each use are merged or split is the job of perfectionist::import_granularity_mismatch.

Why restrict this?

This is a stylistic preference, not a correctness issue. Neither layout is wrong in the abstract — the violation is a mismatch with the project's configured style. Enforcing one keeps import blocks scanning uniformly and makes import diffs predictable. rustfmt's group_imports option can enforce the same shape, but only on the nightly channel; this lint gives stable-toolchain projects a hard CI check instead of a silent reformat. The rule is inactive by default; enable it and pick a style in dylint.toml:

[perfectionist]
enable = ["import_grouping_mismatch"]

["perfectionist::import_grouping_mismatch"]
style = "multi_block"
reexports = "grouped"

Example

Style: Multi block

Avoid:

use clap::Parser;
use std::time::Duration;
use crate::args::Args;

Prefer:

use std::time::Duration;

use crate::args::Args;

use clap::Parser;

Style: Single block

Avoid:

use std::time::Duration;

use crate::args::Args;

use clap::Parser;

Prefer: (one contiguous block; inner order left to cargo fmt)

use clap::Parser;
use crate::args::Args;
use std::time::Duration;

Style: Single block, #[cfg]-gated imports

Avoid: (cfg-gated imports mixed into the one block)

use std::fs::Metadata;
#[cfg(unix)]
use std::os::unix::fs::MetadataExt;
use super::size::Bytes;

Prefer: (cfg-gated imports kept in a trailing block)

use std::fs::Metadata;
use super::size::Bytes;

#[cfg(unix)]
use std::os::unix::fs::MetadataExt;

Re-exports in their own block (reexports = "grouped")

Avoid: (a pub use re-export mixed in with private imports)

pub use reflection::Reflection;
use super::size;

Prefer: (re-exports kept in their own leading block)

pub use reflection::Reflection;

use super::size;

Split re-exports (reexports = "split")

Avoid: (submodule re-exports and alias re-exports intermixed)

pub use Reflection as HardlinkListReflection;
pub use iter::Iter;
pub use reflection::Reflection;

Prefer: (submodule re-exports lead, alias re-exports follow)

pub use iter::Iter;
pub use reflection::Reflection;

pub use Reflection as HardlinkListReflection;

Source: src/rules/import_grouping_mismatch.rs

perfectionist::impure_macro_arguments↑ top

activemacro invocation passes an impure expression that should be bound to a let first

What it does

Flags impure expressions passed as top-level arguments to a function-like (name!(...)) or array-like (name![...]) macro invocation. The fix is to bind the expression to a let first and pass the binding instead, guaranteeing exactly-once evaluation.

Curly-brace invocations (name! { ... }) are out of scope: by convention they are DSL bodies (thread_local! { ... }, quote! { ... }, html! { ... }) where the evaluation contract is the macro's, not the call site's.

Why is this bad?

A function-like or array-like macro may evaluate any top-level argument zero, one, or many times depending on its matcher. Functions guarantee exactly-once evaluation per argument; macros do not, even when the call shape looks identical. The classic case is debug_assert_eq!:

debug_assert_eq!(map.insert(key, value), None, "duplicate");

In debug builds the call runs and the assertion holds. In release builds debug_assertions is off, the body folds to if false { ... }, and the argument expressions are not evaluated — insert never runs and the map ends the function in a state the author did not intend. The bug only surfaces under --release.

The same trap covers any macro that expands its capture more than once (min!/max!-style, retry loops): a side-effecting expression repeated produces wrong results.

Terminology

In this rule, pure means safe for the surrounding macro to drop or duplicate: evaluating the argument zero, one, or many times is observationally equivalent. Impure is anything else, and is what the rule flags.

The classification is syntactic: the rule recognises a curated set of shapes known to satisfy the property and treats everything else as impure. A const fn call, a Result::map chain over a pure base, or vec.fold(...) is therefore impure under this rule unless its shape is recognised — the lint cannot prove side-effect-freedom in general, only spot it. The trade-off favours flagging side-effect-free expressions over silently passing a real hazard. The set is narrower than the functional-programming notion of purity and is keyed to what a macro can actually do with its captures, not to side-effect-freedom in the abstract.

The recognised pure shapes are: literals, paths, field accesses, indexing of pure bases, dereferences, references, the logical / bitwise not of a pure expression (!ready), casts, the unit literal (), parenthesised / tuple / array-literal / array-repeat groups whose elements are all pure, binary chains of pure operands joined by side-effect-free operators, zero-arg method calls whose name is in the curated pure-getter set (len, is_empty, as_str, as_bytes, as_ref, as_mut, as_deref, as_slice, plus anything in extra_pure_methods), and calls to core / std macros whose expansion is a compile- time constant (concat!, env!, option_env!, include_str!, include_bytes!, stringify!, cfg!, line!, column!, file!, module_path!, plus anything in extra_pure_macros). A comparison like vec.len() <= cap evaluates the same way regardless of how many times the macro touches it, so binding it to a let would only force the comparison to run in release builds for no benefit; the same logic applies to env!("HOME") inside debug_assert_eq!(...) — there is nothing to evaluate at runtime.

Example

Bad:

debug_assert_eq!(map.insert(key, value), None, "duplicate");

Good:

let ejected = map.insert(key, value);
debug_assert_eq!(ejected, None, "duplicate");

Source: src/rules/impure_macro_arguments.rs

perfectionist::lint_attribute_trailing_comment↑ top

activetrailing comment on a lint-level attribute should be lifted into a reason = "..." field

What it does

When a lint-level attribute (#[allow], #[expect], #[warn], #[deny], #[forbid]) carries a trailing // ... line comment — on the same source line as the attribute's closing ] — that documents why the level was chosen, lifts the comment into the attribute's reason = "..." field and removes the original comment.

Only the trailing placement counts: a same-line comment after ] is unambiguously about the attribute. A comment on the preceding line is intentionally out of scope — it is just as often documentation for the next item as it is attribute rationale, and a static check cannot tell the two apart.

Doc comments (///, //!) and block comments (/* ... */) are out of scope.

Why restrict this?

This is a stylistic preference, not a correctness issue. reason = "..." is part of the attribute and travels with it through every refactor; a free-floating comment can be separated from its attribute by an unrelated edit. Compiler diagnostics render the reason field in the lint's message, so the rationale reaches the reader at the moment of confusion. One canonical location for the rationale also removes the "is this comment for the attribute, or for the next item?" question.

Example

Avoid:

#[allow(clippy::too_many_arguments)] // matches upstream signature
fn build_fetcher(/* ... */) {}

Prefer:

#[allow(clippy::too_many_arguments, reason = "matches upstream signature")]
fn build_fetcher(/* ... */) {}

Configuration: none.

Source: src/rules/lint_attribute_trailing_comment.rs

perfectionist::macro_trailing_comma↑ top

activemacro invocation does not follow rustfmt's vertical trailing-comma policy

What it does

For function-like macro invocations whose top-level arguments are comma-separated, enforces rustfmt's trailing_comma = "Vertical" policy that rustfmt itself does not apply inside macro bodies: multi-line invocations must end with a trailing comma; single-line invocations must not.

Eligibility is name-based — a curated list of core / std and well-known third-party macros (vec!, format!, println!, assert_eq!, dbg!, log::info!, tracing::debug!, anyhow::bail!, maplit::hashmap!, ...), extended via extra_macros and overridden via ignore.

Attribute-style invocations (#[derive(...)], #[serde(...)], etc.) are out of scope.

Why restrict this?

This is a stylistic preference, not a correctness issue. rustfmt's default trailing_comma = "Vertical" policy keeps argument lists uniform: every multi-line list ends with a comma, every single-line list does not. rustfmt opts out of macro bodies because a macro matcher can make the trailing comma load-bearing; for the curated macros covered by this lint, it cannot, and the policy applies without risk.

Multi-line invocations whose first top-level token starts on the opening-delimiter line (visual-indent / compact layout, e.g. vec![Inner { ... }]) are skipped: rustfmt's Vertical policy only adds a trailing comma when each top-level item is on its own line, separate from the delimiter, and strips any comma added to the compact shape. The two tools have to agree.

Example

Avoid:

let xs = vec![
    1,
    2,
    3
];
let ys = vec![1, 2, 3,];

Prefer:

let xs = vec![
    1,
    2,
    3,
];
let ys = vec![1, 2, 3];

Source: src/rules/macro_trailing_comma.rs

perfectionist::named_prelude_imports↑ top

activenamed item cherry-picked from a prelude module instead of glob-imported

What it does

Flags a use statement that cherry-picks a named item out of a prelude module (use serde::prelude::Serialize;) and leaves the glob form (use serde::prelude::*;) alone. The set of segment names treated as preludes is configurable via prelude_segment_names (default ["prelude"]), and individual prelude paths can be exempted with allowed_paths.

This is the dual of perfectionist::wildcard_imports: that rule restricts globs in general but lets preludes glob freely, while this rule restricts named imports from a prelude and lets the glob form through.

Why restrict this?

This is a stylistic preference, not a correctness issue. A prelude module is, by convention, a curated set of items the crate author decided should always travel together as a glob. Cherry-picking individual items from a prelude defeats that intent and usually means the importer should reach into the prelude's source module instead. A standalone import is rewritten to the item's canonical module; a brace-list leaf (use foo::prelude::{A, B};) — or a name that resolves through several modules at once — is flagged with a help instead, since a single use can't always reproduce it.

Example

Avoid:

use serde::prelude::Serialize;
use diesel::prelude::{table, AsChangeset};

Prefer:

From the canonical module: import each item where it actually lives.

use serde::Serialize;
use diesel::{table, AsChangeset};

As a prelude glob: pull in the whole curated set at once.

use diesel::prelude::*;

Source: src/rules/named_prelude_imports.rs

perfectionist::needless_borrowed_parameters↑ top

activeborrowed parameter is only used to produce its owned form

What it does

Flags a function or method parameter taken by shared reference (&str, &Path, &OsStr, &CStr, &[T]) whose only use in the body is to produce its owned counterpart (String, PathBuf, OsString, CString, Vec<T>) — via to_owned, to_string, to_path_buf, to_vec, to_os_string, clone, into, or String::from(..) and friends. Such a parameter should take the owned form directly.

Only the conservative single-use case is implemented: the parameter must be referenced exactly once, that use must be the conversion, and the conversion must execute unconditionally — no if / match / loop, closure, or short-circuiting && / || may sit between it and the enclosing function. This is deliberately conservative: even the always-executed if condition and match scrutinee positions count as disqualifying, not just the branch arms. The broader dominance-analysis cases described in planned-rules/needless-borrowed-parameters.md are still pending.

Why restrict this?

This is a stylistic preference, not a correctness issue. Taking the borrowed form and converting inside the body forces a copy even when the caller already owns the value. Taking the owned form moves the caller's value straight in; a caller that holds only a borrow performs the very same conversion at the call site that the borrowed signature was performing internally. The total number of copies is identical for the worst caller and one cheaper for the best caller.

Interaction with Clippy

clippy::needless_pass_by_value (pedantic, off by default) covers the opposite direction: a by-value parameter that is never consumed should be taken by reference. clippy::ptr_arg (style, on by default) is orthogonal — it rewrites a &String / &Vec<T> / &PathBuf parameter to the more permissive &str / &[T] / &Path. Neither moves a borrowed parameter to its owned form, so enabling all three gives full coverage of the owned-vs-borrowed trade-off.

Example

Avoid:

fn push_path(list: &mut Vec<PathBuf>, item: &Path) {
    list.push(item.to_path_buf());
}

Prefer:

fn push_path(list: &mut Vec<PathBuf>, item: PathBuf) {
    list.push(item);
}

Source: src/rules/needless_borrowed_parameters.rs

perfectionist::overly_long_print_macro↑ top

activesplittable print macro with an embedded-newline template exceeds the configured line width

What it does

Flags a println!-style macro call whose format template embeds a \n newline and whose source line is wider than max_line_width display columns, and folds the template across lines with the backslash-newline continuation escape:

println!(
    "error: The error was caused by {err_src}\n\
    hint: Run {magic_cmd} to solve the problem",
);

The rewrite is byte-for-byte output-preserving: every \n stays, and the trailing \<newline><indent> continuation strips exactly the source newline and indentation it adds.

Eligibility is name-based — a curated list of the macros whose output is unchanged by the fold (println!, eprintln!, print!, eprint!, writeln!, write!, and the log family log! / error! / warn! / info! / debug! / trace!), replaced wholesale via target_macros. Macros that return a value (format!, format_args!) or terminate (panic!, assert!, the debug_assert* family, ...) are deliberately out of scope.

A template that is a runtime expression rather than a string literal, a raw string literal, or a template with no foldable interior \n, is left alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. A long single line whose string already contains \n is hard to read and hard to scan in a diff; folding it at the embedded newlines lets each output line read as its own source line without changing a byte of what the program prints.

Example

Avoid:

println!("error: The error was caused by {err_src}\nhint: Run {magic_cmd} to solve the problem");

Prefer:

println!(
    "error: The error was caused by {err_src}\n\
    hint: Run {magic_cmd} to solve the problem",
);

Source: src/rules/overly_long_print_macro.rs

perfectionist::single_letter_closure_param↑ top

activeclosure parameter has a single-letter name

What it does

Flags closure parameters whose identifier is one ASCII letter, unless the closure is a trivial single-expression callback or the identifier is in the conventional-name exempt set (n for an unsigned count, f for a fmt::Formatter, i / j / k for indices). "Single-expression" is a shared precondition for the trivial-callback exception: the body must be a bare expression or a block whose only content is a trailing expression — a body with any let binding or other statement before the trailing expression disqualifies the closure regardless of which branch below would otherwise apply. Given that, one of two further shapes must hold:

• the closure is the immediate argument of a call whose callee name is in the trivial-callback method set (sort_by, sort_by_key, min_by, max_by, binary_search_by, cmp_by, partial_cmp_by, fold, try_fold, ...). The set also covers the matching adaptors from itertools (sorted_by, k_smallest_by, minmax_by_key, ...) and into-sorted (into_sorted_by, into_sorted_by_key, ...);
• the body is a trivial wrapper around the parameter — a field access (|x| x.field), a method call (|x| x.foo()), a one-argument call where the parameter is the sole argument (|x| f(x)), a reference (|x| &x), or a macro call (|x| vec![x], |x| dbg!(x), |x| format!("{x}")). Surrounding * / & operators around the parameter inside any of the non-macro shapes are peeled before the match, so |s| (*s).foo() qualifies.

The conventional-name exempt set matches the one used by perfectionist::single_letter_function_param: |i| ... is the canonical index closure, just as fn step(i: usize) is the canonical index parameter. Bodies that use the index for slicing or arithmetic (|i| &hex[i..i + 2]) are not structurally trivial, so the exempt set is what keeps them out of the diagnostic.

Why restrict this?

This is a stylistic preference, not a correctness issue. A multi-line closure body whose parameter is a single letter forces the reader to scroll back to the closure header for context on every reference. The trivial-callback exception covers sort_by(|a, b| ...) and .map(|x| x.field) shapes that are short enough that the parameter's role is unambiguous from the call site.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character closure parameters, under a single crate-wide threshold and one shared allow-list. It cannot express this rule's trivial-callback exemption (.map(|x| x.field), sort_by(|a, b| ...)) or its conventional-name set, so it flags the short callbacks this rule deliberately allows. Enabling both is redundant — choose the context-aware behaviour here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

.map(|t| {
    let columns = build_columns(t);
    format_row(&columns)
})

Prefer:

.map(|tree_row| {
    let columns = build_columns(tree_row);
    format_row(&columns)
})

Source: src/rules/single_letter_closure_param.rs

perfectionist::single_letter_const_generic↑ top

activeconst generic parameter has a single-letter name

What it does

Flags const generic parameter declarations (<const N: usize>) whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A single-letter const generic parameter is opaque at every use site; a descriptive identifier (LEN, COLS, LANES) documents the parameter's role both at the declaration and at every substitution.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) flags short identifiers in many positions, but explicitly skips const generic parameters — its visitor returns early on GenericParamKind::Const, so it never flags <const N: usize>. This rule covers exactly that gap, so the two are complementary rather than redundant: enable both to also catch short bindings, parameters, and item names.

Example

Avoid:

struct Data<Left, Right, const M: usize, const N: usize> {
    left:  [Left;  M],
    right: [Right; N],
}

Prefer:

struct Data<Left, Right, const LEFT_LEN: usize, const RIGHT_LEN: usize> {
    left:  [Left;  LEFT_LEN],
    right: [Right; RIGHT_LEN],
}

Source: src/rules/single_letter_const_generic.rs

perfectionist::single_letter_const_item↑ top

activeconst item has a single-letter name

What it does

Flags const items (free, associated, and block-level) whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A single-letter const item is opaque at every use site, and the item's scope (module-wide or crate-wide for pub const) makes that opacity propagate. A descriptive identifier (DIMENSION, BUFFER_LEN, MAX_RETRIES) carries its own documentation.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character const item names, under a single crate-wide min-ident-chars-threshold and one shared allow-list that spans several kinds at once — bindings, parameters, and item names. (It skips generic and const-generic parameters, which the single_letter_* family handles separately.) This rule governs const items alone, with its own allowed_idents. Enabling both is redundant for const items — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

const N: usize = 2;

Prefer:

const DIMENSION_COUNT: usize = 2;

Source: src/rules/single_letter_const_item.rs

perfectionist::single_letter_function_param↑ top

activefunction parameter has a single-letter name

What it does

Flags function and method parameters whose identifier is one ASCII letter, except for a curated set of conventional names (n for an unsigned count, f for a fmt::Formatter, i / j / k for indices).

Why restrict this?

This is a stylistic preference, not a correctness issue. Parameter names are the first piece of documentation a caller reads (in rustdoc, in IDE hover tips, in error messages). A descriptive parameter name carries that documentation; a single letter does not.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character function parameters, under a single crate-wide min-ident-chars-threshold and one shared allow-list spanning several kinds at once (bindings, parameters, item names). This rule governs parameters alone and ships parameter-tuned default allowances (n, f, i, j, k) plus an independent extra_allowed_idents / extra_denied_idents pair. Enabling both is redundant for parameters — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

fn write_row(w: &mut Writer, t: &TreeRow) -> io::Result<()> { ... }

Prefer:

fn write_row(writer: &mut Writer, tree_row: &TreeRow) -> io::Result<()> { ... }

Source: src/rules/single_letter_function_param.rs

perfectionist::single_letter_generic↑ top

activegeneric type parameter has a single-letter name

What it does

Flags generic type parameters whose identifier is one ASCII letter (T, U, K, V, ...).

Why restrict this?

This is a stylistic preference, not a correctness issue. Single-letter generic names propagate through the type signatures and bounds; they force every reader to scroll back to the declaration to recover the role of each parameter. Descriptive names (Element, Key, Reader) keep complex signatures self-documenting.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) flags short identifiers in many positions, but explicitly skips generic type parameters — its visitor returns early on GenericParamKind::Type, so it never flags <T>. This rule covers exactly that gap, so the two are complementary rather than redundant: enable both to also catch short bindings, parameters, and item names.

Single-character lifetime names ('a) are likewise out of scope for the single_letter_* family; clippy::single_char_lifetime_names (restriction) covers those.

Example

Avoid:

pub fn collect_keys<K, V>(map: BTreeMap<K, V>) -> Vec<K> {
    /* fifty lines */
}

Prefer:

pub fn collect_keys<Key, Value>(map: BTreeMap<Key, Value>) -> Vec<Key> {
    /* fifty lines */
}

Configuration: none.

Source: src/rules/single_letter_generic.rs

perfectionist::single_letter_let_binding↑ top

activelet binding has a single-letter name

What it does

Flags let x = ...; bindings whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A descriptive let binding documents what the right-hand side computed; a single-letter name does not. The rule allows let n = ... and other names in a configurable set of exempt identifiers for the well-worn cases (unsigned counts).

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character let bindings, under a single crate-wide min-ident-chars-threshold and one shared allow-list spanning several kinds at once (bindings, parameters, item names). This rule governs let bindings alone, with its own exempt set. Enabling both is redundant for let bindings — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

let m = entry.metadata()?;

Prefer:

let metadata = entry.metadata()?;

Source: src/rules/single_letter_let_binding.rs

perfectionist::single_letter_static_item↑ top

activestatic item has a single-letter name

What it does

Flags static items whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A single-letter static item is opaque at every use site, and the item's scope (module-wide or crate-wide for pub static) makes that opacity propagate. A descriptive identifier (BUFFER, CACHE, COUNTER) carries its own documentation.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character static item names, under a single crate-wide min-ident-chars-threshold and one shared allow-list that spans several kinds at once — bindings, parameters, and item names. (It skips generic and const-generic parameters, which the single_letter_* family handles separately.) This rule governs static items alone, with its own allowed_idents. Enabling both is redundant for static items — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

static N: AtomicUsize = AtomicUsize::new(0);

Prefer:

static REQUEST_COUNT: AtomicUsize = AtomicUsize::new(0);

Source: src/rules/single_letter_static_item.rs

perfectionist::thiserror_usage↑ top

activethiserror import, derive, or attribute; this catalogue prefers derive_more::{Display, Error}

What it does

Flags every use of thiserror in the consumer crate. Three syntactic shapes trigger the lint:

1. Derives. #[derive(thiserror::Error)] directly, or #[derive(Error)] / #[derive(te::Error)] when a sibling use thiserror::Error; / use thiserror as te; brings the derive macro into scope under any local name, anywhere in the crate. #[cfg_attr(_, derive(thiserror::Error))] is unwrapped (including nested cfg_attr).
2. Attributes. #[error(...)] attributes attached to an item the rule has already classified as thiserror-derived, on the item, its enum variants, or its fields. #[cfg_attr(_, error(...))] is unwrapped symmetrically with the derive side.
3. Imports. Every use or extern crate statement that brings a thiserror path into scope: use thiserror::*, use thiserror::Error, use thiserror::Error as MyError;, use thiserror::{self as te};, use thiserror as te;, extern crate thiserror;, extern crate thiserror as te;, the braced top-level form use {thiserror::Error, ...};, and pub use re-exports.

The lint is detection-only: it emits a help-style diagnostic pointing at the offending site and suggests migrating to #[derive(derive_more::Display, derive_more::Error)]. There is no autofix — the migration involves a mix of derive-list edits, format-string positional translation (thiserror's {0} ↔ derive_more's {_0}), attribute renames (#[error(...)] ↔ #[display(...)]), and edge cases (#[error(transparent)], #[backtrace]) whose mechanical rewrite is too risky to apply without review.

Alias collection is crate-wide rather than per-module: a use thiserror::Error; anywhere in the crate makes the bare #[derive(Error)] short-hand resolve as thiserror everywhere. In practice that overlap is rare and the rule treats it as acceptable false-positive surface; a project that hits it can suppress individual sites with #[expect(perfectionist::thiserror_usage)].

Why restrict this?

This is a stylistic preference, not a correctness issue. The catalogue picks derive_more for error formatting and source chaining. Mixing in thiserror fragments the attribute vocabulary across the codebase and adds a second derive crate that has no functional capability derive_more lacks. A project that wants the choice the other way around can disable this rule.

Example

Avoid:

use thiserror::Error;

#[derive(Debug, Error)]
pub enum MyError {
    #[error("missing field {0}")]
    MissingField(MissingFieldError),
}

Prefer:

use derive_more::{Display, Error};

#[derive(Debug, Display, Error)]
pub enum MyError {
    #[display("missing field {_0}")]
    MissingField(MissingFieldError),
}

Configuration: none.

Source: src/rules/thiserror_usage.rs

perfectionist::uncombined_self_import↑ top

inactivea module import and an adjacent item import from it can be combined through self

What it does

Folds two adjacent use statements — one importing a module and one importing an item from that same module — into a single use module::{self, item};. The rule is inactive by default; a project opts in via [perfectionist].enable.

Why restrict this?

This is a stylistic preference, not a correctness issue. A project that wants a module and the items it re-exports to travel under one use enables this rule so the grouping is applied uniformly rather than decided case by case:

[perfectionist]
enable = ["uncombined_self_import"]

The autofix is MaybeIncorrect whenever it narrows the namespaces an import brings into scope: folding a bare use module; into {self, ...} imports only the module, while the bare form imports every namespace named module (type, value, macro) — a difference that matters only in the rare case where a value or macro shares the module's name in the same parent.

Interaction with Clippy

clippy::unnecessary_self_imports (restriction, off by default) is the opposite policy: it flags a sole use module::{self}; and unwraps it to use module;. It matches only the single-item {self} form, so it never touches the multi-item {self, item} groups this rule produces. The two are mirror images — pick one direction and do not enable both.

Example

Avoid:

use foo::bar;
use foo::bar::Baz;

Prefer:

use foo::bar::{self, Baz};

Configuration: none.

Source: src/rules/uncombined_self_import.rs

perfectionist::unicode_ellipsis_in_comments↑ top

activeU+2026 HORIZONTAL ELLIPSIS in non-doc comments; prefer ...

What it does

Forbids U+2026 HORIZONTAL ELLIPSIS (…) in regular // and /* */ comments. Doc comments (///, //!) are covered by a sibling lint.

Why restrict this?

This is a stylistic preference, not a correctness issue. ASCII ... survives every encoding round-trip, every terminal, every grep invocation, and every git diff viewer without rendering as ? or a tofu box. The Unicode form usually arrives by accident from autocorrect.

Example

Avoid:

// TODO: handle the empty-tree case…

Prefer:

// TODO: handle the empty-tree case...

Source: src/rules/unicode_ellipsis_in_comments.rs

perfectionist::unicode_ellipsis_in_docs↑ top

activeU+2026 HORIZONTAL ELLIPSIS in doc comments; prefer ...

What it does

Forbids U+2026 HORIZONTAL ELLIPSIS (…) in doc comments — /// and //! line forms and the /** */ / /*! */ block forms. Prefer the three-ASCII-dot form .... Regular // and /* */ comments are covered by a sibling lint (perfectionist::unicode_ellipsis_in_comments).

Why restrict this?

This is a stylistic preference, not a correctness issue. ASCII ... survives every encoding round-trip, every terminal, every copy-paste, every grep invocation, and every git diff viewer without rendering as ? or a tofu box. The visual difference between … and ... is small enough that the Unicode form usually arrives by accident — autocorrect, an IDE smart-quote setting — rather than as a deliberate choice in technical writing.

Example

Avoid:

/// Walk the tree, collecting sizes…

Prefer:

/// Walk the tree, collecting sizes...

Source: src/rules/unicode_ellipsis_in_docs.rs

perfectionist::unicode_ellipsis_in_panic_messages↑ top

activeU+2026 HORIZONTAL ELLIPSIS in panic / assertion / expect messages; prefer ...

What it does

Forbids U+2026 HORIZONTAL ELLIPSIS (…) in the message of a panic-family or assertion-style macro (panic!, unimplemented!, todo!, unreachable!, assert!, assert_eq!, assert_ne!, debug_assert*!) and in the expect / expect_err argument on Option and Result. Prefer the three-ASCII-dot form ....

Why restrict this?

This is a stylistic preference, not a correctness issue. Panic and assertion messages surface in stderr, CI logs, crash reporters, and on terminals whose locale or encoding may not be UTF-8. ASCII ... renders identically everywhere.

Interaction with Clippy

clippy::non_ascii_literal (restriction, off by default) also catches U+2026 in a panic-family message, but only as a side effect of forbidding all non-ASCII in string and char literals: it cannot be narrowed to the ellipsis, offers no ... autofix, and does not reach the sibling perfectionist::unicode_ellipsis_in_comments / unicode_ellipsis_in_docs cases (comments and doc comments are not literals). Use this rule for the targeted fix, or non_ascii_literal for a blanket ASCII-only-literals policy.

Example

Avoid:

panic!("could not parse manifest…");
let manifest = load().expect("config missing…");

Prefer:

panic!("could not parse manifest...");
let manifest = load().expect("config missing...");

Custom macros

The extra_macros configuration accepts any macro name, but the lint's per-macro knowledge of which argument is the message only covers the built-in panic / assertion macros. A custom macro added through this knob is treated as if its first argument were the message; an assert_eq!-shaped wrapper would therefore also scan its value-position literals. Adding per-macro skip counts requires extending the configuration schema and is out of scope for the initial rule.

Source: src/rules/unicode_ellipsis_in_panic_messages.rs

perfectionist::unknown_perfectionist_lints↑ top

activelint-control attribute references a perfectionist::* lint that this plugin does not register

What it does

Flags lint-control attributes (allow, warn, deny, forbid, expect, including under cfg_attr) whose lint name starts with perfectionist:: but does not name a lint this plugin actually registers.

Why is this bad?

Typos and stale references in #[allow(perfectionist::...)] silently neutralise the suppression they were written for. rustc's own unknown_lints covers tool-prefixed names inconsistently; this rule fills the gap and offers a "did you mean" hint against the registered set.

Example

Bad:

#[allow(perfectionist::unicode_ellipsis_in_comment)] // typo
fn legacy() {}

Good:

#[allow(perfectionist::unicode_ellipsis_in_comments)]
fn legacy() {}

Source: src/rules/unknown_perfectionist_lints.rs

perfectionist::unordered_derives↑ top

inactivetrait names in a #[derive(...)] list are not in the configured order

What it does

Enforces a project-wide ordering of trait names inside a single #[derive(...)] list. Two styles are configurable via style:

• alphabetical (default) — every trait name must be in ASCII-case-insensitive alphabetical order.
• prefix_then_alphabetical — the configured prefix list of traits goes first, in the listed order; remaining traits are sorted alphabetically after.

Trait matching is by the final path segment, so serde::Deserialize is matched as Deserialize. The lint does not police how derives are partitioned across multiple #[derive(...)] lines — that's a layout decision left to the author.

A cfg-gated derive written as #[cfg_attr(<cfg>, derive(...))] is checked the same way as a bare #[derive(...)]; the cfg predicate is left untouched.

Why restrict this?

This is a stylistic preference, not a correctness issue. The trait order inside #[derive(...)] has no semantic effect: #[derive(Debug, Clone)] and #[derive(Clone, Debug)] produce identical impls. A project-wide convention makes derive lists scan uniformly across the codebase. cargo fmt does not reorder derives, so this lint is the only mechanism for enforcing one.

The opinion is opt-in: a project that doesn't want to commit to a single ordering shouldn't have to set anything. The rule is therefore inactive by default — enable it per crate by adding to dylint.toml:

[perfectionist]
enable = ["unordered_derives"]

Example

Style: Alphabetical (default)

Avoid:

#[derive(Debug, Clone, Copy)]
struct Point;

Prefer:

#[derive(Clone, Copy, Debug)]
struct Point;

Style: Prefix then alphabetical

Avoid:

#[derive(Clone, Debug, Serialize, Copy)]
struct Point;

Prefer: (default prefix: Debug, Default, Clone, Copy, ..., then the remaining traits alphabetically)

#[derive(Debug, Clone, Copy, Serialize)]
struct Point;

Source: src/rules/unordered_derives.rs

perfectionist::unpinned_repo_ref↑ top

activerepository URL references a branch or tag instead of a commit SHA

What it does

Flags URLs that reference a file or directory inside a hosted git repository (GitHub, GitLab, Bitbucket, Codeberg / Gitea, sourcehut, etc.) when the ref in the URL is a branch or tag rather than a commit SHA. Projects that deliberately link to version-shaped refs can opt into accepting those patterns via allow_version_patterns. Scans doc comments and regular comments by default; string literals are opt-in via scan_string_literals.

This rule only concerns whether the ref is mutable; the length of an accepted SHA is perfectionist::commit_id_length_mismatch's concern, and perfectionist::bare_url ensures the URL is wrapped. The three lints layer rather than overlap.

Why restrict this?

This is a stylistic preference, not a correctness issue. A branch ref such as /blob/main/... resolves to whatever that branch currently points at, so the linked content can change — or disappear — without warning after the link is written. A tag ref is steadier but still not pinned: a tag can be removed, and a version-shaped name is not even guaranteed to be a tag (a branch named v1.2.3 is valid Git). A commit SHA is the only ref that always denotes the exact content the author linked to.

Example

Avoid:

/// See <https://github.com/owner/repo/blob/main/src/lib.rs>.

Prefer:

/// See <https://github.com/owner/repo/blob/8c1f6e2/src/lib.rs>.

Source: src/rules/unpinned_repo_ref.rs

perfectionist::wildcard_imports↑ top

activeglob (*) import in a module body, outside the prelude and root-re-export exceptions

What it does

Flags glob (*) use statements — use foo::bar::*; — in module bodies. Two exceptions are enabled by default and each can be turned off individually:

• prelude — a glob whose final non-glob path segment names a prelude module is allowed: use rayon::prelude::*;, use diesel::prelude::*;. The recognised names are configurable via prelude_segment_names.
• root_reexport — a re-export glob (pub use ...::*) at the top level of a module body is allowed: pub use submodule::*; in lib.rs.

The case the rule is most concerned with is use super::*; inside a #[cfg(test)] mod tests block; explicit imports must replace it. A project that wants a stricter posture disables either or both exceptions, or names extra always-allowed paths, in dylint.toml.

Why restrict this?

This is a stylistic preference, not a correctness issue. A glob import compiles and runs correctly; the project simply prefers explicit imports. Naming each imported item keeps a module's dependencies visible at the top of the file, stops an upstream addition from silently shadowing a local name, and makes a grep for where a name comes from land on a real use. Preludes and root re-exports are the two places the glob form is idiomatic, so they are exempt by default.

Why not clippy::wildcard_imports?

Clippy's wildcard_imports (an allow-by-default pedantic lint) flags the same glob uses and, by default, exempts prelude imports, pub use re-exports, and use super::*; inside any module whose name contains test — overlapping this rule's exceptions. But all of those exemptions, together with the allowed-wildcard-imports path list, are coupled behind a single warn-on-all-wildcard-imports boolean: left at its default (false) the test-module super::*; carve-out is on, so use super::*; inside mod tests is not flagged; set to true, every exemption drops at once, including the prelude one. There is no setting that keeps prelude::* exempt while flagging use super::*; in a #[cfg(test)] mod tests block — which is exactly this rule's headline case. This rule decouples them: the prelude and root_reexport exceptions toggle independently (with a configurable prelude_segment_names and the allowed_paths escape hatch), and there is no test-module carve-out, so the test super::*; glob is flagged by default. Reach for clippy::wildcard_imports if its coarser, all-or-nothing exemption model is enough; reach for this rule when the test-module distinction matters. Paired with perfectionist::named_prelude_imports it expresses the project's full posture: preludes must be glob-imported, and globs are allowed only for preludes.

Example

Avoid:

#[cfg(test)]
mod tests {
    use super::*;
}

Prefer:

#[cfg(test)]
mod tests {
    use super::{ParsedThing, parse_thing};
}

Not flagged: the prelude and root-re-export exceptions.

use rayon::prelude::*;
pub use submodule::*;

Source: src/rules/wildcard_imports.rs