feat(biome_graphql_analyze): implement useConsistentGraphqlDescriptions

.changeset/chubby-bottles-lick.md

@@ -0,0 +1,25 @@
+---
+"@biomejs/biome": patch
+---
+
+Added the nursery rule [`useConsistentGraphqlDescriptions`](https://biomejs.dev/linter/rules/use-consistent-graphql-descriptions/), requiring all descriptions to follow the same style (either block or inline) inside GraphQL files.
+
+**Invalid:**
+
+```graphql
+enum EnumValue {
+  "this is a description"
+  DEFAULT
+}
+```
+
+**Valid:**
+
+```graphql
+enum EnumValue {
+  """
+  this is a description
+  """
+  DEFAULT
+}
+```

crates/biome_diagnostics_categories/src/categories.rs

@@ -197,6 +197,7 @@ define_categories! {
     "lint/nursery/useBiomeSuppressionComment": "https://biomejs.dev/linter/rules/use-biome-suppression-comment",
     "lint/nursery/useConsistentArrowReturn": "https://biomejs.dev/linter/rules/use-consistent-arrow-return",
     "lint/nursery/useConsistentObjectDefinition": "https://biomejs.dev/linter/rules/use-consistent-object-definition",
+    "lint/nursery/useConsistentGraphqlDescriptions": "https://biomejs.dev/linter/rules/use-consistent-graphql-descriptions",
     "lint/nursery/useDeprecatedDate": "https://biomejs.dev/linter/rules/use-deprecated-date",
     "lint/nursery/useExhaustiveSwitchCases": "https://biomejs.dev/linter/rules/use-exhaustive-switch-cases",
     "lint/nursery/useExplicitFunctionReturnType": "https://biomejs.dev/linter/rules/use-explicit-type",

crates/biome_graphql_analyze/src/lint/nursery.rs

@@ -4,5 +4,6 @@
 
 use biome_analyze::declare_lint_group;
 pub mod no_empty_source;
+pub mod use_consistent_graphql_descriptions;
 pub mod use_deprecated_date;
-declare_lint_group! { pub Nursery { name : "nursery" , rules : [self :: no_empty_source :: NoEmptySource , self :: use_deprecated_date :: UseDeprecatedDate ,] } }
+declare_lint_group! { pub Nursery { name : "nursery" , rules : [self :: no_empty_source :: NoEmptySource , self :: use_consistent_graphql_descriptions :: UseConsistentGraphqlDescriptions , self :: use_deprecated_date :: UseDeprecatedDate ,] } }

crates/biome_graphql_analyze/src/lint/nursery/use_consistent_graphql_descriptions.rs

@@ -0,0 +1,114 @@
+use biome_analyze::{
+    Ast, Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule,
+};
+use biome_console::markup;
+use biome_graphql_syntax::GraphqlDescription;
+use biome_rowan::AstNode;
+use biome_rule_options::use_consistent_graphql_descriptions::{
+    Style, UseConsistentGraphqlDescriptionsOptions,
+};
+
+declare_lint_rule! {
+    /// Require all descriptions to follow the same style (either block or inline) to  maintain consistency and improve readability across the schema.
+    ///
+    /// ## Examples
+    ///
+    /// ### style: `block`
+    ///
+    /// #### Invalid
+    ///
+    /// ```graphql,expect_diagnostic
+    /// enum EnumValue {
+    ///   "this is a description"
+    ///   DEFAULT
+    /// }
+    /// ```
+    ///
+    /// #### Valid
+    ///
+    /// ```graphql
+    /// enum EnumValue {
+    ///   """
+    ///   this is a description
+    ///   """
+    ///   DEFAULT
+    /// }
+    /// ```
+    ///
+    /// ## Options
+    ///
+    /// ### `style`
+    ///
+    /// This option will specify the description style.
+    /// - `"block"`: Requires triple-quoted block descriptions (`"""..."""`)
+    /// - `"inline"`: Requires single-quoted inline descriptions (`"..."`)
+    ///
+    /// Default `"block"`
+    ///
+    /// ```json,options
+    /// {
+    ///   "options": {
+    ///     "style": "inline"
+    ///   }
+    /// }
+    /// ```
+    ///
+    /// ```graphql,expect_diagnostic,use_options
+    /// enum EnumValue {
+    ///   """
+    ///   this is a description
+    ///   """
+    ///   DEFAULT
+    /// }
+    /// ```
+    ///
+    pub UseConsistentGraphqlDescriptions {
+        version: "next",
+        name: "useConsistentGraphqlDescriptions",
+        language: "graphql",
+        sources: &[RuleSource::EslintGraphql("description-style").same()],
+        recommended: false,
+    }
+}
+
+impl Rule for UseConsistentGraphqlDescriptions {
+    type Query = Ast<GraphqlDescription>;
+    type State = ();
+    type Signals = Option<Self::State>;
+    type Options = UseConsistentGraphqlDescriptionsOptions;
+
+    fn run(ctx: &RuleContext<Self>) -> Option<Self::State> {
+        let node = ctx.query();
+        let style = ctx.options().style.unwrap_or_default();
+
+        let value = node.graphql_string_value().ok()?;
+
+        if style == Style::Block && !value.is_block() {
+            return Some(());
+        }
+
+        if style == Style::Inline && value.is_block() {
+            return Some(());
+        }
+
+        None
+    }
+
+    fn diagnostic(ctx: &RuleContext<Self>, _state: &Self::State) -> Option<RuleDiagnostic> {
+        let span = ctx.query().range();
+        let style = ctx.options().style.unwrap_or_default();
+
+        Some(
+            RuleDiagnostic::new(
+                rule_category!(),
+                span,
+                markup! {
+                    "Unexpected "{if style == Style::Block { Style::Inline } else { Style::Block }}" description style."
+                },
+            )
+            .note(markup! {
+                    "To stay consistent within the project, write the description "{style}" style."
+            }),
+        )
+    }
+}

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/block/invalid.graphql

@@ -0,0 +1,8 @@
+enum EnumValue {
+	"basic"
+	BASIC
+	"fluent"
+	FLUENT
+	"native"
+	NATIVE
+}

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/block/invalid.graphql.snap

@@ -0,0 +1,67 @@
+---
+source: crates/biome_graphql_analyze/tests/spec_tests.rs
+expression: invalid.graphql
+---
+# Input
+```graphql
+enum EnumValue {
+	"basic"
+	BASIC
+	"fluent"
+	FLUENT
+	"native"
+	NATIVE
+}
+
+```
+
+# Diagnostics
+```
+invalid.graphql:2:2 lint/nursery/useConsistentGraphqlDescriptions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected inline description style.
+  
+    1 │ enum EnumValue {
+  > 2 │ 	"basic"
+      │ 	^^^^^^^
+    3 │ 	BASIC
+    4 │ 	"fluent"
+  
+  i To stay consistent within the project, write the description block style.
+  
+
+```
+
+```
+invalid.graphql:4:2 lint/nursery/useConsistentGraphqlDescriptions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected inline description style.
+  
+    2 │ 	"basic"
+    3 │ 	BASIC
+  > 4 │ 	"fluent"
+      │ 	^^^^^^^^
+    5 │ 	FLUENT
+    6 │ 	"native"
+  
+  i To stay consistent within the project, write the description block style.
+  
+
+```
+
+```
+invalid.graphql:6:2 lint/nursery/useConsistentGraphqlDescriptions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected inline description style.
+  
+    4 │ 	"fluent"
+    5 │ 	FLUENT
+  > 6 │ 	"native"
+      │ 	^^^^^^^^
+    7 │ 	NATIVE
+    8 │ }
+  
+  i To stay consistent within the project, write the description block style.
+  
+
+```

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/block/valid.graphql

@@ -0,0 +1,15 @@
+# should not generate diagnostics
+enum EnumValue {
+	"""
+	basic
+	"""
+	BASIC
+	"""
+	fluent
+	"""
+	FLUENT
+	"""
+	native
+	"""
+	NATIVE
+}

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/block/valid.graphql.snap

@@ -0,0 +1,23 @@
+---
+source: crates/biome_graphql_analyze/tests/spec_tests.rs
+expression: valid.graphql
+---
+# Input
+```graphql
+# should not generate diagnostics
+enum EnumValue {
+	"""
+	basic
+	"""
+	BASIC
+	"""
+	fluent
+	"""
+	FLUENT
+	"""
+	native
+	"""
+	NATIVE
+}
+
+```

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/inline/invalid.graphql

@@ -0,0 +1,14 @@
+enum EnumValue {
+	"""
+	basic
+	"""
+	BASIC
+	"""
+	fluent
+	"""
+	FLUENT
+	"""
+	native
+	"""
+	NATIVE
+}

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/inline/invalid.graphql.snap

@@ -0,0 +1,82 @@
+---
+source: crates/biome_graphql_analyze/tests/spec_tests.rs
+expression: invalid.graphql
+---
+# Input
+```graphql
+enum EnumValue {
+	"""
+	basic
+	"""
+	BASIC
+	"""
+	fluent
+	"""
+	FLUENT
+	"""
+	native
+	"""
+	NATIVE
+}
+
+```
+
+# Diagnostics
+```
+invalid.graphql:2:2 lint/nursery/useConsistentGraphqlDescriptions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected block description style.
+
+    1 │ enum EnumValue {
+  > 2 │ 	"""
+      │ 	^^^
+  > 3 │ 	basic
+  > 4 │ 	"""
+      │ 	^^^
+    5 │ 	BASIC
+    6 │ 	"""
+
+  i To stay consistent within the project, write the description inline style.
+
+
+```
+
+```
+invalid.graphql:6:2 lint/nursery/useConsistentGraphqlDescriptions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected block description style.
+
+     4 │ 	"""
+     5 │ 	BASIC
+   > 6 │ 	"""
+       │ 	^^^
+   > 7 │ 	fluent
+   > 8 │ 	"""
+       │ 	^^^
+     9 │ 	FLUENT
+    10 │ 	"""
+
+  i To stay consistent within the project, write the description inline style.
+
+
+```
+
+```
+invalid.graphql:10:2 lint/nursery/useConsistentGraphqlDescriptions ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Unexpected block description style.
+
+     8 │ 	"""
+     9 │ 	FLUENT
+  > 10 │ 	"""
+       │ 	^^^
+  > 11 │ 	native
+  > 12 │ 	"""
+       │ 	^^^
+    13 │ 	NATIVE
+    14 │ }
+
+  i To stay consistent within the project, write the description inline style.
+
+
+```

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/inline/invalid.options.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "../../../../../../../packages/@biomejs/biome/configuration_schema.json",
+  "linter": {
+    "rules": {
+      "nursery": {
+        "useConsistentGraphqlDescriptions": {
+          "level": "error",
+          "options": {
+            "style": "inline"
+          }
+        }
+      }
+    }
+  }
+}

crates/biome_graphql_analyze/tests/specs/nursery/useConsistentGraphqlDescriptions/inline/valid.graphql

@@ -0,0 +1,9 @@
+# should not generate diagnostics
+enum EnumValue {
+	"basic"
+	BASIC
+	"fluent"
+	FLUENT
+	"native"
+	NATIVE
+}