Annotate kotlin.reflect.jvm.reflect with ExperimentalReflectionOnLambdas

This function was always experimental, as explained in its kdoc, but it
was introduced before opt-in requirement markers were supported. Thus,
breaking changes (such as in KT-42746) were always expected, and the
`@ExperimentalReflectionOnLambdas` annotation just makes it clearer.

 #KT-45486 Fixed

compiler/testData/codegen/box/reflection/lambdaClasses/parameterNamesAndNullability.kt

@@ -1,5 +1,5 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
-
 // WITH_REFLECT
 
 import kotlin.reflect.KParameter

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnDefaultWithInlineClassArgument.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnLambdaInArrayConstructor.kt

@@ -1,5 +1,5 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
-// WITH_RUNTIME
 // WITH_REFLECT
 
 import kotlin.reflect.jvm.*
@@ -10,4 +10,4 @@ fun box(): String {
     assertNotNull(Array(1) { {} }.single().reflect())
 
     return "OK"
-}
+}

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnLambdaInConstructor.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnLambdaInField.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnLambdaInStaticField.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnLambdaInSuspend.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 // WITH_COROUTINES

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnLambdaInSuspendLambda.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 // WITH_COROUTINES

compiler/testData/codegen/box/reflection/lambdaClasses/reflectOnSuspendLambdaInField.kt

@@ -1,3 +1,4 @@
+// !USE_EXPERIMENTAL: kotlin.reflect.jvm.ExperimentalReflectionOnLambdas
 // TARGET_BACKEND: JVM
 // WITH_REFLECT
 

core/reflection.jvm/src/kotlin/reflect/jvm/reflectLambda.kt

@@ -21,6 +21,7 @@ import org.jetbrains.kotlin.metadata.deserialization.TypeTable
 import org.jetbrains.kotlin.metadata.jvm.deserialization.JvmMetadataVersion
 import org.jetbrains.kotlin.metadata.jvm.deserialization.JvmProtoBufUtil
 import org.jetbrains.kotlin.serialization.deserialization.MemberDeserializer
+import kotlin.annotation.AnnotationTarget.*
 import kotlin.reflect.KFunction
 import kotlin.reflect.jvm.internal.EmptyContainerForLocal
 import kotlin.reflect.jvm.internal.KFunctionImpl
@@ -31,6 +32,7 @@ import kotlin.reflect.jvm.internal.deserializeToDescriptor
  * returns a [KFunction] instance providing introspection capabilities for that lambda or function expression and its parameters.
  * Not all features are currently supported, in particular [KCallable.call] and [KCallable.callBy] will fail at the moment.
  */
+@ExperimentalReflectionOnLambdas
 fun <R> Function<R>.reflect(): KFunction<R>? {
     val annotation = javaClass.getAnnotation(Metadata::class.java) ?: return null
     val data = annotation.data1.takeUnless(Array<String>::isEmpty) ?: return null
@@ -47,3 +49,30 @@ fun <R> Function<R>.reflect(): KFunction<R>? {
     @Suppress("UNCHECKED_CAST")
     return KFunctionImpl(EmptyContainerForLocal, descriptor) as KFunction<R>
 }
+
+/**
+ * This annotation marks the experimental kotlin-reflect API that allows to approximate a Kotlin lambda or a function expression instance
+ * to a [KFunction] instance. The behavior of this API may be changed or the API may be removed completely in any further release.
+ *
+ * Any usage of a declaration annotated with `@ExperimentalReflectionOnLambdas` should be accepted either by
+ * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalReflectionOnLambdas::class)`,
+ * or by using the compiler argument `-Xopt-in=kotlin.reflect.jvm.ExperimentalReflectionOnLambdas`.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+@Retention(AnnotationRetention.BINARY)
+@Target(
+    CLASS,
+    ANNOTATION_CLASS,
+    PROPERTY,
+    FIELD,
+    LOCAL_VARIABLE,
+    VALUE_PARAMETER,
+    CONSTRUCTOR,
+    FUNCTION,
+    PROPERTY_GETTER,
+    PROPERTY_SETTER,
+    TYPEALIAS
+)
+@MustBeDocumented
+@SinceKotlin("1.5")
+annotation class ExperimentalReflectionOnLambdas

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-reflect.txt

@@ -66,6 +66,9 @@ public final class kotlin/reflect/full/NoSuchPropertyException : java/lang/Excep
 	public synthetic fun <init> (Ljava/lang/Exception;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 }
 
+public abstract interface annotation class kotlin/reflect/jvm/ExperimentalReflectionOnLambdas : java/lang/annotation/Annotation {
+}
+
 public final class kotlin/reflect/jvm/KCallablesJvm {
 	public static final fun isAccessible (Lkotlin/reflect/KCallable;)Z
 	public static final fun setAccessible (Lkotlin/reflect/KCallable;Z)V