[Build, Gradle] Introduce ad-hoc deprecation of classes bundled into …

…fat jar

The intention is to mark all the compiler classes bundled into KGP as deprecated to discourage their usage and provide a proper migration guide via the deprecation message
^KT-70251 In Progress
Relates to KT-70543

gradle/libs.versions.toml

@@ -40,6 +40,7 @@ compose-snapshot-version = "1.8.0-SNAPSHOT"
 ant = "1.10.14"
 kotlin-for-gradle-plugins-compilation = "2.0.20-RC"
 intellij-asm = "9.0"
+diff-utils = "4.12"
 # Wasm specific
 wasmedge = "0.14.0"
 
@@ -99,6 +100,7 @@ xerces = { module = "xerces:xercesImpl", version.ref = "xerces" }
 
 ant = { module = "org.apache.ant:ant", version.ref = "ant" }
 intellij-asm = { module = "org.jetbrains.intellij.deps:asm-all", version.ref = "intellij-asm" }
+diff-utils = { module = "io.github.java-diff-utils:java-diff-utils", version.ref = "diff-utils" }
 
 [plugins]
 jetbrains-ideaExt = { id = "org.jetbrains.gradle.plugin.idea-ext", version.ref = "jetbrains-ideaExt" }

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle71Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle74Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle75Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle76Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle80Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle81Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle82Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Gradle85Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/asm-deprecation/Jar.deprecations

@@ -0,0 +1,29 @@
+The following packages are (non-transitively) deprecated by the `asm-deprecating-transformer` plugin:
+package org.jetbrains.kotlin
+package org.jetbrains.kotlin.build.report
+package org.jetbrains.kotlin.build.report.metrics
+package org.jetbrains.kotlin.cli.common
+package org.jetbrains.kotlin.cli.common.arguments
+package org.jetbrains.kotlin.cli.common.environment
+package org.jetbrains.kotlin.cli.common.fir
+package org.jetbrains.kotlin.cli.common.messages
+package org.jetbrains.kotlin.cli.common.modules
+package org.jetbrains.kotlin.cli.common.output
+package org.jetbrains.kotlin.cli.common.profiling
+package org.jetbrains.kotlin.cli.common.repl
+package org.jetbrains.kotlin.cli.jvm
+package org.jetbrains.kotlin.cli.jvm.compiler
+package org.jetbrains.kotlin.cli.jvm.compiler.pipeline
+package org.jetbrains.kotlin.cli.jvm.config
+package org.jetbrains.kotlin.cli.jvm.plugins
+package org.jetbrains.kotlin.cli.metadata
+package org.jetbrains.kotlin.cli.plugins
+package org.jetbrains.kotlin.compiler.plugin
+package org.jetbrains.kotlin.compilerRunner
+package org.jetbrains.kotlin.compilerRunner.btapi
+package org.jetbrains.kotlin.config
+package org.jetbrains.kotlin.incremental
+package org.jetbrains.kotlin.incremental.components
+package org.jetbrains.kotlin.incremental.js
+package org.jetbrains.kotlin.incremental.storage
+package org.jetbrains.kotlin.util.capitalizeDecapitalize

libraries/tools/kotlin-gradle-plugin/build.gradle.kts

@@ -6,6 +6,7 @@ plugins {
     id("gradle-plugin-common-configuration")
     id("org.jetbrains.kotlinx.binary-compatibility-validator")
     id("android-sdk-provisioner")
+    id("asm-deprecating-transformer")
 }
 
 repositories {
@@ -266,6 +267,57 @@ tasks {
              */
             pivotVersion = KotlinMetadataPivotVersion(1, 6, 0)
         }
+        asmDeprecation {
+            val exclusions = listOf(
+                "org.jetbrains.kotlin.gradle.**", // part of the plugin
+                "org.jetbrains.kotlin.project.model.**", // part of the plugin
+                "org.jetbrains.kotlin.statistics.**", // part of the plugin
+                "org.jetbrains.kotlin.swiftexport.ExperimentalSwiftExportDsl", // part of the plugin
+                "org.jetbrains.kotlin.tooling.**", // part of the plugin
+                "org.jetbrains.kotlin.org.**", // already shadowed dependencies
+                "org.jetbrains.kotlin.com.**", // already shadowed dependencies
+                "org.jetbrains.kotlin.it.unimi.**", // already shadowed dependencies
+                "org.jetbrains.kotlin.internal.**", // already internal package
+            )
+            val deprecationMessage = """
+                You're using a Kotlin compiler class bundled into KGP for its internal needs.
+                This is discouraged and will not be supported in future releases.
+                The class in this artifact is scheduled for removal in Kotlin 2.2. Please define dependency on it in an alternative way.
+                See https://kotl.in/gradle/internal-compiler-symbols for more details
+            """.trimIndent()
+            deprecateClassesByPattern("org.jetbrains.kotlin.**", deprecationMessage, exclusions)
+        }
+    }
+    GradlePluginVariant.values().forEach { variant ->
+        val sourceSet = sourceSets.getByName(variant.sourceSetName)
+        val taskSuffix = sourceSet.jarTaskName.capitalize()
+        val shadowJarTaskName = "$EMBEDDABLE_COMPILER_TASK_NAME$taskSuffix"
+        asmDeprecation {
+            val dumpTask = registerDumpDeprecationsTask(shadowJarTaskName, taskSuffix)
+            val dumpAllTask = getOrCreateTask<Task>("dumpDeprecations") {
+                dependsOn(dumpTask)
+            }
+            val expectedFileDoesNotExistMessage = """
+                The file with expected deprecations for the compiler modules bundled into KGP does not exist.
+                Run ./gradlew ${project.path}:${dumpTask.name} first to create it.
+                You may also use ./gradlew ${project.path}:${dumpAllTask.name} to dump deprecations of all fat jars.
+                Context: https://youtrack.jetbrains.com/issue/KT-70251
+            """.trimIndent()
+            val checkFailureMessage = """
+                Expected deprecations applied to the compiler modules bundled into KGP does not match with the actually applied ones.
+                Run ./gradlew ${project.path}:${dumpTask.name} to see the difference.
+                You may also use ./gradlew ${project.path}:${dumpAllTask.name} to dump deprecations of all fat jars.
+                Use INFO level log for the exact deprecated classes set.
+                Either commit the difference or adjust the package relocation rules in ${buildFile.absolutePath}
+                Please be sure to leave a comment explaining any changes related to this failure clear enough.
+                Context: https://youtrack.jetbrains.com/issue/KT-70251
+            """.trimIndent()
+            val checkTask =
+                registerCheckDeprecationsTask(shadowJarTaskName, taskSuffix, expectedFileDoesNotExistMessage, checkFailureMessage)
+            named("check") {
+                dependsOn(checkTask)
+            }
+        }
     }
 }
 

repo/codebase-tests/tests/org/jetbrains/kotlin/code/CodeConformanceTest.kt

@@ -140,6 +140,7 @@ class CodeConformanceTest : TestCase() {
                 "repo/gradle-build-conventions/generators/build/generated-sources",
                 "repo/gradle-build-conventions/compiler-tests-convention/build/generated-sources",
                 "repo/gradle-build-conventions/android-sdk-provisioner/build/generated-sources",
+                "repo/gradle-build-conventions/asm-deprecating-transformer/build/generated-sources",
                 ".gradle/expanded",
             )
         )