feat: Use @file:ProjectCoordinates in --export-to-gradle-project

This commit enhances the `--export-to-gradle-project` feature by allowing kscripts to define their own target Maven coordinates (groupId, artifactId, version) via a new `@file:ProjectCoordinates` annotation.

Key changes:

1.  **Annotation Parsing (`Script.kt`, `Parser.kt`, `model/ProjectCoordinates.kt`):**
    - I introduced a new data class `model.ProjectCoordinates` to hold `group`, `artifact`, and `version`.
    - The `Script` model now includes an optional `projectCoordinates` field.
    - I updated `LineParser.kt` and `Parser.kt` to recognize and parse `@file:ProjectCoordinates(group="...", artifact="...", version="...")` annotations from script files.
    - The parsed coordinates are stored in the `Script` object via `ResolutionContext` and `SectionResolver`.

2.  **Project Generation (`generator/ProjectGenerator.kt`):**
    - The `exportToGradleProject` function now retrieves any `ProjectCoordinates` defined in the script.
    - These script-defined coordinates are prioritized when setting:
        - `group` in `build.gradle.kts`.
        - `version` in `build.gradle.kts`.
        - `rootProject.name` in `settings.gradle.kts` (derived from the artifactId).
    - Fallback logic (using script package name, output directory name, or defaults) is retained if the annotation or specific attributes are missing.
    - The package path for source files (`src/main/kotlin/...`, `src/test/kotlin/...`) and the `package` declaration in the generated `.kt` file are now based on the `effectiveProjectGroup` (derived from the annotation or fallbacks).
    - Default `mainClassName` derivation also uses `effectiveProjectGroup`.

This makes the project generation feature more declarative, allowing the script itself to be the source of truth for its intended Maven identity when being "graduated" into a full Gradle project.

Author: google-labs-jules[bot]

src/main/kotlin/io/github/kscripting/kscript/generator/ProjectGenerator.kt

@@ -48,21 +48,37 @@ fun exportToGradleProject(scriptFilePathString: String, outputDir: Path, cliOpti
             infoMsg("Successfully created directory: $outputDir")
         }
 
-        // 1. Determine Project Properties
-        val projectName = outputDir.fileName.toString()
-        // Try to use script package name for group, fallback to default
-        val projectGroup = if (script.packageName.value.isNotBlank()) script.packageName.value else "com.example"
-        val projectVersion = "1.0-SNAPSHOT" // Default version
+        // 1. Determine Project Properties, prioritizing @file:ProjectCoordinates
+        val scriptCoordinates = script.projectCoordinates
+
+        if (scriptCoordinates != null && (scriptCoordinates.group != null || scriptCoordinates.artifact != null || scriptCoordinates.version != null)) {
+            infoMsg("Using project coordinates from @file:ProjectCoordinates annotation:")
+            scriptCoordinates.group?.let { infoMsg("  Group: $it") }
+            scriptCoordinates.artifact?.let { infoMsg("  Artifact: $it") }
+            scriptCoordinates.version?.let { infoMsg("  Version: $it") }
+        }
+
+        val effectiveProjectGroup = scriptCoordinates?.group?.takeIf { it.isNotBlank() }
+            ?: script.packageName.value.takeIf { it.isNotBlank() }
+            ?: "com.example"
+
+        val effectiveArtifactId = scriptCoordinates?.artifact?.takeIf { it.isNotBlank() }
+            ?: outputDir.fileName.toString()
+
+        val effectiveProjectVersion = scriptCoordinates?.version?.takeIf { it.isNotBlank() }
+            ?: "1.0-SNAPSHOT"
+
+        val projectNameForSettings = effectiveArtifactId // For settings.gradle.kts rootProject.name
 
-        infoMsg("Project Name: $projectName")
-        infoMsg("Project Group: $projectGroup")
-        infoMsg("Project Version: $projectVersion")
+        infoMsg("Effective Project Name (for settings.gradle.kts): $projectNameForSettings")
+        infoMsg("Effective Project Group: $effectiveProjectGroup")
+        infoMsg("Effective Project Version: $effectiveProjectVersion")
 
         // 2. Create standard project directories
-        val srcMainKotlinPath = projectGroup.replace(".", "/")
-        val srcMainKotlinDir = outputDir.resolve("src/main/kotlin").resolve(srcMainKotlinPath)
+        val packagePath = effectiveProjectGroup.replace(".", "/")
+        val srcMainKotlinDir = outputDir.resolve("src/main/kotlin").resolve(packagePath)
         val srcMainResourcesDir = outputDir.resolve("src/main/resources")
-        val srcTestKotlinDir = outputDir.resolve("src/test/kotlin").resolve(srcMainKotlinPath)
+        val srcTestKotlinDir = outputDir.resolve("src/test/kotlin").resolve(packagePath)
         val srcTestResourcesDir = outputDir.resolve("src/test/resources")
 
         Files.createDirectories(srcMainKotlinDir)
@@ -77,7 +93,7 @@ fun exportToGradleProject(scriptFilePathString: String, outputDir: Path, cliOpti
         // 3. Generate settings.gradle.kts
         val settingsFile = outputDir.resolve("settings.gradle.kts")
         val settingsContent = """
-            |rootProject.name = "$projectName"
+            |rootProject.name = "$projectNameForSettings"
             |""".trimMargin()
         Files.writeString(settingsFile, settingsContent)
         infoMsg("Successfully generated: $settingsFile")
@@ -87,8 +103,8 @@ fun exportToGradleProject(scriptFilePathString: String, outputDir: Path, cliOpti
         val customReposString = script.repositories.joinToString("\n            ") { "maven { url = uri(\"${it.value}\") }" }
 
         // Determine main class name
-        val scriptBaseName = scriptFile.nameWithoutExtension.replaceFirstChar { if (it.isLowerCase()) it.titlecase() else it.toString() }
-        val mainClassName = script.entryPoint?.value ?: "${projectGroup}.${scriptBaseName}Kt"
+        val scriptBaseName = scriptFile.nameWithoutExtension.replaceFirstChar { if (it.isLowerCase()) it.titlecase(Locale.getDefault()) else it.toString() }
+        val mainClassName = script.entryPoint?.value?.takeIf { it.isNotBlank() } ?: "${effectiveProjectGroup}.${scriptBaseName}Kt"
 
         // Kotlin options and compiler options (basic for now)
         // More complex mapping can be done later. For now, just ensure jvmTarget.
@@ -100,8 +116,8 @@ fun exportToGradleProject(scriptFilePathString: String, outputDir: Path, cliOpti
         |    application
         |}
         |
-        |group = "$projectGroup"
-        |version = "$projectVersion"
+        |group = "$effectiveProjectGroup"
+        |version = "$effectiveProjectVersion"
         |
         |repositories {
         |    mavenCentral()
@@ -149,8 +165,8 @@ fun exportToGradleProject(scriptFilePathString: String, outputDir: Path, cliOpti
         val contentLines = mutableListOf<String>()
 
         // Add package declaration
-        if (projectGroup.isNotBlank()) {
-            contentLines.add("package $projectGroup")
+        if (effectiveProjectGroup.isNotBlank()) {
+            contentLines.add("package $effectiveProjectGroup")
             contentLines.add("") // Add a blank line after package
         }
 
@@ -234,7 +250,7 @@ fun exportToGradleProject(scriptFilePathString: String, outputDir: Path, cliOpti
             warnMsg("gradle-wrapper.properties not found in kscript project, skipping copy. Project will need 'gradle wrapper' task run manually.")
         }
 
-        infoMsg("Project generation for '$projectName' is complete.")
+        infoMsg("Project generation for '$projectNameForSettings' is complete.")
 
     } catch (e: Exception) {
         errorMsg("Error during project generation for $scriptFilePathString: ${e.message}")

src/main/kotlin/io/github/kscripting/kscript/model/ProjectCoordinates.kt

@@ -0,0 +1,12 @@
+package io.github.kscripting.kscript.model
+
+/**
+ * Represents project coordinates that can be defined in a kscript file
+ * via the `@file:ProjectCoordinates(group="...", artifact="...", version="...")` annotation.
+ * All properties are optional.
+ */
+data class ProjectCoordinates(
+    val group: String? = null,
+    val artifact: String? = null,
+    val version: String? = null
+) : ScriptAnnotation

src/main/kotlin/io/github/kscripting/kscript/model/Script.kt

@@ -18,6 +18,8 @@ data class Script(
     val compilerOpts: Set<CompilerOpt>,
     val deprecatedItems: Set<DeprecatedItem>,
 
+    val projectCoordinates: ProjectCoordinates? = null, // Added new field
+
     val scriptNodes: Set<ScriptNode>,
     val rootNode: ScriptNode,
 

src/main/kotlin/io/github/kscripting/kscript/parser/LineParser.kt

@@ -8,6 +8,12 @@ object LineParser {
     private const val deprecatedAnnotation = "Deprecated annotation:"
     private val sheBang = listOf(SheBang)
 
+    // Regex for @file:ProjectCoordinates(group="...", artifact="...", version="...")
+    private val PROJECT_COORDINATES_ANNOTATION_REGEX = Regex("""^@file:ProjectCoordinates\s*\((.*)\)""")
+    // Regex for parsing individual attributes like group="value", artifact='value', version=value
+    // It captures the key, and then one of the possible quote types for the value, or unquoted value.
+    private val ATTRIBUTE_REGEX = Regex("""(group|artifact|version)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s,)]+))""")
+
     fun parseSheBang(scriptLocation: ScriptLocation, line: Int, text: String): List<ScriptAnnotation> {
         if (text.startsWith("#!/")) {
             return sheBang
@@ -357,4 +363,49 @@ object LineParser {
         scriptLocation: ScriptLocation, line: Int, introText: String, existing: String, replacement: String
     ): DeprecatedItem =
         DeprecatedItem(scriptLocation, line, "$introText\n$existing\nshould be replaced with:\n$replacement")
+
+    fun parseProjectCoordinates(scriptLocation: ScriptLocation, line: Int, text: String): List<ScriptAnnotation> {
+        val trimmedText = text.trim()
+        val matchResult = PROJECT_COORDINATES_ANNOTATION_REGEX.find(trimmedText)
+
+        if (matchResult != null) {
+            val attributesString = matchResult.groupValues[1]
+            try {
+                val projectCoordinates = extractProjectCoordinatesFromAttributes(attributesString)
+                // It's possible to return an empty ProjectCoordinates if attributesString is empty or only whitespace
+                // We might want to consider if an empty coordinate set is a valid annotation or should be an error/emptyList()
+                return listOf(projectCoordinates)
+            } catch (e: ParseException) {
+                // Augment parse exception with location context
+                throw ParseException("Invalid @file:ProjectCoordinates annotation at $scriptLocation line $line: ${e.messageOriginal}", e)
+            }
+        }
+        return emptyList()
+    }
+
+    private fun extractProjectCoordinatesFromAttributes(attributesString: String): ProjectCoordinates {
+        var group: String? = null
+        var artifact: String? = null
+        var version: String? = null
+
+        if (attributesString.isBlank()) {
+            // Return default (all null) if attributes string is empty or blank
+            return ProjectCoordinates(null, null, null)
+        }
+
+        ATTRIBUTE_REGEX.findAll(attributesString).forEach { matchResult ->
+            val key = matchResult.groupValues[1]
+            // Value can be in group 2 (double-quoted), 3 (single-quoted), or 4 (unquoted)
+            val value = matchResult.groupValues[2].takeIf { it.isNotEmpty() }
+                ?: matchResult.groupValues[3].takeIf { it.isNotEmpty() }
+                ?: matchResult.groupValues[4]
+
+            when (key) {
+                "group" -> group = value
+                "artifact" -> artifact = value
+                "version" -> version = value
+            }
+        }
+        return ProjectCoordinates(group, artifact, version)
+    }
 }

src/main/kotlin/io/github/kscripting/kscript/parser/Parser.kt

@@ -15,6 +15,7 @@ class Parser {
         LineParser::parseCompilerOpts,
         LineParser::parseImport,
         LineParser::parsePackage,
+        LineParser::parseProjectCoordinates, // Added new parser function
     )
 
     fun parse(scriptLocation: ScriptLocation, string: String): List<Section> {

src/main/kotlin/io/github/kscripting/kscript/resolver/ResolutionContext.kt

@@ -20,4 +20,5 @@ data class ResolutionContext(
     val compilerOpts: MutableSet<CompilerOpt> = mutableSetOf(),
     val importNames: MutableSet<ImportName> = mutableSetOf(),
     val deprecatedItems: MutableSet<DeprecatedItem> = mutableSetOf(),
+    var projectCoordinates: ProjectCoordinates? = null, // Added for @file:ProjectCoordinates
 )

src/main/kotlin/io/github/kscripting/kscript/resolver/ScriptResolver.kt

@@ -174,6 +174,7 @@ class ScriptResolver(
             resolutionContext.kotlinOpts,
             resolutionContext.compilerOpts,
             resolutionContext.deprecatedItems,
+            resolutionContext.projectCoordinates, // Pass the new field
             resolutionContext.scriptNodes,
             scriptNode,
             digest

src/main/kotlin/io/github/kscripting/kscript/resolver/SectionResolver.kt

@@ -149,6 +149,18 @@ class SectionResolver(
             is DeprecatedItem -> {
                 resolutionContext.deprecatedItems.add(scriptAnnotation)
             }
+
+            is ProjectCoordinates -> {
+                if (resolutionContext.projectCoordinates == null) { // Process only the first one found
+                    resolutionContext.projectCoordinates = scriptAnnotation
+                }
+                // else {
+                // Potentially log a warning if multiple @file:ProjectCoordinates are found,
+                // but for now, we just keep the first one encountered.
+                // io.github.kscripting.kscript.util.Logger.warnMsg("Multiple @file:ProjectCoordinates annotations found. Using the first one: ${resolutionContext.projectCoordinates}")
+                // }
+                resolvedScriptAnnotations += scriptAnnotation // Add to section's annotations
+            }
         }
 
         return resolvedScriptAnnotations