[Gradle] Rename experimental annotations to opt-in annotations in DSL

Methods and accessors with old names are preserved in public API and marked as deprecated now
#KT-38111 In Progress

libraries/tools/kotlin-gradle-plugin-api/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/LanguageSettingsBuilder.kt

@@ -18,7 +18,10 @@ interface LanguageSettingsBuilder : LanguageSettings {
 
     override val enabledLanguageFeatures: Set<String>
 
+    @Deprecated("Unsupported and will be removed in next major releases", replaceWith = ReplaceWith("optInAnnotation(name)"))
     fun useExperimentalAnnotation(name: String)
 
+    fun optInAnnotation(name: String)
+
     override val experimentalAnnotationsInUse: Set<String>
 }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/GradleProjectModuleBuilder.kt

@@ -165,7 +165,7 @@ class GradleProjectModuleBuilder(private val addInferredSourceSetVisibilityAsExp
                             ?: listOf(compilation.defaultSourceSetName)
 
                     variantNames.forEach { variantName ->
-                        val variant = BasicKotlinModuleVariant(this@apply, variantName, DefaultLanguageSettingsBuilder())
+                        val variant = BasicKotlinModuleVariant(this@apply, variantName, DefaultLanguageSettingsBuilder(project))
                         moduleByFragment[variant] = this@apply
                         variantToCompilation[variant] = compilation
                         fragments.add(variant)

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/DependencyGraphResolver.kt

@@ -48,7 +48,11 @@ class GradleKotlinDependencyGraphResolver(
 
         fun getKotlinModuleFromComponentResult(component: ResolvedComponentResult): KotlinModule =
             moduleResolver.resolveDependency(requestingModule, component.toModuleDependency())
-                ?: buildSyntheticPlainModule(component, component.variants.singleOrNull()?.displayName ?: "default")
+                ?: buildSyntheticPlainModule(
+                    component,
+                    component.variants.singleOrNull()?.displayName ?: "default",
+                    requestingModule.project
+                )
 
         fun nodeFromModule(componentResult: ResolvedComponentResult, kotlinModule: KotlinModule): GradleDependencyGraphNode {
             val id = kotlinModule.moduleIdentifier

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/DependencyResolution.kt

@@ -117,11 +117,12 @@ class GradleModuleDependencyResolver(
 // TODO think about multi-variant stub modules for non-Kotlin modules which got more than one chosen variant
 internal fun buildSyntheticPlainModule(
     resolvedComponentResult: ResolvedComponentResult,
-    singleVariantName: String
+    singleVariantName: String,
+    project: Project
 ): ExternalPlainKotlinModule {
     val moduleDependency = resolvedComponentResult.toModuleDependency()
     return ExternalPlainKotlinModule(BasicKotlinModule(moduleDependency.moduleIdentifier).apply {
-        BasicKotlinModuleVariant(this@apply, singleVariantName, DefaultLanguageSettingsBuilder()).apply {
+        BasicKotlinModuleVariant(this@apply, singleVariantName, DefaultLanguageSettingsBuilder(project)).apply {
             fragments.add(this)
             this.declaredModuleDependencies.addAll(
                 resolvedComponentResult.dependencies

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinGradleFragment.kt

@@ -37,7 +37,7 @@ open class KotlinGradleFragmentInternal @Inject constructor(
     // TODO pull up to KotlinModuleFragment
     // FIXME apply to compilation
     // FIXME check for consistency
-    override val languageSettings: LanguageSettingsBuilder = DefaultLanguageSettingsBuilder()
+    override val languageSettings: LanguageSettingsBuilder = DefaultLanguageSettingsBuilder(project)
 
     override fun refines(other: KotlinGradleFragment) {
         checkCanRefine(other)

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/sources/ConsistencyChecker.kt

@@ -48,16 +48,16 @@ internal class FragmentConsistencyChecks<T>(
         consistencyConditionHint = unstableFeaturesHint
     )
 
-    private val experimentalAnnotationsInUseHint = "The dependent $unitName must use all experimental annotations that its dependency uses."
+    private val optInAnnotationsInUseHint = "The dependent $unitName must use all opt-in annotations that its dependency uses."
 
-    val experimentalAnnotationsCheck = ConsistencyCheck<T, Set<String>>(
-        name = "set of experimental annotations in use",
-        getValue = { unit -> unit.languageSettings().experimentalAnnotationsInUse },
+    val optInAnnotationsCheck = ConsistencyCheck<T, Set<String>>(
+        name = "set of opt-in annotations in use",
+        getValue = { unit -> unit.languageSettings().optInAnnotationsInUse },
         leftExtendsRightConsistently = { left, right -> left.containsAll(right) },
-        consistencyConditionHint = experimentalAnnotationsInUseHint
+        consistencyConditionHint = optInAnnotationsInUseHint
     )
 
-    val allChecks = listOf(languageVersionCheck, unstableFeaturesCheck, experimentalAnnotationsCheck)
+    val allChecks = listOf(languageVersionCheck, unstableFeaturesCheck, optInAnnotationsCheck)
 }
 
 internal class FragmentConsistencyChecker<T>(

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/sources/DefaultKotlinSourceSet.kt

@@ -65,7 +65,7 @@ class DefaultKotlinSourceSet(
         filter.include("**/*.kts")
     }
 
-    override val languageSettings: LanguageSettingsBuilder = DefaultLanguageSettingsBuilder()
+    override val languageSettings: LanguageSettingsBuilder = DefaultLanguageSettingsBuilder(project)
 
     override val resources: SourceDirectorySet = createDefaultSourceDirectorySet(project, "$name resources")
 

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/sources/DefaultLanguageSettingsBuilder.kt

@@ -6,6 +6,7 @@
 package org.jetbrains.kotlin.gradle.plugin.sources
 
 import org.gradle.api.InvalidUserDataException
+import org.gradle.api.Project
 import org.gradle.api.file.FileCollection
 import org.gradle.api.provider.Provider
 import org.gradle.api.tasks.SourceTask
@@ -17,11 +18,12 @@ import org.jetbrains.kotlin.gradle.plugin.LanguageSettingsBuilder
 import org.jetbrains.kotlin.gradle.plugin.statistics.KotlinBuildStatsService
 import org.jetbrains.kotlin.gradle.tasks.AbstractKotlinCompile
 import org.jetbrains.kotlin.gradle.tasks.AbstractKotlinNativeCompile
+import org.jetbrains.kotlin.gradle.utils.SingleWarningPerBuild
 import org.jetbrains.kotlin.project.model.LanguageSettings
 import org.jetbrains.kotlin.statistics.metrics.BooleanMetrics
 import org.jetbrains.kotlin.statistics.metrics.StringMetrics
 
-internal class DefaultLanguageSettingsBuilder : LanguageSettingsBuilder {
+internal class DefaultLanguageSettingsBuilder(@Transient private val project: Project) : LanguageSettingsBuilder {
     private var languageVersionImpl: LanguageVersion? = null
 
     override var languageVersion: String?
@@ -60,12 +62,33 @@ internal class DefaultLanguageSettingsBuilder : LanguageSettingsBuilder {
         enabledLanguageFeaturesImpl += languageFeature
     }
 
-    private val experimentalAnnotationsInUseImpl = mutableSetOf<String>()
+    private val optInAnnotationsInUseImpl = mutableSetOf<String>()
 
-    override val experimentalAnnotationsInUse: Set<String> = experimentalAnnotationsInUseImpl
+    override val optInAnnotationsInUse: Set<String> = optInAnnotationsInUseImpl
+
+    override val experimentalAnnotationsInUse: Set<String>
+        get() {
+            SingleWarningPerBuild.deprecation(
+                project,
+                "Kotlin language settings property",
+                "experimentalAnnotationsInUse",
+                "optInAnnotationsInUse"
+            )
+            return optInAnnotationsInUse
+        }
+
+    override fun optInAnnotation(name: String) {
+        optInAnnotationsInUseImpl += name
+    }
 
     override fun useExperimentalAnnotation(name: String) {
-        experimentalAnnotationsInUseImpl += name
+        SingleWarningPerBuild.deprecation(
+            project,
+            "Kotlin language settings function",
+            "useExperimentalAnnotation",
+            "optInAnnotation"
+        )
+        optInAnnotation(name)
     }
 
     /* A Kotlin task that is responsible for code analysis of the owner of this language settings builder. */
@@ -114,10 +137,10 @@ internal fun applyLanguageSettingsToKotlinOptions(
             add("-XXLanguage:+$featureName")
         }
     
-        languageSettingsBuilder.experimentalAnnotationsInUse.forEach { annotationName ->
+        languageSettingsBuilder.optInAnnotationsInUse.forEach { annotationName ->
             add("-Xopt-in=$annotationName")
         }
-    
+
         if (languageSettingsBuilder is DefaultLanguageSettingsBuilder) {
             addAll(languageSettingsBuilder.freeCompilerArgs)
         }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/targets/native/tasks/KotlinNativeTasks.kt

@@ -423,8 +423,12 @@ constructor(
     val enabledLanguageFeatures: Set<String>
         @Input get() = languageSettings.enabledLanguageFeatures
 
+    @Deprecated("Unsupported and will be removed in next major releases", replaceWith = ReplaceWith("optInAnnotationsInUse"))
     val experimentalAnnotationsInUse: Set<String>
-        @Input get() = languageSettings.experimentalAnnotationsInUse
+        @Internal get() = languageSettings.experimentalAnnotationsInUse
+
+    val optInAnnotationsInUse: Set<String>
+        @Input get() = languageSettings.optInAnnotationsInUse
     // endregion.
 
     // region Kotlin options.
@@ -457,7 +461,7 @@ constructor(
         enabledLanguageFeatures.forEach { featureName ->
             add("-XXLanguage:+$featureName")
         }
-        experimentalAnnotationsInUse.forEach { annotationName ->
+        optInAnnotationsInUse.forEach { annotationName ->
             add("-Xopt-in=$annotationName")
         }
     }
@@ -622,7 +626,7 @@ constructor(
             it.enabledLanguageFeatures.forEach { featureName ->
                 add("-XXLanguage:+$featureName")
             }
-            it.experimentalAnnotationsInUse.forEach { annotationName ->
+            it.optInAnnotationsInUse.forEach { annotationName ->
                 add("-Xopt-in=$annotationName")
             }
         }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/utils/singleAction.kt

@@ -35,4 +35,9 @@ internal object SingleWarningPerBuild {
     fun show(project: Project, warningText: String) = SingleActionPerBuild.run(project, ACTION_ID_SHOW_WARNING + warningText) {
         project.logger.warn(warningText)
     }
+
+    fun deprecation(project: Project, context: String, target: String, replacement: String?) {
+        val replacementMessage = replacement?.let { " Please, use '$replacement' instead." } ?: ""
+        show(project, "Warning: $context '$target' is deprecated and will be removed in next major releases.$replacementMessage\n")
+    }
 }

libraries/tools/kotlin-project-model/src/main/kotlin/LanguageSettings.kt

@@ -10,5 +10,8 @@ interface LanguageSettings {
     val apiVersion: String?
     val progressiveMode: Boolean
     val enabledLanguageFeatures: Set<String>
+
+    @Deprecated("Unsupported and will be removed in next major releases", replaceWith = ReplaceWith("optInAnnotationsInUse"))
     val experimentalAnnotationsInUse: Set<String>
+    val optInAnnotationsInUse: Set<String>
 }