Promote lint. settings over top-level settings (#9476)

crates/ruff_workspace/src/configuration.rs

@@ -396,11 +396,11 @@ impl Configuration {
 
     pub fn from_options(options: Options, project_root: &Path) -> Result<Self> {
         let lint = if let Some(mut lint) = options.lint {
-            lint.common = lint.common.combine(options.lint_top_level);
+            lint.common = lint.common.combine(options.lint_top_level.common);
             lint
         } else {
             LintOptions {
-                common: options.lint_top_level,
+                common: options.lint_top_level.common,
                 ..LintOptions::default()
             }
         };

crates/ruff_workspace/src/options.rs

@@ -6,6 +6,7 @@ use rustc_hash::{FxHashMap, FxHashSet};
 use serde::{Deserialize, Serialize};
 use strum::IntoEnumIterator;
 
+use crate::options_base::{OptionsMetadata, Visit};
 use ruff_formatter::IndentStyle;
 use ruff_linter::line_width::{IndentWidth, LineLength};
 use ruff_linter::rules::flake8_pytest_style::settings::SettingsError;
@@ -420,21 +421,21 @@ pub struct Options {
     )]
     pub tab_size: Option<IndentWidth>,
 
+    #[option_group]
     pub lint: Option<LintOptions>,
 
     /// The lint sections specified at the top level.
     #[serde(flatten)]
-    pub lint_top_level: LintCommonOptions,
+    pub lint_top_level: DeprecatedTopLevelLintOptions,
 
     /// Options to configure code formatting.
     #[option_group]
     pub format: Option<FormatOptions>,
 }
 
-/// Experimental section to configure Ruff's linting. This new section will eventually
-/// replace the top-level linting options.
+/// Configures how ruff checks your code.
 ///
-/// Options specified in the `lint` section take precedence over the top-level settings.
+/// Options specified in the `lint` section take precedence over the deprecated top-level settings.
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(Debug, PartialEq, Eq, Default, OptionsMetadata, Serialize, Deserialize)]
 #[serde(deny_unknown_fields, rename_all = "kebab-case")]
@@ -477,15 +478,69 @@ pub struct LintOptions {
     pub preview: Option<bool>,
 }
 
+/// Newtype wrapper for [`LintCommonOptions`] that allows customizing the JSON schema and omitting the fields from the [`OptionsMetadata`].
+#[derive(Debug, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct DeprecatedTopLevelLintOptions {
+    pub common: LintCommonOptions,
+}
+
+impl OptionsMetadata for DeprecatedTopLevelLintOptions {
+    fn record(_visit: &mut dyn Visit) {
+        // Intentionally empty. Omit all fields from the documentation and instead promote the options under the `lint.` section.
+        // This doesn't create an empty 'common' option  because the field in the `Options` struct is marked with `#[serde(flatten)]`.
+        // Meaning, the code here flattens no-properties into the parent, which is what we want.
+    }
+}
+
+#[cfg(feature = "schemars")]
+impl schemars::JsonSchema for DeprecatedTopLevelLintOptions {
+    fn schema_name() -> std::string::String {
+        "DeprecatedTopLevelLintOptions".to_owned()
+    }
+    fn schema_id() -> std::borrow::Cow<'static, str> {
+        std::borrow::Cow::Borrowed(std::concat!(
+            std::module_path!(),
+            "::",
+            "DeprecatedTopLevelLintOptions"
+        ))
+    }
+    fn json_schema(gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
+        use schemars::schema::Schema;
+
+        let common_schema = LintCommonOptions::json_schema(gen);
+        let mut schema_obj = common_schema.into_object();
+
+        if let Some(object) = schema_obj.object.as_mut() {
+            for property in object.properties.values_mut() {
+                if let Schema::Object(property_object) = property {
+                    if let Some(metadata) = &mut property_object.metadata {
+                        metadata.deprecated = true;
+                    } else {
+                        property_object.metadata = Some(Box::new(schemars::schema::Metadata {
+                            deprecated: true,
+                            ..schemars::schema::Metadata::default()
+                        }));
+                    }
+                }
+            }
+        }
+
+        Schema::Object(schema_obj)
+    }
+}
+
 // Note: This struct should be inlined into [`LintOptions`] once support for the top-level lint settings
 // is removed.
-
+// Don't add any new options to this struct. Add them to [`LintOptions`] directly to avoid exposing them in the
+// global settings.
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[derive(
     Debug, PartialEq, Eq, Default, OptionsMetadata, CombineOptions, Serialize, Deserialize,
 )]
 #[serde(deny_unknown_fields, rename_all = "kebab-case")]
 pub struct LintCommonOptions {
+    // WARNING: Don't add new options to this type. Add them to `LintOptions` instead.
     /// A list of allowed "confusable" Unicode characters to ignore when
     /// enforcing `RUF001`, `RUF002`, and `RUF003`.
     #[option(
@@ -734,6 +789,7 @@ pub struct LintCommonOptions {
     )]
     pub unfixable: Option<Vec<RuleSelector>>,
 
+    // WARNING: Don't add new options to this type. Add them to `LintOptions` instead.
     /// Options for the `flake8-annotations` plugin.
     #[option_group]
     pub flake8_annotations: Option<Flake8AnnotationsOptions>,
@@ -830,6 +886,8 @@ pub struct LintCommonOptions {
     #[option_group]
     pub pyupgrade: Option<PyUpgradeOptions>,
 
+    // WARNING: Don't add new options to this type. Add them to `LintOptions` instead.
+
     // Tables are required to go last.
     /// A list of mappings from file pattern to rule codes or prefixes to
     /// exclude, when considering any matching files.
@@ -857,6 +915,7 @@ pub struct LintCommonOptions {
         "#
     )]
     pub extend_per_file_ignores: Option<FxHashMap<String, Vec<RuleSelector>>>,
+    // WARNING: Don't add new options to this type. Add them to `LintOptions` instead.
 }
 
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
@@ -2816,9 +2875,7 @@ impl PyUpgradeOptions {
     }
 }
 
-/// Experimental: Configures how `ruff format` formats your code.
-///
-/// Please provide feedback in [this discussion](https://github.com/astral-sh/ruff/discussions/7310).
+/// Configures the way ruff formats your code.
 #[derive(
     Debug, PartialEq, Eq, Default, Deserialize, Serialize, OptionsMetadata, CombineOptions,
 )]