feat(compiler, parser): support executable document descriptions

Support for parsing and serializing descriptions on:
- (longhand) operation definitions
- fragment definitions
- variable definitions

As described by the latest GraphQL spec draft: graphql/graphql-spec#1170

Adding a description on a query shorthand (bare braced selection set) raises a
parse error.

This is a breaking change for apollo-compiler due to the addition of new fields:
- `apollo_compiler::ast::OperationDefinition::description`
- `apollo_compiler::ast::FragmentDefinition::description`
- `apollo_compiler::ast::VariableDefinition::description`
- `apollo_compiler::executable::Operation::description`
- `apollo_compiler::executable::Fragment::description`

For most users, adding `description: None` anywhere they create one of these
structures is good enough.

Author: goto-bus-stop

crates/apollo-compiler/src/ast/from_cst.rs

@@ -125,6 +125,7 @@ impl Convert for cst::OperationDefinition {
             ast::OperationType::Query
         };
         Some(Self::Target {
+            description: self.description().convert(file_id)?,
             operation_type,
             name: self.name().convert(file_id)?,
             variables: collect_opt(file_id, self.variable_definitions(), |x| {
@@ -147,6 +148,7 @@ impl Convert for cst::FragmentDefinition {
 
     fn convert(&self, file_id: FileId) -> Option<Self::Target> {
         Some(Self::Target {
+            description: self.description().convert(file_id)?,
             name: self.fragment_name()?.name()?.convert(file_id)?,
             type_condition: self.type_condition()?.convert(file_id)?,
             directives: ast::DirectiveList(collect_opt(file_id, self.directives(), |x| {
@@ -530,6 +532,7 @@ impl Convert for cst::VariableDefinition {
         };
         let ty = &self.ty()?;
         Some(Self::Target {
+            description: self.description().convert(file_id)?,
             name: self.variable()?.name()?.convert(file_id)?,
             ty: with_location(file_id, ty.syntax(), ty.convert(file_id)?),
             default_value,

crates/apollo-compiler/src/ast/mod.rs

@@ -116,6 +116,7 @@ pub enum Definition {
 /// [_OperationDefinition_](https://spec.graphql.org/draft/#OperationDefinition).
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct OperationDefinition {
+    pub description: Option<Node<str>>,
     pub operation_type: OperationType,
     pub name: Option<Name>,
     pub variables: Vec<Node<VariableDefinition>>,
@@ -127,6 +128,7 @@ pub struct OperationDefinition {
 /// [_FragmentDefinition_](https://spec.graphql.org/draft/#FragmentDefinition).
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct FragmentDefinition {
+    pub description: Option<Node<str>>,
     pub name: Name,
     pub type_condition: NamedType,
     pub directives: DirectiveList,
@@ -335,6 +337,7 @@ pub enum DirectiveLocation {
 /// in an [`OperationDefinition`].
 #[derive(Clone, Debug, Eq, PartialEq, Hash)]
 pub struct VariableDefinition {
+    pub description: Option<Node<str>>,
     pub name: Name,
     pub ty: Node<Type>,
     pub default_value: Option<Node<Value>>,

crates/apollo-compiler/src/ast/serialize.rs

@@ -194,6 +194,7 @@ impl OperationDefinition {
     fn serialize_impl(&self, state: &mut State) -> fmt::Result {
         // Deconstruct to get a warning if we forget to serialize something
         let Self {
+            description,
             operation_type,
             name,
             variables,
@@ -208,6 +209,7 @@ impl OperationDefinition {
             && variables.is_empty()
             && directives.is_empty();
         if !shorthand {
+            serialize_description(state, description)?;
             state.write(operation_type.name())?;
             if let Some(name) = &name {
                 state.write(" ")?;
@@ -230,11 +232,13 @@ impl OperationDefinition {
 impl FragmentDefinition {
     fn serialize_impl(&self, state: &mut State) -> fmt::Result {
         let Self {
+            description,
             name,
             type_condition,
             directives,
             selection_set,
         } = self;
+        serialize_description(state, description)?;
         display!(state, "fragment {} on {}", name, type_condition)?;
         directives.serialize_impl(state)?;
         state.write(" ")?;
@@ -581,11 +585,13 @@ impl Directive {
 impl VariableDefinition {
     fn serialize_impl(&self, state: &mut State) -> fmt::Result {
         let Self {
+            description,
             name,
             ty,
             default_value,
             directives,
         } = self;
+        serialize_description(state, description)?;
         state.write("$")?;
         state.write(name)?;
         state.write(": ")?;

crates/apollo-compiler/src/executable/from_ast.rs

@@ -140,6 +140,7 @@ impl Operation {
         let mut selection_set = SelectionSet::new(ty);
         selection_set.extend_from_ast(schema, errors, &ast.selection_set);
         Some(Self {
+            description: ast.description.clone(),
             operation_type: ast.operation_type,
             name: ast.name.clone(),
             variables: ast.variables.clone(),
@@ -170,6 +171,7 @@ impl Fragment {
         let mut selection_set = SelectionSet::new(ast.type_condition.clone());
         selection_set.extend_from_ast(schema, errors, &ast.selection_set);
         Some(Self {
+            description: ast.description.clone(),
             name: ast.name.clone(),
             directives: ast.directives.clone(),
             selection_set,

crates/apollo-compiler/src/executable/mod.rs

@@ -123,6 +123,7 @@ pub struct FieldSet {
 /// annotated with type information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Operation {
+    pub description: Option<Node<str>>,
     pub operation_type: OperationType,
     pub name: Option<Name>,
     pub variables: Vec<Node<VariableDefinition>>,
@@ -134,6 +135,7 @@ pub struct Operation {
 /// annotated with type information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Fragment {
+    pub description: Option<Node<str>>,
     pub name: Name,
     pub directives: DirectiveList,
     pub selection_set: SelectionSet,

crates/apollo-compiler/src/executable/serialize.rs

@@ -28,6 +28,7 @@ impl ExecutableDocument {
 impl Operation {
     fn to_ast(&self, location: Option<SourceSpan>) -> ast::Definition {
         let def = ast::OperationDefinition {
+            description: self.description.clone(),
             operation_type: self.operation_type,
             name: self.name.clone(),
             variables: self.variables.clone(),
@@ -45,6 +46,7 @@ impl Operation {
 impl Fragment {
     fn to_ast(&self, location: Option<SourceSpan>) -> ast::Definition {
         let def = ast::FragmentDefinition {
+            description: self.description.clone(),
             name: self.name.clone(),
             type_condition: self.selection_set.ty.clone(),
             directives: self.directives.clone(),

crates/apollo-compiler/test_data/diagnostics/0125_query_shorthand_description.graphql

@@ -0,0 +1,14 @@
+"Get all our time machine models."
+{
+  timeMachines {
+    model
+  }
+}
+
+type TimeMachine {
+  id: ID!
+  model: String
+}
+type Query {
+  timeMachines: [TimeMachine]
+}

crates/apollo-compiler/test_data/ok/0001_annonymous_operation_definition.txt

@@ -98,6 +98,7 @@ ExecutableDocument {
     operations: OperationMap {
         anonymous: Some(
             1..31 @3 Operation {
+                description: None,
                 operation_type: Query,
                 name: None,
                 variables: [],

crates/apollo-compiler/test_data/ok/0002_multiple_named_operation_definitions.txt

@@ -133,6 +133,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "getCatName": 0..41 @4 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "getCatName",
@@ -189,6 +190,7 @@ ExecutableDocument {
                 },
             },
             "getOwnerName": 43..106 @4 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "getOwnerName",

crates/apollo-compiler/test_data/ok/0010_operation_with_defined_fields.txt

@@ -252,6 +252,7 @@ ExecutableDocument {
         anonymous: None,
         named: {
             "getProduct": 0..68 @12 Operation {
+                description: None,
                 operation_type: Query,
                 name: Some(
                     "getProduct",