feat(codegen-kotlin): FR-019 Kotlin — @provided enums

Kotlin already materializes a package-level abstract field.enum ONCE as a
standalone `enum class` (KotlinEnumEmitter + KotlinTypeMapper.enumTypeName,
deduped by FQN), so the shared-materialize half of FR-019 was already satisfied.
This adds the @provided arm, gated by the shared
fixtures/codegen-conformance/shared-provided-enum oracle:

- New Fr019SharedEnum helper (Kotlin port of the TS/C#/Java reference): resolves
  the package-level abstract super, reads @provided own-only, and computes the
  external ClassName <ns>.E for a provided enum — ns resolved from the
  providedEnumPackages (package->namespace) generator arg then the
  providedEnumNamespace fallback (ADR-0001). Unresolved package => codegen error
  naming the enum + package.
- KotlinEntityGenerator: skip emitting the enum class for a @provided shared enum
  and reference it at the configured namespace; inline + non-provided shared enums
  unchanged (byte-identical default).
- No loader work — @provided registration lives in the Java metadata module
  (metadata-ktx shares it).
- New KotlinFr019SharedProvidedConformanceTest (materialize-once / provided-ref /
  missing-config-error). Existing KotlinEnumConformanceTest unchanged (standalone
  materialization already its expectation).

codegen-kotlin 225/0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/Fr019SharedEnum.kt

@@ -0,0 +1,110 @@
+package com.metaobjects.generator.kotlin
+
+import com.metaobjects.MetaRoot
+import com.metaobjects.field.EnumField
+import com.metaobjects.field.MetaField
+import com.metaobjects.generator.GeneratorException
+import com.metaobjects.generator.util.GeneratorUtil
+import com.squareup.kotlinpoet.ClassName
+
+/**
+ * FR-019 — shared + externally-provided enum resolution (Kotlin port of the TS reference
+ * `enum-shared.ts`, the C# `Fr019SharedEnum`, and the Java `Fr019SharedEnum`).
+ *
+ * Kotlin already materializes a package-level abstract `field.enum` ONCE as a standalone
+ * `enum class` ([KotlinEnumEmitter] + [KotlinTypeMapper.enumTypeName], deduped by FQN), so the
+ * shared-materialize half of FR-019 is already satisfied. This object adds the `@provided` arm:
+ * detecting a `@provided` shared enum (skip materialization) and resolving its reference to a
+ * per-port-configured namespace (ADR-0001 — never an FQN in metadata). The namespace binds to the
+ * enum's declaring metadata package via a package→namespace map + a single fallback, both
+ * generator args.
+ */
+internal object Fr019SharedEnum {
+
+    /** Per-port config for resolving a `@provided` enum's Kotlin namespace. Generator args only. */
+    data class ProvidedEnumConfig(val fallbackNamespace: String?, val packageNamespaces: Map<String, String>) {
+        companion object {
+            fun of(fallback: String?, packageMapArg: String?): ProvidedEnumConfig =
+                ProvidedEnumConfig(fallback?.trim()?.takeIf { it.isNotEmpty() }, parsePackageMap(packageMapArg))
+        }
+    }
+
+    /**
+     * Parse the `providedEnumPackages` generator arg — a `;`-delimited list of
+     * `<metaPackage>=<namespace>` entries (metadata package in `::` form), e.g.
+     * `"acme::shop=com.acme.ext;acme::billing=com.acme.money"`. Empty map for null/blank.
+     */
+    fun parsePackageMap(arg: String?): Map<String, String> {
+        if (arg.isNullOrBlank()) return emptyMap()
+        val map = LinkedHashMap<String, String>()
+        for (entry in arg.split(";")) {
+            val eq = entry.indexOf('=')
+            if (eq <= 0) continue
+            val key = entry.substring(0, eq).trim()
+            val value = entry.substring(eq + 1).trim()
+            if (key.isNotEmpty() && value.isNotEmpty()) map[key] = value
+        }
+        return map
+    }
+
+    /**
+     * The package-level abstract `field.enum` a concrete enum field resolves to via `extends`, or
+     * `null` for an inline enum. Qualifies only when the immediate super is (a) an [EnumField],
+     * (b) abstract, AND (c) a direct child of the metadata root ([MetaRoot]) — a sibling of
+     * `object.entity`, not an abstract field nested inside an object.
+     */
+    fun resolveSharedEnumDecl(field: MetaField<*>): EnumField? {
+        if (field !is EnumField) return null
+        val sup = field.superField as? EnumField ?: return null
+        if (!GeneratorUtil.isAbstract(sup)) return null
+        if (sup.parent !is MetaRoot) return null
+        return sup
+    }
+
+    /** Own-only read of `@provided` on an enum declaration. */
+    fun isProvided(decl: EnumField): Boolean {
+        if (!decl.hasMetaAttr(EnumField.ATTR_PROVIDED, false)) return false
+        val raw = runCatching { decl.getMetaAttr(EnumField.ATTR_PROVIDED, false).value }.getOrNull()
+        return when (raw) {
+            is Boolean -> raw
+            else -> raw?.toString()?.toBoolean() ?: false
+        }
+    }
+
+    /** True iff [field] resolves to a `@provided` shared enum (its type is referenced, not emitted). */
+    fun isProvidedEnumField(field: MetaField<*>): Boolean {
+        val decl = resolveSharedEnumDecl(field) ?: return false
+        return isProvided(decl)
+    }
+
+    /**
+     * The [ClassName] a consuming property emits for a `@provided` shared enum — `<ns>.<Name>`, with
+     * `ns` resolved from the package map (keyed by the enum's declaring metadata package) then the
+     * single fallback. Throws a codegen-time [GeneratorException] naming the enum + package when
+     * unresolved. Returns `null` when [field] is NOT a `@provided` shared enum, so the caller falls
+     * back to the normal materialized [KotlinTypeMapper.enumTypeName].
+     */
+    fun providedClassName(field: MetaField<*>, config: ProvidedEnumConfig): ClassName? {
+        val decl = resolveSharedEnumDecl(field) ?: return null
+        if (!isProvided(decl)) return null
+        val (_, shortRaw) = PackageMapping.splitFqn(decl.name)
+        val simple = shortRaw.replaceFirstChar { it.uppercase() }
+        val metaPackage = metaPackageOf(decl.name)
+        val ns = config.packageNamespaces[metaPackage]?.takeIf { it.isNotBlank() } ?: config.fallbackNamespace
+        if (ns.isNullOrBlank()) {
+            throw GeneratorException(
+                "provided enum \"$simple\" (declared in package \"$metaPackage\") is marked @provided " +
+                "but no Kotlin namespace is configured to reference it from. Map its package via the " +
+                "providedEnumPackages generator arg (\"$metaPackage=your.app.enums\") or set the single " +
+                "providedEnumNamespace fallback, so the generated code can reference \"$simple\"."
+            )
+        }
+        return ClassName(ns, simple)
+    }
+
+    /** The declaration's metadata package in `::` form, stripped of the trailing `::Name`. */
+    private fun metaPackageOf(fqn: String): String {
+        val idx = fqn.lastIndexOf("::")
+        return if (idx < 0) "" else fqn.substring(0, idx)
+    }
+}

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinEntityGenerator.kt

@@ -53,10 +53,20 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
 
     override fun getFilterClass(): Class<MetaObject> = MetaObject::class.java
 
+    /**
+     * FR-019 per-port config for resolving `@provided` enum namespaces, parsed from the
+     * `providedEnumNamespace` (single fallback) + `providedEnumPackages` (package→namespace map)
+     * generator args. Empty by default; a referenced provided enum with no resolvable namespace is
+     * a codegen-time error.
+     */
+    private var fr019Config = Fr019SharedEnum.ProvidedEnumConfig(null, emptyMap())
+
     /** Real work happens here — sidesteps the parent's print-style writer machinery. */
     override fun execute(loader: MetaDataLoader) {
         parseArgs()
         val outRoot = Paths.get(outDir.absolutePath)
+        fr019Config = Fr019SharedEnum.ProvidedEnumConfig.of(
+            getArg("providedEnumNamespace"), getArg("providedEnumPackages"))
         // emitAbstractShapes (default OFF): when ON, an abstract entity is emitted as a Kotlin
         // `interface` shape (read-only properties) instead of being suppressed. It is NEVER
         // emitted as an instantiable @Serializable data class — abstracts are scaffolding.
@@ -83,7 +93,9 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         // Emit one Kotlin enum class file per `field.enum` child BEFORE the data class
         // so the resolved property type (a ClassName) points at a real file. Deduped per run.
         for (field in obj.metaFields) {
-            if (field is EnumField) KotlinEnumEmitter.emitEnumFile(obj, field, outRoot, emittedEnumFqns)
+            // FR-019: a @provided shared enum is referenced externally, never materialized — skip it.
+            if (field is EnumField && !Fr019SharedEnum.isProvidedEnumField(field))
+                KotlinEnumEmitter.emitEnumFile(obj, field, outRoot, emittedEnumFqns)
         }
 
         val (pkg, shortName) = PackageMapping.splitFqn(obj.name)
@@ -146,7 +158,9 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
      */
     protected open fun emitAbstractShape(obj: MetaObject, outRoot: Path, loader: MetaDataLoader, emittedEnumFqns: MutableSet<String>) {
         for (field in obj.metaFields) {
-            if (field is EnumField) KotlinEnumEmitter.emitEnumFile(obj, field, outRoot, emittedEnumFqns)
+            // FR-019: a @provided shared enum is referenced externally, never materialized — skip it.
+            if (field is EnumField && !Fr019SharedEnum.isProvidedEnumField(field))
+                KotlinEnumEmitter.emitEnumFile(obj, field, outRoot, emittedEnumFqns)
         }
 
         val (pkg, shortName) = PackageMapping.splitFqn(obj.name)
@@ -189,6 +203,9 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
 
     /** The Kotlin TypeName for a single (non-array) element of [field]. */
     protected open fun resolveElementType(field: MetaField<*>, owner: MetaObject, loader: MetaDataLoader): TypeName {
+        // FR-019: a @provided shared enum is referenced at its configured external namespace
+        // (<ns>.E) instead of the materialized in-package class; an unresolved namespace throws.
+        Fr019SharedEnum.providedClassName(field, fr019Config)?.let { return it }
         // field.enum → typed enum class generated alongside this entity.
         KotlinTypeMapper.enumTypeName(field, owner)?.let { return it }
         if (field is ObjectField) {

server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinFr019SharedProvidedConformanceTest.kt

@@ -0,0 +1,88 @@
+package com.metaobjects.generator.kotlin
+
+import com.metaobjects.metadata.ktx.loadString
+import com.metaobjects.loader.MetaDataLoader
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import java.nio.file.Files
+import java.nio.file.Path
+import kotlin.io.path.readText
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+/**
+ * Cross-port FR-019 conformance (Kotlin). Loads the shared fixture
+ * `fixtures/codegen-conformance/shared-provided-enum/input/meta.json` and asserts the two FR-019
+ * behaviors (ADR-0026):
+ *  - Shared materialization — a package-level abstract `field.enum` (`Priority`) extended by TWO
+ *    entities is materialized ONCE as a standalone `enum class Priority`; both data classes type
+ *    their property as it (no per-entity redeclaration).
+ *  - `@provided` — a package-level abstract `field.enum` (`Currency`, `@provided: true`) is NOT
+ *    materialized; consuming data classes reference it at the configured namespace
+ *    (`<ns>.Currency`). A referenced provided enum with no configured namespace is a codegen-time
+ *    error naming the enum.
+ */
+class KotlinFr019SharedProvidedConformanceTest {
+
+    private fun loadFixture(): MetaDataLoader {
+        val fixture = Path.of(System.getProperty("user.dir"))
+            .resolve("../../..").normalize()
+            .resolve("fixtures/codegen-conformance/shared-provided-enum/input/meta.json")
+        assertTrue(Files.exists(fixture), "shared FR-019 fixture missing at $fixture")
+        return loadString("sharedProvidedEnumFixture", Files.readString(fixture))
+    }
+
+    private fun generate(providedEnumNamespace: String?): Path {
+        val out = Files.createTempDirectory("kgen-fr019-conf-")
+        val args = mutableMapOf("outputDir" to out.toString())
+        if (providedEnumNamespace != null) args["providedEnumNamespace"] = providedEnumNamespace
+        KotlinEntityGenerator().apply { setArgs(args) }.execute(loadFixture())
+        return out
+    }
+
+    @Test
+    fun `shared enum is materialized once and referenced by both entities`() {
+        val out = generate("com.acme.ext")
+        try {
+            val priorityEnum = out.resolve("acme/shop/Priority.kt")
+            assertTrue(Files.exists(priorityEnum), "shared Priority.kt enum class must be materialized")
+            val enumSrc = priorityEnum.readText()
+            assertTrue("enum class Priority" in enumSrc, "expected shared `enum class Priority`; saw:\n$enumSrc")
+            for (m in listOf("LOW", "MEDIUM", "HIGH"))
+                assertTrue(m in enumSrc, "member $m must be present; saw:\n$enumSrc")
+
+            for (name in listOf("Ticket.kt", "Order.kt")) {
+                val dc = out.resolve("acme/shop").resolve(name)
+                assertTrue(Files.exists(dc), "$name must be emitted")
+                val src = dc.readText()
+                assertTrue("priority" in src && "Priority" in src,
+                    "$name must type its priority property as the shared enum; saw:\n$src")
+                // Same-package reference: no redeclaration and no cross-package import.
+                assertFalse("enum class Priority" in src, "$name must NOT redeclare the shared enum; saw:\n$src")
+            }
+        } finally {
+            out.toFile().deleteRecursively()
+        }
+    }
+
+    @Test
+    fun `provided enum is not materialized and referenced at the configured namespace`() {
+        val out = generate("com.acme.ext")
+        try {
+            assertFalse(Files.exists(out.resolve("acme/shop/Currency.kt")),
+                "provided Currency must NOT be materialized")
+            val ticket = out.resolve("acme/shop/Ticket.kt").readText()
+            assertTrue("com.acme.ext.Currency" in ticket || "import com.acme.ext.Currency" in ticket,
+                "currency property must reference the configured external namespace; saw:\n$ticket")
+        } finally {
+            out.toFile().deleteRecursively()
+        }
+    }
+
+    @Test
+    fun `provided enum with no namespace config is a codegen error naming the enum`() {
+        val ex = assertThrows<RuntimeException> { generate(null) }
+        assertTrue(ex.message?.contains("Currency") == true,
+            "error must name the provided enum Currency; was: ${ex.message}")
+    }
+}