[build] add checks to ensure that no modules which are part of the IDE plugin do not use experimental stdlib API

to ensure binary compatibility with stdlib inside IntelliJ.

This includes using the latest stable kotlin API version and
forbidding using experimental declarations from stdlib.

^KT-62510

libraries/tools/ide-plugin-dependencies-validator/README.md

@@ -0,0 +1,42 @@
+# IDE Plugin Dependencies Validator
+
+Some projects inside the Kotlin repository are used inside the IntelliJ Kotlin plugin. Those projects have special restrictions forbidding
+experimental Kotlin stdlib API use in them. The `:tools:ide-plugin-dependencies-validator` project is a tool to check that those
+restrictions are not violated.
+
+See [KTIJ-20529](https://youtrack.jetbrains.com/issue/KTIJ-20529).
+
+## Details
+
+IntelliJ IDEA has its own bundled Kotlin stdlib, which is used across the IntelliJ repository. This stdlib is usually the latest available
+stable Kotlin stdlib. Kotlin repository is compiled against a snapshot Kotlin stdlib. So, the projects from the Kotlin repository,
+which bundle to IntelliJ, are compiled against snapshot stdlib, but on the runtime in IntelliJ, there is a fixed and stable version of
+Kotlin stdlib. To avoid binary compatibility problems that may arise at runtime in IntelliJ, experimental stdlib declarations for which
+binary compatibility is not guaranteed are not allowed to be used inside Kotlin projects used in IntelliJ.
+
+The list of such projects used inside IntelliJ Kotlin Plugin can be found at `projectsUsedInIntelliJKotlinPlugin` property
+inside [the root build.gradle.kts](build.gradle.kts)
+
+## Checks
+
+The tool checks on all projects defined in `projectsUsedInIntelliJKotlinPlugin`.
+
+* No opt-ins for experimental stdlib annotations are used inside the source code. The check works by syntax only, and no code resolution is
+  performed. This is not a hundred percent reliable, but it usually works unless there is a name conflict with experimental opt-in
+  annotations
+  from stdlib. The code for those checks can be found at `org.jetbrains.Kotlin.ide.plugin.dependencies.validator` package.
+* The Kotlin API version used is the same as the version of Kotlin stdlib used inside the IntelliJ Platform. This is defined
+  by `kotlinApiVersionForProjectsUsedInIntelliJKotlinPlugin` property.
+* No opt-ins for experimental stdlib annotations are used inside the build definition files. The check works by
+  checking that no `-opt-in` arguments with experimental stdlib annotations are defined
+  in `KotlinJvmCompile.KotlinOptions.freeCompilerArgs`.
+
+## Running Checks
+
+`gradle :tools:ide-plugin-dependencies-validator:checkIdeDependenciesConfiguration` task runs the check. It consists of two subtasks:
+
+* `gradle :tools:ide-plugin-dependencies-validator:checkIdeDependenciesConfiguration` task checks the build configuration of projects.
+* `gradle :tools:ide-plugin-dependencies-validator:run` task checks Kotlin source files inside the project for experimental annotations
+  usages.
+
+