Add composite script examples demonstrating .main.kts @file:Import functionality

Author: imbananko

jvm/main-kts/MainKts.md

@@ -72,4 +72,5 @@ with easy interaction with Kotlin code and can be executed:
   ```
   kotlin kotlin-shell.main.kts main-kts/example.txt
   ```
+- [`composite/composite.main.kts`](scripts/composite/composite.main.kts) demonstrates script composition capabilities via `@file:Import` annotation
 

jvm/main-kts/scripts/composite/composite.main.kts

@@ -0,0 +1,23 @@
+#!/usr/bin/env kotlin
+
+/**
+ * A script demonstrating the composition functionality of .main.kts scripts using imports.
+ *
+ * Key features:
+ * - Supports both relative and absolute paths for imports
+ * - Multiple imports using repeated annotations
+ * - All public top-level declarations (variables, functions, classes) from imported scripts
+ *   become available in the importing script
+ * - Each imported script is evaluated when imported, not just its declarations are included
+ * - Imported scripts are evaluated in the order they appear
+ *
+ * Note: Import resolution is performed relative to the importing script's location
+ * when using relative paths.
+ */
+
+
+@file:Import("kts/simple.kts")
+@file:Import("imported.main.kts")
+
+sharedMainKtsVar++
+println("simple.kts members: $ktsScriptClassMembers")

jvm/main-kts/scripts/composite/imported.main.kts

@@ -0,0 +1,4 @@
+var sharedMainKtsVar = 2
+
+// The __FILE__ variable contains the absolute path of the current .main.kts script
+println("Hi from $__FILE__")

jvm/main-kts/scripts/composite/kts/simple.kts

@@ -0,0 +1,11 @@
+import kotlin.reflect.full.declaredMembers
+
+// Kotlin scripts (.kts files) automatically include these dependencies:
+// 1. kotlin-script-runtime.jar - provides script-specific functionality
+val scriptArgs = args
+
+// 2. kotlin-stdlib.jar - provides the Kotlin standard library
+println("Hello from simple.kts! Args=$scriptArgs")
+
+// 3. kotlin-reflect.jar - provides reflection capabilities
+val ktsScriptClassMembers = this::class.declaredMembers