Bump Gradle, Kotlin, and local dependencies

.agents/_TOC.md

@@ -1,18 +1,16 @@
 # Table of Contents
 
 1. [Quick Reference Card](quick-reference-card.md)
-2. [Purpose](purpose.md)
-3. [Project overview](project-overview.md)
-4. [Coding guidelines](coding-guidelines.md)
-5. [Documentation & comments](documentation-guidelines.md)
-6. [Documentation typography & structure](documentation-typography-and-structure.md)
-7. [Documentation tasks](documentation-tasks.md)
-8. [Running builds](running-builds.md)
-9. [Version policy](version-policy.md)
-10. [Project structure expectations](project-structure-expectations.md)
-11. [Testing](testing.md)
-12. [Safety rules](safety-rules.md)
-13. [Advanced safety rules](advanced-safety-rules.md)
-14. [Refactoring guidelines](refactoring-guidelines.md)
-15. [Common tasks](common-tasks.md)
-16. [Java to Kotlin conversion](java-kotlin-conversion.md)
+2. [Project overview](project-overview.md)
+3. [Coding guidelines](coding-guidelines.md)
+4. [Documentation & comments](documentation-guidelines.md)
+5. [Documentation tasks](documentation-tasks.md)
+6. [Running builds](running-builds.md)
+7. [Version policy](version-policy.md)
+8. [Project structure expectations](project-structure-expectations.md)
+9. [Testing](testing.md)
+10. [Safety rules](safety-rules.md)
+11. [Advanced safety rules](advanced-safety-rules.md)
+12. [Refactoring guidelines](refactoring-guidelines.md)
+13. [Common tasks](common-tasks.md)
+14. [Java to Kotlin conversion](java-kotlin-conversion.md)

.agents/project-overview.md

@@ -2,7 +2,6 @@
 
 - **Languages**: Kotlin (primary), Java (secondary).
 - **Build tool**: Gradle with Kotlin DSL.
-- **Architecture**: Event-driven Command Query Responsibility Segregation (CQRS).
 - **Static analysis**: detekt, ErrorProne, Checkstyle, PMD. 
 - **Testing**: JUnit 5, Kotest Assertions, Codecov.
 - **Tools used**: Gradle plugins, IntelliJ IDEA Platform, KSP, KotlinPoet, Dokka.

.agents/project-structure-expectations.md

@@ -16,6 +16,6 @@ buildSrc/
 build.gradle.kts # Kotlin-based build configuration
 settings.gradle.kts # Project structure and settings
 README.md # Project overview
-AGENTS.md # LLM agent instructions (this file)
+AGENTS.md # Entry point for LLM agent instructions
 version.gradle.kts # Declares the project version. 
 ```

.agents/refactoring-guidelines.md

@@ -1,3 +1,3 @@
 # ⚙️ Refactoring guidelines
 
-- Do not replace Kotest assertions with standard Kotlin's Built-In Test Assertions.
+- Do NOT replace Kotest assertions with standard Kotlin's built-in test assertions.

.junie/guidelines.md

@@ -1,9 +1,9 @@
 # Guidelines for Junie and AI Agent from JetBrains
 
-Read the `../.agents/_TOC.md` file at the root of the project to understand:
+Read the `../.agents/_TOC.md` file to understand:
  - the agent responsibilities,
- - project overview, 
- - coding guidelines, 
+ - project overview,
+ - coding guidelines,
  - other relevant topics.
 
 Also follow the Junie-specific rules described below.

CLAUDE.md

@@ -0,0 +1,17 @@
+# Project Configuration for Claude Code
+
+## Agent Guidelines
+Please read and follow all guidelines in the project's agent documentation:
+
+- Start with the table of contents: `./agents/_TOC.md`.
+- Follow all linked documents from the TOC.
+- Apply all coding standards, formatting rules, and project conventions found in these documents.
+
+## Key Points for Claude Code
+- All guidelines in the `.agents` directory apply to Claude Code interactions.
+- Pay special attention to Kotlin formatting requirements (trailing newlines, detekt compliance).
+- Follow project-specific conventions documented in the agent guidelines.
+
+## Priority
+The `.agents` directory contains the authoritative project standards.
+These take precedence over default behaviors.

buildSrc/build.gradle.kts

@@ -24,6 +24,8 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
 /**
  * This script uses two declarations of the constant [licenseReportVersion] because
  * currently there is no way to define a constant _before_ a build script of `buildSrc`.
@@ -73,7 +75,7 @@ val grGitVersion = "4.1.1"
  * This version may change from the [version of Kotlin][io.spine.dependency.lib.Kotlin.version]
  * used by the project.
  */
-val kotlinEmbeddedVersion = "2.1.21"
+val kotlinEmbeddedVersion = "2.2.21"
 
 /**
  * The version of Guava used in `buildSrc`.
@@ -140,9 +142,9 @@ val koverVersion = "0.9.1"
  *
  * `7.1.2` is the last version compatible with Gradle 7.x. Newer versions require Gradle v8.x.
  *
- * @see <a href="https://github.com/johnrengelman/shadow/releases">Shadow Plugin releases</a>
+ * @see <a href="https://github.com/GradleUp/shadow">Shadow Plugin releases</a>
  */
-val shadowVersion = "8.3.6"
+val shadowVersion = "9.2.2"
 
 configurations.all {
     resolutionStrategy {
@@ -158,6 +160,17 @@ configurations.all {
     }
 }
 
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_17)
+    }
+}
+
 dependencies {
     api("com.github.jk1:gradle-license-report:$licenseReportVersion")
     api(platform("org.jetbrains.kotlin:kotlin-bom:$kotlinEmbeddedVersion"))

buildSrc/settings.gradle.kts

@@ -31,3 +31,7 @@ pluginManagement {
         mavenCentral()
     }
 }
+
+plugins {
+    id("org.gradle.toolchains.foojay-resolver-convention").version("1.0.0")
+}

buildSrc/src/main/kotlin/BuildExtensions.kt

@@ -31,15 +31,18 @@ import io.spine.dependency.build.GradleDoctor
 import io.spine.dependency.build.Ksp
 import io.spine.dependency.build.PluginPublishPlugin
 import io.spine.dependency.lib.Protobuf
+import io.spine.dependency.local.Compiler
+import io.spine.dependency.local.CoreJvmCompiler
 import io.spine.dependency.local.McJava
-import io.spine.dependency.local.ProtoData
 import io.spine.dependency.local.ProtoTap
 import io.spine.dependency.test.Kotest
 import io.spine.dependency.test.Kover
 import io.spine.gradle.repo.standardToSpineSdk
 import org.gradle.api.Project
 import org.gradle.api.Task
+import org.gradle.api.file.DuplicatesStrategy
 import org.gradle.api.tasks.JavaExec
+import org.gradle.jvm.tasks.Jar
 import org.gradle.kotlin.dsl.ScriptHandlerScope
 import org.gradle.plugin.use.PluginDependenciesSpec
 import org.gradle.plugin.use.PluginDependencySpec
@@ -79,37 +82,43 @@ fun ScriptHandlerScope.standardSpineSdkRepositories() {
 val ScriptHandlerScope.protobuf: Protobuf
     get() = Protobuf
 
+/**
+ * Shortcut to [CoreJvmCompiler] dependency object for using under `buildScript`.
+ */
+val ScriptHandlerScope.coreJvmCompiler: CoreJvmCompiler
+    get() = CoreJvmCompiler
+
 /**
  * Shortcut to [McJava] dependency object for using under `buildScript`.
  */
 val ScriptHandlerScope.mcJava: McJava
     get() = McJava
 
 /**
- * Shortcut to [McJava] dependency object.
+ * Shortcut to [CoreJvmCompiler] dependency object.
  *
  * This plugin is not published to Gradle Portal and cannot be applied directly to a project.
  * Firstly, it should be put to buildscript's classpath and then applied by ID only.
  */
-val PluginDependenciesSpec.mcJava: McJava
-    get() = McJava
+val PluginDependenciesSpec.coreJvmCompiler: CoreJvmCompiler
+    get() = CoreJvmCompiler
 
 /**
- * Shortcut to [ProtoData] dependency object for using under `buildscript`.
+ * Shortcut to [Compiler] dependency object for using under `buildscript`.
  */
-val ScriptHandlerScope.protoData: ProtoData
-    get() = ProtoData
+val ScriptHandlerScope.spineCompiler: Compiler
+    get() = Compiler
 
 /**
- * Shortcut to [ProtoData] dependency object.
+ * Shortcut to [Compiler] dependency object.
  *
  * This plugin is published at Gradle Plugin Portal.
  * But when used in a pair with [mcJava], it cannot be applied directly to a project.
- * It is so, because [mcJava] uses [protoData] as its dependency.
+ * It is so, because [mcJava] uses [spineCompiler] as its dependency.
  * And the buildscript's classpath ends up with both of them.
  */
-val PluginDependenciesSpec.protoData: ProtoData
-    get() = ProtoData
+val PluginDependenciesSpec.spineCompiler: Compiler
+    get() = Compiler
 
 /**
  * Provides shortcuts for applying plugins from our dependency objects.
@@ -162,11 +171,11 @@ val PluginDependenciesSpec.`plugin-publish`: PluginDependencySpec
 
 /**
  * Configures the dependencies between third-party Gradle tasks
- * and those defined via ProtoData and Spine Model Compiler.
+ * and those defined via the Spine Compiler and its plugins.
  *
  * It is required to avoid warnings in build logs, detecting the undeclared
  * usage of Spine-specific task output by other tasks,
- * e.g., the output of `launchProtoData` is used by `compileKotlin`.
+ * e.g., the output of `launchSpineCompiler` is used by `compileKotlin`.
  */
 @Suppress("unused")
 fun Project.configureTaskDependencies() {
@@ -297,31 +306,58 @@ fun Project.setRemoteDebug(taskName: String, enabled: Boolean = true) {
 }
 
 /**
- * Sets remote debug options for the `launchProtoData` task.
+ * Sets remote debug options for the `launchSpineCompiler` task.
  *
  * @param enabled if `true` the task will be suspended.
  *
  * @see remoteDebug
  */
-fun Project.protoDataRemoteDebug(enabled: Boolean = true) =
-    setRemoteDebug("launchProtoData", enabled)
+fun Project.spineCompilerRemoteDebug(enabled: Boolean = true) =
+    setRemoteDebug("launchSpineCompiler", enabled)
 
 /**
- * Sets remote debug options for the `launchTestProtoData` task.
+ * Sets remote debug options for the `launchTestSpineCompiler` task.
  *
  * @param enabled if `true` the task will be suspended.
  *
  * @see remoteDebug
  */
-fun Project.testProtoDataRemoteDebug(enabled: Boolean = true) =
-    setRemoteDebug("launchTestProtoData", enabled)
+fun Project.testSpineCompilerRemoteDebug(enabled: Boolean = true) =
+    setRemoteDebug("launchTestSpineCompiler", enabled)
 
 /**
- * Sets remote debug options for the `launchTestFixturesProtoData` task.
+ * Sets remote debug options for the `launchTestFixturesSpineCompiler` task.
  *
  * @param enabled if `true` the task will be suspended.
  *
  * @see remoteDebug
  */
-fun Project.testFixturesProtoDataRemoteDebug(enabled: Boolean = true) =
-    setRemoteDebug("launchTestFixturesProtoData", enabled)
+fun Project.testFixturesSpineCompilerRemoteDebug(enabled: Boolean = true) =
+    setRemoteDebug("launchTestFixturesSpineCompiler", enabled)
+
+/**
+ * Parts of names of configurations to be excluded by
+ * `artifactMeta/excludeConfigurations/containing` in the modules
+ * where `io.spine.atifact-meta` plugin is applied.
+ */
+val buildToolConfigurations: Array<String> = arrayOf(
+    "detekt",
+    "jacoco",
+    "pmd",
+    "checkstyle",
+    "checkerframework",
+    "ksp",
+    "dokka",
+)
+
+/**
+ * Make the `sourcesJar` task accept duplicated input which seems to occur
+ * somewhere inside Protobuf Gradle Plugin.
+ */
+fun Project.allowDuplicationInSourcesJar() {
+    tasks.withType(Jar::class.java).configureEach {
+        if (name == "sourcesJar") {
+            duplicatesStrategy = DuplicatesStrategy.INCLUDE
+        }
+    }
+}

buildSrc/src/main/kotlin/DokkaExts.kt

@@ -69,11 +69,17 @@ fun DependencyHandlerScope.useDokkaWithSpineExtensions() {
 private fun DependencyHandler.dokkaPlugin(dependencyNotation: Any): Dependency? =
     add("dokkaPlugin", dependencyNotation)
 
+/**
+ * Resolves the directory where Dokka outputs HTML documentation for the given language.
+ */
 internal fun Project.dokkaOutput(language: String): File {
     val lng = language.titleCaseFirstChar()
     return layout.buildDirectory.dir("docs/dokka$lng").get().asFile
 }
 
+/**
+ * Locates a Dokka configuration file under the `buildSrc` resources.
+ */
 fun Project.dokkaConfigFile(file: String): File {
     val dokkaConfDir = project.rootDir.resolve("buildSrc/src/main/resources/dokka")
     return dokkaConfDir.resolve(file)