[validation] Normalize the order of arguments of checked definitions (#6650)

* Also normalize the order of arguments

* Also sort the implemented interfaces

* update test fixtures

Author: martinbonnin

libraries/apollo-ast/src/commonMain/kotlin/com/apollographql/apollo/ast/Issue.kt

@@ -45,7 +45,12 @@ class UnknownDirective(
 ) : GraphQLValidationIssue
 
 /**
- * The definition is inconsistent with the expected one.
+ * The provided schema contains a definition that doesn't match the GraphQL specification.
+ *
+ * This may happen in particular for directive that are in the process of being specified like `@defer` (as of Jul 2025).
+ *
+ * Because the Apollo compiler expects a certain shape of directive and arguments, anything else may trigger
+ * a crash in the compiler. By validating explicitly, the error is more explicit.
  */
 class IncompatibleDefinition(
     name: String,

libraries/apollo-ast/src/commonMain/kotlin/com/apollographql/apollo/ast/internal/semanticEquals.kt

@@ -11,18 +11,25 @@ internal fun GQLNode.semanticEquals(other: GQLNode?): Boolean {
   return toSemanticSdl() == other.toSemanticSdl()
 }
 
+/**
+ * Normalizes the given [GQLNode].
+ *
+ * Two nodes with the same normalized representation behave the same during execution.
+ *
+ * Especially, descriptions are removed and field, inputFields, arguments, etc.. are sorted lexicographically.
+ */
 internal fun GQLNode.toSemanticSdl(): String {
   return transform2 { node ->
     when (node) {
       is GQLInputValueDefinition -> node.copy(description = null)
-      is GQLObjectTypeDefinition -> node.copy(description = null)
+      is GQLObjectTypeDefinition -> node.copy(description = null, fields = node.fields.sortedBy { it.name }, implementsInterfaces = node.implementsInterfaces.sortedBy { it })
       is GQLScalarTypeDefinition -> node.copy(description = null)
-      is GQLInputObjectTypeDefinition -> node.copy(description = null)
-      is GQLUnionTypeDefinition -> node.copy(description = null)
-      is GQLEnumTypeDefinition -> node.copy(description = null)
-      is GQLInterfaceTypeDefinition -> node.copy(description = null)
-      is GQLFieldDefinition -> node.copy(description = null)
-      is GQLDirectiveDefinition -> node.copy(description = null)
+      is GQLInputObjectTypeDefinition -> node.copy(description = null, inputFields = node.inputFields.sortedBy { it.name })
+      is GQLUnionTypeDefinition -> node.copy(description = null, memberTypes = node.memberTypes.sortedBy { it.name })
+      is GQLEnumTypeDefinition -> node.copy(description = null, enumValues = node.enumValues.sortedBy { it.name })
+      is GQLInterfaceTypeDefinition -> node.copy(description = null, fields = node.fields.sortedBy { it.name }, implementsInterfaces = node.implementsInterfaces.sortedBy { it })
+      is GQLFieldDefinition -> node.copy(description = null, arguments = node.arguments.sortedBy { it.name })
+      is GQLDirectiveDefinition -> node.copy(description = null, arguments = node.arguments.sortedBy { it.name })
       is GQLEnumValueDefinition -> node.copy(description = null)
       is GQLFragmentDefinition -> node.copy(description = null)
       is GQLOperationDefinition -> node.copy(description = null)

libraries/apollo-ast/src/commonTest/kotlin/com/apollographql/apollo/graphql/ast/test/SchemaTest.kt

@@ -2,6 +2,7 @@ package com.apollographql.apollo.graphql.ast.test
 
 import com.apollographql.apollo.ast.ForeignSchema
 import com.apollographql.apollo.ast.internal.SchemaValidationOptions
+import com.apollographql.apollo.ast.internal.toSemanticSdl
 import com.apollographql.apollo.ast.parseAsGQLDocument
 import com.apollographql.apollo.ast.toGQLDocument
 import com.apollographql.apollo.ast.toSchema
@@ -150,4 +151,27 @@ class SchemaTest {
     assertEquals(1, result.issues.size)
     assertEquals("Apollo: unknown definition '@unknownDirective'", result.issues.first().message)
   }
+
+  @Test
+  fun descriptionsAndArgumentOrderDoesNotMatterForSemanticComparison() {
+    // language=graphql
+    val document1 = """
+      directive @defer(
+        "Deferred behaviour is controlled by this argument" 
+        if: Boolean! = true, 
+        "A unique label that represents the fragment being deferred" 
+        label: String
+      ) on FRAGMENT_SPREAD|INLINE_FRAGMENT
+    """.trimIndent()
+
+    // language=graphql
+    val document2 = """
+      directive @defer(
+        label: String,
+        if: Boolean! = true, 
+      ) on FRAGMENT_SPREAD|INLINE_FRAGMENT
+    """.trimIndent()
+
+    assertEquals(document1.toGQLDocument().toSemanticSdl(),document2.toGQLDocument().toSemanticSdl())
+  }
 }