Merge pull request #234 from SpineEventEngine/migrate-to-compiler

Migrate to the Compiler API

Author: alexander-yevsyukov

.agents/_TOC.md

@@ -0,0 +1,16 @@
+# Table of Contents
+
+1. [Quick Reference Card](quick-reference-card.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/advanced-safety-rules.md

@@ -0,0 +1,6 @@
+# 🚨 Advanced safety rules
+
+- Do **not** auto-update external dependencies without explicit request.
+- Do **not** inject analytics or telemetry code.
+- Flag any usage of unsafe constructs (e.g., reflection, I/O on the main thread).
+- Avoid generating blocking calls inside coroutines.

.agents/coding-guidelines.md

@@ -0,0 +1,39 @@
+# 🧾 Coding guidelines
+
+## Core principles
+
+- Adhere to [Spine Event Engine Documentation][spine-docs] for coding style.
+- Generate code that compiles cleanly and passes static analysis.
+- Respect existing architecture, naming conventions, and project structure.
+- Write clear, incremental commits with descriptive messages.
+- Include automated tests for any code change that alters functionality.
+
+## Kotlin best practices
+
+### ✅ Prefer
+- **Kotlin idioms** over Java-style approaches:
+  - Extension functions
+  - `when` expressions 
+  - Smart casts
+  - Data classes and sealed classes
+  - Immutable data structures
+- **Simple nouns** over composite nouns (`user` > `userAccount`)  
+- **Generic parameters** over explicit variable types (`val list = mutableList<Dependency>()`)  
+- **Java interop annotations** only when needed (`@file:JvmName`, `@JvmStatic`)
+- **Kotlin DSL** for Gradle files
+
+### ❌ Avoid
+- Mutable data structures
+- Java-style verbosity (builders with setters)
+- Redundant null checks (`?.let` misuse)
+- Using `!!` unless clearly justified
+- Type names in variable names (`userObject`, `itemList`)
+- String duplication (use constants in companion objects)
+- Mixing Groovy and Kotlin DSLs in build logic
+- Reflection unless specifically requested
+
+## Text formatting
+ - ✅ Remove double empty lines in the code.
+ - ✅ Remove trailing space characters in the code.
+
+[spine-docs]: https://github.com/SpineEventEngine/documentation/wiki

.agents/common-tasks.md

@@ -0,0 +1,6 @@
+# 📋 Common tasks
+
+- **Adding a new dependency**: Update relevant files in `buildSrc` directory.
+- **Creating a new module**: Follow existing module structure patterns.
+- **Documentation**: Use KDoc style for public and internal APIs.
+- **Testing**: Create comprehensive tests using Kotest assertions.

.agents/documentation-guidelines.md

@@ -0,0 +1,14 @@
+# Documentation & comments
+
+## Commenting guidelines
+- Avoid inline comments in production code unless necessary.
+- Inline comments are helpful in tests.
+- When using TODO comments, follow the format on the [dedicated page][todo-comments].
+- File and directory names should be formatted as code.
+
+## Avoid widows, runts, orphans, or rivers
+
+Agents should **AVOID** text flow patters illustrated
+on [this diagram](widow-runt-orphan-river.jpg).
+
+[todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments

.agents/documentation-tasks.md

@@ -0,0 +1,20 @@
+# 📄 Documentation tasks
+
+1. Ensure all public and internal APIs have KDoc examples.
+2. Add in-line code blocks for clarity in tests.
+3. Convert inline API comments in Java to KDoc in Kotlin:
+   ```java
+   // Literal string to be inlined whenever a placeholder references a non-existent argument.
+   private final String missingArgumentMessage = "[MISSING ARGUMENT]";
+   ```
+   transforms to:
+   ```kotlin
+   /**
+    * Literal string to be inlined whenever a placeholder references a non-existent argument.
+    */
+    private val missingArgumentMessage = "[MISSING ARGUMENT]"
+   ```
+
+4. Javadoc -> KDoc conversion tasks:
+   - Remove `<p>` tags in the line with text: `"<p>This"` -> `"This"`.
+   - Replace `<p>` with empty line if the tag is the only text in the line.

.agents/java-kotlin-conversion.md

@@ -0,0 +1,43 @@
+# 🪄 Converting Java code to Kotlin
+
+* Java code API comments are Javadoc format.
+* Kotlin code API comments are in KDoc format. 
+ 
+## Javadoc to KDoc conversion
+
+* The wording of original Javadoc comments must be preserved.
+                                                                      
+## Treating nullability
+
+* Use nullable Kotlin type only if the type in Java is annotated as `@Nullable`.
+
+## Efficient Conversion Workflow
+
+* First, analyze the entire Java file structure before beginning conversion to understand dependencies and class relationships.
+* Convert Java code to Kotlin systematically: imports first, followed by class definitions, methods, and finally expressions.
+* Preserve all existing functionality and behavior during conversion.
+* Maintain original code structure and organization to ensure readability.
+
+## Common Java to Kotlin Patterns
+
+* Convert Java getters/setters to Kotlin properties with appropriate visibility modifiers.
+* Transform Java static methods to companion object functions or top-level functions as appropriate.
+* Replace Java anonymous classes with Kotlin lambda expressions when possible.
+* Convert Java interfaces with default methods to Kotlin interfaces with implementations.
+* Transform Java builders to Kotlin DSL patterns when appropriate.
+
+## Error Prevention
+
+* Pay special attention to Java's checked exceptions versus Kotlin's unchecked exceptions.
+* Be cautious with Java wildcards (`? extends`, `? super`) conversion to Kotlin's `out` and `in` type parameters.
+* Ensure proper handling of Java static initialization blocks in Kotlin companion objects.
+* Verify that Java overloaded methods convert correctly with appropriate default parameter values in Kotlin.
+* Remember that Kotlin has smart casts which can eliminate explicit type casting needed in Java.
+
+## Documentation Conversion
+
+* Convert `@param` to `@param` with the same description.
+* Convert `@return` to `@return` with the same description.
+* Convert `@throws` to `@throws` with the same description.
+* Convert `{@link}` to `[name][fully.qualified.Name]` format.
+* Convert `{@code}` to inline code with backticks (`).

.agents/project-overview.md

@@ -0,0 +1,7 @@
+# 🛠️ Project overview
+
+- **Languages**: Kotlin (primary), Java (secondary).
+- **Build tool**: Gradle with Kotlin DSL.
+- **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

@@ -0,0 +1,21 @@
+# 📁 Project structure expectations
+
+```yaml
+.github
+buildSrc/
+<module-1>
+  src/
+  ├── main/
+  │ ├── kotlin/ # Kotlin source files
+  │ └── java/ # Legacy Java code
+  ├── test/
+  │ └── kotlin/ # Unit and integration tests
+  build.gradle.kts # Kotlin-based build configuration
+<module-2>
+<module-3>
+build.gradle.kts # Kotlin-based build configuration
+settings.gradle.kts # Project structure and settings
+README.md # Project overview
+AGENTS.md # Entry point for LLM agent instructions
+version.gradle.kts # Declares the project version. 
+```

.agents/quick-reference-card.md

@@ -0,0 +1,10 @@
+# 📝 Quick Reference Card
+
+```
+🔑 Key Information:
+- Kotlin/Java project with CQRS architecture
+- Use ChatGPT for documentation, Codex for code generation, GPT-4o for complex analysis
+- Follow coding guidelines in Spine Event Engine docs
+- Always include tests with code changes
+- Version bump required for all PRs
+```