Clippy

Clippy is a collection of over 800 lints designed to catch common mistakes and improve Rust code quality. Lints are organized into categories, each with a default lint level (allow, warn, deny). You can control the strictness of Clippy by adjusting these levels.

Lint Categories

When developing a new Clippy lint, you must decide whether to implement EarlyLintPass or LateLintPass. This decision is based on whether your lint requires access to type and symbol information.

EarlyLintPass

Use EarlyLintPass if your lint only deals with syntax-related issues. It operates on the Abstract Syntax Tree (AST) level after expansion but before lowering to HIR.

• Pros: Faster execution.
• Limitations: No access to type information or symbol meanings; nodes are only identified by their position in the AST.
• Use Case: Checking function names (e.g., detecting functions named foo) or other purely syntactic patterns.

LateLintPass

Use LateLintPass if your lint needs to inspect types or symbols. It operates at the HIR level and has access to type-checking information.

• Pros: Access to LateContext methods like maybe_typeck_results and typeck_results to inspect types.
• Use Case: Most Clippy lints fall into this category because they often need to verify if a method exists on a specific type or if a variable's type matches a certain pattern.
• Limitations: Slower than EarlyLintPass.

The proposal outlines several advanced features that could be implemented to enhance the pattern matching system:

• Early Filtering: Evaluating conditions (e.g., where !in_macro(#then.span)) as soon as a specific part of the pattern is matched to improve performance.
• Backreferences: Using syntax like =#target to ensure multiple parts of a pattern match the exact same value (e.g., for detecting a = a + b patterns).
• Negation Operators: Using syntax like Lit(!Bool(_)) to match a node that is not a specific type.
• Functional Composition: Allowing the definition of reusable sub-patterns using a function-like syntax to reduce repetition in complex lints.
• Descendant Matching: Extending the syntax to match subtrees that are not direct descendants of the current node.
• Language Agnosticism: The system is designed such that by implementing a new PatternTree and IsMatch trait, it could be used to lint other programming languages or even the pattern syntax itself.

Syntax tree patterns are inspired by regular expressions and use sequences, repetitions, and alternatives to match against a PatternTree.

Core Mechanics:

• PatternTree: A structure representing the hierarchy of the syntax tree (similar to AST/HIR).
• IsMatch Trait: The mechanism that connects the PatternTree to the actual syntax tree implementation.
• Matching Behavior: When a pattern can match a node in multiple ways (e.g., due to ambiguity in repetitions), the current implementation returns the first match it finds (it does not currently support greedy/non-greedy selection).

Comparison to Rust-like syntax: Unlike a quote! macro approach which uses actual Rust syntax, syntax-tree-patterns require knowledge of the PatternTree structure. This avoids the complexity of operator precedence and the ambiguity of naming submatches in a language with implicit structure.

Clippy works on code that has already been expanded and desugared. This can lead to false positives in macro-generated code. To avoid linting code the user cannot modify, use these tools:

• span.from_expansion(): Returns true if the span is from a macro expansion or desugaring. Use this to skip macro-generated code immediately.
• span.ctxt(): Returns the SpanContext. You can use this to check if two spans belong to the same macro expansion context. If left.span.ctxt() != right.span.ctxt(), the expressions likely originate from different parts of a macro expansion.
• span.in_external_macro(sm): Returns true if the span is inside a macro defined in a foreign crate. Use this to avoid linting code generated by external dependencies.

// Detect if a span is from macro expansion and skip
if expr.span.from_expansion() {
    return;
}

// Check if two spans are in the same macro context
if left.span.ctxt() != right.span.ctxt() {
    // The coder most likely cannot modify this expression
    return;
}

// Detect if a span is from a macro in a foreign crate
if match_span.in_external_macro(cx.sess().source_map()) {
    // Skip lints for macros from other crates
}