Merge codegen-kotlin Phase D — field.object @storage handling

dmealing · dmealing · commit 22f91ab51c95 · 2026-05-25T23:31:17.000-04:00
KotlinEntityGenerator now walks BOTH object.entity AND object.value (needed so field.object references resolve to a generated data class). A field.object @objectref="X" emits a typed reference to the X data class. KotlinExposedTableGenerator handles @storage on field.object: - @storage="flattened" → one column per sub-field, prefixed: addressStreet/addressCity/addressZip on the parent table. Kotlin prop = camelCase concat; SQL column = snake_case. Nullable iff parent field nullable OR sub-field optional. - @storage="jsonb" (and the default when absent) → single jsonb column: metadata = jsonb("metadata", { Json.encodeToString(it) }, { Json.decodeFromString(it) }) Consumers add exposed-json + kotlinx-serialization-json deps. KotlinTypeMapper.exposedColumnSpec(field, colName) overload added to let flattened sub-columns override physical column name without mutating fields. 45 module tests green (41 baseline + 4 new storage tests).
diff --git a/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinEntityGenerator.kt b/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinEntityGenerator.kt
@@ -1,6 +1,7 @@
 package com.metaobjects.generator.kotlin
 
 import com.metaobjects.field.MetaField
+import com.metaobjects.field.ObjectField
 import com.metaobjects.generator.GeneratorIOWriter
 import com.metaobjects.generator.direct.MultiFileDirectGeneratorBase
 import com.metaobjects.loader.MetaDataLoader
@@ -11,18 +12,24 @@ import com.squareup.kotlinpoet.FunSpec
 import com.squareup.kotlinpoet.KModifier
 import com.squareup.kotlinpoet.ParameterSpec
 import com.squareup.kotlinpoet.PropertySpec
+import com.squareup.kotlinpoet.TypeName
 import com.squareup.kotlinpoet.TypeSpec
 import java.io.OutputStream
 import java.io.PrintWriter
 import java.nio.file.Path
 import java.nio.file.Paths
 
 /**
- * Generator: one @Serializable Kotlin data class per `object.entity`.
+ * Generator: one @Serializable Kotlin data class per `object.entity` and `object.value`.
  *
- * <p>Skips abstract objects, payload-only `object.value` instances, and any subType other
- * than `entity`. KotlinPoet emits whole files; the parent class's print-style writer
- * machinery is bypassed in favour of a direct override of [execute].
+ * <p>Skips abstract objects and any subType other than `entity` or `value`. KotlinPoet emits
+ * whole files; the parent class's print-style writer machinery is bypassed in favour of a
+ * direct override of [execute].
+ *
+ * <p>Nested objects: when a parent field is a `field.object` with `@objectRef`, the parent
+ * data class gets a typed property referencing the generated `object.value` data class
+ * (e.g., `val address: Address`). The `@storage` attr (`flattened` / `jsonb`) does not
+ * affect Kotlin type emission — it only affects the Exposed table's column shape.
  *
  * <p>Args:
  * <ul>
@@ -38,14 +45,17 @@ class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
     override fun execute(loader: MetaDataLoader) {
         parseArgs()
         val outRoot = Paths.get(outDir.absolutePath)
-        for (entity in loader.metaObjects) {
-            if (entity.subType != "entity") continue   // ignore object.value; payload generator handles those
-            emit(entity, outRoot)
+        for (obj in loader.metaObjects) {
+            // Emit a data class for both entities AND value objects. Value objects (object.value)
+            // are referenced by field.object on entities; the value class must exist for the
+            // entity's typed property to resolve.
+            if (obj.subType != MetaObject.SUBTYPE_ENTITY && obj.subType != MetaObject.SUBTYPE_VALUE) continue
+            emit(obj, outRoot, loader)
         }
     }
 
-    private fun emit(entity: MetaObject, outRoot: Path) {
-        val (pkg, shortName) = PackageMapping.splitFqn(entity.name)
+    private fun emit(obj: MetaObject, outRoot: Path, loader: MetaDataLoader) {
+        val (pkg, shortName) = PackageMapping.splitFqn(obj.name)
         val serializable = ClassName("kotlinx.serialization", "Serializable")
 
         val typeBuilder = TypeSpec.classBuilder(shortName)
@@ -54,8 +64,8 @@ class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
             .addKdoc("GENERATED — do not hand-edit. Regenerated from metadata.\n")
 
         val ctorBuilder = FunSpec.constructorBuilder()
-        for (field in entity.metaFields) {
-            val baseType = KotlinTypeMapper.kotlinTypeName(field)
+        for (field in obj.metaFields) {
+            val baseType = resolvePropertyType(field, loader)
             val nullable = !isRequired(field)
             val propType = if (nullable) baseType.copy(nullable = true) else baseType
             val propName = field.name
@@ -75,6 +85,43 @@ class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         fileSpec.writeTo(outRoot)
     }
 
+    /**
+     * Resolve the Kotlin TypeName for a single property. For `field.object` fields,
+     * the type is a reference to the generated data class of the field's `@objectRef`
+     * (e.g., `Address` for `field.object @objectRef="Address"`). The `@storage` attr
+     * is intentionally NOT consulted here — flattened vs jsonb only affects the
+     * persistence column shape, not the in-memory shape.
+     */
+    private fun resolvePropertyType(field: MetaField<*>, loader: MetaDataLoader): TypeName {
+        if (field is ObjectField) {
+            val ref = readObjectRef(field)
+            if (ref != null) {
+                val target = resolveObjectByShortOrFqn(loader, ref)
+                if (target != null) {
+                    val (targetPkg, targetShort) = PackageMapping.splitFqn(target.name)
+                    return ClassName(targetPkg, targetShort)
+                }
+            }
+        }
+        return KotlinTypeMapper.kotlinTypeName(field)
+    }
+
+    /** Read the `@objectRef` attr off a field (own-only); null if absent. */
+    private fun readObjectRef(field: MetaField<*>): String? {
+        if (!field.hasMetaAttr(ObjectField.ATTR_OBJECTREF, false)) return null
+        return runCatching { field.getMetaAttr(ObjectField.ATTR_OBJECTREF, false).valueAsString }
+            .getOrNull()
+    }
+
+    /** Resolve a MetaObject (entity OR value) by FQN match or short-name match. */
+    private fun resolveObjectByShortOrFqn(loader: MetaDataLoader, ref: String): MetaObject? {
+        for (child in loader.metaObjects) {
+            val short = child.name.substringAfterLast("::")
+            if (child.name == ref || short == ref) return child
+        }
+        return null
+    }
+
     /**
      * Required iff explicit `@required: true` attribute is set on the field; otherwise nullable.
      * MVP heuristic — refined when richer required-detection lands (see fr-003 spec).
diff --git a/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGenerator.kt b/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGenerator.kt
@@ -1,6 +1,7 @@
 package com.metaobjects.generator.kotlin
 
 import com.metaobjects.field.MetaField
+import com.metaobjects.field.ObjectField
 import com.metaobjects.generator.GeneratorIOWriter
 import com.metaobjects.generator.direct.MultiFileDirectGeneratorBase
 import com.metaobjects.identity.MetaIdentity
@@ -54,6 +55,8 @@ class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         val incrementPk = primary?.generation == MetaIdentity.GENERATION_INCREMENT
 
         val fkColumns = buildFkColumns(entity, loader)
+        val objectColumns = buildObjectColumns(entity, primaryFieldName, loader)
+        val needsJsonbImport = objectColumns.any { it.kind == ObjectColumnKind.JSONB }
 
         val source = buildString {
             if (pkg.isNotEmpty()) {
@@ -63,17 +66,29 @@ class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
             if (fkColumns.any { it.hasReferenceOption }) {
                 append("import org.jetbrains.exposed.sql.ReferenceOption\n")
             }
+            if (needsJsonbImport) {
+                append("import org.jetbrains.exposed.sql.json.jsonb\n")
+                append("import kotlinx.serialization.json.Json\n")
+            }
             append("\n")
             append("/** GENERATED — do not hand-edit. Regenerated from metadata. */\n")
             append("object $tableObjectName : Table(\"$tableName\") {\n")
             for (field in entity.metaFields) {
+                if (field is ObjectField) {
+                    // ObjectField columns are produced by buildObjectColumns() so we can
+                    // emit @storage flattened (N columns) or jsonb (1 column) uniformly.
+                    continue
+                }
                 val isPk = field.name == primaryFieldName
                 val nullable = !isPk && !isRequired(field)
                 val baseSpec = KotlinTypeMapper.exposedColumnSpec(field)
                 val withAuto = if (isPk && incrementPk) "$baseSpec.autoIncrement()" else baseSpec
                 val full = if (nullable) "$withAuto.nullable()" else withAuto
                 append("    val ${field.name} = $full\n")
             }
+            for (oc in objectColumns) {
+                append("    val ${oc.propertyName} = ${oc.columnExpr}\n")
+            }
             for (fk in fkColumns) {
                 append("    val ${fk.propertyName} = ${fk.columnExpr}\n")
             }
@@ -88,6 +103,95 @@ class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         Files.writeString(outFile, source)
     }
 
+    // === field.object + @storage column emission ============================
+
+    private enum class ObjectColumnKind { FLATTENED, JSONB }
+
+    /** A single Exposed column derived from a `field.object` (one per flattened sub-field, or one total for jsonb). */
+    private data class ObjectColumnSpec(
+        val propertyName: String,
+        val columnExpr: String,
+        val kind: ObjectColumnKind,
+    )
+
+    /**
+     * Build the Exposed columns contributed by each `field.object` on [entity].
+     *
+     * <ul>
+     *   <li>{@code @storage="flattened"}: one column per field of the referenced
+     *       `object.value`, with property name {@code <parentField><SubFieldCap>} and
+     *       physical column {@code <parentField>_<subField>} (snake-joined). Nullable
+     *       sub-fields → nullable columns.</li>
+     *   <li>{@code @storage="jsonb"} or absent (default-to-jsonb per CLAUDE.md):
+     *       one {@code jsonb(name, encoder, decoder)} column using kotlinx.serialization Json.</li>
+     * </ul>
+     *
+     * Skips field.object children whose `@objectRef` cannot be resolved (defensive — the loader's
+     * validation phase already gates the attr being present).
+     */
+    private fun buildObjectColumns(
+        entity: MetaObject,
+        primaryFieldName: String?,
+        loader: MetaDataLoader,
+    ): List<ObjectColumnSpec> {
+        val result = mutableListOf<ObjectColumnSpec>()
+        for (field in entity.metaFields) {
+            if (field !is ObjectField) continue
+            val parentName = field.name
+            val storage = readStorage(field)        // null → default to jsonb
+            if (storage == STORAGE_FLATTENED) {
+                val ref = readObjectRef(field) ?: continue
+                val target = resolveObjectByShortOrFqn(loader, ref) ?: continue
+                val parentNullable = parentName != primaryFieldName && !isRequired(field)
+                for (subField in target.metaFields) {
+                    val propertyName = parentName + subField.name.replaceFirstChar { it.uppercase() }
+                    val colName = parentName + "_" + subField.name
+                    val baseSpec = KotlinTypeMapper.exposedColumnSpec(subField, colName)
+                    // Sub-column is nullable iff the parent is nullable OR the sub-field itself is.
+                    val nullable = parentNullable || !isRequired(subField)
+                    val full = if (nullable) "$baseSpec.nullable()" else baseSpec
+                    result.add(ObjectColumnSpec(propertyName, full, ObjectColumnKind.FLATTENED))
+                }
+            } else {
+                // jsonb (explicit) OR absent (default per CLAUDE.md back-compat rule).
+                val colName = parentName
+                val expr = "jsonb(\"$colName\", { Json.encodeToString(it) }, { Json.decodeFromString(it) })"
+                val parentNullable = parentName != primaryFieldName && !isRequired(field)
+                val full = if (parentNullable) "$expr.nullable()" else expr
+                result.add(ObjectColumnSpec(parentName, full, ObjectColumnKind.JSONB))
+            }
+        }
+        return result
+    }
+
+    /** Read the `@storage` attr (own-only); null when absent. */
+    private fun readStorage(field: ObjectField): String? {
+        if (!field.hasMetaAttr(ATTR_STORAGE, false)) return null
+        return runCatching { field.getMetaAttr(ATTR_STORAGE, false).valueAsString }.getOrNull()
+    }
+
+    /** Read the `@objectRef` attr (own-only); null when absent. */
+    private fun readObjectRef(field: ObjectField): String? {
+        if (!field.hasMetaAttr(ObjectField.ATTR_OBJECTREF, false)) return null
+        return runCatching { field.getMetaAttr(ObjectField.ATTR_OBJECTREF, false).valueAsString }
+            .getOrNull()
+    }
+
+    /** Resolve a MetaObject (entity OR value) by FQN match or short-name match. */
+    private fun resolveObjectByShortOrFqn(loader: MetaDataLoader, ref: String): MetaObject? {
+        for (child in loader.metaObjects) {
+            val short = child.name.substringAfterLast("::")
+            if (child.name == ref || short == ref) return child
+        }
+        return null
+    }
+
+    private companion object {
+        /** Cross-language @storage attr on field.object — values: flattened | jsonb (default). */
+        const val ATTR_STORAGE = "storage"
+        const val STORAGE_FLATTENED = "flattened"
+    }
+
     // === FK column emission from relationship.composition ====================
 
     /** A foreign-key column derived from a `relationship.composition` child. */
diff --git a/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinTypeMapper.kt b/server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinTypeMapper.kt
@@ -66,8 +66,14 @@ object KotlinTypeMapper {
     }
 
     /** Map a MetaField to the Exposed `Table` column statement (e.g., `varchar("name", 100)`). */
-    fun exposedColumnSpec(field: MetaField<*>): String {
-        val colName = field.name
+    fun exposedColumnSpec(field: MetaField<*>): String = exposedColumnSpec(field, field.name)
+
+    /**
+     * Same as [exposedColumnSpec], but with an explicit physical column name. Used by the
+     * `@storage: "flattened"` codepath to emit prefixed columns (e.g., `address_street`)
+     * for nested object.value fields without mutating the underlying MetaField.
+     */
+    fun exposedColumnSpec(field: MetaField<*>, colName: String): String {
         return when {
             field is StringField    -> "varchar(\"$colName\", ${stringMaxLength(field)})"
             field is IntegerField   -> "integer(\"$colName\")"
diff --git a/server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinEntityGeneratorTest.kt b/server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinEntityGeneratorTest.kt
@@ -39,4 +39,50 @@ class KotlinEntityGeneratorTest {
             outDir.toFile().deleteRecursively()
         }
     }
+
+    @Test fun fieldObjectEmitsTypedNestedReference() {
+        // User has a field.object → Address; Address is an object.value with three fields.
+        // Expected: User.kt has `val address: Address?` AND Address.kt is also emitted
+        // as a @Serializable data class.
+        val fx = """{
+          "metadata.root": { "package": "acme::demo", "children": [
+            { "object.value": { "name": "Address", "children": [
+                { "field.string": { "name": "street", "@required": true } },
+                { "field.string": { "name": "city",   "@required": true } },
+                { "field.string": { "name": "zip",    "@required": true } }
+            ] } },
+            { "object.entity": { "name": "User", "children": [
+                { "field.long":   { "name": "id" } },
+                { "field.object": { "name": "address",
+                    "@objectRef": "Address", "@storage": "flattened" } }
+            ] } }
+          ] }
+        }""".trimIndent()
+
+        val outDir = Files.createTempDirectory("kgen-fo-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("fo", fx))
+
+            val userKt = outDir.resolve("acme/demo/User.kt")
+            val addrKt = outDir.resolve("acme/demo/Address.kt")
+            assertTrue(Files.exists(userKt),
+                "expected $userKt; files=${Files.walk(outDir).toList()}")
+            assertTrue(Files.exists(addrKt),
+                "expected $addrKt (object.value should be emitted); files=${Files.walk(outDir).toList()}")
+
+            val userSrc = Files.readString(userKt)
+            assertTrue("val address: Address?" in userSrc,
+                "expected typed nested ref `val address: Address?` in:\n$userSrc")
+
+            val addrSrc = Files.readString(addrKt)
+            assertTrue("data class Address" in addrSrc, addrSrc)
+            assertTrue("val street: String" in addrSrc, addrSrc)
+            assertTrue("val city: String" in addrSrc, addrSrc)
+            assertTrue("val zip: String" in addrSrc, addrSrc)
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
 }
diff --git a/server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGeneratorTest.kt b/server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGeneratorTest.kt
