Make enum as sealed class Unknown constructor opt-in (apollographql#5813)

* Make enum as sealed class Unknown constructor opt-in

* Introduce ApolloEnumConstructor

* Update libraries/apollo-annotations/src/commonMain/kotlin/com/apollographql/apollo3/annotations/ApolloEnumConstructor.kt

Co-authored-by: Martin Bonnin <[email protected]>

* Update libraries/apollo-annotations/src/commonMain/kotlin/com/apollographql/apollo3/annotations/ApolloEnumConstructor.kt

Co-authored-by: Martin Bonnin <[email protected]>

---------

Co-authored-by: Martin Bonnin <[email protected]>

Author: BoD

libraries/apollo-annotations/api/apollo-annotations.api

@@ -27,6 +27,9 @@ public final class com/apollographql/apollo3/annotations/ApolloDeprecatedSince$V
 	public static fun values ()[Lcom/apollographql/apollo3/annotations/ApolloDeprecatedSince$Version;
 }
 
+public abstract interface annotation class com/apollographql/apollo3/annotations/ApolloEnumConstructor : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class com/apollographql/apollo3/annotations/ApolloExperimental : java/lang/annotation/Annotation {
 }
 

libraries/apollo-annotations/src/commonMain/kotlin/com/apollographql/apollo3/annotations/ApolloEnumConstructor.kt

@@ -0,0 +1,9 @@
+package com.apollographql.apollo3.annotations
+
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING,
+    message = "The `UNKNOWN__` class represents GraphQL enums that are not present in the schema and whose `rawValue` cannot be checked at build time. You may want to update your schema instead of calling this constructor directly."
+)
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CONSTRUCTOR)
+annotation class ApolloEnumConstructor

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/KotlinSymbols.kt

@@ -105,6 +105,7 @@ internal object KotlinSymbols {
 
   val ApolloAdaptableWith = ClassName(ClassNames.apolloAnnotationsPackageName, "ApolloAdaptableWith")
   val ApolloExperimental = ClassName(ClassNames.apolloAnnotationsPackageName, "ApolloExperimental")
+  val ApolloEnumConstructor = ClassName(ClassNames.apolloAnnotationsPackageName, "ApolloEnumConstructor")
 
   val JsExport = ClassName("kotlin.js", "JsExport")
 

libraries/apollo-compiler/src/main/kotlin/com/apollographql/apollo3/compiler/codegen/kotlin/schema/EnumAsSealedBuilder.kt

@@ -89,8 +89,8 @@ internal class EnumAsSealedBuilder(
 
   private fun IrEnum.unknownValueTypeSpec(): TypeSpec {
     return TypeSpec.classBuilder("UNKNOWN__")
-        .addKdoc("%L", "An enum value that wasn't known at compile time.\n")
-        .primaryConstructor(primaryConstructorSpec)
+        .addKdoc("An enum value that wasn't known at compile time.\nConstructor is annotated with [%T] to prevent instantiation outside of this file.", KotlinSymbols.ApolloEnumConstructor)
+        .primaryConstructor(unknownValuePrimaryConstructorSpec)
         .superclass(selfClassName)
         .addSuperclassConstructorParameter("rawValue·=·rawValue")
         .addFunction(
@@ -132,7 +132,7 @@ internal class EnumAsSealedBuilder(
                 .map { CodeBlock.of("%S·->·%T", it.name, it.valueClassName()) }
                 .joinToCode(separator = "\n", suffix = "\n")
         )
-        .addCode("else -> %T(rawValue)\n", unknownValueClassName())
+        .addCode("else -> @OptIn(%T::class) %T(rawValue)\n", KotlinSymbols.ApolloEnumConstructor, unknownValueClassName())
         .endControlFlow()
         .build()
   }
@@ -167,19 +167,20 @@ internal class EnumAsSealedBuilder(
     return ClassName(selfClassName.packageName, selfClassName.simpleName, "UNKNOWN__")
   }
 
-  private val primaryConstructorSpec =
-      FunSpec.constructorBuilder()
-          .addParameter("rawValue", KotlinSymbols.String)
-          .build()
+  private val unknownValuePrimaryConstructorSpec =
+    FunSpec.constructorBuilder()
+        .addAnnotation(KotlinSymbols.ApolloEnumConstructor)
+        .addParameter("rawValue", KotlinSymbols.String)
+        .build()
 
   private val primaryConstructorWithOverriddenParamSpec =
-      FunSpec.constructorBuilder()
-          .addParameter("rawValue", KotlinSymbols.String)
-          .build()
+    FunSpec.constructorBuilder()
+        .addParameter("rawValue", KotlinSymbols.String)
+        .build()
 
   private val rawValuePropertySpec =
-      PropertySpec.builder("rawValue", KotlinSymbols.String)
-          .initializer("rawValue")
-          .build()
+    PropertySpec.builder("rawValue", KotlinSymbols.String)
+        .initializer("rawValue")
+        .build()
 
-}
+}