feat(graphql_analyze): add useUniqueGraphqlOperationName (#8013)

Author: Jayllyz

.changeset/rich-memes-sleep.md

@@ -0,0 +1,37 @@
+---
+"@biomejs/biome": patch
+---
+
+Added the GraphQL nursery rule [`useUniqueGraphqlOperationName`](https://biomejs.dev/linter/rules/use-unique-graphql-operation-name). This rule ensures that all GraphQL operations within a document have unique names.
+
+**Invalid:**
+```graphql
+query user {
+  user {
+    id
+  }
+}
+
+query user {
+  user {
+    id
+    email
+  }
+}
+```
+
+**Valid:**
+```graphql
+query user {
+  user {
+    id
+  }
+}
+
+query userWithEmail {
+  user {
+    id
+    email
+  }
+}
+```

Cargo.lock

@@ -209,6 +209,7 @@ define_categories! {
     "lint/nursery/useQwikMethodUsage": "https://biomejs.dev/linter/rules/use-qwik-method-usage",
     "lint/nursery/useQwikValidLexicalScope": "https://biomejs.dev/linter/rules/use-qwik-valid-lexical-scope",
     "lint/nursery/useSortedClasses": "https://biomejs.dev/linter/rules/use-sorted-classes",
+    "lint/nursery/useUniqueGraphqlOperationName": "https://biomejs.dev/linter/rules/use-unique-graphql-operation-name",
     "lint/nursery/useVueDefineMacrosOrder": "https://biomejs.dev/linter/rules/use-vue-define-macros-order",
     "lint/nursery/useVueMultiWordComponentNames": "https://biomejs.dev/linter/rules/use-vue-multi-word-component-names",
     "lint/nursery/useVueValidVBind": "https://biomejs.dev/linter/rules/use-vue-valid-v-bind",

crates/biome_configuration/src/analyzer/linter/rules.rs

@@ -24,6 +24,7 @@ biome_rule_options       = { workspace = true }
 biome_string_case        = { workspace = true }
 biome_suppression        = { workspace = true }
 jiff                     = { workspace = true }
+rustc-hash               = { workspace = true }
 schemars                 = { workspace = true, optional = true }
 serde                    = { workspace = true, features = ["derive"] }
 

crates/biome_diagnostics_categories/src/categories.rs

@@ -6,4 +6,5 @@ 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_consistent_graphql_descriptions :: UseConsistentGraphqlDescriptions , self :: use_deprecated_date :: UseDeprecatedDate ,] } }
+pub mod use_unique_graphql_operation_name;
+declare_lint_group! { pub Nursery { name : "nursery" , rules : [self :: no_empty_source :: NoEmptySource , self :: use_consistent_graphql_descriptions :: UseConsistentGraphqlDescriptions , self :: use_deprecated_date :: UseDeprecatedDate , self :: use_unique_graphql_operation_name :: UseUniqueGraphqlOperationName ,] } }

crates/biome_graphql_analyze/Cargo.toml

@@ -0,0 +1,115 @@
+use biome_analyze::{
+    Ast, Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule,
+};
+use biome_console::markup;
+use biome_graphql_syntax::GraphqlRoot;
+use biome_rowan::{AstNode, TextRange, TokenText};
+use biome_rule_options::use_unique_graphql_operation_name::UseUniqueGraphqlOperationNameOptions;
+use rustc_hash::FxHashMap;
+
+declare_lint_rule! {
+    /// Enforce unique operation names across a GraphQL document.
+    ///
+    /// This rule ensures that all GraphQL operations (queries, mutations, subscriptions) have unique names.
+    /// Using unique operation names is essential for proper identification and reducing confusion.
+    ///
+    /// :::note
+    /// This rule currently does not work across multiple files.
+    /// :::
+    ///
+    /// ## Examples
+    ///
+    /// ### Invalid
+    ///
+    /// ```graphql,expect_diagnostic
+    /// query user {
+    ///   user {
+    ///     id
+    ///   }
+    /// }
+    ///
+    /// query user {
+    ///   me {
+    ///     id
+    ///   }
+    /// }
+    /// ```
+    ///
+    /// ### Valid
+    ///
+    /// ```graphql
+    /// query user {
+    ///   user {
+    ///     id
+    ///   }
+    /// }
+    ///
+    /// query me {
+    ///   me {
+    ///     id
+    ///   }
+    /// }
+    /// ```
+    ///
+    pub UseUniqueGraphqlOperationName {
+        version: "next",
+        name: "useUniqueGraphqlOperationName",
+        language: "graphql",
+        recommended: false,
+        sources: &[RuleSource::EslintGraphql("unique-operation-name").inspired()],
+    }
+}
+
+pub struct DuplicateOperationName {
+    name: TokenText,
+    text_range: TextRange,
+}
+
+impl Rule for UseUniqueGraphqlOperationName {
+    type Query = Ast<GraphqlRoot>;
+    type State = DuplicateOperationName;
+    type Signals = Box<[Self::State]>;
+    type Options = UseUniqueGraphqlOperationNameOptions;
+
+    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
+        let root = ctx.query();
+        let mut operation_names: FxHashMap<TokenText, TextRange> = FxHashMap::default();
+        let mut duplicates = vec![];
+
+        for definition in root.definitions() {
+            if let Some(operation) = definition.as_graphql_operation_definition()
+                && let Some(name_token) = operation.name()
+                && let Ok(token) = name_token.value_token()
+            {
+                let name = token.token_text_trimmed();
+                let text_range = operation.range();
+
+                if let Some(_existing_range) = operation_names.insert(name.clone(), text_range) {
+                    duplicates.push(DuplicateOperationName { name, text_range });
+                }
+            }
+        }
+
+        duplicates.into_boxed_slice()
+    }
+
+    fn diagnostic(_ctx: &RuleContext<Self>, state: &Self::State) -> Option<RuleDiagnostic> {
+        let DuplicateOperationName { name, text_range } = state;
+
+        Some(
+            RuleDiagnostic::new(
+                rule_category!(),
+                text_range,
+                markup! {
+                    "Operation named \""{ name.text() }"\" is already defined."
+                },
+            )
+            .note(markup! {
+                "GraphQL operation names must be unique to ensure proper identification."
+            })
+            .note(markup! {
+                "Rename the operation to have a unique name."
+            }),
+        )
+    }
+}

crates/biome_graphql_analyze/src/lint/nursery.rs

@@ -0,0 +1,29 @@
+query user {
+  user {
+    id
+  }
+}
+
+query user {
+  me {
+    id
+  }
+}
+
+mutation updateUser {
+  updateUser {
+    id
+  }
+}
+
+mutation updateUser {
+  updateProfile {
+    name
+  }
+}
+
+mutation updateUser {
+  updateSettings {
+    theme
+  }
+}

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

@@ -0,0 +1,109 @@
+---
+source: crates/biome_graphql_analyze/tests/spec_tests.rs
+expression: invalid.graphql
+---
+# Input
+```graphql
+query user {
+  user {
+    id
+  }
+}
+
+query user {
+  me {
+    id
+  }
+}
+
+mutation updateUser {
+  updateUser {
+    id
+  }
+}
+
+mutation updateUser {
+  updateProfile {
+    name
+  }
+}
+
+mutation updateUser {
+  updateSettings {
+    theme
+  }
+}
+
+```
+
+# Diagnostics
+```
+invalid.graphql:7:1 lint/nursery/useUniqueGraphqlOperationName ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Operation named "user" is already defined.
+  
+     5 │ }
+     6 │ 
+   > 7 │ query user {
+       │ ^^^^^^^^^^^^
+   > 8 │   me {
+   > 9 │     id
+  > 10 │   }
+  > 11 │ }
+       │ ^
+    12 │ 
+    13 │ mutation updateUser {
+  
+  i GraphQL operation names must be unique to ensure proper identification.
+  
+  i Rename the operation to have a unique name.
+  
+
+```
+
+```
+invalid.graphql:19:1 lint/nursery/useUniqueGraphqlOperationName ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Operation named "updateUser" is already defined.
+  
+    17 │ }
+    18 │ 
+  > 19 │ mutation updateUser {
+       │ ^^^^^^^^^^^^^^^^^^^^^
+  > 20 │   updateProfile {
+  > 21 │     name
+  > 22 │   }
+  > 23 │ }
+       │ ^
+    24 │ 
+    25 │ mutation updateUser {
+  
+  i GraphQL operation names must be unique to ensure proper identification.
+  
+  i Rename the operation to have a unique name.
+  
+
+```
+
+```
+invalid.graphql:25:1 lint/nursery/useUniqueGraphqlOperationName ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Operation named "updateUser" is already defined.
+  
+    23 │ }
+    24 │ 
+  > 25 │ mutation updateUser {
+       │ ^^^^^^^^^^^^^^^^^^^^^
+  > 26 │   updateSettings {
+  > 27 │     theme
+  > 28 │   }
+  > 29 │ }
+       │ ^
+    30 │ 
+  
+  i GraphQL operation names must be unique to ensure proper identification.
+  
+  i Rename the operation to have a unique name.
+  
+
+```

crates/biome_graphql_analyze/tests/specs/nursery/useUniqueGraphqlOperationName/invalid.graphql

@@ -0,0 +1,33 @@
+# should not generate diagnostics
+
+query user {
+  user {
+    id
+  }
+}
+
+query me {
+  me {
+    id
+  }
+}
+
+mutation updateUser {
+  updateUser {
+    id
+  }
+}
+
+mutation updateProfile {
+  updateProfile {
+    name
+  }
+}
+
+query {
+  field
+}
+
+subscription {
+  newMessage
+}