Refactor schema validation (#6396)

* Refactor schema validation

* unbreak IJ plugin

* add terms to the glossary

Author: martinbonnin

benchmark/microbenchmark/src/main/graphql/conferences/extra.graphqls

@@ -1,6 +1,6 @@
 extend schema
 @link(
-  url: "https://specs.apollo.dev/kotlin_labs/v0.3",
+  url: "https://specs.apollo.dev/kotlin_labs/v0.4",
   import: ["@fieldPolicy", "@typePolicy"]
 )
 

design-docs/Glossary.md

@@ -125,3 +125,29 @@ Fields that are used to compute a Cache key for an object.
 
 Field arguments that control pagination, e.g. `first`, `after`, etc. They should be omitted when computing a field key so different pages can be merged into the same field.
 
+
+### API schema
+
+The server schema as seen from introspection (can be either JSON or SDL)
+
+### Server definition
+
+A definition present in the API schema.
+
+Examples: `@include`, `@oneOf`, `__Schema`
+
+### Client definition
+
+A definition that is added to the API schema by the client, using either @link or by concatenating new definitions to the schema.
+
+### Linked definition
+
+A definition is added to a schema using @link.
+ 
+Examples: `@targetName`, `@typePolicy`
+
+### Checked definitions
+
+A definition that is recognized by Apollo Kotlin and required to be a certain shape. Apollo Kotlin checks those definitions to avoid crashes in the compiler and/or surprising behaviours. This is typically the case for server definitions that and are not specified yet and/or may vary depending on the version of the spec used.
+
+Examples: `@oneOf`, `@semanticNonNull`, `@targetName`

intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQLUnresolvedReferenceInspectionSuppressor.kt

@@ -1,5 +1,6 @@
 package com.apollographql.ijplugin.inspection
 
+import com.apollographql.apollo.annotations.ApolloInternal
 import com.apollographql.apollo.ast.GQLDirectiveDefinition
 import com.apollographql.apollo.ast.linkDefinitions
 import com.apollographql.ijplugin.util.KOTLIN_LABS_DEFINITIONS
@@ -15,6 +16,7 @@ import com.intellij.lang.jsgraphql.psi.GraphQLDirective
 import com.intellij.lang.jsgraphql.psi.GraphQLDirectivesAware
 import com.intellij.psi.PsiElement
 
+@OptIn(ApolloInternal::class)
 private val KNOWN_DIRECTIVES: List<GQLDirectiveDefinition> by lazy {
   linkDefinitions().directives() + NULLABILITY_DEFINITIONS.directives() + KOTLIN_LABS_DEFINITIONS.directives()
 }

intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/Link.kt

@@ -3,10 +3,10 @@
 package com.apollographql.ijplugin.util
 
 import com.apollographql.apollo.annotations.ApolloInternal
+import com.apollographql.apollo.ast.AUTO_IMPORTED_KOTLIN_LABS_VERSION
 import com.apollographql.apollo.ast.GQLDefinition
 import com.apollographql.apollo.ast.GQLDirectiveDefinition
 import com.apollographql.apollo.ast.GQLNamed
-import com.apollographql.apollo.ast.KOTLIN_LABS_VERSION
 import com.apollographql.apollo.ast.NULLABILITY_VERSION
 import com.apollographql.apollo.ast.kotlinLabsDefinitions
 import com.apollographql.apollo.ast.nullabilityDefinitions
@@ -28,10 +28,10 @@ val NULLABILITY_DEFINITIONS: List<GQLDefinition> by lazy {
   nullabilityDefinitions(NULLABILITY_VERSION)
 }
 
-const val KOTLIN_LABS_URL = "https://specs.apollo.dev/kotlin_labs/$KOTLIN_LABS_VERSION"
+const val KOTLIN_LABS_URL = "https://specs.apollo.dev/kotlin_labs/$AUTO_IMPORTED_KOTLIN_LABS_VERSION"
 
 val KOTLIN_LABS_DEFINITIONS: List<GQLDefinition> by lazy {
-  kotlinLabsDefinitions(KOTLIN_LABS_VERSION)
+  kotlinLabsDefinitions(AUTO_IMPORTED_KOTLIN_LABS_VERSION)
 }
 
 const val CATCH = "catch"

libraries/apollo-ast/api/apollo-ast.api

@@ -766,8 +766,6 @@ public final class com/apollographql/apollo/ast/GqldirectiveKt {
 
 public final class com/apollographql/apollo/ast/GqldocumentKt {
 	public static final fun builtinDefinitions ()Ljava/util/List;
-	public static final fun kotlinLabsDefinitions (Ljava/lang/String;)Ljava/util/List;
-	public static final fun linkDefinitions ()Ljava/util/List;
 	public static final fun nullabilityDefinitions (Ljava/lang/String;)Ljava/util/List;
 	public static final fun toSchema (Lcom/apollographql/apollo/ast/GQLDocument;)Lcom/apollographql/apollo/ast/Schema;
 	public static final fun withBuiltinDefinitions (Lcom/apollographql/apollo/ast/GQLDocument;)Lcom/apollographql/apollo/ast/GQLDocument;

libraries/apollo-ast/api/apollo-ast.klib.api

@@ -1298,6 +1298,4 @@ final fun (kotlin/String).com.apollographql.apollo.ast/toGQLValue(com.apollograp
 final fun (okio/Path).com.apollographql.apollo.ast/parseAsGQLDocument(com.apollographql.apollo.ast/ParserOptions = ...): com.apollographql.apollo.ast/GQLResult<com.apollographql.apollo.ast/GQLDocument> // com.apollographql.apollo.ast/parseAsGQLDocument|parseAsGQLDocument@okio.Path(com.apollographql.apollo.ast.ParserOptions){}[0]
 final fun (okio/Path).com.apollographql.apollo.ast/toGQLDocument(com.apollographql.apollo.ast/ParserOptions = ..., kotlin/Boolean = ...): com.apollographql.apollo.ast/GQLDocument // com.apollographql.apollo.ast/toGQLDocument|toGQLDocument@okio.Path(com.apollographql.apollo.ast.ParserOptions;kotlin.Boolean){}[0]
 final fun com.apollographql.apollo.ast/builtinDefinitions(): kotlin.collections/List<com.apollographql.apollo.ast/GQLDefinition> // com.apollographql.apollo.ast/builtinDefinitions|builtinDefinitions(){}[0]
-final fun com.apollographql.apollo.ast/kotlinLabsDefinitions(kotlin/String): kotlin.collections/List<com.apollographql.apollo.ast/GQLDefinition> // com.apollographql.apollo.ast/kotlinLabsDefinitions|kotlinLabsDefinitions(kotlin.String){}[0]
-final fun com.apollographql.apollo.ast/linkDefinitions(): kotlin.collections/List<com.apollographql.apollo.ast/GQLDefinition> // com.apollographql.apollo.ast/linkDefinitions|linkDefinitions(){}[0]
 final fun com.apollographql.apollo.ast/nullabilityDefinitions(kotlin/String): kotlin.collections/List<com.apollographql.apollo.ast/GQLDefinition> // com.apollographql.apollo.ast/nullabilityDefinitions|nullabilityDefinitions(kotlin.String){}[0]

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

@@ -18,4 +18,7 @@ class ForeignSchema(
     val version: String,
     val definitions: List<GQLDefinition>,
     val directivesToStrip: List<String> = definitions.filterIsInstance<GQLDirective>().map { it.name },
-)
+) {
+  val nameWithVersion: String
+    get() = "$name/$version"
+}

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

@@ -1,6 +1,6 @@
 package com.apollographql.apollo.ast
 
-import com.apollographql.apollo.annotations.ApolloInternal
+import com.apollographql.apollo.annotations.ApolloDeprecatedSince
 
 /**
  * All the issues that can be collected while analyzing a graphql document
@@ -33,20 +33,17 @@ class ParsingError(override val message: String, override val sourceLocation: So
 /**
  * An unknown directive was found.
  *
- * In a perfect world everyone uses SDL schemas, and we can validate directives but in this world, a lot of users rely
- * on introspection schemas that do not contain directives. If this happens, we pass them through without validation.
+ * In case a user rely on non-introspection schemas (that do not contain directives definitions), the apollo compiler:
+ * - adds the built-in directives (`@include`, `@skip`, ...)
+ * - adds the `kotlin_labs/v3` directives (for legacy reasons, will be removed in a future version)
  *
- * In some cases (e.g. `@oneOf`) we want to enforce that the directive is defined. In that case [requireDefinition] is true and the issue
- * will be raised as an error rather than warning.
+ * For anything else, including `@defer` and `@oneOf`, a full schema is required so that the compiler can do feature
+ * detection and validate operation based on what the server actually supports.
  */
-class UnknownDirective @ApolloInternal constructor(
+class UnknownDirective(
     override val message: String,
     override val sourceLocation: SourceLocation?,
-    @ApolloInternal
-    val requireDefinition: Boolean,
-) : GraphQLValidationIssue {
-  constructor(message: String, sourceLocation: SourceLocation?) : this(message, sourceLocation, false)
-}
+) : GraphQLValidationIssue
 
 /**
  * The definition is inconsistent with the expected one.
@@ -72,12 +69,16 @@ class UnusedFragment(override val message: String, override val sourceLocation:
  */
 class DuplicateTypeName(override val message: String, override val sourceLocation: SourceLocation?) : GraphQLValidationIssue
 
+/**
+ * This is a bit abused for kotlin_labs directive that override the existing ones for compatibility reasons.
+ * This is so that `ApolloCompiler` can later on treat them as warnings.
+ */
 class DirectiveRedefinition(
     val name: String,
     existingSourceLocation: SourceLocation?,
     override val sourceLocation: SourceLocation?,
 ) : GraphQLValidationIssue {
-  override val message = "Directive '${name}' is defined multiple times. First definition is: ${existingSourceLocation.pretty()}"
+  override val message = "Implicit kotlin_labs definition '@${name}' overrides explicit one provided by the schema. Import kotlin_labs explicitly using @link."
 }
 
 class NoQueryType(override val message: String, override val sourceLocation: SourceLocation?) : GraphQLValidationIssue

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

@@ -58,9 +58,9 @@ class Schema internal constructor(
   )
 
   /**
-   * @param name the current name of the directive (like "kotlin_labs__nonnull")
+   * @param name the current name of the directive (like "kotlin_labs__targetName")
    *
-   * @return the original directive name (like "nonnull")
+   * @return the original directive name (like "targetName") or null if the directive was not linked.
    */
   fun originalDirectiveName(name: String): String {
     return foreignNames["@$name"]?.substring(1) ?: name
@@ -179,7 +179,7 @@ class Schema internal constructor(
     val directives = typeDefinitions.values.filterIsInstance<GQLObjectTypeDefinition>().flatMap { it.directives } +
         typeDefinitions.values.filterIsInstance<GQLInterfaceTypeDefinition>().flatMap { it.directives } +
         typeDefinitions.values.filterIsInstance<GQLUnionTypeDefinition>().flatMap { it.directives }
-    return directives.any { it.name == TYPE_POLICY }
+    return directives.any { originalDirectiveName(it.name) == TYPE_POLICY }
   }
 
   /**
@@ -199,15 +199,21 @@ class Schema internal constructor(
   }
 
   companion object {
+    @ApolloExperimental
+    const val ONE_OF = "oneOf"
+    @ApolloExperimental
+    const val DEFER = "defer"
+
+    @ApolloExperimental
+    const val LINK = "link"
+
     const val TYPE_POLICY = "typePolicy"
     const val FIELD_POLICY = "fieldPolicy"
     const val NONNULL = "nonnull"
     const val OPTIONAL = "optional"
     const val REQUIRES_OPT_IN = "requiresOptIn"
     const val TARGET_NAME = "targetName"
 
-    @ApolloExperimental
-    const val ONE_OF = "oneOf"
     @ApolloExperimental
     const val CATCH = "catch"
     @ApolloExperimental
@@ -216,8 +222,6 @@ class Schema internal constructor(
     const val SEMANTIC_NON_NULL = "semanticNonNull"
     @ApolloExperimental
     const val SEMANTIC_NON_NULL_FIELD = "semanticNonNullField"
-    @ApolloExperimental
-    const val LINK = "link"
 
     const val FIELD_POLICY_FOR_FIELD = "forField"
     const val FIELD_POLICY_KEY_ARGS = "keyArgs"
@@ -242,14 +246,18 @@ class Schema internal constructor(
     }
 
     internal fun rootOperationTypeDefinition(operationType: String, definitions: List<GQLDefinition>): GQLTypeDefinition? {
-      return definitions.filterIsInstance<GQLSchemaDefinition>().single()
+      return rootOperationTypeDefinition(definitions.filterIsInstance<GQLSchemaDefinition>().single(), operationType, definitions.filterIsInstance<GQLObjectTypeDefinition>().associateBy { it.name })
+    }
+
+    internal fun rootOperationTypeDefinition(schemaTypeDefinition: GQLSchemaDefinition, operationType: String, typeDefinitions: Map<String, GQLTypeDefinition>): GQLTypeDefinition? {
+      return schemaTypeDefinition
           .rootOperationTypeDefinitions
           .singleOrNull {
             it.operationType == operationType
           }
           ?.namedType
           ?.let { namedType ->
-            definitions.filterIsInstance<GQLObjectTypeDefinition>().single { it.name == namedType }
+            typeDefinitions.get(namedType)
           }
     }
   }