Strip Common Indentation from BlockString Descriptions

Multi-line descriptions need to have their common indentation level
 (which results from indentation of that part of the schema, rather than
 being intentional for the description text) removed to ensure the
 descriptions use the correct value, are formatted correctly etc

This is to meet the condition documented in the GraphQL spec:

https://graphql.github.io/graphql-spec/June2018/#sec-String-Value

> Since block strings represent freeform text often used in indented
>  positions, the string value semantics of a block string excludes
>  uniform indentation and blank initial and trailing lines via
>  BlockStringValue().

Author: dackroyd

internal/common/blockstring.go

@@ -0,0 +1,103 @@
+// MIT License
+//
+// Copyright (c) 2019 GraphQL Contributors
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// This implementation has been adapted from the graphql-js reference implementation
+// https://github.com/graphql/graphql-js/blob/5eb7c4ded7ceb83ac742149cbe0dae07a8af9a30/src/language/blockString.js
+// which is released under the MIT License above.
+
+package common
+
+import (
+	"strings"
+)
+
+// Produces the value of a block string from its parsed raw value, similar to
+// CoffeeScript's block string, Python's docstring trim or Ruby's strip_heredoc.
+//
+// This implements the GraphQL spec's BlockStringValue() static algorithm.
+func blockString(raw string) string {
+	lines := strings.Split(raw, "\n")
+
+	// Remove common indentation from all lines except the first (which has none)
+	ind := blockStringIndentation(lines)
+	if ind > 0 {
+		for i := 1; i < len(lines); i++ {
+			l := lines[i]
+			if len(l) < ind {
+				lines[i] = ""
+				continue
+			}
+			lines[i] = l[ind:]
+		}
+	}
+
+	// Remove leading and trailing blank lines
+	trimStart := 0
+	for i := 0; i < len(lines) && isBlank(lines[i]); i++ {
+		trimStart++
+	}
+	lines = lines[trimStart:]
+	trimEnd := 0
+	for i := len(lines) - 1; i > 0 && isBlank(lines[i]); i-- {
+		trimEnd++
+	}
+	lines = lines[:len(lines)-trimEnd]
+
+	return strings.Join(lines, "\n")
+}
+
+func blockStringIndentation(lines []string) int {
+	var commonIndent *int
+	for i := 1; i < len(lines); i++ {
+		l := lines[i]
+		indent := leadingWhitespace(l)
+		if indent == len(l) {
+			// don't consider blank/empty lines
+			continue
+		}
+		if indent == 0 {
+			return 0
+		}
+		if commonIndent == nil || indent < *commonIndent {
+			commonIndent = &indent
+		}
+	}
+	if commonIndent == nil {
+		return 0
+	}
+	return *commonIndent
+}
+
+func isBlank(s string) bool {
+	return len(s) == 0 || leadingWhitespace(s) == len(s)
+}
+
+func leadingWhitespace(s string) int {
+	i := 0
+	for _, r := range s {
+		if r != '\t' && r != ' ' {
+			break
+		}
+		i++
+	}
+	return i
+}

internal/common/lexer.go

@@ -184,8 +184,7 @@ func (l *Lexer) consumeTripleQuoteComment() string {
 	}
 	val := buf.String()
 	val = val[:len(val)-numQuotes]
-	val = strings.TrimSpace(val)
-	return val
+	return blockString(val)
 }
 
 func (l *Lexer) consumeStringComment() string {

internal/schema/schema_test.go

@@ -73,7 +73,7 @@ func TestParse(t *testing.T) {
 			},
 		},
 		{
-			name: "Parses type with multi-line description string",
+			name: "Parses type with simple multi-line 'BlockString' description",
 			sdl: `
 			"""
 			Multi-line description.
@@ -95,7 +95,120 @@ func TestParse(t *testing.T) {
 			},
 		},
 		{
-			name: "Parses type with multi-line description and ignores comments",
+			name: "Parses type with empty multi-line 'BlockString' description",
+			sdl: `
+			"""
+			"""
+			type Type {
+				field: String
+			}`,
+			useStringDescriptions: true,
+			validateSchema: func(s *schema.Schema) error {
+				const typeName = "Type"
+				typ, ok := s.Types[typeName].(*schema.Object)
+				if !ok {
+					return fmt.Errorf("type %q not found", typeName)
+				}
+				if want, have := "", typ.Description(); want != have {
+					return fmt.Errorf("invalid description: want %q, have %q", want, have)
+				}
+				return nil
+			},
+		},
+		{
+			name: "Parses type with multi-line 'BlockString' description",
+			sdl: `
+			"""
+			First line of the description.
+
+			Second line of the description.
+
+				query {
+					code {
+						example
+					}
+				}
+
+			Notes:
+
+			 * First note
+			 * Second note
+			"""
+			type Type {
+				field: String
+			}`,
+			useStringDescriptions: true,
+			validateSchema: func(s *schema.Schema) error {
+				const typeName = "Type"
+				typ, ok := s.Types[typeName].(*schema.Object)
+				if !ok {
+					return fmt.Errorf("type %q not found", typeName)
+				}
+				want := "First line of the description.\n\nSecond line of the description.\n\n\tquery {\n\t\tcode {\n\t\t\texample\n\t\t}\n\t}\n\nNotes:\n\n * First note\n * Second note"
+				if have := typ.Description(); want != have {
+					return fmt.Errorf("invalid description: want %q, have %q", want, have)
+				}
+				return nil
+			},
+		},
+		{
+			name: "Parses type with un-indented multi-line 'BlockString' description",
+			sdl: `
+			"""
+First line of the description.
+
+Second line of the description.
+			"""
+			type Type {
+				field: String
+			}`,
+			useStringDescriptions: true,
+			validateSchema: func(s *schema.Schema) error {
+				const typeName = "Type"
+				typ, ok := s.Types[typeName].(*schema.Object)
+				if !ok {
+					return fmt.Errorf("type %q not found", typeName)
+				}
+				want := "First line of the description.\n\nSecond line of the description."
+				if have := typ.Description(); want != have {
+					return fmt.Errorf("invalid description: want %q, have %q", want, have)
+				}
+				return nil
+			},
+		},
+		{
+			name: "Parses type with space-indented multi-line 'BlockString' description",
+			sdl: `
+            """
+            First line of the description.
+
+            Second line of the description.
+
+                query {
+                    code {
+                        example
+                    }
+                }
+            """
+            type Type {
+                field: String
+            }`,
+			useStringDescriptions: true,
+			validateSchema: func(s *schema.Schema) error {
+				const typeName = "Type"
+				typ, ok := s.Types[typeName].(*schema.Object)
+				if !ok {
+					return fmt.Errorf("type %q not found", typeName)
+				}
+				want := "First line of the description.\n\nSecond line of the description.\n\n    query {\n        code {\n            example\n        }\n    }"
+				if have := typ.Description(); want != have {
+					return fmt.Errorf("invalid description: want %q, have %q", want, have)
+				}
+				return nil
+			},
+		},
+		{
+			name: "Parses type with multi-line 'BlockString' description and ignores comments",
 			sdl: `
 			"""
 			Multi-line description with ignored comments.