Introduce a #[diagnostic::on_unknown_item] attribute

This PR introduces a `#[diagnostic::on_unknown_item]` attribute that
allows crate authors to customize the error messages emitted by
unresolved imports. The main usecase for this is using this attribute as
part of a proc macro that expects a certain external module structure to
exist or certain dependencies to be there.

For me personally the motivating use-case are several derives in diesel,
that expect to refer to a `tabe` module. That is done either
implicitly (via the name of the type with the derive) or explicitly by
the user. This attribute would allow us to improve the error message in
both cases:

* For the implicit case we could explicity call out our
assumptions (turning the name into lower case, adding an `s` in the end)
+ point to the explicit variant as alternative
* For the explicit variant we would add additional notes to tell the
user why this is happening and what they should look for to fix the
problem (be more explicit about certain diesel specific assumptions of
the module structure)

I assume that similar use-cases exist for other proc-macros as well,
therefore I decided to put in the work implementing this new attribute.
I would also assume that this is likely not useful for std-lib internal
usage.

Author: weiznich

compiler/rustc_feature/src/builtin_attrs.rs

@@ -1193,7 +1193,7 @@ pub static BUILTIN_ATTRIBUTE_MAP: LazyLock<FxHashMap<Symbol, &BuiltinAttribute>>
 
 pub fn is_stable_diagnostic_attribute(sym: Symbol, _features: &Features) -> bool {
     match sym {
-        sym::on_unimplemented | sym::do_not_recommend => true,
+        sym::on_unimplemented | sym::do_not_recommend | sym::on_unknown_item => true,
         _ => false,
     }
 }

compiler/rustc_passes/messages.ftl

@@ -152,6 +152,9 @@ passes_deprecated_attribute =
 passes_diagnostic_diagnostic_on_unimplemented_only_for_traits =
     `#[diagnostic::on_unimplemented]` can only be applied to trait definitions
 
+passes_diagnostic_diagnostic_on_unknown_item_only_for_imports =
+    `#[diagnostic::on_unknown_item]` can only be applied to `use` statements
+
 passes_diagnostic_item_first_defined =
     the diagnostic item is first defined here
 
@@ -356,6 +359,11 @@ passes_ignored_derived_impls =
      *[other] traits {$trait_list}, but these are
     } intentionally ignored during dead code analysis
 
+passes_ignored_diagnostic_option = `{$option_name}` is ignored due to previous definition of `{$option_name}`
+    .other_label = `{$option_name}` is first declared here
+    .label = `{$option_name}` is already declared here
+    .help = consider removing the second `{$option_name}` as it is ignored anyway
+
 passes_implied_feature_not_exist =
     feature `{$implied_by}` implying `{$feature}` does not exist
 
@@ -474,6 +482,11 @@ passes_macro_export_on_decl_macro =
 passes_macro_use =
     `#[{$name}]` only has an effect on `extern crate` and modules
 
+passes_malformed_on_unknown_item_attr =
+    malformed `#[diagnostic::on_unknown_item]` attribute
+    .label = the `#[diagnostic::on_unknown_item]` attribute expects at least one option
+    .help = at least one of the following options is required: `message`, `label` or `note`
+
 passes_may_dangle =
     `#[may_dangle]` must be applied to a lifetime or type generic parameter in `Drop` impl
 
@@ -752,6 +765,11 @@ passes_unknown_lang_item =
     definition of an unknown lang item: `{$name}`
     .label = definition of unknown lang item `{$name}`
 
+passes_unknown_option_for_on_unknown_item =
+    unknown `{$option_name}` option for `#[diagnostic::on_unknown_item]` attribute
+    .help = only `message`, `note` and `label` are allowed as options
+    .label = invalid option found here
+
 passes_unlabeled_cf_in_while_condition =
     `break` or `continue` with no label in the condition of a `while` loop
     .label = unlabeled `{$cf_type}` in the condition of a `while` loop

compiler/rustc_passes/src/check_attr.rs

@@ -44,6 +44,38 @@ use crate::{errors, fluent_generated as fluent};
 #[diag(passes_diagnostic_diagnostic_on_unimplemented_only_for_traits)]
 struct DiagnosticOnUnimplementedOnlyForTraits;
 
+#[derive(LintDiagnostic)]
+#[diag(passes_diagnostic_diagnostic_on_unknown_item_only_for_imports)]
+struct DiagnosticOnUnknownItemOnlyForImports;
+
+#[derive(LintDiagnostic)]
+#[diag(passes_malformed_on_unknown_item_attr)]
+#[help]
+pub(crate) struct MalformedOnUnknownItemAttr {
+    #[label]
+    pub span: Span,
+}
+
+#[derive(LintDiagnostic)]
+#[diag(passes_unknown_option_for_on_unknown_item)]
+#[help]
+pub(crate) struct UnknownOptionForOnUnknownItemAttr {
+    pub option_name: String,
+    #[label]
+    pub span: Span,
+}
+
+#[derive(LintDiagnostic)]
+#[diag(passes_ignored_diagnostic_option)]
+#[help]
+pub(crate) struct IgnoredDiagnositcOption {
+    pub option_name: &'static str,
+    #[label]
+    pub span: Span,
+    #[label(passes_other_label)]
+    pub prev_span: Span,
+}
+
 fn target_from_impl_item<'tcx>(tcx: TyCtxt<'tcx>, impl_item: &hir::ImplItem<'_>) -> Target {
     match impl_item.kind {
         hir::ImplItemKind::Const(..) => Target::AssocConst,
@@ -120,6 +152,9 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
                 [sym::diagnostic, sym::on_unimplemented, ..] => {
                     self.check_diagnostic_on_unimplemented(attr.span, hir_id, target)
                 }
+                [sym::diagnostic, sym::on_unknown_item, ..] => {
+                    self.check_diagnostic_on_unknown_item(attr.span, hir_id, target, attr)
+                }
                 [sym::inline, ..] => self.check_inline(hir_id, attr, span, target),
                 [sym::coverage, ..] => self.check_coverage(attr, span, target),
                 [sym::optimize, ..] => self.check_optimize(hir_id, attr, span, target),
@@ -393,6 +428,78 @@ impl<'tcx> CheckAttrVisitor<'tcx> {
         }
     }
 
+    /// Checks if `#[diagnostic::on_unknown_item]` is applied to an import definition
+    fn check_diagnostic_on_unknown_item(
+        &self,
+        attr_span: Span,
+        hir_id: HirId,
+        target: Target,
+        attr: &Attribute,
+    ) {
+        if !matches!(target, Target::Use) {
+            self.tcx.emit_node_span_lint(
+                UNKNOWN_OR_MALFORMED_DIAGNOSTIC_ATTRIBUTES,
+                hir_id,
+                attr_span,
+                DiagnosticOnUnknownItemOnlyForImports,
+            );
+        }
+        if let Some(meta) = attr.meta_item_list() {
+            let mut message = None;
+            let mut label = None;
+            for item in meta {
+                if item.has_name(sym::message) {
+                    if let Some(message_span) = message {
+                        self.tcx.emit_node_span_lint(
+                            UNKNOWN_OR_MALFORMED_DIAGNOSTIC_ATTRIBUTES,
+                            hir_id,
+                            item.span(),
+                            IgnoredDiagnositcOption {
+                                option_name: "message",
+                                span: item.span(),
+                                prev_span: message_span,
+                            },
+                        );
+                    }
+                    message = Some(item.span());
+                } else if item.has_name(sym::label) {
+                    if let Some(label_span) = label {
+                        self.tcx.emit_node_span_lint(
+                            UNKNOWN_OR_MALFORMED_DIAGNOSTIC_ATTRIBUTES,
+                            hir_id,
+                            item.span(),
+                            IgnoredDiagnositcOption {
+                                option_name: "label",
+                                span: item.span(),
+                                prev_span: label_span,
+                            },
+                        );
+                    }
+                    label = Some(item.span());
+                } else if item.has_name(sym::note) {
+                    // accept any number of notes
+                } else {
+                    self.tcx.emit_node_span_lint(
+                        UNKNOWN_OR_MALFORMED_DIAGNOSTIC_ATTRIBUTES,
+                        hir_id,
+                        item.span(),
+                        UnknownOptionForOnUnknownItemAttr {
+                            option_name: item.name_or_empty().to_string(),
+                            span: item.span(),
+                        },
+                    );
+                }
+            }
+        } else {
+            self.tcx.emit_node_span_lint(
+                UNKNOWN_OR_MALFORMED_DIAGNOSTIC_ATTRIBUTES,
+                hir_id,
+                attr_span,
+                MalformedOnUnknownItemAttr { span: attr_span },
+            );
+        }
+    }
+
     /// Checks if an `#[inline]` is applied to a function or a closure.
     fn check_inline(&self, hir_id: HirId, attr: &Attribute, span: Span, target: Target) {
         match target {

compiler/rustc_resolve/src/build_reduced_graph.rs

@@ -28,7 +28,7 @@ use tracing::debug;
 
 use crate::Namespace::{MacroNS, TypeNS, ValueNS};
 use crate::def_collector::collect_definitions;
-use crate::imports::{ImportData, ImportKind};
+use crate::imports::{ImportData, ImportKind, OnUnknownItemData};
 use crate::macros::{MacroRulesBinding, MacroRulesScope, MacroRulesScopeRef};
 use crate::{
     BindingKey, Determinacy, ExternPreludeEntry, Finalize, MacroData, Module, ModuleKind,
@@ -446,6 +446,7 @@ impl<'a, 'ra, 'tcx> BuildReducedGraphVisitor<'a, 'ra, 'tcx> {
             root_span,
             root_id,
             vis,
+            on_unknown_item_attr: OnUnknownItemData::from_attrs(&item.attrs),
         });
 
         self.r.indeterminate_imports.push(import);
@@ -939,6 +940,7 @@ impl<'a, 'ra, 'tcx> BuildReducedGraphVisitor<'a, 'ra, 'tcx> {
             span: item.span,
             module_path: Vec::new(),
             vis,
+            on_unknown_item_attr: OnUnknownItemData::from_attrs(&item.attrs),
         });
         if used {
             self.r.import_use_map.insert(import, Used::Other);
@@ -1071,7 +1073,7 @@ impl<'a, 'ra, 'tcx> BuildReducedGraphVisitor<'a, 'ra, 'tcx> {
             }
         }
 
-        let macro_use_import = |this: &Self, span, warn_private| {
+        let macro_use_import = |this: &mut Self, span, warn_private| {
             this.r.arenas.alloc_import(ImportData {
                 kind: ImportKind::MacroUse { warn_private },
                 root_id: item.id,
@@ -1084,6 +1086,7 @@ impl<'a, 'ra, 'tcx> BuildReducedGraphVisitor<'a, 'ra, 'tcx> {
                 span,
                 module_path: Vec::new(),
                 vis: ty::Visibility::Restricted(CRATE_DEF_ID),
+                on_unknown_item_attr: OnUnknownItemData::from_attrs(&item.attrs),
             })
         };
 
@@ -1252,6 +1255,7 @@ impl<'a, 'ra, 'tcx> BuildReducedGraphVisitor<'a, 'ra, 'tcx> {
                     span,
                     module_path: Vec::new(),
                     vis,
+                    on_unknown_item_attr: OnUnknownItemData::from_attrs(&item.attrs),
                 });
                 self.r.import_use_map.insert(import, Used::Other);
                 let import_binding = self.r.import(binding, import);

compiler/rustc_resolve/src/imports.rs

@@ -3,6 +3,7 @@
 use std::cell::Cell;
 use std::mem;
 
+use rustc_ast as ast;
 use rustc_ast::NodeId;
 use rustc_data_structures::fx::FxHashSet;
 use rustc_data_structures::intern::Interned;
@@ -140,6 +141,57 @@ impl<'ra> std::fmt::Debug for ImportKind<'ra> {
     }
 }
 
+#[derive(Debug, Clone, Default)]
+pub(crate) struct OnUnknownItemData {
+    pub(crate) message: Option<String>,
+    pub(crate) label: Option<String>,
+    pub(crate) notes: Option<Vec<String>>,
+}
+
+impl OnUnknownItemData {
+    pub(crate) fn from_attrs(attrs: &[ast::Attribute]) -> Option<OnUnknownItemData> {
+        // the attribute syntax is checked in the check_attr
+        // ast pass, so we just consume any valid
+        // options here and ignore everything else
+        let mut out = OnUnknownItemData::default();
+        for attr in
+            attrs.iter().filter(|a| a.path_matches(&[sym::diagnostic, sym::on_unknown_item]))
+        {
+            if let Some(meta) = attr.meta_item_list() {
+                for item in meta {
+                    if item.has_name(sym::message) {
+                        if out.message.is_none()
+                            && let Some(message) = item.value_str()
+                        {
+                            out.message = Some(message.as_str().to_owned());
+                        }
+                    } else if item.has_name(sym::label) {
+                        if out.label.is_none()
+                            && let Some(label) = item.value_str()
+                        {
+                            out.label = Some(label.as_str().to_owned());
+                        }
+                    } else if item.has_name(sym::note) {
+                        if let Some(note) = item.value_str() {
+                            out.notes = Some(out.notes.unwrap_or_default());
+                            out.notes
+                                .as_mut()
+                                .expect("We initialized it above")
+                                .push(note.as_str().to_owned());
+                        }
+                    }
+                }
+            }
+        }
+
+        if out.message.is_none() && out.label.is_none() && out.notes.is_none() {
+            None
+        } else {
+            Some(out)
+        }
+    }
+}
+
 /// One import.
 #[derive(Debug, Clone)]
 pub(crate) struct ImportData<'ra> {
@@ -176,6 +228,8 @@ pub(crate) struct ImportData<'ra> {
     /// The resolution of `module_path`.
     pub imported_module: Cell<Option<ModuleOrUniformRoot<'ra>>>,
     pub vis: ty::Visibility,
+
+    pub on_unknown_item_attr: Option<OnUnknownItemData>,
 }
 
 /// All imports are unique and allocated on a same arena,
@@ -251,6 +305,7 @@ struct UnresolvedImportError {
     segment: Option<Symbol>,
     /// comes from `PathRes::Failed { module }`
     module: Option<DefId>,
+    on_unknown_item_attr: Option<OnUnknownItemData>,
 }
 
 // Reexports of the form `pub use foo as bar;` where `foo` is `extern crate foo;`
@@ -589,6 +644,7 @@ impl<'ra, 'tcx> Resolver<'ra, 'tcx> {
                     candidates: None,
                     segment: None,
                     module: None,
+                    on_unknown_item_attr: import.on_unknown_item_attr.clone(),
                 };
                 errors.push((*import, err))
             }
@@ -693,16 +749,34 @@ impl<'ra, 'tcx> Resolver<'ra, 'tcx> {
                 format!("`{path}`")
             })
             .collect::<Vec<_>>();
-        let msg = format!("unresolved import{} {}", pluralize!(paths.len()), paths.join(", "),);
+        let msg = if errors.len() == 1
+            && let Some(message) =
+                errors[0].1.on_unknown_item_attr.as_mut().and_then(|a| a.message.take())
+        {
+            message
+        } else {
+            format!("unresolved import{} {}", pluralize!(paths.len()), paths.join(", "),)
+        };
 
         let mut diag = struct_span_code_err!(self.dcx(), span, E0432, "{msg}");
 
-        if let Some((_, UnresolvedImportError { note: Some(note), .. })) = errors.iter().last() {
+        if errors.len() == 1
+            && let Some(notes) =
+                errors[0].1.on_unknown_item_attr.as_mut().and_then(|a| a.notes.take())
+        {
+            for note in notes {
+                diag.note(note);
+            }
+        } else if let Some((_, UnresolvedImportError { note: Some(note), .. })) =
+            errors.iter().last()
+        {
             diag.note(note.clone());
         }
 
-        for (import, err) in errors.into_iter().take(MAX_LABEL_COUNT) {
-            if let Some(label) = err.label {
+        for (import, mut err) in errors.into_iter().take(MAX_LABEL_COUNT) {
+            if let Some(label) =
+                err.on_unknown_item_attr.as_mut().and_then(|a| a.label.take()).or(err.label)
+            {
                 diag.span_label(err.span, label);
             }
 
@@ -956,6 +1030,7 @@ impl<'ra, 'tcx> Resolver<'ra, 'tcx> {
                             candidates: None,
                             segment: Some(segment_name),
                             module,
+                            on_unknown_item_attr: import.on_unknown_item_attr.clone(),
                         },
                         None => UnresolvedImportError {
                             span,
@@ -965,6 +1040,7 @@ impl<'ra, 'tcx> Resolver<'ra, 'tcx> {
                             candidates: None,
                             segment: Some(segment_name),
                             module,
+                            on_unknown_item_attr: import.on_unknown_item_attr.clone(),
                         },
                     };
                     return Some(err);
@@ -1014,6 +1090,7 @@ impl<'ra, 'tcx> Resolver<'ra, 'tcx> {
                             candidates: None,
                             segment: None,
                             module: None,
+                            on_unknown_item_attr: import.on_unknown_item_attr.clone(),
                         });
                     }
                     if !is_prelude
@@ -1229,6 +1306,7 @@ impl<'ra, 'tcx> Resolver<'ra, 'tcx> {
                         }
                     }),
                     segment: Some(ident.name),
+                    on_unknown_item_attr: import.on_unknown_item_attr.clone(),
                 })
             } else {
                 // `resolve_ident_in_module` reported a privacy error.