Preserving graphQL descriptions as descriptions (not converting to co…

…mments) is now the default behaviour.

maven-plugin/pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 
   <modelVersion>4.0.0</modelVersion>
 

maven-plugin/src/it/generate-alterations/expected.graphqls

@@ -15,17 +15,17 @@ type Query {
 
 union Something = A | B | C
 
-"""
-This is an old 
-long comment
-"""
+#This is an old 
+#long comment
 type A {
-  "Old shorter comment"
+  #Old shorter comment
   thing: String
 }
+
 type B {
   thing: String
 }
+
 type C {
   thing: String
 }

maven-plugin/src/it/mojo-description/expected.log

@@ -53,9 +53,9 @@ sortgraphql:sort
       User property: sortgraphql.encoding
       Encoding for the files.
 
-    generateHashDescriptions (Default: true)
+    generateHashDescriptions (Default: false)
       User property: sortgraphql.generateHashDescriptions
-      Use hash sign for descriptions/comments, instead of string literals (with
+      Use hash sign for descriptions, instead of keeping string literals (with
       quote character), when generating the sorted schema file.
 
     generateSchemaDefinition (Default: false)

maven-plugin/src/it/normal-sort/expected.graphqls

@@ -8,13 +8,15 @@ directive @resolve(graph: String!) on FIELD_DEFINITION
 directive @stream on FIELD
 directive @transform(from: String!) on FIELD
 
-#This is a 
-#long comment
+"""
+This is a 
+long comment
+"""
 type Query {
   me: User @resolve(graph: "accounts")
   myVehicle: Vehicle @resolve(graph: "product")
   topAds(first: Int = 5): [Advertisement] @resolve(graph: "advertisement")
-  #Shorter comment
+  "Shorter comment"
   topProducts(first: Int = 5): [Product] @resolve(graph: "product")
   users(filter: UserFilter): [User] @resolve(graph: "accounts")
 }

maven-plugin/src/main/java/sortgraphql/AbstractParentMojo.java

@@ -26,10 +26,10 @@ abstract class AbstractParentMojo extends AbstractMojo {
   protected String encoding;
 
   /**
-   * Use hash sign for descriptions/comments, instead of string literals (with quote character),
+   * Use hash sign for descriptions, instead of keeping string literals (with quote character),
    * when generating the sorted schema file.
    */
-  @Parameter(property = "sortgraphql.generateHashDescriptions", defaultValue = "true")
+  @Parameter(property = "sortgraphql.generateHashDescriptions", defaultValue = "false")
   protected boolean generateHashDescriptions;
 
   /**

pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
   <modelVersion>4.0.0</modelVersion>
 
@@ -42,6 +43,7 @@
         <groupId>org.apache.maven</groupId>
         <artifactId>maven-plugin-api</artifactId>
         <version>3.8.5</version>
+        <scope>provided</scope>
       </dependency>
       <dependency>
         <groupId>org.apache.maven.plugin-tools</groupId>

sorter/pom.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 
   <modelVersion>4.0.0</modelVersion>
 

sorter/src/main/java/sortgraphql/sort/DescriptionOrComment.java

@@ -0,0 +1,46 @@
+package sortgraphql.sort;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Supplier;
+
+public class DescriptionOrComment {
+  private final String comment;
+  private final String description;
+
+  private DescriptionOrComment(String comment, String description) {
+    this.comment = comment;
+    this.description = description;
+  }
+
+  public static DescriptionOrComment comment(String comment) {
+    return new DescriptionOrComment(comment, null);
+  }
+
+  public static DescriptionOrComment description(String description) {
+    return new DescriptionOrComment(null, description);
+  }
+
+  public boolean isNullOrEmpty() {
+    return (comment == null || comment.isEmpty()) && (description == null || description.isEmpty());
+  }
+
+  public boolean isDescription() {
+    if (isNullOrEmpty()) {
+      throw new IllegalStateException("Both comment and description is null");
+    }
+    return comment == null;
+  }
+
+  public String getComment() {
+    return comment;
+  }
+
+  public String getDescription() {
+    return description;
+  }
+
+  public static List<String> lines(Supplier<String> fn) {
+    return Arrays.asList(fn.get().split("\n"));
+  }
+}

sorter/src/main/java/sortgraphql/sort/SchemaPrinter.java

@@ -11,7 +11,6 @@
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Comparator;
 import java.util.List;
 import java.util.function.Consumer;
@@ -23,6 +22,7 @@
 import static graphql.util.EscapeUtil.escapeJsonString;
 import static java.util.Optional.ofNullable;
 import static java.util.stream.Collectors.*;
+import static sortgraphql.sort.DescriptionOrComment.*;
 
 /** This can print an in memory GraphQL schema back to a logical schema definition */
 @PublicApi
@@ -287,9 +287,10 @@ private void printInput(
 
     out.format(
         "input %s%s",
-        type.getName(), 
-        type.getDirectives().isEmpty() ? " " :
-        directivesString(GraphQLInputObjectType.class, type.getDirectives()));
+        type.getName(),
+        type.getDirectives().isEmpty()
+            ? " "
+            : directivesString(GraphQLInputObjectType.class, type.getDirectives()));
     var inputObjectFields = visibility.getFieldDefinitions(type);
     if (!inputObjectFields.isEmpty()) {
       out.append("{\n");
@@ -408,7 +409,8 @@ private Predicate<GraphQLNamedType> matchesTypeName(GraphQLObjectType namedType)
       return testType -> false;
     }
     var name = namedType.getName();
-    return testType -> testType.getName().equals(name) && options.getIncludeSchemaElement().test(testType);
+    return testType ->
+        testType.getName().equals(name) && options.getIncludeSchemaElement().test(testType);
   }
 
   private <T> List<T> removeMatchingItems(
@@ -577,8 +579,10 @@ String directivesString(
   }
 
   private boolean hasDirectiveOnOwnLine(Class<? extends GraphQLSchemaElement> parent) {
-    return parent == GraphQLObjectType.class || parent == GraphQLInterfaceType.class || parent == GraphQLSchemaElement.class
-         || parent == GraphQLInputObjectType.class;
+    return parent == GraphQLObjectType.class
+        || parent == GraphQLInterfaceType.class
+        || parent == GraphQLSchemaElement.class
+        || parent == GraphQLInputObjectType.class;
   }
 
   private String directiveString(GraphQLDirective directive) {
@@ -719,13 +723,13 @@ private String printComments(Object graphQLType, String prefix) {
 
   private void printComments(PrintWriter out, Object graphQLType, String prefix) {
 
-    var descriptionText = getDescription(graphQLType);
-    if (isNullOrEmpty(descriptionText)) {
+    var description = getDescription(graphQLType);
+    if (description.isNullOrEmpty()) {
       return;
     }
 
-    if (!isNullOrEmpty(descriptionText)) {
-      var lines = Arrays.asList(descriptionText.split("\n"));
+    if (description.isDescription()) {
+      var lines = lines(description::getDescription);
       if (options.isDescriptionsAsHashComments()) {
         printMultiLineHashDescription(out, prefix, lines);
       } else if (!lines.isEmpty()) {
@@ -735,6 +739,8 @@ private void printComments(PrintWriter out, Object graphQLType, String prefix) {
           printSingleLineDescription(out, prefix, lines.get(0));
         }
       }
+    } else {
+      printMultiLineHashDescription(out, prefix, lines(description::getComment));
     }
   }
 
@@ -756,10 +762,10 @@ private void printSingleLineDescription(PrintWriter out, String prefix, String s
 
   private boolean hasDescription(Object descriptionHolder) {
     var description = getDescription(descriptionHolder);
-    return !isNullOrEmpty(description);
+    return !description.isNullOrEmpty();
   }
 
-  private String getDescription(Object descriptionHolder) {
+  private DescriptionOrComment getDescription(Object descriptionHolder) {
     if (descriptionHolder instanceof GraphQLObjectType) {
       var type = (GraphQLObjectType) descriptionHolder;
       return description(
@@ -816,13 +822,13 @@ private String getDescription(Object descriptionHolder) {
           ofNullable(type.getDefinition()).map(InputValueDefinition::getDescription).orElse(null));
     } else if (descriptionHolder instanceof GraphQLDirective) {
       var type = (GraphQLDirective) descriptionHolder;
-      return description(type.getDescription(), null);
+      return description(type.getDescription(), ofNullable(type.getDefinition()).map(AbstractDescribedNode::getDescription).orElse(null));
     } else {
       return Assert.assertShouldNeverHappen();
     }
   }
 
-  String description(String runtimeDescription, Description descriptionAst) {
+  DescriptionOrComment description(String runtimeDescription, Description descriptionAst) {
     //
     // 95% of the time if the schema was built from SchemaGenerator then the runtime description is
     // the only description
@@ -832,7 +838,10 @@ String description(String runtimeDescription, Description descriptionAst) {
     if (isNullOrEmpty(descriptionText) && descriptionAst != null) {
       descriptionText = descriptionAst.getContent();
     }
-    return descriptionText;
+    if (descriptionAst == null) {
+      return DescriptionOrComment.comment(descriptionText);
+    }
+    return DescriptionOrComment.description(descriptionText);
   }
 
   private static boolean isNullOrEmpty(String s) {

sorter/src/test/java/cucumber/StepDefinitions.java

@@ -56,6 +56,12 @@ public void generateSchemaDefinition(boolean flag) {
     paramBuilder.setGenerationOptions(flag, pluginParameters.generateAllDirectiveDefinitions, pluginParameters.descriptionsAsHashComments);
   }
 
+  @Given("descriptions as hash comments is {booleanValue}")
+  public void descriptionsAsHashComments(boolean flag) {
+    var pluginParameters = paramBuilder.build();
+    paramBuilder.setGenerationOptions(pluginParameters.generateSchemaDefinition, pluginParameters.generateAllDirectiveDefinitions, flag);
+  }
+
   @Given("schema content")
   public void schemaContent(String content) {
     storeSchemaFile("filename", content);

sorter/src/test/java/sortgraphql/SorterImplTest.java

@@ -144,4 +144,18 @@ void nonHashCommentsShouldTransformComments() throws IOException {
 
     assertThat(util.getTestSchemaContent(), is(expectedSchemaContent));
   }
+
+    @Test
+  void descriptionsInSchemaShouldBePreserved() throws IOException {
+    var util = new TestSchemaUtil("cucumber/descriptions.graphqls", ".test_bak");
+
+    util.getPluginParameterBuilder().setGenerationOptions(false, false, false);
+    util.sortSchemas();
+
+    var expectedSchemaContent =
+        util.getExpectedSchemaContent("cucumber/descriptions_expected.graphqls");
+
+    assertThat(util.getTestSchemaContent(), is(expectedSchemaContent));
+  }
+
 }

sorter/src/test/resources/cucumber/descriptions.graphqls

@@ -0,0 +1,95 @@
+"a scalar"
+scalar _Any
+"used to represent a set of fields (minus the braces around them)."
+scalar _FieldSet
+
+"scary stuff"
+directive @supernatural("directive desc" scary: Boolean = true) on FIELD_DEFINITION
+
+"a directive"
+directive @key(fields: _FieldSet!) repeatable on OBJECT | INTERFACE
+
+"""
+Multi-line
+on type
+"""
+type Query {
+    "A field"
+    me :Me
+}
+
+"A type"
+type Me @key(fields: "id"){
+"""
+Multi-line
+on field
+"""
+    id: ID
+    name: String
+}
+
+"The sound file of a howl"
+scalar Howl
+
+"Contains traits of both"
+union Werewolf = Person | Wolf
+
+interface Animal {
+    doesHowl: Boolean
+}
+
+type Wolf {
+    doesHowl: Boolean
+    howl: Howl
+}
+
+type Person {
+   traits: KindType 
+}
+
+"Mutation"
+type Mutation {
+    bite(victim: Victim): Werewolf @supernatural(scary: true)
+}
+
+"input"
+input Victim {
+    "input field"
+    traits: KindType
+}
+
+"another type"
+type Cat implements CuteAnimal & Animal {
+    doesHowl: Boolean
+    howl: Howl
+   traits: KindType 
+}
+
+"interface"
+interface CuteAnimal implements Animal {
+    "interface field"
+    doesHowl: Boolean
+}
+
+"enum"
+enum wereTypes {
+    """
+    enum value
+    multi-line
+    """
+    WORM @deprecated 
+    WOLF
+    BEAR
+}
+
+"""
+Random 
+subscription
+"""
+type Subscription {
+  monthlyWerewolf: Werewolf  
+}
+
+enum KindType {
+    KIND
+}