Thinktecture.Runtime.Extensions Development Guide

You are working with **Thinktecture.Runtime.Extensions**, a .NET library that provides Smart Enums, Value Objects, and Discriminated Unions through Roslyn Source Generators.

Core Architecture

Project Components

Six Source Generators

1. **SmartEnumSourceGenerator**: `[SmartEnum<T>]` or `[SmartEnum]` - factory methods, operators, Switch/Map

2. **ValueObjectSourceGenerator**: `[ValueObject<T>]` or `[ComplexValueObject]` - factory methods, equality, operators

3. **AdHocUnionSourceGenerator**: `[Union<T1, T2, ...>]` or `[AdHocUnion(...)]` - conversion operators, Switch/Map

4. **RegularUnionSourceGenerator**: `[Union]` inheritance-based unions - factory methods, Switch/Map

5. **ObjectFactorySourceGenerator**: `[ObjectFactory<T>]` - custom serialization/parsing logic

6. **AnnotationsSourceGenerator**: JetBrains annotations if not already present

Two Analyzers

1. **ThinktectureRuntimeExtensionsAnalyzer**: 40+ diagnostic rules validating correct usage

2. **ThinktectureRuntimeExtensionsInternalUsageAnalyzer**: Prevents usage of internal library APIs

Key Type Patterns

Smart Enums

**Keyless `[SmartEnum]`**: Type-safe enums without underlying values (items as public static readonly fields)

**Keyed `[SmartEnum<TKey>]`**: Type-safe enums with underlying key values (int, string, Guid, custom types)

Value Objects

**Simple `[ValueObject<TKey>]`**: Single-value immutable types (e.g., Amount, ProductId)

**Complex `[ComplexValueObject]`**: Multi-property immutable types (e.g., DateRange)

Discriminated Unions

**Ad-hoc `[Union<T1, T2>]`**: Simple 2-5 type combinations with implicit conversion operators

**Regular `[Union]`**: Inheritance-based unions with derived types and static factory methods

Critical Development Rules

Zero-Tolerance for Hallucination

**NEVER guess or assume API behavior for external libraries/frameworks:**

1. **Use Context7 MCP** to verify external APIs:

- `mcp__context7__resolve-library-id` to find library ID

- `mcp__context7__get-library-docs` to retrieve accurate documentation

- Required for: .NET BCL, ASP.NET Core, Entity Framework Core, serialization frameworks, Roslyn APIs

2. **State uncertainty explicitly**: "I need to verify the API behavior using Context7"

3. **This project's code is authoritative** - use Serena tools to explore internal codebase

Task Delegation Pattern

**ALWAYS delegate to subagents for:**

**Do NOT delegate:**

Validation Implementation

**Always prefer `ValidateFactoryArguments` over `ValidateConstructorArguments`:**

Best Practices

Code Style

Type Design Rules

1. **Types must be `partial`** for source generators to work

2. **String-based keys/members**: Always explicitly specify equality comparer (`[KeyMemberEqualityComparer<MyType, string, StringComparer>]`)

3. **Immutability**: All members readonly (fields) or no setter/private init (properties)

4. **Constructors**: Keep private to enforce factory method usage

5. **Smart Enum items**: Must be public static readonly fields

6. **Arithmetic operators**: Use unchecked arithmetic context (overflow wraps around)

Runtime Metadata System

Generated types implement `IMetadataOwner` interface enabling:

The `MetadataLookup` class provides cached metadata discovery via reflection. Object factories have priority over key-based metadata.

**Essential reading**: See "Runtime Metadata System" section in `CLAUDE-FEATURE-DEV.md` when implementing serialization integrations or custom conversion logic.

Common Commands

```bash

Build and test

dotnet build

dotnet restore

dotnet test

Requirements: .NET 10.0 SDK (see global.json)

C# 11+ for generated code

Multiple .NET versions (8.0, 9.0, 10.0) for testing

```

Framework Integration

**Serialization**: System.Text.Json, MessagePack, Newtonsoft.Json, ProtoBuf - reference package for auto-generation or manually register converters

**Entity Framework Core**: Version-specific packages (8/9/10) - call `.UseThinktectureValueConverters()` on DbContextOptionsBuilder

**ASP.NET Core**: Model binding via `IParsable<T>` interface (auto-generated) - use `[ObjectFactory<string>]` for custom parsing

**Swashbuckle/OpenAPI**: Schema and operation filters for proper documentation

Troubleshooting

| Issue | Solution |

|-------|----------|

| "Type must be partial" | Add `partial` keyword to class/struct |

| "String-based value object needs equality comparer" | Add `[KeyMemberEqualityComparer<MyType, string, StringComparer>]` |

| "Smart enum has no items" | Ensure items are public static readonly fields |

| Serialization not working | Reference integration package or manually register converters |

| EF Core not converting | Call `.UseThinktectureValueConverters()` on DbContextOptionsBuilder |

| ISpanParsable not available | Requires NET9+ target framework and key type implementing `ISpanParsable<TKey>` |

Key Files

Specialized Documentation

Consult these files in the repository for specific tasks:

Implementation Workflow Example

When adding a new feature:

1. User requests feature → Use `feature-implementation-planner` subagent to create plan

2. Plan approved → Use `feature-implementer` subagent to write code

3. Implementation complete → Use `feature-test-writer` subagent to add tests

4. Tests passing → Use `documentation-updater` subagent to update docs

5. All done → Use `feature-reviewer` subagent for final review

Remember