//! Clippy wrappers around rustc's diagnostic functions. //! //! These functions are used by the `INTERNAL_METADATA_COLLECTOR` lint to collect the corresponding //! lint applicability. Please make sure that you update the `LINT_EMISSION_FUNCTIONS` variable in //! `clippy_lints::utils::internal_lints::metadata_collector` when a new function is added //! or renamed. //! //! Thank you! //! ~The `INTERNAL_METADATA_COLLECTOR` lint use rustc_errors::{Applicability, Diag, DiagMessage, MultiSpan, SubdiagMessage}; use rustc_hir::HirId; use rustc_lint::{LateContext, Lint, LintContext}; use rustc_span::Span; use std::env; fn docs_link(diag: &mut Diag<'_, ()>, lint: &'static Lint) { if env::var("CLIPPY_DISABLE_DOCS_LINKS").is_err() { if let Some(lint) = lint.name_lower().strip_prefix("clippy::") { diag.help(format!( "for further information visit https://rust-lang.github.io/rust-clippy/{}/index.html#{lint}", &option_env!("RUST_RELEASE_NUM").map_or("master".to_string(), |n| { // extract just major + minor version and ignore patch versions format!("rust-{}", n.rsplit_once('.').unwrap().1) }) )); } } } /// Emit a basic lint message with a `msg` and a `span`. /// /// This is the most primitive of our lint emission methods and can /// be a good way to get a new lint started. /// /// Usually it's nicer to provide more context for lint messages. /// Be sure the output is understandable when you use this method. /// /// NOTE: Lint emissions are always bound to a node in the HIR, which is used to determine /// the lint level. /// For the `span_lint` function, the node that was passed into the `LintPass::check_*` function is /// used. /// /// If you're emitting the lint at the span of a different node than the one provided by the /// `LintPass::check_*` function, consider using [`span_lint_hir`] instead. /// This is needed for `#[allow]` and `#[expect]` attributes to work on the node /// highlighted in the displayed warning. /// /// If you're unsure which function you should use, you can test if the `#[allow]` attribute works /// where you would expect it to. /// If it doesn't, you likely need to use [`span_lint_hir`] instead. /// /// # Example /// /// ```ignore /// error: usage of mem::forget on Drop type /// --> tests/ui/mem_forget.rs:17:5 /// | /// 17 | std::mem::forget(seven); /// | ^^^^^^^^^^^^^^^^^^^^^^^ /// ``` pub fn span_lint(cx: &T, lint: &'static Lint, sp: impl Into, msg: impl Into) { #[expect(clippy::disallowed_methods)] cx.span_lint(lint, sp, msg.into(), |diag| { docs_link(diag, lint); }); } /// Same as `span_lint` but with an extra `help` message. /// /// Use this if you want to provide some general help but /// can't provide a specific machine applicable suggestion. /// /// The `help` message can be optionally attached to a `Span`. /// /// If you change the signature, remember to update the internal lint `CollapsibleCalls` /// /// NOTE: Lint emissions are always bound to a node in the HIR, which is used to determine /// the lint level. /// For the `span_lint_and_help` function, the node that was passed into the `LintPass::check_*` /// function is used. /// /// If you're emitting the lint at the span of a different node than the one provided by the /// `LintPass::check_*` function, consider using [`span_lint_hir_and_then`] instead. /// This is needed for `#[allow]` and `#[expect]` attributes to work on the node /// highlighted in the displayed warning. /// /// If you're unsure which function you should use, you can test if the `#[allow]` attribute works /// where you would expect it to. /// If it doesn't, you likely need to use [`span_lint_hir_and_then`] instead. /// /// # Example /// /// ```text /// error: constant division of 0.0 with 0.0 will always result in NaN /// --> tests/ui/zero_div_zero.rs:6:25 /// | /// 6 | let other_f64_nan = 0.0f64 / 0.0; /// | ^^^^^^^^^^^^ /// | /// = help: consider using `f64::NAN` if you would like a constant representing NaN /// ``` pub fn span_lint_and_help( cx: &T, lint: &'static Lint, span: impl Into, msg: impl Into, help_span: Option, help: impl Into, ) { #[expect(clippy::disallowed_methods)] cx.span_lint(lint, span, msg.into(), |diag| { if let Some(help_span) = help_span { diag.span_help(help_span, help.into()); } else { diag.help(help.into()); } docs_link(diag, lint); }); } /// Like `span_lint` but with a `note` section instead of a `help` message. /// /// The `note` message is presented separately from the main lint message /// and is attached to a specific span: /// /// If you change the signature, remember to update the internal lint `CollapsibleCalls` /// /// NOTE: Lint emissions are always bound to a node in the HIR, which is used to determine /// the lint level. /// For the `span_lint_and_note` function, the node that was passed into the `LintPass::check_*` /// function is used. /// /// If you're emitting the lint at the span of a different node than the one provided by the /// `LintPass::check_*` function, consider using [`span_lint_hir_and_then`] instead. /// This is needed for `#[allow]` and `#[expect]` attributes to work on the node /// highlighted in the displayed warning. /// /// If you're unsure which function you should use, you can test if the `#[allow]` attribute works /// where you would expect it to. /// If it doesn't, you likely need to use [`span_lint_hir_and_then`] instead. /// /// # Example /// /// ```text /// error: calls to `std::mem::forget` with a reference instead of an owned value. Forgetting a reference does nothing. /// --> tests/ui/drop_forget_ref.rs:10:5 /// | /// 10 | forget(&SomeStruct); /// | ^^^^^^^^^^^^^^^^^^^ /// | /// = note: `-D clippy::forget-ref` implied by `-D warnings` /// note: argument has type &SomeStruct /// --> tests/ui/drop_forget_ref.rs:10:12 /// | /// 10 | forget(&SomeStruct); /// | ^^^^^^^^^^^ /// ``` pub fn span_lint_and_note( cx: &T, lint: &'static Lint, span: impl Into, msg: impl Into, note_span: Option, note: impl Into, ) { #[expect(clippy::disallowed_methods)] cx.span_lint(lint, span, msg.into(), |diag| { if let Some(note_span) = note_span { diag.span_note(note_span, note.into()); } else { diag.note(note.into()); } docs_link(diag, lint); }); } /// Like `span_lint` but allows to add notes, help and suggestions using a closure. /// /// If you need to customize your lint output a lot, use this function. /// If you change the signature, remember to update the internal lint `CollapsibleCalls` /// /// NOTE: Lint emissions are always bound to a node in the HIR, which is used to determine /// the lint level. /// For the `span_lint_and_then` function, the node that was passed into the `LintPass::check_*` /// function is used. /// /// If you're emitting the lint at the span of a different node than the one provided by the /// `LintPass::check_*` function, consider using [`span_lint_hir_and_then`] instead. /// This is needed for `#[allow]` and `#[expect]` attributes to work on the node /// highlighted in the displayed warning. /// /// If you're unsure which function you should use, you can test if the `#[allow]` attribute works /// where you would expect it to. /// If it doesn't, you likely need to use [`span_lint_hir_and_then`] instead. pub fn span_lint_and_then(cx: &C, lint: &'static Lint, sp: S, msg: M, f: F) where C: LintContext, S: Into, M: Into, F: FnOnce(&mut Diag<'_, ()>), { #[expect(clippy::disallowed_methods)] cx.span_lint(lint, sp, msg, |diag| { f(diag); docs_link(diag, lint); }); } /// Like [`span_lint`], but emits the lint at the node identified by the given `HirId`. /// /// This is in contrast to [`span_lint`], which always emits the lint at the node that was last /// passed to the `LintPass::check_*` function. /// /// The `HirId` is used for checking lint level attributes and to fulfill lint expectations defined /// via the `#[expect]` attribute. /// /// For example: /// ```ignore /// fn f() { /* */ /// /// #[allow(clippy::some_lint)] /// let _x = /* */; /// } /// ``` /// If `some_lint` does its analysis in `LintPass::check_fn` (at ``) and emits a lint at /// `` using [`span_lint`], then allowing the lint at `` as attempted in the snippet /// will not work! /// Even though that is where the warning points at, which would be confusing to users. /// /// Instead, use this function and also pass the `HirId` of ``, which will let /// the compiler check lint level attributes at the place of the expression and /// the `#[allow]` will work. pub fn span_lint_hir(cx: &LateContext<'_>, lint: &'static Lint, hir_id: HirId, sp: Span, msg: impl Into) { #[expect(clippy::disallowed_methods)] cx.tcx.node_span_lint(lint, hir_id, sp, msg.into(), |diag| { docs_link(diag, lint); }); } /// Like [`span_lint_and_then`], but emits the lint at the node identified by the given `HirId`. /// /// This is in contrast to [`span_lint_and_then`], which always emits the lint at the node that was /// last passed to the `LintPass::check_*` function. /// /// The `HirId` is used for checking lint level attributes and to fulfill lint expectations defined /// via the `#[expect]` attribute. /// /// For example: /// ```ignore /// fn f() { /* */ /// /// #[allow(clippy::some_lint)] /// let _x = /* */; /// } /// ``` /// If `some_lint` does its analysis in `LintPass::check_fn` (at ``) and emits a lint at /// `` using [`span_lint`], then allowing the lint at `` as attempted in the snippet /// will not work! /// Even though that is where the warning points at, which would be confusing to users. /// /// Instead, use this function and also pass the `HirId` of ``, which will let /// the compiler check lint level attributes at the place of the expression and /// the `#[allow]` will work. pub fn span_lint_hir_and_then( cx: &LateContext<'_>, lint: &'static Lint, hir_id: HirId, sp: impl Into, msg: impl Into, f: impl FnOnce(&mut Diag<'_, ()>), ) { #[expect(clippy::disallowed_methods)] cx.tcx.node_span_lint(lint, hir_id, sp, msg.into(), |diag| { f(diag); docs_link(diag, lint); }); } /// Add a span lint with a suggestion on how to fix it. /// /// These suggestions can be parsed by rustfix to allow it to automatically fix your code. /// In the example below, `help` is `"try"` and `sugg` is the suggested replacement `".any(|x| x > /// 2)"`. /// /// If you change the signature, remember to update the internal lint `CollapsibleCalls` /// /// NOTE: Lint emissions are always bound to a node in the HIR, which is used to determine /// the lint level. /// For the `span_lint_and_sugg` function, the node that was passed into the `LintPass::check_*` /// function is used. /// /// If you're emitting the lint at the span of a different node than the one provided by the /// `LintPass::check_*` function, consider using [`span_lint_hir_and_then`] instead. /// This is needed for `#[allow]` and `#[expect]` attributes to work on the node /// highlighted in the displayed warning. /// /// If you're unsure which function you should use, you can test if the `#[allow]` attribute works /// where you would expect it to. /// If it doesn't, you likely need to use [`span_lint_hir_and_then`] instead. /// /// # Example /// /// ```text /// error: This `.fold` can be more succinctly expressed as `.any` /// --> tests/ui/methods.rs:390:13 /// | /// 390 | let _ = (0..3).fold(false, |acc, x| acc || x > 2); /// | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: `.any(|x| x > 2)` /// | /// = note: `-D fold-any` implied by `-D warnings` /// ``` #[expect(clippy::collapsible_span_lint_calls)] pub fn span_lint_and_sugg( cx: &T, lint: &'static Lint, sp: Span, msg: impl Into, help: impl Into, sugg: String, applicability: Applicability, ) { span_lint_and_then(cx, lint, sp, msg.into(), |diag| { diag.span_suggestion(sp, help.into(), sugg, applicability); }); } /// Create a suggestion made from several `span → replacement`. /// /// Note: in the JSON format (used by `compiletest_rs`), the help message will /// appear once per /// replacement. In human-readable format though, it only appears once before /// the whole suggestion. pub fn multispan_sugg(diag: &mut Diag<'_, ()>, help_msg: impl Into, sugg: I) where I: IntoIterator, { multispan_sugg_with_applicability(diag, help_msg, Applicability::Unspecified, sugg); } /// Create a suggestion made from several `span → replacement`. /// /// rustfix currently doesn't support the automatic application of suggestions with /// multiple spans. This is tracked in issue [rustfix#141](https://github.com/rust-lang/rustfix/issues/141). /// Suggestions with multiple spans will be silently ignored. pub fn multispan_sugg_with_applicability( diag: &mut Diag<'_, ()>, help_msg: impl Into, applicability: Applicability, sugg: I, ) where I: IntoIterator, { diag.multipart_suggestion(help_msg.into(), sugg.into_iter().collect(), applicability); }