Improvements, refactoring and tests

Author: PawelGerr

.claude/agents/feature-reviewer.md

@@ -20,7 +20,7 @@ When reviewing a newly implemented feature, you will:
 
 **For Smart Enums:**
 - Confirm the type is marked `partial` and uses appropriate attribute (`[SmartEnum]` or `[SmartEnum<TKey>]`)
-- Verify items are public static readonly/const fields or properties
+- Verify items are public static readonly fields
 - Check that keyed enums specify appropriate key member configuration
 - Ensure sealed modifier is present if no derived types exist
 - Validate that comparison operators are only used with keyed enums

.clinerules

@@ -1,15 +1,11 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to the AI assistant when working with code in this repository.
 
 ## Common Commands
 
 ### Build and Test
-- **Build solution**: `dotnet build --configuration Release`
+- **Build solution**: `dotnet build`
 - **Restore packages**: `dotnet restore`
-- **Run all tests**: `dotnet test --configuration Release`
-- **Pack NuGet packages**: `dotnet pack --configuration Release --output out`
-- **Format code**: `dotnet format`
+- **Run all tests**: `dotnet test`
 
 ### Development Requirements
 - .NET 9.0 SDK (as specified in global.json)
@@ -22,7 +18,7 @@ This is a .NET library providing **Smart Enums**, **Value Objects**, and **Discr
 
 ### Core Components
 - **`src/Thinktecture.Runtime.Extensions`**: Core library with base interfaces, attributes, and runtime helpers
-  - Attributes: `SmartEnumAttribute<TKey>`, `SmartEnumAttribute`, `ValueObjectAttribute<TKey>`, `ComplexValueObjectAttribute`, `UnionAttribute<T1,T2,...>` (up to 5 type parameters), `UnionAttribute`, `ObjectFactoryAttribute<T>`
+  - Attributes: `SmartEnumAttribute<TKey>`, `SmartEnumAttribute`, `ValueObjectAttribute<TKey>`, `ComplexValueObjectAttribute`, `UnionAttribute<T1,T2,...>` (up to 5 type parameters), `UnionAttribute`, `AdHocUnionAttribute`, `ObjectFactoryAttribute<T>`
   - Additional attributes: `KeyMemberEqualityComparerAttribute`, `KeyMemberComparerAttribute`, `MemberEqualityComparerAttribute`, `IgnoreMemberAttribute`, `ValidationErrorAttribute`, `UseDelegateFromConstructorAttribute`, `UnionSwitchMapOverloadAttribute`
   - Key interfaces: `ISmartEnum<TKey>`, `IEnum`, `IKeyedObject<TKey>`, `IKeyedValueObject<TKey>`, `IComplexValueObject`, `IValidationError`, `IObjectFactory<T>`
   - Utility types: `ValidationError`, `ComparerAccessors`, collection helpers (EmptyDictionary, EmptyLookup, SingleItemReadOnlyDictionary, etc.)
@@ -75,7 +71,7 @@ The `Thinktecture.Runtime.Extensions.SourceGenerator` project contains multiple
 
 #### Analyzers
 1. **`ThinktectureRuntimeExtensionsAnalyzer`**: Main diagnostic analyzer with 40+ diagnostic rules that validates correct usage of library features
-   - **Type structure**: Ensures types with `[SmartEnum]`, `[ValueObject]`, or `[Union]` are `partial`, are class/struct, not generic (except regular unions and complex value objects), not nested in generic types
+   - **Type structure**: Ensures types with `[SmartEnum]`, `[ValueObject]`, `[Union]`, or `[AdHocUnion]` are `partial`, are class/struct, not generic (except regular unions and complex value objects), not nested in generic types
    - **Constructor rules**: Validates constructors are private, no primary constructors allowed
    - **Member validation**:
      - Fields must be readonly, properties must be readonly (no set) or have private init
@@ -105,7 +101,7 @@ The `Thinktecture.Runtime.Extensions.SourceGenerator` project contains multiple
 
 #### 1. Smart Enums
 **Keyless**: `[SmartEnum]` - Type-safe enums without underlying values
-- Items are defined as public static readonly/const fields or properties
+- Items are defined as public static readonly fields
 - Cannot use comparison operators (no key to compare)
 - Supports `Switch`/`Map` methods, equality operators, serialization
 - Must be sealed if no derived types
@@ -150,7 +146,7 @@ The `Thinktecture.Runtime.Extensions.SourceGenerator` project contains multiple
 - Validation: Implement `ValidateFactoryArguments` (preferred) or `ValidateConstructorArguments`
 
 #### 3. Discriminated Unions
-**Ad-hoc Unions**: `[Union<T1, T2>]` through `[Union<T1, T2, T3, T4, T5>]`
+**Ad-hoc Unions**: `[Union<T1, T2>]` through `[Union<T1, T2, T3, T4, T5>]`, or non generic `[AdHocUnion(Type t1, Type t2, Type? t3, Type? t4, Type? t5)]`
 - Simple combination of 2-5 types without inheritance
 - Generates implicit conversion operators from each type to union (configurable via `ConversionFromValue`)
 - Type checking: `IsT1`, `IsT2`, etc. properties
@@ -276,15 +272,22 @@ The source generators follow a consistent pattern:
 
 ## Testing Strategy
 - xUnit for unit testing
-- AwesomeAssertions for readable assertions
-- Verify.Xunit for snapshot testing
+- Analyze whether `Theory` can be used for parameterized tests, before considering separate tests for each case
+- Edge cases must be tested as well
+- AwesomeAssertions for readable assertions (uses same api as FluentAssertions)
+- Verify.Xunit for snapshot testing (useful for generated code verification)
 - Comprehensive tests for generated code, serialization, and framework integration
+- Follow Arrange-Act-Assert pattern for unit tests
+- The tests should have same folder structure as the source code (e.g., with class `Ns1/Ns2/MyClass.cs` -> `Ns1/Ns2/MyCassTests/MyMethod.cs`)
+- Create a separate test class/file for every public member (eg. for class `MyClass` with method `MyMethod` create `MyCassTests/MyMethod.cs`)
+- If the tests requires a `CSharpCompilation` use base class `test/Thinktecture.Runtime.Extensions.SourceGenerator.Tests/CompilationTestBase.cs`
+- When testing attributes, use real attributes, like `SmartEnumAttribute`, `ValueObjectAttribute`, `ComplexValueObjectAttribute`, `UnionAttribute`, `ObjectFactoryAttribute`, etc. Don't use fake attributes.
 
 ## Code Style
 - Follow `.editorconfig` settings (especially in `src/.editorconfig`)
-- **XML documentation required** for all publicly visible types and members (except source generator, test, and sample projects)
+- **XML documentation required** for all publicly visible types and members (except source generator, analyzer, test, and sample projects)
 - Multi-target framework support (net7.0 base, with EF Core version-specific projects)
-- Use `dotnet format` to format the entire solution
+- Don't use `#region`/`#endregion`
 
 ## Common Troubleshooting and Best Practices
 
@@ -294,14 +297,14 @@ The source generators follow a consistent pattern:
 3. **Null handling**: For nullable key types, consider using `NullInFactoryMethodsYieldsNull` or `EmptyStringInFactoryMethodsYieldsNull` instead of throwing exceptions
 4. **Immutability**: All members should be readonly (fields) or have no setter/private init (properties)
 5. **Constructors**: Keep constructors private to enforce use of factory methods (`Create`, `TryCreate`)
-6. **Smart Enum items**: Must be public static readonly/const - non-static properties won't be recognized as items
+6. **Smart Enum items**: Must be public static readonly fields - non-static fields or properties won't be recognized as items
 7. **Serialization**: Reference integration packages in the same project as your types for automatic code generation, or manually register converter factories
 8. **Partial keyword**: Types must be marked `partial` for source generators to work
 
 ### Common Issues
 1. **"Type must be partial"**: Add `partial` keyword to your class/struct declaration
 2. **"String-based value object needs equality comparer"**: Add `[KeyMemberEqualityComparer<MyType, string, StringComparer>]` attribute
-3. **"Smart enum has no items"**: Ensure items are public static readonly/const fields or properties of the enum type
+3. **"Smart enum has no items"**: Ensure items are public static readonly fields of the enum type
 4. **"Custom key member implementation not found"**: When using `SkipKeyMember = true`, ensure you've implemented the key member with the correct name and type
 5. **"Members disallowing default values must be required"**: Properties with `IDisallowDefaultValue` constraint must use `required` keyword or be initialized
 6. **Serialization not working**: Ensure integration package is referenced, or manually register converters/formatters
@@ -325,3 +328,143 @@ The source generators follow a consistent pattern:
 - **Result<T>**: Generic union for success/failure without exceptions (`Success(T Value)`, `Failure(string Error)`)
 - **PartiallyKnownDate**: Regular union for dates with varying precision (year only, year/month, full date)
 - **Jurisdiction**: Complex domain modeling combining unions and value objects
+
+---
+
+## Attribute Configuration Reference
+
+This section lists constructor arguments and configurable properties for key attributes.
+
+Notes:
+- Defaults shown reflect runtime defaults from constructors or property getters.
+- Some properties only take effect under certain conditions (see descriptions).
+
+### Base Attributes (common configuration)
+
+- ValueObjectAttributeBase (base for ValueObjectAttribute<TKey>, ComplexValueObjectAttribute)
+  - Properties:
+    - SkipFactoryMethods: bool — do not generate Create/TryCreate/Validate
+    - ConstructorAccessModifier: AccessModifier — default Private
+    - CreateFactoryMethodName: string — default "Create" (whitespace resets to default)
+    - TryCreateFactoryMethodName: string — default "TryCreate" (whitespace resets to default)
+    - SkipToString: bool — skip ToString() generation
+    - AllowDefaultStructs: bool — allow default(struct) instances (structs only)
+    - DefaultInstancePropertyName: string — default "Empty" (structs only)
+    - SerializationFrameworks: SerializationFrameworks — default All
+
+- UnionAttributeBase (base for AdHocUnionAttribute and generic UnionAttribute<...>)
+  - Properties:
+    - DefaultStringComparison: StringComparison — default OrdinalIgnoreCase
+    - SkipToString: bool — skip ToString() generation
+    - ConstructorAccessModifier: UnionConstructorAccessModifier — default Public
+    - ConversionFromValue: ConversionOperatorsGeneration — default Implicit
+    - ConversionToValue: ConversionOperatorsGeneration — default Explicit
+    - SwitchMethods: SwitchMapMethodsGeneration — configure Switch generation
+    - MapMethods: SwitchMapMethodsGeneration — configure Map generation
+    - SwitchMapStateParameterName: string? — default "state"
+    - UseSingleBackingField: bool — default false
+
+### SmartEnumAttribute (keyless)
+- Targets: class
+- Constructors:
+  - SmartEnumAttribute()
+- Properties:
+  - EqualityComparisonOperators: OperatorsGeneration — generation for equality operators
+  - SwitchMethods: SwitchMapMethodsGeneration — Switch generation
+  - MapMethods: SwitchMapMethodsGeneration — Map generation
+  - SwitchMapStateParameterName: string? — default "state"
+
+### SmartEnumAttribute<TKey>
+- Targets: class; where TKey : notnull
+- Constructors:
+  - SmartEnumAttribute() — sets defaults
+- Properties:
+  - KeyMemberType: Type — default typeof(TKey)
+  - KeyMemberAccessModifier: AccessModifier — default Public
+  - KeyMemberKind: MemberKind — default Property
+  - KeyMemberName: string — default "_key" if private field; otherwise "Key"
+  - SkipIComparable: bool — skip IComparable<T> when key not comparable
+  - SkipIParsable: bool — skip IParsable<T> when key not string/IParsable
+  - ComparisonOperators: OperatorsGeneration — comparison operators (depends on EqualityComparisonOperators)
+  - EqualityComparisonOperators: OperatorsGeneration — equality operators; coerced to at least ComparisonOperators
+  - SkipIFormattable: bool — skip IFormattable when key not IFormattable
+  - SkipToString: bool — skip ToString()
+  - SwitchMethods: SwitchMapMethodsGeneration
+  - MapMethods: SwitchMapMethodsGeneration
+  - ConversionToKeyMemberType: ConversionOperatorsGeneration — default Implicit
+  - ConversionFromKeyMemberType: ConversionOperatorsGeneration — default Explicit
+  - SerializationFrameworks: SerializationFrameworks — default All
+  - SwitchMapStateParameterName: string? — default "state"
+
+### ValueObjectAttribute<TKey>
+- Targets: class | struct; where TKey : notnull
+- Inherits: ValueObjectAttributeBase
+- Constructors:
+  - ValueObjectAttribute() — sets defaults
+- Properties:
+  - KeyMemberType: Type — readonly, typeof(TKey)
+  - KeyMemberAccessModifier: AccessModifier — default Private
+  - KeyMemberKind: MemberKind — default Field
+  - KeyMemberName: string — default "_value" if private field; otherwise "Value"
+  - SkipKeyMember: bool — do not generate key member; implement manually (use KeyMemberName)
+  - NullInFactoryMethodsYieldsNull: bool — Create/TryCreate/Validate return null on null input (class + factories only; implied true if EmptyStringInFactoryMethodsYieldsNull is true)
+  - EmptyStringInFactoryMethodsYieldsNull: bool — string-key empty/whitespace yields null (class + factories only)
+  - SkipIComparable: bool — skip if key not comparable and no custom comparer
+  - SkipIParsable: bool — skip if factories skipped or key not string/IParsable
+  - AdditionOperators: OperatorsGeneration — requires key supports these ops
+  - SubtractionOperators: OperatorsGeneration — requires key supports these ops
+  - MultiplyOperators: OperatorsGeneration — requires key supports these ops
+  - DivisionOperators: OperatorsGeneration — requires key supports these ops
+  - ComparisonOperators: OperatorsGeneration — depends on EqualityComparisonOperators
+  - EqualityComparisonOperators: OperatorsGeneration — coerced to at least ComparisonOperators
+  - SkipIFormattable: bool — skip if key not IFormattable
+  - ConversionToKeyMemberType: ConversionOperatorsGeneration — default Implicit
+  - UnsafeConversionToKeyMemberType: ConversionOperatorsGeneration — default Explicit (may throw)
+  - ConversionFromKeyMemberType: ConversionOperatorsGeneration — default Explicit
+
+### ComplexValueObjectAttribute
+- Targets: class | struct
+- Inherits: ValueObjectAttributeBase
+- Properties:
+  - DefaultStringComparison: StringComparison — default OrdinalIgnoreCase
+
+### UnionAttribute<T1, T2>, ..., UnionAttribute<T1, T2, T3, T4, T5>
+- Targets: class | struct
+- Inherits: UnionAttributeBase
+- Properties (per generic parameter):
+  - T1Name, T2Name, ...: string? — override member name (default: type name)
+  - T1IsNullableReferenceType, T2IsNullableReferenceType, ...: bool — mark as nullable reference type (no effect for structs)
+
+### AdHocUnionAttribute (non-generic version of UnionAttribute<T1, T2, ...>)
+- Targets: class | struct
+- Inherits: UnionAttributeBase
+- Constructors:
+  - AdHocUnionAttribute(Type t1, Type t2, Type? t3 = null, Type? t4 = null, Type? t5 = null)
+- Properties:
+  - T1, T2: Type — required member types
+  - T3, T4, T5: Type? — optional member types
+  - T1Name..T5Name: string? — override member names (default: type name)
+  - T1IsNullableReferenceType..T5IsNullableReferenceType: bool — mark as nullable reference type (no effect for structs)
+
+### UnionAttribute (regular inheritance-based unions)
+- Targets: class
+- Constructors:
+    - UnionAttribute() — sets ConversionFromValue = Implicit
+- Properties:
+    - SwitchMethods: SwitchMapMethodsGeneration
+    - MapMethods: SwitchMapMethodsGeneration
+    - ConversionFromValue: ConversionOperatorsGeneration — default Implicit
+    - SwitchMapStateParameterName: string? — default "state"
+
+### ObjectFactoryAttribute<T>
+- Targets: class | struct; AllowMultiple = true
+- Constructors:
+  - ObjectFactoryAttribute() — configures factory for typeof(T)
+- Properties:
+  - Type: Type — value type the factory accepts (readonly; typeof(T))
+  - UseForSerialization: SerializationFrameworks — frameworks that should use the factory/type
+  - UseWithEntityFramework: bool — enable EF Core integration for this factory
+  - UseForModelBinding: bool (init-only) — enable ASP.NET Core model binding
+  - HasCorrespondingConstructor: bool (init-only) — indicates presence of a single-parameter ctor of type `Type`
+- Obsolete alias:
+  - ValueObjectFactoryAttribute<T> — use ObjectFactoryAttribute<T> instead