Add support for descriptions on executable documents (GraphQL September 2025)

[DaleSeo]

Summary

Implements support for descriptions on executable documents as specified in the GraphQL September 2025 spec.

This feature allows descriptions (documentation strings) to be added to:

• Operations (query, mutation, subscription)
• Fragments
• Variable definitions

Implements graphql/graphql-spec#1170

Reference implementation: graphql/graphql-js#4430

Motivation

Descriptions are a core feature of GraphQL for documenting schemas. This extends that capability to executable documents, enabling:

• Better self-documenting queries and fragments
• Improved tooling and IDE support
• Enhanced code generation capabilities
• Better integration with AI-powered tools (e.g., Apollo MCP Server)

Descriptions remain non-semantic - they do not affect execution, validation, or response behavior.

Example Usage

"""
Request the current status of a time machine and its operator.
"""
query GetTimeMachineStatus(
  "The unique serial number of the time machine to inspect."
  $machineId: ID!

  """
  The year to check the status for.
  **Warning:** certain years may trigger an anomaly in the space-time continuum.
  """
  $year: Int
) {
  timeMachine(id: $machineId) {
    ...TimeMachineDetails
    operator {
      name
      licenseLevel
    }
    status(year: $year)
  }
}

"Time machine details."
fragment TimeMachineDetails on TimeMachine {
  id
  model
  lastMaintenance
}

Changes

• Updated graphql.ungram to add optional Description to executable definitions
• Updated parser grammar for operations, fragments, and variables
• Added error handling for invalid usage (descriptions on shorthand queries)
• Regenerated CST nodes via cargo xtask codegen
• Updated all spec references from October 2021 to September 2025

No breaking changes. This is a purely additive feature:

• Descriptions are optional on all executable definitions
• Existing documents without descriptions continue to work unchanged
• Descriptions are non-semantic (don't affect validation or execution)

Tests

• Added test for operations with descriptions
• Added test for error case (shorthand queries with descriptions)
• Updated snapshot tests

[lrlna]

Closing as a duplicate of #974