Houtamelo.Spire 3.0.0

Houtamelo.Spire

Roslyn analyzers and source generators for C# type safety — struct initialization enforcement, discriminated unions, and exhaustive switch checking.

Installation

dotnet add package Houtamelo.Spire

Rules

Discriminated Unions

The source generator provides:

• Kind enum and kind property for variant discrimination.
• Factory methods (Shape.Circle(5.0)) and IsVariant properties (shape.IsCircle).
• Property-pattern and Deconstruct support for switch.
• Optional JSON serialization (System.Text.Json, Newtonsoft.Json).
• Exhaustive switch checking (SPIRE009) and field access safety (SPIRE011-014).
• 5 struct memory layouts + record unions.

Define a struct union with [DiscriminatedUnion]:

using Houtamelo.Spire;

[DiscriminatedUnion(Layout.Additive)]
partial struct Shape
{
    [Variant] public static partial Shape Circle(double radius);
    [Variant] public static partial Shape Square(int side);
    [Variant] public static partial Shape Point();
}

Construct and match:

Shape shape = Shape.Circle(5.0);

// Property pattern
var area = shape switch
{
    { kind: Shape.Kind.Circle, radius: var r } => Math.PI * r * r,
    { kind: Shape.Kind.Square, side: var s }   => s * s,
    { kind: Shape.Kind.Point }                 => 0,
};

// Deconstruct pattern
area = shape switch 
{
    (Shape.Kind.Circle, radius: var r) => Math.PI * r * r,
    (Shape.Kind.Square, side: var s)   => s * s,
    (Shape.Kind.Point, _)              => 0,
};

Record types are also supported:

[DiscriminatedUnion]
partial abstract record Shape
{
    public partial record Circle(double radius) : Shape;
    public partial record Square(int side) : Shape;
    public partial record Point() : Shape;
}

See docs/discriminated-unions.md for the full guide.

EnforceExhaustiveness

The analyzer provides:

• Exhaustive switch checking over enum members or sealed subtypes (SPIRE015).
• Invalid enum cast detection (SPIRE016).
• Inherits all [EnforceInitialization] rules (SPIRE001-008) — prevents default(T), uninitialized arrays, etc.
• Works on enums, abstract classes, and interfaces.

Apply [EnforceExhaustiveness] to a type to require exhaustive switches:

using Houtamelo.Spire.Core;

[EnforceExhaustiveness]
public abstract class Animal { }
public sealed class Dog : Animal { }
public sealed class Cat : Animal { }

// SPIRE015: switch does not handle 'Cat'
string Describe(Animal a) => a switch
{
    Dog => "dog",
};

See docs/exhaustiveness.md for the full guide.

Discriminated Unions — Layout Strategy Comparison

N=1000, .NET 11.0, AMD Ryzen 9 9900X. Full results in docs/benchmark-results/.

Legend: Ctor = Construction, Prop = Property Pattern, Decon = Deconstruct

Choosing a layout

• Default choice: Layout.Additive — fastest struct match, zero-alloc property access, works with generics.
• Reference semantics or JSON: record — fastest construction, best JSON deserialization, natural C# pattern matching. Trades GC pressure for speed.
• No generics, unmanaged-heavy: Layout.Overlap — true field overlap for minimal struct size. Cannot handle generic type parameters.
• Skewed variant distribution (80%+ one variant): Layout.BoxedTuple — fieldless fast-path is sub-nanosecond. Poor uniform performance.
• C# 15 native unions: comparable to Additive/Record depending on usage; avoids source generator overhead.
• Avoid: Layout.BoxedFields — outperformed by Additive in most categories. Only advantage: zero-alloc Deconstruct (fields already boxed).

License

MIT