zdl-kotlin: refactor FluentMap to extension methods

Author: ivangsa

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to ZDL Kotlin
+
+## Building Locally
+
+### Prerequisites
+- JDK 17 or higher
+- Node.js 18 or higher (for JS/NPM package)
+
+### Build Commands
+
+```bash
+# Build the project
+./gradlew build
+
+# Publish to local Maven repository
+./gradlew clean publishToMavenLocal
+
+# Run tests
+./gradlew test
+
+# Run tests with coverage
+./gradlew build koverHtmlReport
+
+# Build JS package and run Node.js integration tests
+./gradlew nodeIntegrationTest
+```
+
+## Release Process
+
+### 1. Create a Release
+
+Trigger the **Create Gradle Release** workflow from GitHub Actions:
+
+1. Go to **Actions** → **Create Gradle Release** → **Run workflow**
+2. Enter the release version (e.g., `1.5.0`)
+3. Enter the next development version (e.g., `1.6.0-SNAPSHOT`)
+
+This workflow will:
+- Update version in `build.gradle.kts` to the release version
+- Create a git tag `v{version}`
+- Update version to the next development version
+- Create a PR with the changes
+- Auto-merge the PR
+- Push the release tag
+
+### 2. Publish the Release
+
+After the tag is created, create a GitHub Release:
+
+1. Go to **Releases** → **Draft a new release**
+2. Select the tag created in step 1 (e.g., `v1.5.0`)
+3. Generate release notes or write your own
+4. Publish the release
+
+This automatically triggers the **Publish Release to Maven Central and NPM** workflow, which:
+- Builds and tests the project
+- Publishes to Maven Central
+- Publishes to NPM registry as `@zenwave360/zdl`
+
+### 3. Snapshot Releases
+
+Snapshots are automatically published when pushing to `develop` or `next` branches via the **Build and Publish Snapshots** workflow.
+
+> **Note**: Snapshot publishing to Maven Central is currently disabled. Enable by uncommenting the publish step in `.github/workflows/publish-snapshots.yml`.
+
+## Required Secrets
+
+The following GitHub secrets must be configured for releases:
+
+- `CENTRAL_USERNAME` - Maven Central username
+- `CENTRAL_TOKEN` - Maven Central token
+- `SIGN_KEY` - GPG signing key
+- `SIGN_KEY_PASS` - GPG signing key password
+- `NPM_TOKEN` - NPM authentication token
+

nodejs-test-project/package-lock.json

@@ -30,7 +30,7 @@ class ZdlParser {
         return this
     }
 
-    fun parseModel(model: String): ZdlModel {
+    fun parseModel(model: String): Map<String, Any?> {
         val zdl = CharStreams.fromString(model)
         val lexer = ZdlLexer(zdl)
         val tokens = CommonTokenStream(lexer)
@@ -49,7 +49,7 @@ class ZdlParser {
         } catch (e: Exception) {
             e.printStackTrace()
         }
-        return zdlModel
+        return zdlModel.asJavaMap()
     }
 }
 

src/commonMain/kotlin/io/zenwave360/zdl/ZdlParser.kt

@@ -1,37 +1,64 @@
 package io.zenwave360.zdl.antlr
 
-class FluentMap private constructor(
-    private val backingMap: MutableMap<String, Any?> = linkedMapOf()
-) : MutableMap<String, Any?> by backingMap {
-
-    companion object {
-        fun build(block: FluentMap.() -> Unit = {}): FluentMap =
-            FluentMap(linkedMapOf()).apply(block)
-    }
-
-    // Provide access to underlying Java Map (useful for JSONPath on JVM)
-    fun asJavaMap(): MutableMap<String, Any?> = backingMap
-
-    // Idiomatic API (avoid signature clash with MutableMap.put)
-    fun putEntry(key: String, value: Any?): FluentMap = apply { backingMap[key] = value }
-    fun putAllEntries(map: Map<String, Any?>): FluentMap = apply { backingMap.putAll(map) }
-
-    fun appendTo(collection: String, key: String, value: Any?): FluentMap = apply {
-        val nestedMap = backingMap.getOrPut(collection) { linkedMapOf<String, Any?>() } as MutableMap<String, Any?>
-        nestedMap[key] = value
-    }
-
-    fun appendToWithMap(collection: String, map: Map<String, Any?>): FluentMap = apply {
-        val nestedMap = backingMap.getOrPut(collection) { linkedMapOf<String, Any?>() } as MutableMap<String, Any?>
-        nestedMap.putAll(map)
-    }
-
-    fun appendToList(collection: String, value: Any?): FluentMap = apply {
-        val nestedList = backingMap.getOrPut(collection) { mutableListOf<Any?>() } as MutableList<Any?>
-        nestedList.add(value)
-    }
-
-    // Compatibility API (to be refactored later)
-    fun with(key: String, value: Any?): FluentMap = putEntry(key, value)
+/**
+ * Utility functions for building and manipulating MutableMap instances with a fluent API.
+ * These replace the previous FluentMap class to avoid ClassCastException issues with Java interop.
+ */
+
+/**
+ * Build a new MutableMap with optional initialization block.
+ */
+fun buildMap(block: MutableMap<String, Any?>.() -> Unit = {}): MutableMap<String, Any?> =
+    linkedMapOf<String, Any?>().apply(block)
+
+/**
+ * Put a key-value pair and return the map for chaining.
+ */
+fun MutableMap<String, Any?>.with(key: String, value: Any?): MutableMap<String, Any?> =
+    apply { this[key] = value }
+
+/**
+ * Put a key-value pair and return the map for chaining (alias for with).
+ */
+fun MutableMap<String, Any?>.putEntry(key: String, value: Any?): MutableMap<String, Any?> =
+    apply { this[key] = value }
+
+/**
+ * Put all entries from another map and return the map for chaining.
+ */
+fun MutableMap<String, Any?>.putAllEntries(map: Map<String, Any?>): MutableMap<String, Any?> =
+    apply { this.putAll(map) }
+
+/**
+ * Append a key-value pair to a nested map within this map.
+ * If the collection doesn't exist, it will be created as a LinkedHashMap.
+ */
+fun MutableMap<String, Any?>.appendTo(collection: String, key: String, value: Any?): MutableMap<String, Any?> = apply {
+    val nestedMap = this.getOrPut(collection) { linkedMapOf<String, Any?>() } as MutableMap<String, Any?>
+    nestedMap[key] = value
 }
 
+/**
+ * Append all entries from a map to a nested map within this map.
+ * If the collection doesn't exist, it will be created as a LinkedHashMap.
+ */
+fun MutableMap<String, Any?>.appendToWithMap(collection: String, map: Map<String, Any?>): MutableMap<String, Any?> = apply {
+    val nestedMap = this.getOrPut(collection) { linkedMapOf<String, Any?>() } as MutableMap<String, Any?>
+    nestedMap.putAll(map)
+}
+
+/**
+ * Append a value to a nested list within this map.
+ * If the collection doesn't exist, it will be created as a MutableList.
+ */
+fun MutableMap<String, Any?>.appendToList(collection: String, value: Any?): MutableMap<String, Any?> = apply {
+    val nestedList = this.getOrPut(collection) { mutableListOf<Any?>() } as MutableList<Any?>
+    nestedList.add(value)
+}
+
+/**
+ * Returns this map (useful for Java interop compatibility).
+ * Previously used to unwrap FluentMap to underlying map.
+ */
+fun MutableMap<String, Any?>.asJavaMap(): MutableMap<String, Any?> = this
+