feat: parse descriptions in executable documents (#1182)

Author: obmarg

cynic-parser/ast-generator/domain/executable.graphql

@@ -4,10 +4,11 @@
 union ExecutableDefinition
   @file(name: "definition")
   @variant(names: ["Operation", "Fragment"]) =
-    OperationDefinition
+  | OperationDefinition
   | FragmentDefinition
 
 type OperationDefinition @file(name: "operation") {
+  description: Description
   operation_type: OperationType! @spanned(nullable: true)
   name: String @spanned
   variable_definitions: [VariableDefinition]
@@ -16,6 +17,7 @@ type OperationDefinition @file(name: "operation") {
 }
 
 type FragmentDefinition @file(name: "fragment") {
+  description: Description
   name: String! @spanned
   type_condition: String! @spanned
   directives: [Directive]
@@ -25,7 +27,7 @@ type FragmentDefinition @file(name: "fragment") {
 union Selection
   @file(name: "selections")
   @variant(names: ["Field", "InlineFragment", "FragmentSpread"]) =
-    FieldSelection
+  | FieldSelection
   | InlineFragment
   | FragmentSpread
 
@@ -59,12 +61,20 @@ type Argument @file(name: "argument") {
 }
 
 type VariableDefinition @file(name: "variable") {
+  description: Description
   name: String! @spanned
   ty: Type!
   default_value: ConstValue
   directives: [Directive]
 }
 
+type Description @file(name: "descriptions") {
+  literal: StringLiteral!
+  span: Span!
+}
+
+scalar Span @inline
+
 # OperationType is marked as @inline which means it just gets
 # stored inside records instead of getting IDs & records.
 scalar OperationType @inline
@@ -78,3 +88,5 @@ scalar ConstValue @file(name: "value")
 # String is built in, but easier to implement stuff if its just in the .graphql file
 # It is also special cased a bit in the rust code
 scalar String
+
+scalar StringLiteral @file(name: "strings")

cynic-parser/src/common/mod.rs

@@ -1,10 +1,12 @@
 mod id_range;
 mod int_value;
+mod string_literal;
 mod strings;
 mod types;
 
 pub use id_range::{IdOperations, IdRange, IdRangeIter};
 pub use int_value::IntValue;
+pub use string_literal::{StringLiteral, StringLiteralKind};
 pub use strings::MalformedStringError;
 pub use types::*;
 

cynic-parser/src/common/string_literal.rs

@@ -0,0 +1,62 @@
+use std::{borrow::Cow, fmt};
+
+use crate::common::trim_block_string_whitespace;
+
+#[derive(Clone, Copy, Debug)]
+pub struct StringLiteral<'a>(StringLiteralInner<'a>);
+
+impl<'a> StringLiteral<'a> {
+    pub(crate) fn new_string(inner: &'a str) -> Self {
+        Self(StringLiteralInner::String(inner))
+    }
+
+    pub(crate) fn new_block(inner: &'a str) -> Self {
+        Self(StringLiteralInner::BlockString(inner))
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+enum StringLiteralInner<'a> {
+    String(&'a str),
+    BlockString(&'a str),
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum StringLiteralKind {
+    String,
+    Block,
+}
+
+impl<'a> StringLiteral<'a> {
+    pub fn to_cow(&self) -> Cow<'a, str> {
+        match self.0 {
+            StringLiteralInner::String(string) => Cow::Borrowed(string),
+            StringLiteralInner::BlockString(string) => {
+                // This is more intense - we need to unquote the string
+                //
+                // TODO: Look into recording what work needs done at parse time
+                Cow::Owned(trim_block_string_whitespace(string))
+            }
+        }
+    }
+
+    pub fn raw_untrimmed_str(&self) -> &'a str {
+        match self.0 {
+            StringLiteralInner::String(string) => string,
+            StringLiteralInner::BlockString(string) => string,
+        }
+    }
+
+    pub fn kind(&self) -> StringLiteralKind {
+        match self.0 {
+            StringLiteralInner::String(_) => StringLiteralKind::String,
+            StringLiteralInner::BlockString(_) => StringLiteralKind::Block,
+        }
+    }
+}
+
+impl fmt::Display for StringLiteral<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.to_cow().as_ref())
+    }
+}

cynic-parser/src/executable/generated.rs

@@ -21,6 +21,7 @@ mod prelude {
 
 pub mod argument;
 pub mod definition;
+pub mod descriptions;
 pub mod directive;
 pub mod fragment;
 pub mod operation;
@@ -33,3 +34,7 @@ mod value {
 
     pub use crate::values::{ConstValue, Value};
 }
+
+mod strings {
+    pub(super) use crate::common::StringLiteral;
+}

cynic-parser/src/executable/generated/descriptions.rs

@@ -0,0 +1,57 @@
+use super::prelude::*;
+use super::{
+    ExecutableId,
+    ids::{DescriptionId, StringLiteralId},
+    strings::StringLiteral,
+};
+#[allow(unused_imports)]
+use std::fmt::{self, Write};
+
+pub struct DescriptionRecord {
+    pub literal: StringLiteralId,
+    pub span: Span,
+}
+
+#[derive(Clone, Copy)]
+pub struct Description<'a>(pub(in super::super) ReadContext<'a, DescriptionId>);
+
+impl<'a> Description<'a> {
+    pub fn literal(&self) -> StringLiteral<'a> {
+        let document = self.0.document;
+        document.read(document.lookup(self.0.id).literal)
+    }
+    pub fn span(&self) -> Span {
+        let document = self.0.document;
+        document.lookup(self.0.id).span
+    }
+}
+
+impl Description<'_> {
+    pub fn id(&self) -> DescriptionId {
+        self.0.id
+    }
+}
+
+impl fmt::Debug for Description<'_> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Description")
+            .field("literal", &self.literal())
+            .field("span", &self.span())
+            .finish()
+    }
+}
+
+impl ExecutableId for DescriptionId {
+    type Reader<'a> = Description<'a>;
+    fn read(self, document: &ExecutableDocument) -> Self::Reader<'_> {
+        Description(ReadContext { id: self, document })
+    }
+}
+
+impl IdReader for Description<'_> {
+    type Id = DescriptionId;
+    type Reader<'a> = Description<'a>;
+    fn new(id: Self::Id, document: &'_ ExecutableDocument) -> Self::Reader<'_> {
+        document.read(id)
+    }
+}

cynic-parser/src/executable/generated/fragment.rs

@@ -1,14 +1,16 @@
 use super::prelude::*;
 use super::{
     ExecutableId,
+    descriptions::Description,
     directive::Directive,
-    ids::{DirectiveId, FragmentDefinitionId, SelectionId},
+    ids::{DescriptionId, DirectiveId, FragmentDefinitionId, SelectionId},
     selections::Selection,
 };
 #[allow(unused_imports)]
 use std::fmt::{self, Write};
 
 pub struct FragmentDefinitionRecord {
+    pub description: Option<DescriptionId>,
     pub name: StringId,
     pub name_span: Span,
     pub type_condition: StringId,
@@ -22,6 +24,13 @@ pub struct FragmentDefinitionRecord {
 pub struct FragmentDefinition<'a>(pub(in super::super) ReadContext<'a, FragmentDefinitionId>);
 
 impl<'a> FragmentDefinition<'a> {
+    pub fn description(&self) -> Option<Description<'a>> {
+        let document = self.0.document;
+        document
+            .lookup(self.0.id)
+            .description
+            .map(|id| document.read(id))
+    }
     pub fn name(&self) -> &'a str {
         let document = &self.0.document;
         document.lookup(document.lookup(self.0.id).name)
@@ -61,6 +70,7 @@ impl FragmentDefinition<'_> {
 impl fmt::Debug for FragmentDefinition<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("FragmentDefinition")
+            .field("description", &self.description())
             .field("name", &self.name())
             .field("type_condition", &self.type_condition())
             .field("directives", &self.directives())

cynic-parser/src/executable/generated/operation.rs

@@ -1,15 +1,17 @@
 use super::prelude::*;
 use super::{
     ExecutableId,
+    descriptions::Description,
     directive::Directive,
-    ids::{DirectiveId, OperationDefinitionId, SelectionId, VariableDefinitionId},
+    ids::{DescriptionId, DirectiveId, OperationDefinitionId, SelectionId, VariableDefinitionId},
     selections::Selection,
     variable::VariableDefinition,
 };
 #[allow(unused_imports)]
 use std::fmt::{self, Write};
 
 pub struct OperationDefinitionRecord {
+    pub description: Option<DescriptionId>,
     pub operation_type: OperationType,
     pub operation_type_span: Option<Span>,
     pub name: Option<StringId>,
@@ -24,6 +26,13 @@ pub struct OperationDefinitionRecord {
 pub struct OperationDefinition<'a>(pub(in super::super) ReadContext<'a, OperationDefinitionId>);
 
 impl<'a> OperationDefinition<'a> {
+    pub fn description(&self) -> Option<Description<'a>> {
+        let document = self.0.document;
+        document
+            .lookup(self.0.id)
+            .description
+            .map(|id| document.read(id))
+    }
     pub fn operation_type(&self) -> OperationType {
         let document = self.0.document;
         document.lookup(self.0.id).operation_type
@@ -70,6 +79,7 @@ impl OperationDefinition<'_> {
 impl fmt::Debug for OperationDefinition<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("OperationDefinition")
+            .field("description", &self.description())
             .field("operation_type", &self.operation_type())
             .field("name", &self.name())
             .field("variable_definitions", &self.variable_definitions())

cynic-parser/src/executable/generated/variable.rs

@@ -1,15 +1,17 @@
 use super::prelude::*;
 use super::{
     ExecutableId,
+    descriptions::Description,
     directive::Directive,
-    ids::{ConstValueId, DirectiveId, TypeId, VariableDefinitionId},
+    ids::{ConstValueId, DescriptionId, DirectiveId, TypeId, VariableDefinitionId},
     types::Type,
     value::ConstValue,
 };
 #[allow(unused_imports)]
 use std::fmt::{self, Write};
 
 pub struct VariableDefinitionRecord {
+    pub description: Option<DescriptionId>,
     pub name: StringId,
     pub name_span: Span,
     pub ty: TypeId,
@@ -21,6 +23,13 @@ pub struct VariableDefinitionRecord {
 pub struct VariableDefinition<'a>(pub(in super::super) ReadContext<'a, VariableDefinitionId>);
 
 impl<'a> VariableDefinition<'a> {
+    pub fn description(&self) -> Option<Description<'a>> {
+        let document = self.0.document;
+        document
+            .lookup(self.0.id)
+            .description
+            .map(|id| document.read(id))
+    }
     pub fn name(&self) -> &'a str {
         let document = &self.0.document;
         document.lookup(document.lookup(self.0.id).name)
@@ -55,6 +64,7 @@ impl VariableDefinition<'_> {
 impl fmt::Debug for VariableDefinition<'_> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("VariableDefinition")
+            .field("description", &self.description())
             .field("name", &self.name())
             .field("ty", &self.ty())
             .field("default_value", &self.default_value())

cynic-parser/src/executable/ids.rs

@@ -62,6 +62,8 @@ make_id!(OperationDefinitionId, OperationDefinitionRecord, operations);
 
 make_id!(FragmentDefinitionId, FragmentDefinitionRecord, fragments);
 
+make_id!(DescriptionId, DescriptionRecord, descriptions);
+
 make_id!(SelectionId, SelectionRecord, selections);
 impl_id_range_ops!(SelectionId);
 
@@ -106,3 +108,9 @@ impl AstLookup<StringId> for ExecutableDocument {
         &self.strings[(index.0.get() - 1) as usize]
     }
 }
+
+#[derive(Clone, Copy)]
+pub enum StringLiteralId {
+    String(StringId),
+    Block(BlockStringLiteralId),
+}

cynic-parser/src/executable/mod.rs

@@ -8,6 +8,7 @@ pub mod writer;
 
 mod extensions;
 mod generated;
+mod string_literal;
 mod types;
 mod values;
 
@@ -17,6 +18,7 @@ pub use self::{
     generated::{
         argument::Argument,
         definition::ExecutableDefinition,
+        descriptions::Description,
         directive::Directive,
         fragment::FragmentDefinition,
         operation::OperationDefinition,
@@ -46,6 +48,7 @@ pub struct ExecutableDocument {
     directives: Vec<storage::DirectiveRecord>,
     arguments: Vec<storage::ArgumentRecord>,
     variables: Vec<storage::VariableDefinitionRecord>,
+    descriptions: Vec<storage::DescriptionRecord>,
 
     types: Vec<types::TypeRecord>,
 
@@ -105,6 +108,7 @@ pub mod storage {
         generated::{
             argument::ArgumentRecord,
             definition::ExecutableDefinitionRecord,
+            descriptions::DescriptionRecord,
             directive::DirectiveRecord,
             fragment::FragmentDefinitionRecord,
             operation::OperationDefinitionRecord,