[typemap] Diagnose unsupported constructor shapes

Documentation/docs-mobile/TOC.yml

@@ -330,6 +330,14 @@
         href: messages/xa4249.md
       - name: XA4258
         href: messages/xa4258.md
+      - name: XA4259
+        href: messages/xa4259.md
+      - name: XA4260
+        href: messages/xa4260.md
+      - name: XA4261
+        href: messages/xa4261.md
+      - name: XA4262
+        href: messages/xa4262.md
       - name: XA4263
         href: messages/xa4263.md
       - name: XA4301

Documentation/docs-mobile/messages/index.md

@@ -228,6 +228,10 @@ Either change the value in the AndroidManifest.xml to match the $(SupportedOSPla
 + [XA4255](xa4255.md): Generated trimmable type map Java source '{path}' was not found.
 + [XA4256](xa4256.md): Skipping Java peer type '{type}' from assembly '{assembly}' because referenced type '{referencedType}' from assembly '{referencedAssembly}' could not be resolved in '{path}'. This type will not be included in the trimmable type map.
 + [XA4258](xa4258.md): Java name '{name}' contains reserved Java identifier '{identifier}'. Change the package or type name.
++ [XA4259](xa4259.md): Type '{type}' has multiple managed constructors that map to the same Java Native Interface (JNI) signature '{signature}'.
++ [XA4260](xa4260.md): Type '{type}' has a constructor parameter type '{parameterType}' that cannot be represented in a Java constructor.
++ [XA4261](xa4261.md): Type '{type}' has Java constructor signature '{signature}', but its base type does not expose a compatible Java constructor.
++ [XA4262](xa4262.md): Type '{type}' has an invalid [Export] SuperArgumentsString value '{value}'.
 + [XA4263](xa4263.md): The exported member '{member}' has unsupported signature type '{type}'. Use a Java peer type, a supported managed-to-Java mapping, or [ExportParameter].
 + XA4300: Native library '{library}' will not be bundled because it has an unsupported ABI.
 + [XA4301](xa4301.md): Apk already contains the item `xxx`.

Documentation/docs-mobile/messages/xa4259.md

@@ -0,0 +1,23 @@
+---
+title: .NET for Android error XA4259
+description: XA4259 error code
+ms.date: 08/28/2026
+f1_keywords:
+  - "XA4259"
+---
+
+# .NET for Android error XA4259
+
+## Example message
+
+```text
+error XA4259: Type 'Example.MyActivity' has multiple managed constructors that map to the same Java Native Interface (JNI) signature '(I)V'. Change the constructor parameter types so each constructor has a unique JNI signature.
+```
+
+## Issue
+
+Two managed constructor parameter lists collapse to the same JNI signature. For example, `int` and `uint` both map to Java `int`, and two managed binding types can alias the same Java type.
+
+## Solution
+
+Remove one constructor or change its parameters so every Java-visible constructor has a unique JNI signature.

Documentation/docs-mobile/messages/xa4260.md

@@ -0,0 +1,23 @@
+---
+title: .NET for Android error XA4260
+description: XA4260 error code
+ms.date: 08/28/2026
+f1_keywords:
+  - "XA4260"
+---
+
+# .NET for Android error XA4260
+
+## Example message
+
+```text
+error XA4260: Type 'Example.MyActivity' has a constructor parameter type 'System.Int32&' that cannot be represented in a Java constructor. Remove the constructor or change the parameter to a supported Java type.
+```
+
+## Issue
+
+Java callable wrappers cannot represent generic parameters or instantiations, by-reference types, pointers, function pointers, or rectangular arrays in constructor signatures.
+
+## Solution
+
+Remove the Java-visible constructor or use primitive, string, bound Java object, or single-dimensional array parameters.

Documentation/docs-mobile/messages/xa4261.md

@@ -0,0 +1,23 @@
+---
+title: .NET for Android error XA4261
+description: XA4261 error code
+ms.date: 08/28/2026
+f1_keywords:
+  - "XA4261"
+---
+
+# .NET for Android error XA4261
+
+## Example message
+
+```text
+error XA4261: Type 'Example.MyActivity' has Java constructor signature '(Ljava/lang/String;)V', but its base type does not expose a compatible Java constructor. Add a compatible base constructor or remove the derived constructor.
+```
+
+## Issue
+
+The generated Java constructor must invoke a Java constructor on its base type. No compatible base constructor or parameterless fallback is available.
+
+## Solution
+
+Expose a compatible registered constructor on the base type, add a parameterless base constructor, or remove the derived constructor.

Documentation/docs-mobile/messages/xa4262.md

@@ -0,0 +1,23 @@
+---
+title: .NET for Android error XA4262
+description: XA4262 error code
+ms.date: 08/28/2026
+f1_keywords:
+  - "XA4262"
+---
+
+# .NET for Android error XA4262
+
+## Example message
+
+```text
+error XA4262: Type 'Example.MyActivity' has an invalid [Export] SuperArgumentsString value 'p1'. The value references a constructor parameter that does not exist.
+```
+
+## Issue
+
+`SuperArgumentsString` references a generated Java constructor parameter outside the available `p0`, `p1`, and subsequent parameter range.
+
+## Solution
+
+Correct the parameter reference or remove `SuperArgumentsString` to forward all constructor parameters to the Java base constructor.

src/Microsoft.Android.Sdk.TrimmableTypeMap/ITrimmableTypeMapLogger.cs

@@ -27,6 +27,10 @@ void LogUnresolvableJavaPeerSkippedWarning (
 	void LogExportFieldOnGenericTypeError ();
 	void LogExportFieldReturnsVoidError ();
 	void LogUnsupportedExportSignatureError (string memberName, string managedTypeName);
+	void LogAmbiguousConstructorSignatureError (string managedTypeName, string jniSignature);
+	void LogUnsupportedConstructorParameterTypeError (string managedTypeName, string parameterType);
+	void LogMissingBaseConstructorError (string managedTypeName, string jniSignature);
+	void LogInvalidSuperArgumentsStringError (string managedTypeName, string superArgumentsString);
 	void LogCustomJavaObjectError (string managedTypeName);
 	void LogCustomJavaObjectWarning (string managedTypeName);
 }

src/Microsoft.Android.Sdk.TrimmableTypeMap/Scanner/JavaPeerInfo.cs

@@ -120,6 +120,12 @@ public sealed record JavaPeerInfo
 	/// </summary>
 	public IReadOnlyList<JavaConstructorInfo> JavaConstructors { get; init; } = [];
 
+	/// <summary>
+	/// Constructor shapes which cannot be emitted safely by the trimmable type map.
+	/// Generation reports these before producing any Java or type-map output.
+	/// </summary>
+	public IReadOnlyList<ConstructorDiagnosticInfo> ConstructorDiagnostics { get; init; } = [];
+
 	/// <summary>
 	/// Java fields from [ExportField] attributes.
 	/// Each field is initialized by calling the annotated method.
@@ -384,6 +390,20 @@ public sealed record JavaConstructorInfo
 	public IReadOnlyList<JavaAnnotationInfo> Annotations { get; init; } = [];
 }
 
+public sealed record ConstructorDiagnosticInfo
+{
+	public required ConstructorDiagnosticKind Kind { get; init; }
+	public required string Detail { get; init; }
+}
+
+public enum ConstructorDiagnosticKind
+{
+	AmbiguousJniSignature,
+	UnsupportedParameterType,
+	MissingBaseConstructor,
+	InvalidSuperArgumentsString,
+}
+
 /// <summary>
 /// Describes a Java field from an [ExportField] attribute.
 /// The field is initialized by calling the annotated method.