feat: implement description parsing for executables

Author: DaleSeo

crates/apollo-parser/src/parser/grammar/fragment.rs

@@ -1,3 +1,4 @@
+use crate::parser::grammar::description;
 use crate::parser::grammar::directive;
 use crate::parser::grammar::name;
 use crate::parser::grammar::selection;
@@ -9,12 +10,18 @@ use crate::TokenKind;
 use crate::S;
 use crate::T;
 
-/// See: https://spec.graphql.org/October2021/#FragmentDefinition
+/// See: https://spec.graphql.org/September2025/#sec-Language.Fragments
 ///
 /// *FragmentDefinition*:
-///     **fragment** FragmentName TypeCondition Directives? SelectionSet
+///     Description? **fragment** FragmentName TypeCondition Directives? SelectionSet
 pub(crate) fn fragment_definition(p: &mut Parser) {
     let _g = p.start_node(SyntaxKind::FRAGMENT_DEFINITION);
+
+    // Check for optional description
+    if let Some(TokenKind::StringValue) = p.peek() {
+        description::description(p);
+    }
+
     p.bump(SyntaxKind::fragment_KW);
 
     fragment_name(p);
@@ -30,7 +37,7 @@ pub(crate) fn fragment_definition(p: &mut Parser) {
     }
 }
 
-/// See: https://spec.graphql.org/October2021/#FragmentName
+/// See: https://spec.graphql.org/September2025/#sec-Language.Fragments
 ///
 /// *FragmentName*:
 ///     Name *but not* **on**
@@ -47,7 +54,7 @@ pub(crate) fn fragment_name(p: &mut Parser) {
     }
 }
 
-/// See: https://spec.graphql.org/October2021/#TypeCondition
+/// See: https://spec.graphql.org/September2025/#sec-Language.Fragments
 ///
 /// *TypeCondition*:
 ///     **on** NamedType
@@ -71,7 +78,7 @@ pub(crate) fn type_condition(p: &mut Parser) {
     }
 }
 
-/// See: https://spec.graphql.org/October2021/#InlineFragment
+/// See: https://spec.graphql.org/September2025/#sec-Language.Fragments
 ///
 /// *InlineFragment*:
 ///     **...** TypeCondition? Directives? SelectionSet
@@ -93,7 +100,7 @@ pub(crate) fn inline_fragment(p: &mut Parser) {
     }
 }
 
-/// See: https://spec.graphql.org/October2021/#FragmentSpread
+/// See: https://spec.graphql.org/September2025/#sec-Language.Fragments
 ///
 /// *FragmentSpread*:
 ///     **...** FragmentName Directives?

crates/apollo-parser/src/parser/grammar/operation.rs

@@ -1,3 +1,4 @@
+use crate::parser::grammar::description;
 use crate::parser::grammar::directive;
 use crate::parser::grammar::name;
 use crate::parser::grammar::selection;
@@ -8,13 +9,43 @@ use crate::SyntaxKind;
 use crate::TokenKind;
 use crate::T;
 
-/// See: https://spec.graphql.org/October2021/#OperationDefinition
+/// See: https://spec.graphql.org/September2025/#sec-Language.Operations
 ///
 /// *OperationDefinition*:
-///    OperationType Name? VariableDefinitions? Directives? SelectionSet
+///    Description? OperationType Name? VariableDefinitions? Directives? SelectionSet
 ///    SelectionSet
 pub(crate) fn operation_definition(p: &mut Parser) {
     match p.peek() {
+        Some(TokenKind::StringValue) => {
+            // Description found - must be full operation definition, not shorthand
+            let _g = p.start_node(SyntaxKind::OPERATION_DEFINITION);
+
+            description::description(p);
+
+            // After description, we must have an operation type
+            if let Some(TokenKind::Name) = p.peek() {
+                operation_type(p);
+            } else {
+                return p.err_and_pop("expected an Operation Type after description");
+            }
+
+            if let Some(TokenKind::Name) = p.peek() {
+                name::name(p);
+            }
+
+            if let Some(T!['(']) = p.peek() {
+                variable::variable_definitions(p)
+            }
+
+            if let Some(T![@]) = p.peek() {
+                directive::directives(p, Constness::NotConst);
+            }
+
+            match p.peek() {
+                Some(T!['{']) => selection::selection_set(p),
+                _ => p.err_and_pop("expected a Selection Set"),
+            }
+        }
         Some(TokenKind::Name) => {
             let _g = p.start_node(SyntaxKind::OPERATION_DEFINITION);
 
@@ -46,7 +77,7 @@ pub(crate) fn operation_definition(p: &mut Parser) {
     }
 }
 
-/// See: https://spec.graphql.org/October2021/#OperationType
+/// See: https://spec.graphql.org/September2025/#sec-Language.Operations
 ///
 /// *OperationType*: one of
 ///    **query**    **mutation**    **subscription**
@@ -66,15 +97,25 @@ pub(crate) fn operation_type(p: &mut Parser) {
 mod test {
     use crate::Parser;
 
-    // NOTE @lrlna: related PR to the spec to avoid this issue:
-    // https://github.com/graphql/graphql-spec/pull/892
+    // NOTE @lrlna: Descriptions on operations are now supported in September 2025 spec
+    // https://github.com/graphql/graphql-spec/pull/1170
     #[test]
-    fn it_continues_parsing_when_operation_definition_starts_with_description() {
-        let input = "\"description\"{}";
+    fn it_parses_operation_definition_with_description() {
+        let input = "\"A test query\" query Test { field }";
         let parser = Parser::new(input);
         let cst = parser.parse();
 
-        assert_eq!(cst.errors().len(), 2);
+        assert_eq!(cst.errors().len(), 0);
         assert_eq!(cst.document().definitions().count(), 1);
     }
+
+    #[test]
+    fn it_errors_on_shorthand_query_with_description() {
+        let input = "\"description\"{}";
+        let parser = Parser::new(input);
+        let cst = parser.parse();
+
+        // Should error because descriptions are not allowed on shorthand queries
+        assert!(cst.errors().len() > 0);
+    }
 }

crates/apollo-parser/src/parser/grammar/variable.rs

@@ -1,3 +1,4 @@
+use crate::parser::grammar::description;
 use crate::parser::grammar::directive;
 use crate::parser::grammar::name;
 use crate::parser::grammar::ty;
@@ -9,30 +10,44 @@ use crate::TokenKind;
 use crate::S;
 use crate::T;
 
-/// See: https://spec.graphql.org/October2021/#VariableDefinitions
+/// See: https://spec.graphql.org/September2025/#sec-Language.Variables
 ///
 /// *VariableDefinitions*:
 ///     **(** VariableDefinition* **)**
 pub(crate) fn variable_definitions(p: &mut Parser) {
     let _g = p.start_node(SyntaxKind::VARIABLE_DEFINITIONS);
     p.bump(S!['(']);
 
-    if let Some(T![$]) = p.peek() {
+    // Variable definitions can start with a description (string) or $ (variable)
+    if let Some(TokenKind::StringValue | T![$]) = p.peek() {
         variable_definition(p);
     } else {
         p.err("expected a Variable Definition")
     }
-    p.peek_while_kind(T![$], variable_definition);
+
+    // Continue parsing while we see descriptions or variables
+    loop {
+        match p.peek() {
+            Some(TokenKind::StringValue | T![$]) => variable_definition(p),
+            _ => break,
+        }
+    }
 
     p.expect(T![')'], S![')']);
 }
 
-/// See: https://spec.graphql.org/October2021/#VariableDefinition
+/// See: https://spec.graphql.org/September2025/#sec-Language.Variables
 ///
 /// *VariableDefinition*:
-///     Variable **:** Type DefaultValue? Directives[Const]?
+///     Description? Variable **:** Type DefaultValue? Directives[Const]?
 pub(crate) fn variable_definition(p: &mut Parser) {
     let _guard = p.start_node(SyntaxKind::VARIABLE_DEFINITION);
+
+    // Check for optional description
+    if let Some(TokenKind::StringValue) = p.peek() {
+        description::description(p);
+    }
+
     variable(p);
 
     if let Some(T![:]) = p.peek() {
@@ -53,7 +68,7 @@ pub(crate) fn variable_definition(p: &mut Parser) {
     }
 }
 
-/// See: https://spec.graphql.org/October2021/#Variable
+/// See: https://spec.graphql.org/September2025/#sec-Language.Variables
 ///
 /// *Variable*:
 ///     **$** Name