[generator] Phase 2: Kotlin @JvmInline value class projection

[jonathanpeppers]

Phase 2 of #1431. Builds on #1432 (sibling-collision dedup) by detecting Kotlin @JvmInline value class types in class-parse, surfacing them in api.xml, and projecting them into generator output as readonly struct wrappers — while JNI marshaling stays on the underlying primitive.

What this does

Given Kotlin source like:

@JvmInline
value class MyColor(val value: ULong)
@JvmInline
value class MyAlpha(val value: ULong)
@JvmInline
value class MyDp(val value: Float)

object Widgets {
    fun tint(c: MyColor) { ... }
    fun tint(a: MyAlpha) { ... }
    fun tint(d: MyDp)    { ... }
    fun pad(d: MyDp): MyDp           { ... }
    fun pad(x: MyDp, y: MyDp): MyDp  { ... }
}

The generator now emits:

public readonly partial struct MyColor : System.IEquatable<MyColor> {
    public readonly long Value;
    public MyColor (long value) { Value = value; }
    public static implicit operator long (MyColor value) => value.Value;
    public static implicit operator MyColor (long value) => new MyColor (value);
    // == / != / Equals / GetHashCode / ToString
}
// ...same shape for MyAlpha (long-backed) and MyDp (float-backed).

public static class Widgets {
    public static void  Tint (MyColor c) { ... }   // was: void Tint_Rn_QMJI (long c)
    public static void  Tint (MyAlpha a) { ... }   // was: void Tint_uzYZ1wI (long a)
    public static void  Tint (MyDp d)    { ... }   // was: void Tint_L3D9Hvg (long d)
    public static MyDp  Pad  (MyDp d)            { ... }
    public static MyDp  Pad  (MyDp x, MyDp y)    { ... }
}

The bodies of Tint/Pad still pass the JVM-erased primitive (long/float) across JNI — the implicit conversion operators on the struct make that compile without any thunk changes.

Bytecode layer

• New ClassFile.KotlinInlineClassUnderlyingJniType, MethodInfo.KotlinInlineClassReturnJniType, MethodInfo.KotlinName, ParameterInfo.KotlinInlineClassJniType.
• KotlinFixups.Fixup does a pre-pass DetectInlineClasses that recognizes @JvmInline + KotlinClassFlags.IsInlineClass + a single non-synthetic instance field with a primitive descriptor, then stamps each method's parameter/return JNI types when the Kotlin source-level type was an inline class and the JVM-erased descriptor matches the underlying primitive (so boxed/nullable positions are correctly skipped).
• Recovers the unmangled Kotlin source name from metadata (tint instead of tint-Rn_QMJI) and surfaces it via MethodInfo.KotlinName.
• XmlClassDeclarationBuilder emits kotlin-inline-class, kotlin-inline-class-underlying-jni-type, kotlin-inline-class-jni-type (parameter), kotlin-inline-class-return-jni-type (method), and managedName (unmangled Kotlin name) attributes.

Generator layer

• ClassGen.IsKotlinInlineClass / ClassGen.KotlinInlineClassUnderlyingJniType.
• Parameter.KotlinInlineClassJniType / Method.KotlinInlineClassReturnJniType.
• XmlApiImporter reads the new attributes; the existing managedName codepath delivers the unmangled C# binding name without affecting JNI invocation.
• Parameter.Validate / ReturnValue.Validate apply the projection by looking up the wrapper ClassGen via SymbolTable and overriding managed_type so Type/FullName return the struct while Symbol (and therefore JNI marshaling) stays on the underlying primitive.
• MethodBase.Matches also compares Parameters[i].KotlinInlineClassJniType so two inline classes that share the same JVM primitive (e.g. multiple ULong-backed inline classes on Compose APIs) survive Phase 1's RemoveCollidingSiblings as distinct overloads.
• Parameter.ShouldGenerateKeepAlive returns false for projected inline-class params (avoids needless GC.KeepAlive on a value-type wrapping a primitive).
• New KotlinInlineClassStruct TypeWriter emits the wrapper struct.
• JavaInteropCodeGenerator.WriteType routes inline-class ClassGen instances to the new writer instead of BoundClass.
• New TypeNameUtilities.JniSignatureToJavaTypeName helper (handles nested types via $ → .).

Tests

• Bytecode-Tests: 82 passed (2 pre-existing skips). New KotlinInlineClassCollisionTests exercise the real Kotlin .class fixtures.
• generator-Tests: 7 unit tests in KotlinInlineClassTests plus 1 end-to-end test in KotlinInlineClassEndToEndTests that drives real Kotlin .class files (compiled by tests/Xamarin.Android.Tools.Bytecode-Tests/kotlin-gradle/) through KotlinFixups → XmlClassDeclarationBuilder → XmlApiImporter → Java.Interop.Tools.Generator.Transformation.KotlinFixups → Validate → JavaInteropCodeGenerator. The end-to-end test mirrors the real CodeGenerator.Generate pipeline and would have caught the RemoveCollidingSiblings regression that motivated the MethodBase.Matches fix.
• 23 pre-existing generator-Tests failures are unrelated environment issues (Roslyn / FileStream); confirmed unchanged.

Build-system

The Kotlin/Gradle fixture target (BuildKotlinGradleProject) was extracted into a shared tests/Xamarin.Android.Tools.Bytecode-Tests/kotlin-gradle.targets file imported by both Bytecode-Tests.csproj and generator-Tests.csproj, so the .class files are produced regardless of which test project the build hits first.

Out of scope / known limitations

• Boxed inline-class positions (nullable like MyColor?, generics like List<MyColor>, supertype implementations) still emit Lcom/example/MyColor; references that no longer have a peer class binding. These were rare on the targeted Compose surface; users can unblock them via Metadata.xml (<remove-node>) until a follow-up.
• Reference-backed inline classes (e.g. value class Tag(val raw: String)) are detected as inline classes but the projection path requires a primitive backing field; non-primitive-backed inline classes are skipped and fall through to the legacy peer-class path.
• Generic inline classes (value class Wrap<T>(val v: T)).
• Validation against the Compose material3-android AAR is not part of this PR.

Closes part of #1431. Phase 1 (sibling-collision dedup) was #1432.

[Copilot]

Pull request overview

Adds Kotlin @JvmInline value class awareness end-to-end (bytecode → api.xml → generator) so inline-class parameters/returns can be projected as strongly-typed C# wrappers while preserving JNI marshaling on the JVM-erased underlying primitive.

Changes:

• Detect Kotlin inline/value classes in class-parse, stamp underlying JNI primitive info, and emit new inline-class attributes into api.xml.
• Import the new attributes in the generator and project method parameters/returns to inline-class wrapper types.
• Emit readonly partial struct wrapper types for inline classes and add unit tests covering import/projection/round-tripping.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tools/generator/Utilities/TypeNameUtilities.cs	Adds helper to map JNI reference signatures to Java type names for symbol lookup.
tools/generator/SourceWriters/KotlinInlineClassStruct.cs	New type writer emitting the C# readonly struct wrapper for inline classes.
tools/generator/Java.Interop.Tools.Generator.ObjectModel/ReturnValue.cs	Projects return types to inline-class wrapper structs when stamped.
tools/generator/Java.Interop.Tools.Generator.ObjectModel/Parameter.cs	Projects parameter types to inline-class wrapper structs when stamped; preserves clone data.
tools/generator/Java.Interop.Tools.Generator.ObjectModel/Method.cs	Adds storage for stamped inline-class return JNI type.
tools/generator/Java.Interop.Tools.Generator.ObjectModel/ClassGen.cs	Adds inline-class flags/underlying descriptor to the object model.
tools/generator/Java.Interop.Tools.Generator.Importers/XmlApiImporter.cs	Reads new inline-class XML attributes into the generator model.
tools/generator/Java.Interop.Tools.Generator.CodeGeneration/JavaInteropCodeGenerator.cs	Routes inline classes to the new struct writer.
tests/Xamarin.Android.Tools.Bytecode-Tests/Xamarin.Android.Tools.Bytecode-Tests.targets	Adjusts embedded Kotlin fixture class list.
tests/Xamarin.Android.Tools.Bytecode-Tests/KotlinInlineClassCollisionTests.cs	Adds tests asserting fixup stamping and XML attribute emission.
tests/generator-Tests/Unit-Tests/KotlinInlineClassTests.cs	Adds tests covering XML import and the new helper.
src/Xamarin.Android.Tools.Bytecode/XmlClassDeclarationBuilder.cs	Emits new inline-class XML attributes for classes/methods/parameters.
src/Xamarin.Android.Tools.Bytecode/Methods.cs	Adds fields to carry stamped inline-class parameter/return JNI signatures.
src/Xamarin.Android.Tools.Bytecode/Kotlin/KotlinFixups.cs	Detects inline classes and stamps inline-class parameter/return metadata for projection.
src/Xamarin.Android.Tools.Bytecode/ClassFile.cs	Stores inline-class underlying JNI descriptor on the ClassFile.

[jonathanpeppers]

/review

[github-actions]

✅ Java.Interop PR Reviewer completed successfully!

[github-actions]

✅ LGTM — well-designed feature with minor issues

Summary: This PR adds Kotlin @JvmInline value class projection through the full pipeline (bytecode → api.xml → generator → C# wrapper structs). The architecture is clean — using the existing managedName attribute for name unmangling, projecting managed types while keeping JNI marshaling on primitives via the sym / managed_type split, and carefully filtering to only primitive-backed inline classes.

Issue counts:

• ⚠️ 2 warnings (silent fallback in JniPrimitiveToCSharpType; null-forgiving operator ! usage ×4)
• 💡 1 suggestion (klass2 naming)

Positive callouts:

• The two-pass approach in DetectInlineClasses (pre-scan all classes before processing methods) correctly handles cross-class references regardless of class ordering.
• Good defensive filtering: only primitive-backed inline classes are projected; reference-backed and boxed positions are explicitly excluded with clear documentation of why.
• The end-to-end test (KotlinInlineClassEndToEndTests) exercises the real Kotlin .class fixtures through the full pipeline — much stronger than testing against hand-crafted XML alone.
• Thorough comments linking each piece to the issue tracker (#1431) and explaining the "why" behind design decisions (e.g., why boxed positions are skipped).
• Method.Clone correctly copies KotlinInlineClassReturnJniType, and Parameter.Clone correctly copies KotlinInlineClassJniType.

CI: dotnet.java-interop is still queued/pending. license/cla passed.

Generated by Java.Interop PR Reviewer for issue #1440 · ● 10.6M

[jonathanpeppers]

/review

[github-actions]

✅ Java.Interop PR Reviewer completed successfully!

[github-actions]

⚠️ Needs Changes

Well-structured PR with clean separation between the bytecode-layer detection and generator-layer projection. The new KotlinInlineClassStruct TypeWriter, the ApplyKotlinInlineClassProjection hooks in Parameter/ReturnValue.Validate, and the DetectInlineClasses pre-pass are all thoughtfully designed. The test coverage (4 bytecode tests + 7 generator unit tests + 1 end-to-end test) is solid for the isolated components.

Key Issue

Generator-layer RemoveCollidingSiblings interaction (1 ⚠️): The Phase 1 collision-dedup code in tools/generator/Java.Interop.Tools.Generator.Transformation/KotlinFixups.cs (from PR #1432) was explicitly temporary — its comment reads "Until step 2 of #1431 projects inline-class params...". This PR is step 2, but doesn't update that code. Since RemoveCollidingSiblings runs before Validate (where projection happens), overloads like Tint(MyColor) and Tint(MyAlpha) — both long-backed — would still collide on RawNativeType and one would be removed before the struct projection can disambiguate them. The end-to-end test masks this because it doesn't call KotlinFixups.Fixup(gens).

Suggestions (2 💡)

• ShouldGenerateKeepAlive for projected parameters: After projection, Parameter.Type returns the struct's FullName, which falls through to the default true case in ShouldGenerateKeepAlive, generating unnecessary GC.KeepAlive for value types.
• PascalCase vs MemberToPascalCase: The local helper only uppercases the first character; underscore-separated Kotlin names would produce casing inconsistent with the generator layer.

Positive Callouts

• Clean DetectInlineClasses pre-pass with proper validation (JvmInline annotation + metadata flags + single primitive backing field).
• The GetInlineClassJniType guard that only projects when the JVM-erased descriptor matches the underlying primitive — correctly skipping boxed/nullable positions — is a solid safety check.
• Extracting the Gradle build into a shared kotlin-gradle.targets that both Bytecode-Tests and generator-Tests import is a nice build-system improvement.
• Good decision to keep sym on the underlying primitive while projecting managed_type to the struct — this makes the implicit conversion operators handle the JNI boundary transparently.

Severity	Count
⚠️ Warning	1
💡 Suggestion	2

Generated by Java.Interop PR Reviewer for issue #1440 · ● 18M