feat!: introduce a Kotlin DSL to configure simulations

.gitignore

@@ -66,5 +66,4 @@ scala_compiler.xml
 
 # Exceptions
 # Keep 'build' packages in src directories
-!**/src/**/build/
-!**/src/**/build/**
+!**/src/**/build/

alchemist-api/src/main/kotlin/it/unibo/alchemist/boundary/dsl/BuildDsl.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright (C) 2010-2025, Danilo Pianini and contributors
+ * listed, for each module, in the respective subproject's build.gradle.kts file.
+ *
+ * This file is part of Alchemist, and is distributed under the terms of the
+ * GNU General Public License, with a linking exception,
+ * as described in the file LICENSE in the Alchemist distribution's top directory.
+ */
+
+package it.unibo.alchemist.boundary.dsl
+
+/**
+ * Annotation used to mark classes that should have DSL builder functions generated.
+ * When applied to a class, the DSL processor will generate a builder function
+ * that can be used in Alchemist DSL scripts to create instances of the annotated class.
+ *
+ * @param functionName Custom name for the generated DSL function. If empty, defaults to
+ *   the lowercase version of the class name with the first character lowercased.
+ * @param scope Manual override for the context type. Valid values (case-insensitive):
+ *   - "SIMULATION" or "SIMULATION_CONTEXT" → SimulationContext
+ *   - "EXPORTER" or "EXPORTER_CONTEXT" → ExporterContext
+ *   - "GLOBAL_PROGRAMS" or "GLOBAL_PROGRAMS_CONTEXT" → GlobalProgramsContext
+ *   - "OUTPUT_MONITORS" or "OUTPUT_MONITORS_CONTEXT" → OutputMonitorsContext
+ *   - "TERMINATORS" or "TERMINATORS_CONTEXT" → TerminatorsContext
+ *   - "DEPLOYMENT" or "DEPLOYMENTS_CONTEXT" → DeploymentsContext
+ *   - "DEPLOYMENT_CONTEXT" → DeploymentContext (singular)
+ *   - "PROGRAM" or "PROGRAM_CONTEXT" → ProgramContext
+ *   - "PROPERTY" or "PROPERTY_CONTEXT" → PropertyContext
+ *   If empty, the context type is automatically determined based on the constructor parameters.
+ *   This allows manual context passing to override the default behavior.
+ * @param injectEnvironment Whether to inject an Environment parameter into the generated builder function.
+ * @param injectGenerator Whether to inject a Generator parameter into the generated builder function.
+ * @param injectNode Whether to inject a Node parameter into the generated builder function.
+ * @param injectReaction Whether to inject a Reaction parameter into the generated builder function.
+ */
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.SOURCE)
+annotation class BuildDsl(
+    val functionName: String = "",
+    val scope: String = "",
+    val injectEnvironment: Boolean = true,
+    val injectGenerator: Boolean = true,
+    val injectNode: Boolean = true,
+    val injectReaction: Boolean = true,
+)

alchemist-dsl-processor/build.gradle.kts

@@ -0,0 +1,25 @@
+import Libs.alchemist
+
+plugins {
+    id("kotlin-multiplatform-convention")
+}
+kotlin {
+    jvm()
+    sourceSets {
+        val jvmMain by getting {
+            dependencies {
+                api(alchemist("api"))
+                implementation(libs.ksp.api)
+            }
+            kotlin.srcDir("src/main/kotlin")
+            resources.srcDir("src/main/resources")
+        }
+        val jvmTest by getting {
+            dependencies {
+                implementation(libs.bundles.testing.compile)
+                runtimeOnly(libs.bundles.testing.runtimeOnly)
+            }
+            kotlin.srcDir("src/test/kotlin")
+        }
+    }
+}

alchemist-dsl-processor/src/main/kotlin/it/unibo/alchemist/boundary/dsl/processor/BoundProcessor.kt

@@ -0,0 +1,87 @@
+package it.unibo.alchemist.boundary.dsl.processor
+
+import com.google.devtools.ksp.symbol.KSTypeArgument
+import com.google.devtools.ksp.symbol.KSTypeReference
+import com.google.devtools.ksp.symbol.Variance
+
+/**
+ * Processes type bounds for type parameters, cleaning up internal Kotlin type representations.
+ */
+object BoundProcessor {
+    /**
+     * Processes a type bound reference, cleaning up internal Kotlin type representations and variance annotations.
+     *
+     * @param bound The type reference to process
+     * @param classTypeParamNames List of class type parameter names to replace in the bound
+     * @return A cleaned string representation of the bound with fully qualified names
+     */
+    fun processBound(bound: KSTypeReference, classTypeParamNames: List<String> = emptyList()): String {
+        val resolved = bound.resolve()
+        val decl = resolved.declaration
+        val qualifiedName = decl.qualifiedName?.asString()
+
+        if (qualifiedName != null) {
+            val arguments = resolved.arguments
+            val typeString = if (arguments.isNotEmpty()) {
+                val typeArgs = arguments.joinToString(", ") { arg ->
+                    formatTypeArgument(arg, classTypeParamNames)
+                }
+                "$qualifiedName<$typeArgs>"
+            } else {
+                qualifiedName
+            }
+
+            val nullableSuffix = if (resolved.isMarkedNullable) "?" else ""
+            val result = "$typeString$nullableSuffix"
+            return replaceClassTypeParamReferences(result, classTypeParamNames)
+        }
+
+        val result = TypeExtractor.extractTypeString(bound, emptyList())
+        return replaceClassTypeParamReferences(result, classTypeParamNames)
+    }
+
+    private fun formatTypeArgument(arg: KSTypeArgument, classTypeParamNames: List<String>): String = when {
+        arg.type == null -> "*"
+        arg.variance == Variance.STAR -> "*"
+        arg.variance == Variance.CONTRAVARIANT -> {
+            arg.type?.let {
+                val typeStr = TypeExtractor.extractTypeString(it, emptyList())
+                val replaced = replaceClassTypeParamReferences(typeStr, classTypeParamNames)
+                "in $replaced"
+            } ?: "*"
+        }
+        arg.variance == Variance.COVARIANT -> {
+            arg.type?.let {
+                val typeStr = TypeExtractor.extractTypeString(it, emptyList())
+                val replaced = replaceClassTypeParamReferences(typeStr, classTypeParamNames)
+                "out $replaced"
+            } ?: "*"
+        }
+        else -> {
+            arg.type?.let {
+                val typeStr = TypeExtractor.extractTypeString(it, emptyList())
+                replaceClassTypeParamReferences(typeStr, classTypeParamNames)
+            } ?: "*"
+        }
+    }
+
+    private fun replaceClassTypeParamReferences(boundStr: String, classTypeParamNames: List<String>): String {
+        if (classTypeParamNames.isEmpty()) {
+            return boundStr
+        }
+        var result = boundStr
+        classTypeParamNames.forEach { paramName ->
+            val pattern = Regex("""\b[\w.]+\.$paramName\b""")
+            result = pattern.replace(result) { matchResult ->
+                val matched = matchResult.value
+                val prefix = matched.substringBefore(".$paramName")
+                if (prefix.contains(".")) {
+                    paramName
+                } else {
+                    matched
+                }
+            }
+        }
+        return result
+    }
+}

alchemist-dsl-processor/src/main/kotlin/it/unibo/alchemist/boundary/dsl/processor/ConstructorFinder.kt

@@ -0,0 +1,41 @@
+package it.unibo.alchemist.boundary.dsl.processor
+
+import com.google.devtools.ksp.symbol.KSClassDeclaration
+import com.google.devtools.ksp.symbol.KSFunctionDeclaration
+import com.google.devtools.ksp.symbol.Modifier
+
+/**
+ * Finds a suitable constructor for a class declaration.
+ */
+object ConstructorFinder {
+    /**
+     * Finds a public constructor for the given class declaration.
+     * Prefers the primary constructor, otherwise returns the constructor with the most parameters.
+     *
+     * @param classDecl The class declaration to find a constructor for
+     * @return The found constructor, or null if no suitable constructor exists
+     */
+    fun findConstructor(classDecl: KSClassDeclaration): KSFunctionDeclaration? {
+        val primaryConstructor = classDecl.primaryConstructor
+        if (primaryConstructor != null && isPublicConstructor(primaryConstructor)) {
+            return primaryConstructor
+        }
+
+        val constructors = classDecl.getAllFunctions()
+            .filter { function ->
+                val simpleName = function.simpleName.asString()
+                (simpleName == "<init>" || simpleName == classDecl.simpleName.asString()) &&
+                    isPublicConstructor(function)
+            }
+            .sortedByDescending { it.parameters.size }
+
+        return constructors.firstOrNull()
+    }
+
+    private fun isPublicConstructor(function: KSFunctionDeclaration): Boolean {
+        val modifiers = function.modifiers
+        return !modifiers.contains(Modifier.PRIVATE) &&
+            !modifiers.contains(Modifier.PROTECTED) &&
+            !modifiers.contains(Modifier.INTERNAL)
+    }
+}