Deprecate -Xexperimental compiler argument

This option is not widely used and its implementation relies on a
complicated mechanism of a module-wide metadata, which is not properly
supported in the IDE (see IdeModuleAnnotationsResolver).

 #KT-34649 Fixed

compiler/cli/cli-common/src/org/jetbrains/kotlin/cli/common/arguments/CommonCompilerArguments.kt

@@ -328,7 +328,11 @@ abstract class CommonCompilerArguments : CommonToolArguments() {
         return HashMap<AnalysisFlag<*>, Any>().apply {
             put(AnalysisFlags.skipMetadataVersionCheck, skipMetadataVersionCheck)
             put(AnalysisFlags.multiPlatformDoNotCheckActual, noCheckActual)
-            put(AnalysisFlags.experimental, experimental?.toList().orEmpty())
+            val experimentalFqNames = experimental?.toList().orEmpty()
+            if (experimentalFqNames.isNotEmpty()) {
+                put(AnalysisFlags.experimental, experimentalFqNames)
+                collector.report(CompilerMessageSeverity.WARNING, "'-Xexperimental' is deprecated and will be removed in a future release")
+            }
             put(AnalysisFlags.useExperimental, useExperimental?.toList().orEmpty())
             put(AnalysisFlags.explicitApiVersion, apiVersion != null)
             put(AnalysisFlags.allowResultReturnType, allowResultReturnType)

compiler/testData/cli/jvm/experimentalDeprecatedWarning.out

@@ -1,3 +1,4 @@
+warning: '-Xexperimental' is deprecated and will be removed in a future release
 warning: experimental API marker org.test.Warning2 is deprecated. Warning2
 warning: experimental API marker org.test.Warning1 is deprecated. Warning1
 OK

compiler/testData/cli/jvm/experimentalIsNotAnnotation.out

@@ -1,3 +1,4 @@
+warning: '-Xexperimental' is deprecated and will be removed in a future release
 warning: class org.test.NotAnAnnotation1 is not an experimental API marker annotation
 warning: class org.test.NotAnAnnotation2 is not an experimental API marker annotation
 OK

compiler/testData/cli/jvm/experimentalIsNotMarker.out

@@ -1,3 +1,4 @@
+warning: '-Xexperimental' is deprecated and will be removed in a future release
 warning: class org.test.NotAMarker1 is not an experimental API marker annotation
 warning: class org.test.NotAMarker2 is not an experimental API marker annotation
 OK

compiler/testData/cli/jvm/experimentalNested.out

@@ -1 +1,2 @@
+warning: '-Xexperimental' is deprecated and will be removed in a future release
 OK

compiler/testData/cli/jvm/experimentalUnresolved.out

@@ -1,3 +1,4 @@
+warning: '-Xexperimental' is deprecated and will be removed in a future release
 warning: experimental API marker org.test.Unresolved2 is unresolved. Please make sure it's present in the module dependencies
 warning: experimental API marker org.test.Unresolved1 is unresolved. Please make sure it's present in the module dependencies
 warning: experimental API marker org.test.Unresolved3 is unresolved. Please make sure it's present in the module dependencies