Add knot.toml schema

crates/red_knot_project/Cargo.toml

@@ -28,6 +28,7 @@ pep440_rs = { workspace = true }
 rayon = { workspace = true }
 rustc-hash = { workspace = true }
 salsa = { workspace = true }
+schemars = { workspace = true, optional = true }
 serde = { workspace = true }
 thiserror = { workspace = true }
 toml = { workspace = true }
@@ -40,8 +41,9 @@ insta = { workspace = true, features = ["redactions", "ron"] }
 
 [features]
 default = ["zstd"]
-zstd = ["red_knot_vendored/zstd"]
 deflate = ["red_knot_vendored/deflate"]
+schemars = ["dep:schemars", "ruff_db/schemars", "red_knot_python_semantic/schemars"]
+zstd = ["red_knot_vendored/zstd"]
 
 [lints]
 workspace = true

crates/red_knot_project/src/metadata/options.rs

@@ -18,13 +18,16 @@ use thiserror::Error;
 /// The options for the project.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct Options {
+    /// Configures the type checking environment.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub environment: Option<EnvironmentOptions>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
     pub src: Option<SrcOptions>,
 
+    /// Configures the enabled lints and their severity.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub rules: Option<Rules>,
 }
@@ -177,10 +180,22 @@ impl Options {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct EnvironmentOptions {
+    /// Specifies the version of Python that will be used to execute the source code.
+    /// The version should be specified as a string in the format `M.m` where `M` is the major version
+    /// and `m` is the minor (e.g. "3.0" or "3.6").
+    /// If a version is provided, knot will generate errors if the source code makes use of language features
+    /// that are not supported in that version.
+    /// It will also tailor its use of type stub files, which conditionalizes type definitions based on the version.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub python_version: Option<RangedValue<PythonVersion>>,
 
+    /// Specifies the target platform that will be used to execute the source code.
+    /// If specified, Red Knot will tailor its use of type stub files,
+    /// which conditionalize type definitions based on the platform.
+    ///
+    /// If no platform is specified, knot will use `all` or the current platform in the LSP use case.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub python_platform: Option<RangedValue<PythonPlatform>>,
 
@@ -204,6 +219,7 @@ pub struct EnvironmentOptions {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct SrcOptions {
     /// The root of the project, used for finding first-party modules.
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -212,7 +228,9 @@ pub struct SrcOptions {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, Combine, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case", transparent)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct Rules {
+    #[cfg_attr(feature = "schemars", schemars(with = "schema::Rules"))]
     inner: FxHashMap<RangedValue<String>, RangedValue<Level>>,
 }
 
@@ -226,6 +244,69 @@ impl FromIterator<(RangedValue<String>, RangedValue<Level>)> for Rules {
     }
 }
 
+#[cfg(feature = "schemars")]
+mod schema {
+    use crate::DEFAULT_LINT_REGISTRY;
+    use red_knot_python_semantic::lint::Level;
+    use schemars::gen::SchemaGenerator;
+    use schemars::schema::{
+        InstanceType, Metadata, ObjectValidation, Schema, SchemaObject, SubschemaValidation,
+    };
+    use schemars::JsonSchema;
+
+    pub(super) struct Rules;
+
+    impl JsonSchema for Rules {
+        fn schema_name() -> String {
+            "Rules".to_string()
+        }
+
+        fn json_schema(gen: &mut SchemaGenerator) -> Schema {
+            let registry = &*DEFAULT_LINT_REGISTRY;
+
+            let level_schema = gen.subschema_for::<Level>();
+
+            let properties: schemars::Map<String, Schema> = registry
+                .lints()
+                .iter()
+                .map(|lint| {
+                    (
+                        lint.name().to_string(),
+                        Schema::Object(SchemaObject {
+                            metadata: Some(Box::new(Metadata {
+                                title: Some(lint.summary().to_string()),
+                                description: Some(lint.documentation()),
+                                deprecated: lint.status.is_deprecated(),
+                                default: Some(lint.default_level.to_string().into()),
+                                ..Metadata::default()
+                            })),
+                            subschemas: Some(Box::new(SubschemaValidation {
+                                one_of: Some(vec![level_schema.clone()]),
+                                ..Default::default()
+                            })),
+                            ..Default::default()
+                        }),
+                    )
+                })
+                .collect();
+
+            Schema::Object(SchemaObject {
+                instance_type: Some(InstanceType::Object.into()),
+                object: Some(Box::new(ObjectValidation {
+                    properties,
+                    // Allow unknown rules: Red Knot will warn about them.
+                    // It gives a better experience when using an older Red Knot version because
+                    // the schema will not deny rules that have been removed in newer versions.
+                    additional_properties: Some(Box::new(level_schema)),
+                    ..ObjectValidation::default()
+                })),
+
+                ..Default::default()
+            })
+        }
+    }
+}
+
 #[derive(Error, Debug)]
 pub enum KnotTomlError {
     #[error(transparent)]

crates/red_knot_project/src/metadata/value.rs

@@ -1,8 +1,9 @@
 use crate::combine::Combine;
 use crate::Db;
 use ruff_db::system::{System, SystemPath, SystemPathBuf};
+use ruff_macros::Combine;
 use ruff_text_size::{TextRange, TextSize};
-use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use serde::{Deserialize, Deserializer};
 use std::cell::RefCell;
 use std::cmp::Ordering;
 use std::fmt;
@@ -70,15 +71,19 @@ impl Drop for ValueSourceGuard {
 ///
 /// This ensures that two resolved configurations are identical even if the position of a value has changed
 /// or if the values were loaded from different sources.
-#[derive(Clone)]
+#[derive(Clone, serde::Serialize)]
+#[serde(transparent)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct RangedValue<T> {
     value: T,
+    #[serde(skip)]
     source: ValueSource,
 
     /// The byte range of `value` in `source`.
     ///
     /// Can be `None` because not all sources support a range.
     /// For example, arguments provided on the CLI won't have a range attached.
+    #[serde(skip)]
     range: Option<TextRange>,
 }
 
@@ -266,18 +271,6 @@ where
     }
 }
 
-impl<T> Serialize for RangedValue<T>
-where
-    T: Serialize,
-{
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: Serializer,
-    {
-        self.value.serialize(serializer)
-    }
-}
-
 /// A possibly relative path in a configuration file.
 ///
 /// Relative paths in configuration files or from CLI options
@@ -286,9 +279,19 @@ where
 /// * CLI: The path is relative to the current working directory
 /// * Configuration file: The path is relative to the project's root.
 #[derive(
-    Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash,
+    Debug,
+    Clone,
+    serde::Serialize,
+    serde::Deserialize,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Ord,
+    Hash,
+    Combine,
 )]
 #[serde(transparent)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct RelativePathBuf(RangedValue<SystemPathBuf>);
 
 impl RelativePathBuf {
@@ -325,13 +328,3 @@ impl RelativePathBuf {
         SystemPath::absolute(&self.0, relative_to)
     }
 }
-
-impl Combine for RelativePathBuf {
-    fn combine(self, other: Self) -> Self {
-        Self(self.0.combine(other.0))
-    }
-
-    fn combine_with(&mut self, other: Self) {
-        self.0.combine_with(other.0);
-    }
-}

crates/red_knot_python_semantic/Cargo.toml

@@ -36,6 +36,7 @@ thiserror = { workspace = true }
 tracing = { workspace = true }
 rustc-hash = { workspace = true }
 hashbrown = { workspace = true }
+schemars = { workspace = true, optional = true }
 serde = { workspace = true, optional = true }
 smallvec = { workspace = true }
 static_assertions = { workspace = true }

crates/red_knot_python_semantic/src/lint.rs

@@ -1,6 +1,8 @@
+use core::fmt;
 use itertools::Itertools;
 use ruff_db::diagnostic::{DiagnosticId, LintName, Severity};
 use rustc_hash::FxHashMap;
+use std::fmt::Formatter;
 use std::hash::Hasher;
 use thiserror::Error;
 
@@ -36,13 +38,20 @@ pub struct LintMetadata {
     derive(serde::Serialize, serde::Deserialize),
     serde(rename_all = "kebab-case")
 )]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub enum Level {
+    /// # Ignore
+    ///
     /// The lint is disabled and should not run.
     Ignore,
 
+    /// # Warn
+    ///
     /// The lint is enabled and diagnostic should have a warning severity.
     Warn,
 
+    /// # Error
+    ///
     /// The lint is enabled and diagnostics have an error severity.
     Error,
 }
@@ -61,6 +70,16 @@ impl Level {
     }
 }
 
+impl fmt::Display for Level {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Level::Ignore => f.write_str("ignore"),
+            Level::Warn => f.write_str("warn"),
+            Level::Error => f.write_str("error"),
+        }
+    }
+}
+
 impl TryFrom<Level> for Severity {
     type Error = ();
 
@@ -84,9 +103,11 @@ impl LintMetadata {
 
     /// Returns the documentation line by line with one leading space and all trailing whitespace removed.
     pub fn documentation_lines(&self) -> impl Iterator<Item = &str> {
-        self.raw_documentation
-            .lines()
-            .map(|line| line.strip_prefix(' ').unwrap_or(line).trim_end())
+        self.raw_documentation.lines().map(|line| {
+            line.strip_prefix(char::is_whitespace)
+                .unwrap_or(line)
+                .trim_end()
+        })
     }
 
     /// Returns the documentation as a single string.
@@ -180,6 +201,10 @@ impl LintStatus {
     pub const fn is_removed(&self) -> bool {
         matches!(self, LintStatus::Removed { .. })
     }
+
+    pub const fn is_deprecated(&self) -> bool {
+        matches!(self, LintStatus::Deprecated { .. })
+    }
 }
 
 /// Declares a lint rule with the given metadata.
@@ -223,7 +248,7 @@ macro_rules! declare_lint {
         $vis static $name: $crate::lint::LintMetadata = $crate::lint::LintMetadata {
             name: ruff_db::diagnostic::LintName::of(ruff_macros::kebab_case!($name)),
             summary: $summary,
-            raw_documentation: concat!($($doc,)+ "\n"),
+            raw_documentation: concat!($($doc, '\n',)+),
             status: $status,
             file: file!(),
             line: line!(),