add support for generic ad hoc unions

Author: PawelGerr

.claude/CLAUDE.md

@@ -50,7 +50,7 @@ A .NET library providing Smart Enums, Value Objects, and Discriminated Unions vi
 | Keyless Smart Enum   | `[SmartEnum]`                                 | Type-safe enum without underlying value. Identified by field reference only.                                     |
 | Simple Value Object  | `[ValueObject<TKey>]`                         | Single-value immutable type wrapping one underlying value.                                                       |
 | Complex Value Object | `[ComplexValueObject]`                        | Multi-property immutable type.                                                                                   |
-| Ad-hoc Union         | `[Union<T1, T2, ...>]` or `[AdHocUnion(...)]` | "One of" several types. Up to 5 type parameters. Cannot be generic.                                              |
+| Ad-hoc Union         | `[Union<T1, T2, ...>]` or `[AdHocUnion(...)]` | "One of" several types. Up to 5 type parameters. Can be generic via `TypeParamRef1`–`TypeParamRef5` placeholders. |
 | Regular Union        | `[Union]`                                     | Inheritance-based union. Abstract base with sealed derived types.                                                |
 
 All types must be declared as `partial`. Source generators produce: factory methods (`Create`, `TryCreate`, `Validate`), equality members, conversion operators, `Switch`/`Map` pattern matching, `IParsable<T>`/`ISpanParsable<T>` (NET9+), and serialization integration.
@@ -94,6 +94,8 @@ All types must be declared as `partial`. Source generators produce: factory meth
 
 **Ad-hoc Unions** (`[Union<T1, T2>]` or `[AdHocUnion(...)]`):
 
+- Generic unions: use `TypeParamRef1`–`TypeParamRef5` placeholders (in namespace `Thinktecture`) to reference the union's own type parameters. E.g., `[Union<TypeParamRef1, string>] public partial struct Result<T>`. Nested usage supported (e.g., `List<TypeParamRef1>`). For type parameter members: no implicit/explicit conversion operators (C# limitation), factory methods generated instead.
+- `allows ref struct` is **not supported** on ad-hoc union type parameters (TTRESG073). Ref structs cannot be boxed, which conflicts with equality, `Value` property, and Switch/Map delegate patterns.
 - Stateless types (`TXIsStateless = true`): store only discriminator, not instance. Prefer structs.
 - Backing fields: with 2+ distinct non-stateless reference types, reference types auto-share a single `object? _obj` field (value types keep typed fields). `UseSingleBackingField = true` forces all types (including value types, with boxing) into `_obj`.
 
@@ -156,7 +158,7 @@ SyntaxProvider (filter by attribute via ForAttributeWithMetadataName)
 
 ### Analyzers & Refactorings
 
-1. `ThinktectureRuntimeExtensionsAnalyzer` -- 57 diagnostic rules (`TTRESG` prefix) for correct usage
+1. `ThinktectureRuntimeExtensionsAnalyzer` -- 59 diagnostic rules (`TTRESG` prefix) for correct usage
 2. `ThinktectureRuntimeExtensionsInternalUsageAnalyzer` -- Prevents external use of internal APIs
 3. `SwitchMapCompletionRefactoringProvider` -- IDE refactoring (light bulb action) that auto-generates arguments for `Switch`/`Map`/`SwitchPartially`/`MapPartially` method calls on Smart Enums and Unions
 

.claude/guides/IMPLEMENTATION.md

@@ -154,7 +154,7 @@ public partial class PriorityLevel<TContext> where TContext : notnull
 
 Note: Generated partial declarations do not need to repeat generic constraints -- C# inherits them from the original declaration.
 
-**Important**: Ad-hoc unions cannot be generic (the analyzer enforces this via a diagnostic).
+**Important**: Ad-hoc unions can be generic via `TypeParamRef1`–`TypeParamRef5` placeholders. The source generator resolves these placeholders to the union's own type parameters. For type parameter members, factory methods are generated instead of conversion operators (C# limitation). See diagnostics TTRESG071, TTRESG072, TTRESG107 for validation rules.
 
 ## Nullability Awareness
 

Directory.Build.props

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <Copyright>(c) $([System.DateTime]::Now.Year), Pawel Gerr. All rights reserved.</Copyright>
-    <VersionPrefix>10.1.2</VersionPrefix>
+    <VersionPrefix>10.2.0</VersionPrefix>
     <Authors>Pawel Gerr</Authors>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageProjectUrl>https://github.com/PawelGerr/Thinktecture.Runtime.Extensions</PackageProjectUrl>

docs

@@ -23,7 +23,6 @@ public sealed class ThinktectureRuntimeExtensionsAnalyzer : DiagnosticAnalyzer
       DiagnosticsDescriptors.InnerSmartEnumOnNonFirstLevelMustBePublic,
       DiagnosticsDescriptors.KeyMemberShouldNotBeNullable,
       DiagnosticsDescriptors.StaticPropertiesAreNotConsideredItems,
-      DiagnosticsDescriptors.AdHocUnionsMustNotBeGeneric,
       DiagnosticsDescriptors.BaseClassFieldMustBeReadOnly,
       DiagnosticsDescriptors.BaseClassPropertyMustBeReadOnly,
       DiagnosticsDescriptors.SmartEnumKeyShouldNotBeNullable,
@@ -558,7 +557,6 @@ private static void ValidateAdHocUnion(
 
       CheckConstructors(context, type, mustBePrivate: false, canHavePrimaryConstructor: false);
       TypeMustBePartial(context, type);
-      TypeMustNotBeGeneric(context, type, type.GetTypeIdentifierLocation(context.CancellationToken));
    }
 
    private static void ValidateRegularUnion(
@@ -1102,18 +1100,6 @@ private static void ValidateKeyedSmartEnum(
       ValidateKeyMemberComparers(context, enumType, keyType, smartEnumAttribute, factory, tdsLocation, false);
    }
 
-   private static void TypeMustNotBeGeneric(SymbolAnalysisContext context, INamedTypeSymbol type, Location tdsLocation)
-   {
-      if (!type.TypeParameters.IsDefaultOrEmpty)
-      {
-         ReportDiagnostic(
-            context,
-            DiagnosticsDescriptors.AdHocUnionsMustNotBeGeneric,
-            tdsLocation,
-            BuildTypeName(type));
-      }
-   }
-
    private static void Check_ItemLike_StaticProperties(
       SymbolAnalysisContext context,
       INamedTypeSymbol enumType)

src/Thinktecture.Runtime.Extensions.Analyzers/CodeAnalysis/Diagnostics/ThinktectureRuntimeExtensionsAnalyzer.cs

@@ -33,7 +33,6 @@
  TTRESG049  | ThinktectureRuntimeExtensionsAnalyzer              | Warning  | Complex Value Object with string members needs equality comparer                 
  TTRESG050  | ThinktectureRuntimeExtensionsAnalyzer              | Error    | Method with UseDelegateFromConstructor must be partial                           
  TTRESG051  | ThinktectureRuntimeExtensionsAnalyzer              | Error    | Method with UseDelegateFromConstructor must not have generics                    
- TTRESG052  | ThinktectureRuntimeExtensionsAnalyzer              | Error    | The type must not be inside generic type                                         
  TTRESG053  | ThinktectureRuntimeExtensionsAnalyzer              | Error    | Derived type of a union must not be generic                                      
  TTRESG054  | ThinktectureRuntimeExtensionsAnalyzer              | Error    | Discriminated union must be sealed or have private constructors only             
  TTRESG055  | ThinktectureRuntimeExtensionsAnalyzer              | Error    | Discriminated union implemented using a record must be sealed                    

src/Thinktecture.Runtime.Extensions.Roslyn.Sources/AnalyzerReleases.Shipped.md

@@ -1,10 +1,14 @@
 ### New Rules
 
- Rule ID | Category | Severity | Notes
----------|----------|----------|-------
+ Rule ID   | Category                              | Severity | Notes
+-----------|---------------------------------------|----------|-----------------------------------------------------------------------------
+ TTRESG071 | ThinktectureRuntimeExtensionsAnalyzer | Error    | TypeParamRef index exceeds the number of type parameters
+ TTRESG072 | ThinktectureRuntimeExtensionsAnalyzer | Error    | TypeParamRef cannot be used on non-generic ad-hoc union
+ TTRESG073 | ThinktectureRuntimeExtensionsAnalyzer | Error    | Ad-hoc unions do not support 'allows ref struct' type parameters
+ TTRESG107 | ThinktectureRuntimeExtensionsAnalyzer | Warning  | Generic ad-hoc union does not reference any type parameter via TypeParamRef
 
 ### Removed Rules
 
- Rule ID | Category | Severity | Notes
----------|----------|----------|-------
-TTRESG052 | Thinktecture.Runtime.Extensions | Error | Types are now allowed inside generic types
+ Rule ID   | Category                              | Severity | Notes
+-----------|---------------------------------------|----------|---------------------------------------------
+ TTRESG033 | ThinktectureRuntimeExtensionsAnalyzer | Error    | Ad hoc unions are now allowed to be generic

src/Thinktecture.Runtime.Extensions.Roslyn.Sources/AnalyzerReleases.Unshipped.md

@@ -94,6 +94,23 @@ public static class Convertible
       }
    }
 
+   public static class TypeParamRef
+   {
+      public const string NAMESPACE = "Thinktecture";
+
+      public const string NAME_1 = "TypeParamRef1";
+      public const string NAME_2 = "TypeParamRef2";
+      public const string NAME_3 = "TypeParamRef3";
+      public const string NAME_4 = "TypeParamRef4";
+      public const string NAME_5 = "TypeParamRef5";
+
+      public const string FULL_NAME_1 = $"{NAMESPACE}.{NAME_1}";
+      public const string FULL_NAME_2 = $"{NAMESPACE}.{NAME_2}";
+      public const string FULL_NAME_3 = $"{NAMESPACE}.{NAME_3}";
+      public const string FULL_NAME_4 = $"{NAMESPACE}.{NAME_4}";
+      public const string FULL_NAME_5 = $"{NAMESPACE}.{NAME_5}";
+   }
+
    public static class Attributes
    {
       public const string NAMESPACE = "Thinktecture";

src/Thinktecture.Runtime.Extensions.Roslyn.Sources/CodeAnalysis/Constants.cs

@@ -12,7 +12,6 @@ internal static class DiagnosticsDescriptors
    public static readonly DiagnosticDescriptor InnerSmartEnumOnFirstLevelMustBePrivate = new("TTRESG014", "Inner Smart Enum on first level must be private", "Derived inner Smart Enum '{0}' on first-level must be private", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor InnerSmartEnumOnNonFirstLevelMustBePublic = new("TTRESG015", "Inner Smart Enum on non-first level must be public", "Derived inner Smart Enum '{0}' on non-first-level must be public", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor KeyMemberShouldNotBeNullable = new("TTRESG017", "The key member must not be nullable", "A key member must not be nullable", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
-   public static readonly DiagnosticDescriptor AdHocUnionsMustNotBeGeneric = new("TTRESG033", "Ad hoc unions must not be generic", "Type '{0}' must not be generic", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor BaseClassFieldMustBeReadOnly = new("TTRESG034", "Field of the base class must be read-only", "The field '{0}' of the base class '{1}' must be read-only", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor BaseClassPropertyMustBeReadOnly = new("TTRESG035", "Property of the base class must be read-only", "The property '{0}' of the base class '{1}' must be read-only", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor SmartEnumKeyShouldNotBeNullable = new("TTRESG036", "The key type must not be nullable", "The generic type T of SmartEnumAttribute<T> must not be nullable", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
@@ -46,6 +45,9 @@ internal static class DiagnosticsDescriptors
    public static readonly DiagnosticDescriptor MultipleObjectFactoryAttributesWithUseWithEntityFramework = new("TTRESG068", "Multiple ObjectFactoryAttribute instances cannot have UseWithEntityFramework = true", "Type '{0}' has multiple ObjectFactoryAttribute instances with 'UseWithEntityFramework = true'. Only one ObjectFactoryAttribute can have 'UseWithEntityFramework = true'.", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor MultipleObjectFactoryAttributesWithUseForModelBinding = new("TTRESG069", "Multiple ObjectFactoryAttribute instances cannot have UseForModelBinding = true", "Type '{0}' has multiple ObjectFactoryAttribute instances with 'UseForModelBinding = true'. Only one ObjectFactoryAttribute can have 'UseForModelBinding = true'.", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor MultipleObjectFactoryAttributesWithOverlappingSerializationFrameworks = new("TTRESG070", "Multiple ObjectFactoryAttribute instances cannot specify overlapping serialization frameworks", "Type '{0}' has multiple ObjectFactoryAttribute instances with overlapping serialization frameworks '{1}'. Each serialization framework can only be used by one ObjectFactoryAttribute.", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
+   public static readonly DiagnosticDescriptor TypeParamRefIndexOutOfRange = new("TTRESG071", "TypeParamRef index exceeds the number of type parameters", "TypeParamRef{0} references type parameter at index {0}, but the union type '{1}' has only {2} type parameter(s)", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
+   public static readonly DiagnosticDescriptor TypeParamRefOnNonGenericUnion = new("TTRESG072", "TypeParamRef cannot be used on non-generic ad-hoc union", "TypeParamRef{0} cannot be used on non-generic ad-hoc union '{1}'", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
+   public static readonly DiagnosticDescriptor AllowsRefStructNotSupportedOnAdHocUnion = new("TTRESG073", "Ad-hoc unions do not support 'allows ref struct' type parameters", "Ad-hoc union '{0}' has type parameter '{1}' with 'allows ref struct' which is not supported. Remove the 'allows ref struct' anti-constraint from the type parameter.", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
 
    public static readonly DiagnosticDescriptor ErrorDuringModulesAnalysis = new("TTRESG097", "Error during analysis of referenced modules", "Error during analysis of referenced modules: '{0}'", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Error, true);
    public static readonly DiagnosticDescriptor ErrorDuringCodeAnalysis = new("TTRESG098", "Error during code analysis", "Error during code analysis of '{0}': '{1}'", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Warning, true);
@@ -58,6 +60,7 @@ internal static class DiagnosticsDescriptors
    public static readonly DiagnosticDescriptor MembersDisallowingDefaultValuesMustBeRequired = new("TTRESG104", "The member must be marked as 'required' to ensure proper initialization", "The {0} '{1}' of type '{2}' must be marked as 'required' to ensure proper initialization", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Warning, true);
    public static readonly DiagnosticDescriptor ComparisonAndEqualityOperatorsMismatch = new("TTRESG105", "Comparison and equality operators settings mismatch", "The type '{0}' has 'ComparisonOperators = {1}' and 'EqualityComparisonOperators = {2}' which differ. Set them to the same value.", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Warning, true);
    public static readonly DiagnosticDescriptor InnerTypeDoesNotDeriveFromUnion = new("TTRESG106", "Inner type should derive from union type", "The inner type '{0}' should derive from union type '{1}'", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Warning, true);
+   public static readonly DiagnosticDescriptor GenericUnionWithoutTypeParamRef = new("TTRESG107", "Generic ad-hoc union does not reference any type parameter via TypeParamRef", "Generic ad-hoc union '{0}' does not reference any type parameter via TypeParamRef. All type parameters are unused.", Constants.ANALYZER_CATEGORY, DiagnosticSeverity.Warning, true);
 
    public static readonly DiagnosticDescriptor InternalApiUsage = new("TTRESG1000", "Internal Thinktecture.Runtime.Extensions API usage", "'{0}' is an internal API that supports the Thinktecture.Runtime.Extensions infrastructure and not subject to the same compatibility standards as public APIs. It may be changed or removed without notice in any release.", Constants.INTERNAL_USAGE_ANALYZER_CATEGORY, DiagnosticSeverity.Warning, true);