feat: add description support for operations and fragments

Implements the GraphQL September 2025 specification feature that allows
descriptions on executable definitions (operations and fragments).

Changes:
- Add `description` field to Blueprint.Document.Operation struct
- Add `description` field to Blueprint.Document.Fragment.Named struct
- Add `description` field to Language.OperationDefinition struct
- Add `description` field to Language.Fragment struct
- Update parser to accept descriptions before operations and fragments
- Update Blueprint.Draft conversion to preserve descriptions
- Update SDL rendering to output descriptions for operations/fragments
- Add comprehensive tests for the new functionality

Specification: https://spec.graphql.org/September2025/#sec-Descriptions
Reference: RFC absinthe-graphql#1170

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jwaldrip

lib/absinthe/blueprint/document/fragment/named.ex

@@ -8,6 +8,7 @@ defmodule Absinthe.Blueprint.Document.Fragment.Named do
   defstruct [
     :name,
     :type_condition,
+    :description,
     selections: [],
     directives: [],
     source_location: nil,
@@ -22,6 +23,7 @@ defmodule Absinthe.Blueprint.Document.Fragment.Named do
           directives: [Blueprint.Directive.t()],
           errors: [Absinthe.Phase.Error.t()],
           name: String.t(),
+          description: nil | String.t(),
           selections: [Blueprint.Document.selection_t()],
           schema_node: nil | Absinthe.Type.t(),
           source_location: nil | Blueprint.SourceLocation.t(),

lib/absinthe/blueprint/document/operation.ex

@@ -7,6 +7,7 @@ defmodule Absinthe.Blueprint.Document.Operation do
   defstruct [
     :name,
     :type,
+    :description,
     current: false,
     selections: [],
     directives: [],
@@ -25,6 +26,7 @@ defmodule Absinthe.Blueprint.Document.Operation do
   @type t :: %__MODULE__{
           name: nil | String.t(),
           type: :query | :mutation | :subscription,
+          description: nil | String.t(),
           current: boolean,
           directives: [Blueprint.Directive.t()],
           selections: [Blueprint.Document.selection_t()],

lib/absinthe/language/fragment.ex

@@ -4,13 +4,15 @@ defmodule Absinthe.Language.Fragment do
   alias Absinthe.{Blueprint, Language}
 
   defstruct name: nil,
+            description: nil,
             type_condition: nil,
             directives: [],
             selection_set: nil,
             loc: %{line: nil}
 
   @type t :: %__MODULE__{
           name: String.t(),
+          description: nil | String.t(),
           type_condition: nil | Language.NamedType.t(),
           directives: [Language.Directive.t()],
           selection_set: Language.SelectionSet.t(),
@@ -21,6 +23,7 @@ defmodule Absinthe.Language.Fragment do
     def convert(node, doc) do
       %Blueprint.Document.Fragment.Named{
         name: node.name,
+        description: node.description,
         type_condition: Blueprint.Draft.convert(node.type_condition, doc),
         selections: Blueprint.Draft.convert(node.selection_set.selections, doc),
         directives: Blueprint.Draft.convert(node.directives, doc),

lib/absinthe/language/operation_definition.ex

@@ -5,6 +5,7 @@ defmodule Absinthe.Language.OperationDefinition do
 
   defstruct operation: nil,
             name: nil,
+            description: nil,
             variable_definitions: [],
             directives: [],
             selection_set: nil,
@@ -14,6 +15,7 @@ defmodule Absinthe.Language.OperationDefinition do
   @type t :: %__MODULE__{
           operation: :query | :mutation | :subscription,
           name: nil | String.t(),
+          description: nil | String.t(),
           variable_definitions: [Language.VariableDefinition.t()],
           directives: [Language.Directive.t()],
           selection_set: Language.SelectionSet.t(),
@@ -26,6 +28,7 @@ defmodule Absinthe.Language.OperationDefinition do
       %Blueprint.Document.Operation{
         name: node.name,
         type: node.operation,
+        description: node.description,
         directives: Absinthe.Blueprint.Draft.convert(node.directives, doc),
         variable_definitions: Blueprint.Draft.convert(node.variable_definitions, doc),
         selections: Blueprint.Draft.convert(node.selection_set.selections, doc),

lib/absinthe/language/render.ex

@@ -24,14 +24,17 @@ defmodule Absinthe.Language.Render do
   end
 
   defp render(%Absinthe.Language.OperationDefinition{} = op) do
-    if op.shorthand do
-      concat(operation_definition(op), block(render_list(op.selection_set.selections)))
-    else
-      glue(
-        concat([to_string(op.operation), operation_definition(op)]),
-        block(render_list(op.selection_set.selections))
-      )
-    end
+    doc =
+      if op.shorthand do
+        concat(operation_definition(op), block(render_list(op.selection_set.selections)))
+      else
+        glue(
+          concat([to_string(op.operation), operation_definition(op)]),
+          block(render_list(op.selection_set.selections))
+        )
+      end
+
+    description(doc, op.description)
   end
 
   defp render(%Absinthe.Language.Field{} = field) do
@@ -133,6 +136,7 @@ defmodule Absinthe.Language.Render do
       directives(fragment.directives)
     ])
     |> block(render_list(fragment.selection_set.selections))
+    |> description(fragment.description)
   end
 
   # Schema

src/absinthe_parser.yrl

@@ -31,7 +31,9 @@ Definitions -> Definition : ['$1'].
 Definitions -> Definition Definitions : ['$1'|'$2'].
 
 Definition -> OperationDefinition : '$1'.
+Definition -> DescriptionDefinition OperationDefinition : put_description('$2', '$1').
 Definition -> Fragment : '$1'.
+Definition -> DescriptionDefinition Fragment : put_description('$2', '$1').
 Definition -> TypeDefinition : '$1'.
 
 OperationType -> 'query' : '$1'.