Introduce SubclassOptInRequired annotation (see KT-41886)

core/compiler.common/src/org/jetbrains/kotlin/resolve/checkers/OptInNames.kt

@@ -16,6 +16,8 @@ object OptInNames {
     val REQUIRES_OPT_IN_CLASS_ID = ClassId.topLevel(REQUIRES_OPT_IN_FQ_NAME)
     val OPT_IN_FQ_NAME = FqName("kotlin.OptIn")
     val OPT_IN_CLASS_ID = ClassId.topLevel(OPT_IN_FQ_NAME)
+    val SUBCLASS_OPT_IN_REQUIRED_FQ_NAME = FqName("kotlin.SubclassOptInRequired")
+    val SUBCLASS_OPT_IN_REQUIRED_CLASS_ID = ClassId.topLevel(SUBCLASS_OPT_IN_REQUIRED_FQ_NAME)
 
     val WAS_EXPERIMENTAL_FQ_NAME = FqName("kotlin.WasExperimental")
     val WAS_EXPERIMENTAL_CLASS_ID = ClassId.topLevel(WAS_EXPERIMENTAL_FQ_NAME)

libraries/stdlib/api/js-v1/kotlin.kt

@@ -2755,6 +2755,15 @@ public final class String : kotlin.Comparable<kotlin.String>, kotlin.CharSequenc
     }
 }
 
+@kotlin.annotation.Target(allowedTargets = {AnnotationTarget.CLASS})
+@kotlin.annotation.Retention(value = AnnotationRetention.BINARY)
+@kotlin.SinceKotlin(version = "1.8")
+public final annotation class SubclassOptInRequired : kotlin.Annotation {
+    public constructor SubclassOptInRequired(markerClass: kotlin.reflect.KClass<out kotlin.Annotation>)
+
+    public final val markerClass: kotlin.reflect.KClass<out kotlin.Annotation> { get; }
+}
+
 @kotlin.annotation.Target(allowedTargets = {AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.TYPE_PARAMETER, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD, AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.TYPE, AnnotationTarget.EXPRESSION, AnnotationTarget.FILE, AnnotationTarget.TYPEALIAS})
 @kotlin.annotation.Retention(value = AnnotationRetention.SOURCE)
 public final annotation class Suppress : kotlin.Annotation {

libraries/stdlib/api/js/kotlin.kt

@@ -2389,6 +2389,15 @@ public final class String : kotlin.Comparable<kotlin.String>, kotlin.CharSequenc
     }
 }
 
+@kotlin.annotation.Target(allowedTargets = {AnnotationTarget.CLASS})
+@kotlin.annotation.Retention(value = AnnotationRetention.BINARY)
+@kotlin.SinceKotlin(version = "1.8")
+public final annotation class SubclassOptInRequired : kotlin.Annotation {
+    public constructor SubclassOptInRequired(markerClass: kotlin.reflect.KClass<out kotlin.Annotation>)
+
+    public final val markerClass: kotlin.reflect.KClass<out kotlin.Annotation> { get; }
+}
+
 @kotlin.annotation.Target(allowedTargets = {AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.TYPE_PARAMETER, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD, AnnotationTarget.LOCAL_VARIABLE, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.TYPE, AnnotationTarget.EXPRESSION, AnnotationTarget.FILE, AnnotationTarget.TYPEALIAS})
 @kotlin.annotation.Retention(value = AnnotationRetention.SOURCE)
 public final annotation class Suppress : kotlin.Annotation {

libraries/stdlib/src/kotlin/annotations/OptIn.kt

@@ -55,3 +55,27 @@ public annotation class RequiresOptIn(
 public annotation class OptIn(
     vararg val markerClass: KClass<out Annotation>
 )
+
+/**
+ * Forbids creation of subclasses/sub-interfaces from the annotated class/interface without explicit OptIn.
+ *
+ * This annotation is devoted to specific case when we want subclassing to be experimental.
+ * In this case we annotated the base class or interface with [SubclassOptInRequired].
+ * Without an explicit opt-in we have a compilation error/warning on the subclass/sub-interface after that.
+ *
+ * There are three ways to negate this error/warning:
+ * <ol><li>Annotate subclass or interface with the marker annotation. In this case opt-in is propagated.</li>
+ * <li>Annotate subclass or interface with [OptIn]. In this case opt-in isn't propagated.</li>
+ * <li>Annotate subclass or interface with [SubclassOptInRequired]. In this case opt-in is propagated to subclasses/interfaces only.</li>
+ * </ol>
+ *
+ * Note that [SubclassOptInRequired] does not negate an opt-in usage error itself.
+ *
+ * @property markerClass an opt-in marker to be required
+ */
+@Target(CLASS)
+@Retention(BINARY)
+@SinceKotlin("1.8")
+public annotation class SubclassOptInRequired(
+    val markerClass: KClass<out Annotation>
+)

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

@@ -235,6 +235,10 @@ public abstract interface annotation class kotlin/SinceKotlin : java/lang/annota
 	public abstract fun version ()Ljava/lang/String;
 }
 
+public abstract interface annotation class kotlin/SubclassOptInRequired : java/lang/annotation/Annotation {
+	public abstract fun markerClass ()Ljava/lang/Class;
+}
+
 public abstract interface annotation class kotlin/Suppress : java/lang/annotation/Annotation {
 	public abstract fun names ()[Ljava/lang/String;
 }