perfectionist lints

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

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

Use instead:

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

Source: src/rules/bare_email.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

/// Closes #123 and supersedes #124.

Use instead (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

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

Use instead:

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

Source: src/rules/bare_url.rs

perfectionist::derive_ordering↑ 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.

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 = ["derive_ordering"]

Example

Under style = "alphabetical":

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

Use instead:

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

Source: src/rules/derive_ordering.rs

perfectionist::flat_module_pattern↑ top

activesubmodule defined as module/mod.rs; prefer the flat module.rs layout

What it does

Forbids the module/mod.rs layout for submodules. Each submodule should be defined by a sibling file named after the module (module.rs), with any nested children placed inside the module/ directory next to it.

Why restrict this?

This is a stylistic preference, not a correctness issue. The flat layout keeps the file name unique to its module, so editors, terminal tabs, and grep results identify the module without their parent directory. The mod.rs form produces dozens of identically-named tabs in editors that don't disambiguate by directory.

Example

// Bad
src/foo/mod.rs

// Good
src/foo.rs
src/foo/bar.rs

Configuration: none.

Source: src/rules/flat_module_pattern.rs

perfectionist::import_granularity↑ top

activeimport granularity does not match the configured import_granularity.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.

Globs (use foo::*) are governed by perfectionist::no_star_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

Under the default style = "module":

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

Use instead:

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

Source: src/rules/import_granularity.rs

perfectionist::lint_reason_from_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

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

Use instead:

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

Configuration: none.

Source: src/rules/lint_reason_from_comment.rs

perfectionist::lint_silence_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.

Example

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

Use instead:

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

Source: src/rules/lint_silence_reason.rs

perfectionist::macro_argument_binding↑ 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

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

Use instead:

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

Source: src/rules/macro_argument_binding.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

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

Use instead:

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

Source: src/rules/macro_trailing_comma.rs

perfectionist::non_exhaustive_error↑ 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 = ["non_exhaustive_error"]

Example

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

Use instead:

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

Source: src/rules/non_exhaustive_error.rs

perfectionist::prefer_derive_more_over_thiserror↑ 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.

Because the pass runs pre-expansion and does not consult name resolution, 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 #[allow(perfectionist::prefer_derive_more_over_thiserror)].

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

use thiserror::Error;

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

Use instead:

use derive_more::{Display, Error};

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

Configuration: none.

Source: src/rules/prefer_derive_more_over_thiserror.rs

perfectionist::prefer_raw_string↑ 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.

This includes literals passed as arguments to macros such as println!, format!, vec!, and assert!. Suppress per call site with #[allow(perfectionist::prefer_raw_string)] when the regular form is deliberately preferred.

Pattern-position literals (e.g. match s { "C:\\path" => ... }) are out of scope — the rule only visits expression literals.

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

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

Use instead:

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

Source: src/rules/prefer_raw_string.rs

perfectionist::print_macro_split↑ 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

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

Use instead:

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

Source: src/rules/print_macro_split.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.

Example

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

Use instead:

.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.

Example

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

Use instead:

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.

Example

const N: usize = 2;

Use instead:

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.

Example

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

Use instead:

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. Genuinely canonical cases — impl<T> From<T> for Wrapper<T> and friends, where the trait already imposes the role of T — can be silenced site-by-site with #[allow] or #[expect].

Example

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

Use instead:

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).

Example

let m = entry.metadata()?;

Use instead:

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.

Example

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

Use instead:

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

Source: src/rules/single_letter_static_item.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

// TODO: handle the empty-tree case…

Use instead:

// 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

/// Walk the tree, collecting sizes…

Use instead:

/// 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.

Example

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

Use instead:

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::unit_test_file_layout↑ top

activeunit-test code is in the wrong file or exceeds the inline-test budget

What it does

Enforces where a crate's unit-test code lives. Two independent axes are checked:

1. External-file layout. An external #[cfg(test)] mod <name>; must resolve to the canonical on-disk location. By default that is the nested <parent>/<name>.rs form (tests of src/foo.rs live in src/foo/tests.rs); for such a file the flattened sibling src/foo_tests.rs and the skipped-intermediate src/tests.rs are flagged. A directory-owning parent (lib.rs / main.rs / mod.rs) is the exception: its children already live beside it, so mod tests; in src/lib.rs canonically resolves to src/tests.rs (not src/lib/tests.rs) and is not flagged — matching where Cargo loads it. The sibling style also accepts the flattened form; any skips the layout check.
2. Inline footprint. 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.

The module identifier is irrelevant to the layout rule; only the file's position relative to its parent matters.

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 layout 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; and they put the extracted file in a predictable place so a reader always knows where a module's tests are. The thresholds and the nested-vs-sibling choice are deliberately configurable because the exact budget and directory shape vary by project.

Example

// Bad (external_layout = "nested")
src/foo.rs         declares  #[cfg(test)] mod tests;
src/foo_tests.rs   holds the test code

// Good
src/foo.rs         declares  #[cfg(test)] mod tests;
src/foo/tests.rs   holds the test code

Source: src/rules/unit_test_file_layout.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

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

Use instead:

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

Source: src/rules/unknown_perfectionist_lints.rs