Rollup merge of rust-lang#158468 - obi1kenobi:pg/default-body-stability, r=GuillaumeGomez

Include default-stability info in rustdoc JSON.

Add a `default_unstable` field on associated constants, associated types, and functions. The field is populated only when those items appear inside a trait, only when there's a default present, and when that default is not stable as designated by `#[rustc_default_body_unstable]`. In such a case, the field contains the name of the feature required to use the unstable default.

The purpose of this info is to allow `cargo-semver-checks` to lint the standard library for accidental breakage of stable APIs. Removing a stable default is an example of such breakage, while removing an _unstable_ default is not.

The field is boxed to minimize the size impact on its enclosing type, since for regular crates it will always be `None`.

I also updated `jsondoclint` to assert that it's an error to have a populated `default_unstable` when there's no function body, no default const value, or no default associated type. In the process, I noticed that `jsondoclint` and `jsondocck` are both on edition 2021 — I plan to upgrade them to 2024 in separate PRs.

r? @GuillaumeGomez

**AI disclosure:** This PR is the product of a combination of manual work and AI tools. I secured approval in advance from the designated reviewer. I stand behind the quality of the code I'm submitting, and I vouch it's as good or better compared to if I had written every line by my own hand.

Author: jhpratt

src/librustdoc/json/conversions.rs

@@ -270,6 +270,18 @@ impl FromClean<hir::ConstStability> for Stability {
     }
 }
 
+impl FromClean<hir::DefaultBodyStability> for Box<ProvidedDefaultUnstable> {
+    fn from_clean(stab: &hir::DefaultBodyStability, _renderer: &JsonRenderer<'_>) -> Self {
+        let hir::StabilityLevel::Unstable { .. } = stab.level else {
+            bug!(
+                "unexpected stable default-body stability, \
+                 there's no stable equivalent of `#[rustc_default_body_unstable]`"
+            )
+        };
+        Box::new(ProvidedDefaultUnstable { feature: stab.feature.to_string() })
+    }
+}
+
 impl FromClean<clean::GenericArgs> for Option<Box<GenericArgs>> {
     fn from_clean(generic_args: &clean::GenericArgs, renderer: &JsonRenderer<'_>) -> Self {
         use clean::GenericArgs::*;
@@ -353,18 +365,23 @@ fn from_clean_item(item: &clean::Item, renderer: &JsonRenderer<'_>) -> ItemEnum
         EnumItem(e) => ItemEnum::Enum(e.into_json(renderer)),
         VariantItem(v) => ItemEnum::Variant(v.into_json(renderer)),
         FunctionItem(f) => {
-            ItemEnum::Function(from_clean_function(f, true, header.unwrap(), renderer))
+            ItemEnum::Function(from_clean_function(f, true, None, header.unwrap(), renderer))
         }
         ForeignFunctionItem(f, _) => {
-            ItemEnum::Function(from_clean_function(f, false, header.unwrap(), renderer))
+            ItemEnum::Function(from_clean_function(f, false, None, header.unwrap(), renderer))
         }
         TraitItem(t) => ItemEnum::Trait(t.into_json(renderer)),
         TraitAliasItem(t) => ItemEnum::TraitAlias(t.into_json(renderer)),
-        MethodItem(m, _) => {
-            ItemEnum::Function(from_clean_function(m, true, header.unwrap(), renderer))
-        }
+        MethodItem(m, _) => ItemEnum::Function(from_clean_function(
+            m,
+            true,
+            default_body_stability_for_def_id(renderer.tcx, item.item_id.expect_def_id())
+                .map(|stab| stab.into_json(renderer)),
+            header.unwrap(),
+            renderer,
+        )),
         RequiredMethodItem(m, _) => {
-            ItemEnum::Function(from_clean_function(m, false, header.unwrap(), renderer))
+            ItemEnum::Function(from_clean_function(m, false, None, header.unwrap(), renderer))
         }
         ImplItem(i) => ItemEnum::Impl(i.into_json(renderer)),
         StaticItem(s) => ItemEnum::Static(from_clean_static(s, rustc_hir::Safety::Safe, renderer)),
@@ -385,23 +402,41 @@ fn from_clean_item(item: &clean::Item, renderer: &JsonRenderer<'_>) -> ItemEnum
             })
         }
         // FIXME(generic_const_items): Add support for generic associated consts.
-        RequiredAssocConstItem(_generics, ty) => {
-            ItemEnum::AssocConst { type_: ty.into_json(renderer), value: None }
-        }
+        RequiredAssocConstItem(_generics, ty) => ItemEnum::AssocConst {
+            type_: ty.into_json(renderer),
+            value: None,
+            default_unstable: None,
+        },
         // FIXME(generic_const_items): Add support for generic associated consts.
-        ProvidedAssocConstItem(ci) | ImplAssocConstItem(ci) => ItemEnum::AssocConst {
+        ProvidedAssocConstItem(ci) => ItemEnum::AssocConst {
             type_: ci.type_.into_json(renderer),
             value: Some(ci.kind.expr(renderer.tcx)),
+            default_unstable: default_body_stability_for_def_id(
+                renderer.tcx,
+                item.item_id.expect_def_id(),
+            )
+            .map(|stab| stab.into_json(renderer)),
+        },
+        ImplAssocConstItem(ci) => ItemEnum::AssocConst {
+            type_: ci.type_.into_json(renderer),
+            value: Some(ci.kind.expr(renderer.tcx)),
+            default_unstable: None,
         },
         RequiredAssocTypeItem(g, b) => ItemEnum::AssocType {
             generics: g.into_json(renderer),
             bounds: b.into_json(renderer),
             type_: None,
+            default_unstable: None,
         },
         AssocTypeItem(t, b) => ItemEnum::AssocType {
             generics: t.generics.into_json(renderer),
             bounds: b.into_json(renderer),
             type_: Some(t.item_type.as_ref().unwrap_or(&t.type_).into_json(renderer)),
+            default_unstable: default_body_stability_for_def_id(
+                renderer.tcx,
+                item.item_id.expect_def_id(),
+            )
+            .map(|stab| stab.into_json(renderer)),
         },
         // `convert_item` early returns `None` for stripped items, keywords, attributes and
         // "special" macro rules.
@@ -815,6 +850,7 @@ impl FromClean<clean::Impl> for Impl {
 pub(crate) fn from_clean_function(
     clean::Function { decl, generics }: &clean::Function,
     has_body: bool,
+    default_unstable: Option<Box<ProvidedDefaultUnstable>>,
     header: rustc_hir::FnHeader,
     renderer: &JsonRenderer<'_>,
 ) -> Function {
@@ -823,6 +859,7 @@ pub(crate) fn from_clean_function(
         generics: generics.into_json(renderer),
         header: header.into_json(renderer),
         has_body,
+        default_unstable,
     }
 }
 
@@ -972,6 +1009,17 @@ impl FromClean<ItemType> for ItemKind {
     }
 }
 
+fn default_body_stability_for_def_id(
+    tcx: TyCtxt<'_>,
+    def_id: DefId,
+) -> Option<hir::DefaultBodyStability> {
+    let stability = tcx.lookup_default_body_stability(def_id)?;
+    match stability.level {
+        hir::StabilityLevel::Unstable { .. } => Some(stability),
+        hir::StabilityLevel::Stable { .. } => None,
+    }
+}
+
 fn const_stability_for_def_id(tcx: TyCtxt<'_>, def_id: DefId) -> Option<hir::ConstStability> {
     if !tcx.is_conditionally_const(def_id) {
         // The item cannot be conditionally-const. No const stability here.
@@ -1040,6 +1088,7 @@ fn maybe_from_hir_attr(attr: &hir::Attribute, item_id: ItemId, tcx: TyCtxt<'_>)
         AK::Deprecated { .. } => return Vec::new(), // Handled separately into Item::deprecation.
         AK::Stability { .. } => return Vec::new(),  // Handled separately into Item::stability
         AK::RustcConstStability { .. } => return Vec::new(), // Handled separately into Item::const_stability.
+        AK::RustcBodyStability { .. } => return Vec::new(), // Handled separately by `default_unstable`.
 
         AK::DocComment { .. } => unreachable!("doc comments stripped out earlier"),
 

src/rustdoc-json-types/lib.rs

@@ -114,8 +114,8 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
 // will instead cause conflicts. See #94591 for more. (This paragraph and the "Latest feature" line
 // are deliberately not in a doc comment, because they need not be in public docs.)
 //
-// Latest feature: Add `Item::const_stability`.
-pub const FORMAT_VERSION: u32 = 59;
+// Latest feature: Add default-body stability metadata.
+pub const FORMAT_VERSION: u32 = 60;
 
 /// The root of the emitted JSON blob.
 ///
@@ -288,6 +288,9 @@ pub struct Item {
     /// - `#[stable]` and `#[unstable]` attributes: see the [`Self::stability`] field instead.
     /// - `#[rustc_const_stable]` and `#[rustc_const_unstable]` attributes:
     ///   see the [`Self::const_stability`] field instead.
+    /// - `#[rustc_default_body_unstable]` attributes: instead see `default_unstable` fields on
+    ///   item kinds that can have unstable default values, such as [`Function::default_unstable`],
+    ///   [`ItemEnum::AssocConst::default_unstable`], and [`ItemEnum::AssocType::default_unstable`].
     ///
     /// Attributes appear in pretty-printed Rust form, regardless of their formatting
     /// in the original source code. For example:
@@ -367,6 +370,19 @@ pub enum StabilityLevel {
     Unstable,
 }
 
+/// Information about an unstable default provided by a trait item.
+///
+/// Example unstable defaults include:
+/// - a stable trait function or method whose body is not stable
+/// - a stable trait associated type or const whose default value is not stable
+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
+pub struct ProvidedDefaultUnstable {
+    /// The feature that must be enabled to use the provided default.
+    pub feature: String,
+}
+
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
 #[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
@@ -379,6 +395,9 @@ pub enum StabilityLevel {
 /// - `#[stable]` and `#[unstable]`. These are in [`Item::stability`] instead.
 /// - `#[rustc_const_stable]` and `#[rustc_const_unstable]`. These are in
 ///   [`Item::const_stability`] instead.
+/// - `#[rustc_default_body_unstable]`. These are in the `default_unstable` field on the appropriate
+///   item kinds: [`Function::default_unstable`], [`ItemEnum::AssocConst::default_unstable`],
+///   and [`ItemEnum::AssocType::default_unstable`].
 pub enum Attribute {
     /// `#[non_exhaustive]`
     NonExhaustive,
@@ -875,6 +894,11 @@ pub enum ItemEnum {
         /// //               ^^^^^^^^^^
         /// ```
         value: Option<String>,
+        /// Metadata about an unstable default value provided for the associated constant, if any.
+        ///
+        /// Empty if the associated constant has no default (see [`ItemEnum::AssocConst::value`]),
+        /// or if the default value is stable.
+        default_unstable: Option<Box<ProvidedDefaultUnstable>>,
     },
     /// An associated type of a trait or a type.
     AssocType {
@@ -899,6 +923,11 @@ pub enum ItemEnum {
         /// ```
         #[serde(rename = "type")]
         type_: Option<Type>,
+        /// Metadata about an unstable default value provided for the associated type, if any.
+        ///
+        /// Empty if the associated type has no default (see [`ItemEnum::AssocType::type_`]),
+        /// or if the default value is stable.
+        default_unstable: Option<Box<ProvidedDefaultUnstable>>,
     },
 }
 
@@ -1188,6 +1217,12 @@ pub struct Function {
     pub header: FunctionHeader,
     /// Whether the function has a body, i.e. an implementation.
     pub has_body: bool,
+    /// Metadata about a possible unstable provided default implementation for trait methods.
+    ///
+    /// Only populated for function items inside traits. Empty if the trait method
+    /// does not have a default implementation (see [`Function::has_body`]),
+    /// or if its default implementation is stable.
+    pub default_unstable: Option<Box<ProvidedDefaultUnstable>>,
 }
 
 /// Generic parameters accepted by an item and `where` clauses imposed on it and the parameters.

src/tools/jsondoclint/src/validator.rs

@@ -97,7 +97,7 @@ impl<'a> Validator<'a> {
                 ItemEnum::StructField(x) => self.check_struct_field(x),
                 ItemEnum::Enum(x) => self.check_enum(x),
                 ItemEnum::Variant(x) => self.check_variant(x, id),
-                ItemEnum::Function(x) => self.check_function(x),
+                ItemEnum::Function(x) => self.check_function(x, id),
                 ItemEnum::Trait(x) => self.check_trait(x, id),
                 ItemEnum::TraitAlias(x) => self.check_trait_alias(x),
                 ItemEnum::Impl(x) => self.check_impl(x, id),
@@ -114,12 +114,35 @@ impl<'a> Validator<'a> {
                 ItemEnum::Module(x) => self.check_module(x, id),
                 // FIXME: Why don't these have their own structs?
                 ItemEnum::ExternCrate { .. } => {}
-                ItemEnum::AssocConst { type_, value: _ } => self.check_type(type_),
-                ItemEnum::AssocType { generics, bounds, type_ } => {
+                ItemEnum::AssocConst { type_, value, default_unstable } => {
+                    self.check_type(type_);
+                    if value.is_none()
+                        && let Some(default_unstable) = default_unstable
+                    {
+                        self.fail(
+                            id,
+                            ErrorKind::Custom(format!(
+                                "`default_unstable` must be `None` when `value` is `None`, but \
+                                 assoc const id {} had `default_unstable` with feature `{}`",
+                                id.0, default_unstable.feature
+                            )),
+                        );
+                    }
+                }
+                ItemEnum::AssocType { generics, bounds, type_, default_unstable } => {
                     self.check_generics(generics);
                     bounds.iter().for_each(|b| self.check_generic_bound(b));
                     if let Some(ty) = type_ {
                         self.check_type(ty);
+                    } else if let Some(default_unstable) = default_unstable {
+                        self.fail(
+                            id,
+                            ErrorKind::Custom(format!(
+                                "`default_unstable` must be `None` when `type_` is `None`, but \
+                                 assoc type id {} had `default_unstable` with feature `{}`",
+                                id.0, default_unstable.feature
+                            )),
+                        );
                     }
                 }
             }
@@ -194,9 +217,21 @@ impl<'a> Validator<'a> {
         }
     }
 
-    fn check_function(&mut self, x: &'a Function) {
+    fn check_function(&mut self, x: &'a Function, id: &Id) {
         self.check_generics(&x.generics);
         self.check_function_signature(&x.sig);
+        if !x.has_body
+            && let Some(default_unstable) = &x.default_unstable
+        {
+            self.fail(
+                id,
+                ErrorKind::Custom(format!(
+                    "`default_unstable` must be `None` when `has_body == false`, but \
+                     function item id {} had `default_unstable` with feature `{}`",
+                    id.0, default_unstable.feature
+                )),
+            );
+        }
     }
 
     fn check_trait(&mut self, x: &'a Trait, id: &Id) {