Strip Common Indentation from BlockString Descriptions

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.