Implement filePathPattern in the script configuration with handling

also
- tests
- extending kdoc for the definitions

compiler/testData/codegen/customScript/pathPattern5.kts

@@ -0,0 +1,8 @@
+
+// KOTLIN_SCRIPT_DEFINITION: org.jetbrains.kotlin.codegen.TestScriptWithPathPattern
+
+// param: World
+
+val res = "Hello $name2"
+
+// expected: res=Hello World

compiler/tests/org/jetbrains/kotlin/codegen/AbstractCustomScriptCodegenTest.kt

@@ -149,3 +149,7 @@ abstract class TestScriptWithSimpleEnvVars
 @Suppress("unused")
 @KotlinScript(fileExtension = "customext")
 abstract class TestScriptWithNonKtsExtension(val name: String)
+
+@Suppress("unused")
+@KotlinScript(filePathPattern = "(.*/)?pathPattern[0-9]\\..+")
+abstract class TestScriptWithPathPattern(val name2: String)

compiler/tests/org/jetbrains/kotlin/codegen/CustomScriptCodegenTestGenerated.java

@@ -29,6 +29,11 @@ public class CustomScriptCodegenTestGenerated extends AbstractCustomScriptCodege
         KotlinTestUtils.assertAllTestsPresentByMetadata(this.getClass(), new File("compiler/testData/codegen/customScript"), Pattern.compile("^(.*)$"), TargetBackend.ANY, true);
     }
 
+    @TestMetadata("pathPattern5.kts")
+    public void testPathPattern5_kts() throws Exception {
+        runTest("compiler/testData/codegen/customScript/pathPattern5.kts");
+    }
+
     @TestMetadata("simpleEnvVars.kts")
     public void testSimpleEnvVars_kts() throws Exception {
         runTest("compiler/testData/codegen/customScript/simpleEnvVars.kts");

libraries/scripting/common/src/kotlin/script/experimental/annotations/scriptAnnotations.kt

@@ -25,6 +25,9 @@ import kotlin.script.experimental.api.ScriptEvaluationConfiguration
  * @param fileExtension distinct filename extension for the script type being defined, stored in the configuration
  *        as {@link ScriptCompilationConfigurationKeys#fileExtension},
  *        default - "kts"
+ * @param filePathPattern additional (to the filename extension) RegEx pattern with that the script file path is checked
+ *        as {@link ScriptCompilationConfigurationKeys#filePathPattern},
+ *        default - empty - pattern is not used
  * @param compilationConfiguration an object or a class with default constructor containing initial script compilation configuration
  *        default - {@link ScriptCompilationConfiguration#Default}
  * @param evaluationConfiguration an object or a class with default constructor containing initial script evaluation configuration
@@ -47,6 +50,7 @@ import kotlin.script.experimental.api.ScriptEvaluationConfiguration
 annotation class KotlinScript(
     val displayName: String = "Kotlin script",
     val fileExtension: String = "kts",
+    val filePathPattern: String = "",
     val compilationConfiguration: KClass<out ScriptCompilationConfiguration> = ScriptCompilationConfiguration.Default::class,
     val evaluationConfiguration: KClass<out ScriptEvaluationConfiguration> = ScriptEvaluationConfiguration.Default::class
 )

libraries/scripting/common/src/kotlin/script/experimental/api/scriptCompilation.kt

@@ -3,7 +3,7 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
  */
 
-@file:Suppress("unused")
+@file:Suppress("unused", "RemoveExplicitTypeArguments")
 
 package kotlin.script.experimental.api
 
@@ -59,9 +59,21 @@ val ScriptCompilationConfigurationKeys.displayName by PropertiesCollection.key<S
 
 /**
  * The script filename extension
+ * Used for the primary script definition selection as well as to assign a kotlin-specific file type to the files with the extension in Intellij IDEA
+ * For Intellij IDEA support, it is important to have this extension set to a non-ambiguous name.
+ * See also {@link ScriptCompilationConfigurationKeys#filePathPattern} parameter for more fine-grained script definition selection
  */
 val ScriptCompilationConfigurationKeys.fileExtension by PropertiesCollection.key<String>("kts")
 
+/**
+ * Additional (to the filename extension) RegEx pattern with that the script file path is checked
+ * It is used in the hosts that may have several script definitions registered and need to distinguish script file types not only by extension
+ * The argument passed to the RegEx matcher is equivalent to the File.path, taken relatively from a base path defined by the host
+ * (usually should be the project root or the current directory)
+ * See also {@link ScriptCompilationConfigurationKeys#fileExtension} parameter for the primary script definition selection
+ */
+val ScriptCompilationConfigurationKeys.filePathPattern by PropertiesCollection.key<String>()
+
 /**
  * The superclass for target script class
  */

libraries/scripting/common/src/kotlin/script/experimental/host/configurationFromTemplate.kt

@@ -78,6 +78,9 @@ private fun ScriptCompilationConfiguration.Builder.propertiesFromTemplate(
     if (fileExtension() == null) {
         fileExtension(mainAnnotation.fileExtension)
     }
+    if (filePathPattern() == null) {
+        filePathPattern(mainAnnotation.filePathPattern)
+    }
     if (displayName() == null) {
         displayName(mainAnnotation.displayName)
     }

plugins/scripting/scripting-compiler-impl/src/org/jetbrains/kotlin/scripting/definitions/ScriptDefinition.kt

@@ -120,7 +120,15 @@ abstract class ScriptDefinition : UserDataHolderBase() {
             )
         }
 
-        override fun isScript(file: File): Boolean = file.name.endsWith(".$fileExtension")
+        private val filePathPattern by lazy {
+            compilationConfiguration[ScriptCompilationConfiguration.filePathPattern]?.takeIf { it.isNotBlank() }
+        }
+
+        override fun isScript(file: File): Boolean =
+            file.name.endsWith(".$fileExtension") &&
+                    (filePathPattern?.let {
+                        Regex(it).matches(file.path)
+                    } ?: true)
 
         override val fileExtension: String get() = compilationConfiguration[ScriptCompilationConfiguration.fileExtension]!!