feat: implement nullmark mode for generic return type transformation (#123)

feat: implement nullmark mode for generic return type transformation and add test coverage

Author: ForteScarlet

.gitignore

@@ -5,6 +5,8 @@ build/
 !**/src/main/**/build/
 !**/src/test/**/build/
 
+_docs
+
 ### IntelliJ IDEA ###
 .idea/**
 !.idea/copyright

compiler/suspend-transform-plugin-cli/src/test/kotlin/love/forte/plugin/suspendtrans/cli/ConfigurationSerializeTests.kt

@@ -1,11 +1,9 @@
 package love.forte.plugin.suspendtrans.cli
 
-import love.forte.plugin.suspendtrans.configuration.InternalSuspendTransformConfigurationApi
-import love.forte.plugin.suspendtrans.configuration.SuspendTransformConfiguration
+import love.forte.plugin.suspendtrans.configuration.*
 import love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations.jsPromiseTransformer
 import love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations.jvmAsyncTransformer
 import love.forte.plugin.suspendtrans.configuration.SuspendTransformConfigurations.jvmBlockingTransformer
-import love.forte.plugin.suspendtrans.configuration.TargetPlatform
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
@@ -50,6 +48,53 @@ class ConfigurationSerializeTests {
         }
     }
 
+    @OptIn(InternalSuspendTransformConfigurationApi::class)
+    @Test
+    fun testDecodeTransformReturnTypeGenericMode() {
+        val transformer = Transformer(
+            markAnnotation = jvmAsyncTransformer.markAnnotation,
+            transformFunctionInfo = jvmAsyncTransformer.transformFunctionInfo,
+            transformReturnType = jvmAsyncTransformer.transformReturnType,
+            transformReturnTypeGeneric = jvmAsyncTransformer.transformReturnTypeGeneric,
+            originFunctionIncludeAnnotations = jvmAsyncTransformer.originFunctionIncludeAnnotations,
+            syntheticFunctionIncludeAnnotations = jvmAsyncTransformer.syntheticFunctionIncludeAnnotations,
+            copyAnnotationsToSyntheticFunction = jvmAsyncTransformer.copyAnnotationsToSyntheticFunction,
+            copyAnnotationExcludes = jvmAsyncTransformer.copyAnnotationExcludes,
+            copyAnnotationsToSyntheticProperty = jvmAsyncTransformer.copyAnnotationsToSyntheticProperty,
+            transformReturnTypeGenericMode = TransformReturnTypeGenericMode.NON_NULL,
+        )
+        val config = SuspendTransformConfiguration(
+            transformers = mapOf(TargetPlatform.JVM to listOf(transformer))
+        )
+
+        val decoded = decodeSuspendTransformConfigurationFromHex(config.encodeToHex())
+        assertEquals(config, decoded)
+        assertEquals(
+            TransformReturnTypeGenericMode.NON_NULL,
+            decoded.transformers.getValue(TargetPlatform.JVM).single().transformReturnTypeGenericMode
+        )
+    }
+
+    @OptIn(InternalSuspendTransformConfigurationApi::class)
+    @Test
+    fun testDecodeLegacyWithoutTransformReturnTypeGenericMode() {
+        val config = SuspendTransformConfiguration(
+            transformers = mapOf(
+                TargetPlatform.JVM to listOf(jvmBlockingTransformer, jvmAsyncTransformer),
+                TargetPlatform.JS to listOf(jsPromiseTransformer),
+            )
+        )
+        val legacyHex =
+            "0aba0808011286040a95010a3c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e67180020001208626173654e616d651a06737566666978220a617350726f70657274792a08426c6f636b696e6730003a2b0a086d61726b4e616d6512190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020001a046e616d6512390a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120f2472756e496e426c6f636b696e672420002a240a1e0a0a6b6f746c696e2e6a766d120c4a766d53796e7468657469631800200010001800323c0a360a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1205417069344a18002000100018013801421e0a0a6b6f746c696e2e6a766d120c4a766d53796e74686574696318002000423c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e671800200042390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e631800200042130a066b6f746c696e12054f7074496e1800200042190a0a6b6f746c696e2e6a766d12074a766d4e616d6518002000480012ac040a8f010a390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e63180020001208626173654e616d651a06737566666978220a617350726f70657274792a054173796e6330003a2b0a086d61726b4e616d6512190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020001a046e616d6512360a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120c2472756e496e4173796e63241a2d0a146a6176612e7574696c2e636f6e63757272656e741211436f6d706c657461626c654675747572651800200020012a240a1e0a0a6b6f746c696e2e6a766d120c4a766d53796e7468657469631800200010001800323c0a360a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1205417069344a18002000100018013801421e0a0a6b6f746c696e2e6a766d120c4a766d53796e74686574696318002000423c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e671800200042390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e631800200042130a066b6f746c696e12054f7074496e1800200042190a0a6b6f746c696e2e6a766d12074a766d4e616d651800200048000a970308021292030a8e010a3a0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12094a7350726f6d697365180020001208626173654e616d651a06737566666978220a617350726f70657274792a054173796e6330003a290a086d61726b4e616d6512170a096b6f746c696e2e6a7312064a734e616d65180020001a046e616d6512360a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120c2472756e496e4173796e63241a180a096b6f746c696e2e6a73120750726f6d697365180020002001323d0a370a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1206417069344a7318002000100018013801423a0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12094a7350726f6d6973651800200042130a066b6f746c696e12054f7074496e1800200042170a096b6f746c696e2e6a7312064a734e616d65180020004800"
+
+        val decoded = decodeSuspendTransformConfigurationFromHex(legacyHex)
+
+        assertEquals(config, decoded)
+        decoded.transformers.values.flatten().forEach { transformer ->
+            assertEquals(TransformReturnTypeGenericMode.NORMAL, transformer.transformReturnTypeGenericMode)
+        }
+    }
+
     @OptIn(InternalSuspendTransformConfigurationApi::class)
     @Test
     fun testDecode() {
@@ -68,7 +113,7 @@ class ConfigurationSerializeTests {
         val hex = config.encodeToHex()
 
         assertEquals(
-            "0aba0808011286040a95010a3c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e67180020001208626173654e616d651a06737566666978220a617350726f70657274792a08426c6f636b696e6730003a2b0a086d61726b4e616d6512190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020001a046e616d6512390a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120f2472756e496e426c6f636b696e672420002a240a1e0a0a6b6f746c696e2e6a766d120c4a766d53796e7468657469631800200010001800323c0a360a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1205417069344a18002000100018013801421e0a0a6b6f746c696e2e6a766d120c4a766d53796e74686574696318002000423c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e671800200042390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e631800200042130a066b6f746c696e12054f7074496e1800200042190a0a6b6f746c696e2e6a766d12074a766d4e616d6518002000480012ac040a8f010a390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e63180020001208626173654e616d651a06737566666978220a617350726f70657274792a054173796e6330003a2b0a086d61726b4e616d6512190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020001a046e616d6512360a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120c2472756e496e4173796e63241a2d0a146a6176612e7574696c2e636f6e63757272656e741211436f6d706c657461626c654675747572651800200020012a240a1e0a0a6b6f746c696e2e6a766d120c4a766d53796e7468657469631800200010001800323c0a360a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1205417069344a18002000100018013801421e0a0a6b6f746c696e2e6a766d120c4a766d53796e74686574696318002000423c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e671800200042390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e631800200042130a066b6f746c696e12054f7074496e1800200042190a0a6b6f746c696e2e6a766d12074a766d4e616d651800200048000a970308021292030a8e010a3a0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12094a7350726f6d697365180020001208626173654e616d651a06737566666978220a617350726f70657274792a054173796e6330003a290a086d61726b4e616d6512170a096b6f746c696e2e6a7312064a734e616d65180020001a046e616d6512360a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120c2472756e496e4173796e63241a180a096b6f746c696e2e6a73120750726f6d697365180020002001323d0a370a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1206417069344a7318002000100018013801423a0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12094a7350726f6d6973651800200042130a066b6f746c696e12054f7074496e1800200042170a096b6f746c696e2e6a7312064a734e616d65180020004800",
+            "0abe0808011288040a95010a3c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e67180020001208626173654e616d651a06737566666978220a617350726f70657274792a08426c6f636b696e6730003a2b0a086d61726b4e616d6512190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020001a046e616d6512390a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120f2472756e496e426c6f636b696e672420002a240a1e0a0a6b6f746c696e2e6a766d120c4a766d53796e7468657469631800200010001800323c0a360a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1205417069344a18002000100018013801421e0a0a6b6f746c696e2e6a766d120c4a766d53796e74686574696318002000423c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e671800200042390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e631800200042130a066b6f746c696e12054f7074496e1800200042190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020004800500012ae040a8f010a390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e63180020001208626173654e616d651a06737566666978220a617350726f70657274792a054173796e6330003a2b0a086d61726b4e616d6512190a0a6b6f746c696e2e6a766d12074a766d4e616d65180020001a046e616d6512360a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120c2472756e496e4173796e63241a2d0a146a6176612e7574696c2e636f6e63757272656e741211436f6d706c657461626c654675747572651800200020012a240a1e0a0a6b6f746c696e2e6a766d120c4a766d53796e7468657469631800200010001800323c0a360a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1205417069344a18002000100018013801421e0a0a6b6f746c696e2e6a766d120c4a766d53796e74686574696318002000423c0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e120b4a766d426c6f636b696e671800200042390a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12084a766d4173796e631800200042130a066b6f746c696e12054f7074496e1800200042190a0a6b6f746c696e2e6a766d12074a766d4e616d6518002000480050000a990308021294030a8e010a3a0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12094a7350726f6d697365180020001208626173654e616d651a06737566666978220a617350726f70657274792a054173796e6330003a290a086d61726b4e616d6512170a096b6f746c696e2e6a7312064a734e616d65180020001a046e616d6512360a266c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e72756e74696d65120c2472756e496e4173796e63241a180a096b6f746c696e2e6a73120750726f6d697365180020002001323d0a370a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e1206417069344a7318002000100018013801423a0a296c6f76652e666f7274652e706c7567696e2e73757370656e647472616e732e616e6e6f746174696f6e12094a7350726f6d6973651800200042130a066b6f746c696e12054f7074496e1800200042170a096b6f746c696e2e6a7312064a734e616d651800200048005000",
             hex
         )
 

compiler/suspend-transform-plugin-configuration/src/main/kotlin/love/forte/plugin/suspendtrans/configuration/SuspendTransformConfiguration.kt

@@ -246,6 +246,53 @@ class IncludeAnnotation @InternalSuspendTransformConfigurationApi constructor(
     }
 }
 
+/**
+ * Controls the nullability applied to the generic argument copied from the
+ * original suspend function return type into [Transformer.transformReturnType].
+ *
+ * This setting is only meaningful when [Transformer.transformReturnType] is not
+ * `null` and [Transformer.transformReturnTypeGeneric] is `true`.
+ *
+ * The main use case is [NON_NULL]: some wrapper APIs, such as Reactive
+ * Streams-style containers, do not allow `null` elements and represent absence
+ * as an empty result instead. In that case the generated generic argument should
+ * describe the emitted element as non-null.
+ *
+ * @since 0.14.0
+ */
+@Serializable
+enum class TransformReturnTypeGenericMode {
+    /**
+     * Keep the original return type unchanged.
+     *
+     * Example: `T` remains `T`, and `Foo?` remains `Foo?`.
+     */
+    NORMAL,
+
+    /**
+     * Make the copied generic argument nullable.
+     *
+     * Example: `Foo` becomes `Foo?`.
+     *
+     * This is provided for explicit nullable wrappers. The primary motivation of
+     * this enum is [NON_NULL].
+     */
+    NULLABLE,
+
+    /**
+     * Make the copied generic argument non-nullable.
+     *
+     * For type parameters with nullable bounds, this uses a definitely-not-null
+     * type at the use site, e.g. `T` becomes `T & Any`. It does not rewrite the
+     * original type parameter declaration or its upper bound.
+     *
+     * This is useful for wrappers whose element type cannot be `null`, for
+     * example Reactive Streams-style APIs where `null` must be modeled as an
+     * empty result rather than as an emitted element.
+     */
+    NON_NULL
+}
+
 @Serializable
 class Transformer @InternalSuspendTransformConfigurationApi constructor(
     /**
@@ -331,7 +378,33 @@ class Transformer @InternalSuspendTransformConfigurationApi constructor(
      *
      * @since 0.9.0
      */
-    val copyAnnotationsToSyntheticProperty: Boolean = false
+    val copyAnnotationsToSyntheticProperty: Boolean = false,
+
+    /**
+     * Nullability mode for the generic argument copied from the original return type.
+     *
+     * This is used only when [transformReturnType] is not `null` and
+     * [transformReturnTypeGeneric] is `true`. It changes the generic argument
+     * placed inside the transformed return type, not the original function's type
+     * parameters or their bounds.
+     *
+     * For example, with a transformed return type like `Result<T>` and an
+     * original return type `T : Foo?`, [TransformReturnTypeGenericMode.NON_NULL]
+     * produces a use-site type like `Result<T & Any>`.
+     *
+     * [TransformReturnTypeGenericMode.NON_NULL] is intended for wrappers whose
+     * element type does not accept `null`, such as Reactive Streams-style APIs.
+     * This setting only changes the generated type; the configured transform
+     * function must still implement the matching runtime semantics, such as
+     * converting a `null` result to an empty completion when the wrapper requires it.
+     *
+     * Keep this property at the end of the constructor parameters because the
+     * configuration is serialized with ProtoBuf and field order is part of the
+     * compatibility surface.
+     *
+     * @since 0.14.0
+     */
+    val transformReturnTypeGenericMode: TransformReturnTypeGenericMode = TransformReturnTypeGenericMode.NORMAL,
 ) {
     override fun equals(other: Any?): Boolean {
         if (this === other) return true
@@ -346,6 +419,7 @@ class Transformer @InternalSuspendTransformConfigurationApi constructor(
         if (originFunctionIncludeAnnotations != other.originFunctionIncludeAnnotations) return false
         if (syntheticFunctionIncludeAnnotations != other.syntheticFunctionIncludeAnnotations) return false
         if (copyAnnotationExcludes != other.copyAnnotationExcludes) return false
+        if (transformReturnTypeGenericMode != other.transformReturnTypeGenericMode) return false
 
         return true
     }
@@ -360,11 +434,12 @@ class Transformer @InternalSuspendTransformConfigurationApi constructor(
         result = 31 * result + originFunctionIncludeAnnotations.hashCode()
         result = 31 * result + syntheticFunctionIncludeAnnotations.hashCode()
         result = 31 * result + copyAnnotationExcludes.hashCode()
+        result = 31 * result + transformReturnTypeGenericMode.hashCode()
         return result
     }
 
     override fun toString(): String {
-        return "Transformer(copyAnnotationExcludes=$copyAnnotationExcludes, markAnnotation=$markAnnotation, transformFunctionInfo=$transformFunctionInfo, transformReturnType=$transformReturnType, transformReturnTypeGeneric=$transformReturnTypeGeneric, originFunctionIncludeAnnotations=$originFunctionIncludeAnnotations, syntheticFunctionIncludeAnnotations=$syntheticFunctionIncludeAnnotations, copyAnnotationsToSyntheticFunction=$copyAnnotationsToSyntheticFunction, copyAnnotationsToSyntheticProperty=$copyAnnotationsToSyntheticProperty)"
+        return "Transformer(copyAnnotationExcludes=$copyAnnotationExcludes, markAnnotation=$markAnnotation, transformFunctionInfo=$transformFunctionInfo, transformReturnType=$transformReturnType, transformReturnTypeGeneric=$transformReturnTypeGeneric, originFunctionIncludeAnnotations=$originFunctionIncludeAnnotations, syntheticFunctionIncludeAnnotations=$syntheticFunctionIncludeAnnotations, copyAnnotationsToSyntheticFunction=$copyAnnotationsToSyntheticFunction, copyAnnotationsToSyntheticProperty=$copyAnnotationsToSyntheticProperty, transformReturnTypeGenericMode=$transformReturnTypeGenericMode)"
     }
 }
 

compiler/suspend-transform-plugin/src/main/kotlin/love/forte/plugin/suspendtrans/fir/SuspendTransformFirTransformerAnnotations.kt

@@ -22,6 +22,7 @@
 
 package love.forte.plugin.suspendtrans.fir
 
+import love.forte.plugin.suspendtrans.configuration.TransformReturnTypeGenericMode
 import love.forte.plugin.suspendtrans.configuration.Transformer
 import love.forte.plugin.suspendtrans.utils.toClassId
 import love.forte.plugin.suspendtrans.utils.toInfo
@@ -72,7 +73,11 @@ internal fun SuspendTransformFirTransformer.resolveReturnConeType(
         var typeArguments: Array<ConeTypeProjection> = emptyArray()
 
         if (transformer.transformReturnTypeGeneric) {
-            typeArguments = arrayOf(ConeKotlinTypeProjectionOut(returnTypeRef.coneType))
+            typeArguments = arrayOf(
+                ConeKotlinTypeProjectionOut(
+                    resolveReturnTypeGenericArgument(transformer, returnTypeRef.coneType)
+                )
+            )
         }
 
         returnType.toClassId().createConeType(
@@ -83,6 +88,25 @@ internal fun SuspendTransformFirTransformer.resolveReturnConeType(
     }
     ?: returnTypeRef.coneType
 
+/**
+ * Applies the configured nullability mode to the return type copied into the
+ * transformed return type's generic argument.
+ *
+ * `NULLABLE` asks the FIR type context to explicitly mark the use-site type as
+ * nullable. `NON_NULL` uses Kotlin's definitely-not-null helper so type
+ * parameters with nullable upper bounds can become `T & Any` instead of only
+ * clearing the nullable marker.
+ */
+private fun SuspendTransformFirTransformer.resolveReturnTypeGenericArgument(
+    transformer: Transformer,
+    returnType: ConeKotlinType
+): ConeKotlinType = when (transformer.transformReturnTypeGenericMode) {
+    TransformReturnTypeGenericMode.NORMAL -> returnType
+    TransformReturnTypeGenericMode.NULLABLE -> returnType.withNullability(true, firSession.typeContext)
+    TransformReturnTypeGenericMode.NON_NULL ->
+        returnType.makeConeTypeDefinitelyNotNullOrNotNull(firSession.typeContext)
+}
+
 /**
  * Copies and augments annotations for generated functions, generated properties,
  * and the original source function.