Skip to content

Commit cae612b

Browse files
PawelGerrPawelGerr
committed
Added custom instructions
1 parent 29002d4 commit cae612b

10 files changed

+598
-6
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ These instructions are **not** for end-users of the library. End-user documentat
1919

2020
## Important files
2121

22-
- `Thinktecture.Runtime.Extensions.sln`: The main solution file.
22+
- `Thinktecture.Runtime.Extensions.slnx`: The main solution file.
2323
- `src/`: Contains the source code for the library.
2424
- `test/`: Contains the unit tests.
2525
- `docs/`: Contains the documentation.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
**/obj/**
55
**/packages/**
66
**/test-results/**
7+
.local-memory/**
8+
.serena/cache/**
79

810
*\.sln\.DotSettings\.user
911
*\.csproj\.user

‎.serena/memories/code_style_and_conventions.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Code Style and Conventions
2+
3+
## General Guidelines
4+
5+
### Naming Conventions
6+
- **Classes/Interfaces/Enums/Properties**: PascalCase
7+
- **Methods**: PascalCase
8+
- **Fields**: camelCase with underscore prefix for private fields (`_fieldName`)
9+
- **Parameters/Local Variables**: camelCase
10+
- **Constants**: PascalCase or ALL_CAPS (depending on context)
11+
12+
### Language Features
13+
- **Nullable Reference Types**: Enabled (`<Nullable>enable</Nullable>`)
14+
- **Implicit Usings**: Enabled (`<ImplicitUsings>enable</ImplicitUsings>`)
15+
- **Language Version**: C# 13.0
16+
- **Target Framework**: .NET 7.0 baseline
17+
18+
### Documentation
19+
- **XML Documentation**: Required for all publicly visible types and members
20+
- Exception: Source generators, test projects, and sample projects are exempt
21+
- Use clear, concise descriptions that explain purpose and usage
22+
23+
### File Organization
24+
- **Root Namespace**: `Thinktecture` for all projects
25+
- **Partial Classes**: Common for types using source generators (Smart Enums, Value Objects, Unions)
26+
- **Test Structure**: Mirror the source directory structure in test projects
27+
28+
## Source Generator Patterns
29+
30+
### Value Objects
31+
```csharp
32+
[ValueObject<string>] // Simple value object
33+
public partial struct CustomerId
34+
{
35+
// Validation via static partial method
36+
static partial void ValidateFactoryArguments(ref ValidationError? validationError, ref string value)
37+
{
38+
if (string.IsNullOrWhiteSpace(value))
39+
validationError = new ValidationError("Customer ID cannot be empty");
40+
}
41+
}
42+
43+
[ComplexValueObject] // Multiple properties
44+
public partial class DateRange
45+
{
46+
public DateOnly Start { get; }
47+
public DateOnly End { get; }
48+
49+
static partial void ValidateFactoryArguments(ref ValidationError? validationError, ref DateOnly start, ref DateOnly end)
50+
{
51+
if (end < start)
52+
validationError = new ValidationError("End date cannot be before start date");
53+
}
54+
}
55+
```
56+
57+
### Smart Enums
58+
```csharp
59+
[SmartEnum<string>]
60+
public partial class ShippingMethod
61+
{
62+
public static readonly ShippingMethod Standard = new("STANDARD", basePrice: 5.99m);
63+
public static readonly ShippingMethod Express = new("EXPRESS", basePrice: 15.99m);
64+
65+
private readonly decimal _basePrice;
66+
67+
public decimal CalculatePrice(decimal weight) => _basePrice + (weight * 0.5m);
68+
}
69+
```
70+
71+
### Discriminated Unions
72+
```csharp
73+
// Ad-hoc unions
74+
[Union<string, int>]
75+
public partial class TextOrNumber;
76+
77+
// Regular unions
78+
[Union]
79+
public partial record Result<T>
80+
{
81+
public record Success(T Value) : Result<T>;
82+
public record Failure(string Error) : Result<T>;
83+
}
84+
```
85+
86+
## EditorConfig Compliance
87+
- Follow the settings defined in `.editorconfig` and `src/.editorconfig`
88+
- Use `dotnet format` to ensure compliance
89+
- Key settings:
90+
- Warning level for CA1852 (sealed classes)
91+
- UTF-8 encoding for verified test files
92+
- LF line endings for verification files
93+
94+
## Testing Conventions
95+
- Use **xUnit** framework
96+
- Test file naming: `[ClassName]Tests.cs`
97+
- Test method naming: `[MethodUnderTest]_Should[ExpectedBehavior]_When[Condition]`
98+
- Use **AwesomeAssertions** for readable assertions: `result.Should().Be(expected)`
99+
- Use **Verify.Xunit** for snapshot testing of generated code
100+
- Mock dependencies with **NSubstitute**
101+
102+
## Performance Considerations
103+
- Source generators run at compile-time, not runtime
104+
- Generated code is optimized for performance (reflection-free enumeration, fast lookups)
105+
- Use static methods where possible to avoid closures in Switch/Map operations
106+
- Prefer structs for simple value objects to reduce heap allocations

‎.serena/memories/project_overview.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Thinktecture.Runtime.Extensions Project Overview
2+
3+
## Purpose
4+
This is a .NET library providing runtime extensions that help solve common software development problems:
5+
6+
1. **Smart Enums**: Type-safe, extensible alternatives to traditional C# enums with rich behavior and validation
7+
2. **Value Objects**: Type-safe wrappers that prevent primitive obsession and provide built-in validation
8+
3. **Discriminated Unions**: Type-safe representation of values that can be one of several different types
9+
10+
## Technology Stack
11+
- **.NET 9.0 SDK** (defined in global.json)
12+
- **C# 13.0** with nullable reference types enabled
13+
- **Roslyn Source Generators** for compile-time code generation
14+
- **Roslyn Analyzers** for development-time guidance
15+
- **Central Package Management** via Directory.Packages.props
16+
17+
## Framework Integrations
18+
The library provides integration packages for:
19+
- **Serialization**: System.Text.Json, Newtonsoft.Json, MessagePack, ProtoBuf
20+
- **Entity Framework Core**: Versions 7, 8, and 9
21+
- **ASP.NET Core**: Model binding and API integration
22+
- **Swashbuckle**: OpenAPI documentation support
23+
24+
## Testing Framework
25+
- **xUnit** for unit testing
26+
- **AwesomeAssertions** for readable test assertions
27+
- **Verify.Xunit** for snapshot testing
28+
- **NSubstitute** for mocking
29+
- Test results stored in `test-results/$(TargetFramework)` directory
30+
31+
## Project Structure
32+
- `src/`: Core library and integration packages
33+
- `test/`: Unit tests mirroring the src structure
34+
- `samples/`: Example projects demonstrating usage
35+
- `docs/`: Markdown documentation
36+
- All projects target **.NET 7.0** as baseline with LangVersion 13.0
37+
38+
## Key Features
39+
- Compile-time code generation reduces boilerplate
40+
- Comprehensive validation with descriptive error messages
41+
- Exhaustive pattern matching for unions and smart enums
42+
- Framework integrations for seamless usage in .NET applications
43+
- Rich developer experience with analyzers and code fixes

‎.serena/memories/project_structure_and_architecture.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Project Structure and Architecture
2+
3+
## Repository Layout
4+
```
5+
Thinktecture.Runtime.Extensions/
6+
├── docs/ # Markdown documentation
7+
├── samples/ # Example projects demonstrating usage
8+
├── src/ # Source code
9+
│ ├── Thinktecture.Runtime.Extensions/ # Core library
10+
│ ├── Thinktecture.Runtime.Extensions.SourceGenerator/ # Source generators and analyzers
11+
│ ├── Thinktecture.Runtime.Extensions.Json/ # System.Text.Json integration
12+
│ ├── Thinktecture.Runtime.Extensions.Newtonsoft.Json/ # Newtonsoft.Json integration
13+
│ ├── Thinktecture.Runtime.Extensions.MessagePack/ # MessagePack integration
14+
│ ├── Thinktecture.Runtime.Extensions.ProtoBuf/ # ProtoBuf integration
15+
│ ├── Thinktecture.Runtime.Extensions.EntityFrameworkCore7/ # EF Core 7 integration
16+
│ ├── Thinktecture.Runtime.Extensions.EntityFrameworkCore8/ # EF Core 8 integration
17+
│ ├── Thinktecture.Runtime.Extensions.EntityFrameworkCore9/ # EF Core 9 integration
18+
│ ├── Thinktecture.Runtime.Extensions.AspNetCore/ # ASP.NET Core integration
19+
│ └── Thinktecture.Runtime.Extensions.Swashbuckle/ # OpenAPI integration
20+
├── test/ # Unit tests (mirrors src structure)
21+
└── test-results/ # Test output files
22+
```
23+
24+
## Core Components
25+
26+
### Core Library (`Thinktecture.Runtime.Extensions`)
27+
- **Attributes**: `[ValueObject]`, `[SmartEnum]`, `[Union]`
28+
- **Base Interfaces**: `IValidationError`, `ISmartEnum`, `IComplexValueObject`
29+
- **Utility Types**: `ValidationError`, `Empty` collections, `SingleItem`
30+
- **Core Abstractions**: Foundation types for generated code
31+
32+
### Source Generator (`Thinktecture.Runtime.Extensions.SourceGenerator`)
33+
- **Code Generation**: Creates boilerplate for Smart Enums, Value Objects, Unions
34+
- **Analyzers**: Compile-time diagnostics and warnings
35+
- **Code Fixes**: Automatic fixes for common issues
36+
- **Performance**: Reflection-free generated code
37+
38+
### Integration Packages
39+
Each integration package follows the same pattern:
40+
- **Converters/Formatters**: Handle serialization/deserialization
41+
- **Extension Methods**: Register with DI containers or configure options
42+
- **Type Descriptors**: Enable framework-specific type conversion
43+
44+
## Key Design Patterns
45+
46+
### Source Generator Pattern
47+
- Types are marked with attributes (`[ValueObject]`, `[SmartEnum]`, `[Union]`)
48+
- Source generator creates `partial` implementations at compile-time
49+
- Generated code includes constructors, factory methods, equality, comparison
50+
- Developers implement validation and custom logic in user code
51+
52+
### Validation Pattern
53+
```csharp
54+
// Preferred validation approach
55+
static partial void ValidateFactoryArguments(ref ValidationError? validationError, ref T value)
56+
{
57+
// Return ValidationError for framework integration
58+
// Modify value by reference for normalization
59+
}
60+
61+
// Legacy validation (avoid for new code)
62+
static partial void ValidateConstructorArguments(T value)
63+
{
64+
// Can only throw exceptions
65+
}
66+
```
67+
68+
### Factory Method Pattern
69+
Generated types provide multiple creation methods:
70+
- `Create(T value)`: Throws on validation failure
71+
- `TryCreate(T value, out Type? result)`: Returns bool success
72+
- `Validate(T value, IFormatProvider?, out Type? result)`: Returns ValidationError
73+
74+
### Pattern Matching Support
75+
- `Switch()`: Execute actions based on type/value (void return)
76+
- `Map<TResult>()`: Transform values based on type/value (typed return)
77+
- Both methods are exhaustive by design
78+
79+
## Framework Integration Architecture
80+
81+
### Serialization Strategy
82+
1. **Project Reference Approach** (Preferred):
83+
- Add integration package as project reference
84+
- Attributes automatically applied to types
85+
86+
2. **Manual Registration**:
87+
- Register converter factories in Startup/Program.cs
88+
- More flexible but requires manual setup
89+
90+
### Entity Framework Integration
91+
- Use `.UseThinktectureValueConverters()` extension method
92+
- Automatic value converter registration for all supported types
93+
- Support for complex value objects with multiple properties
94+
95+
### ASP.NET Core Model Binding
96+
- Relies on `IParsable<T>` interface (generated automatically)
97+
- String-based types use `[ObjectFactory<string>]` for custom parsing
98+
- Supports binding from route, query, and body parameters

‎.serena/memories/suggested_commands.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Suggested Commands for Thinktecture.Runtime.Extensions
2+
3+
## Essential Development Commands
4+
5+
### Building
6+
```powershell
7+
# Restore packages
8+
dotnet restore
9+
10+
# Build entire solution
11+
dotnet build
12+
13+
# Build specific project
14+
dotnet build src/Thinktecture.Runtime.Extensions
15+
16+
# Build with specific configuration
17+
dotnet build --configuration Release
18+
```
19+
20+
### Testing
21+
```powershell
22+
# Run all tests
23+
dotnet test
24+
25+
# Run tests for specific project
26+
dotnet test test/Thinktecture.Runtime.Extensions.Json.Tests
27+
28+
# Run tests with detailed output
29+
dotnet test --verbosity normal
30+
31+
# Run tests and generate coverage (if configured)
32+
dotnet test --collect:"XPlat Code Coverage"
33+
```
34+
35+
### Code Quality
36+
```powershell
37+
# Format code according to .editorconfig
38+
dotnet format
39+
40+
# Format only specific project
41+
dotnet format src/Thinktecture.Runtime.Extensions
42+
43+
# Analyze code (built-in analyzers)
44+
dotnet build --verbosity normal # Will show analyzer warnings
45+
```
46+
47+
### Package Management
48+
```powershell
49+
# Add package reference (update Directory.Packages.props for version)
50+
dotnet add package PackageName
51+
52+
# Update packages
53+
dotnet restore --force-evaluate
54+
```
55+
56+
### Common Development Workflow
57+
```powershell
58+
# After making changes
59+
dotnet build
60+
dotnet test
61+
dotnet format
62+
63+
# Before committing
64+
dotnet build --configuration Release
65+
dotnet test --verbosity normal
66+
```
67+
68+
## Windows-Specific Utilities
69+
```powershell
70+
# Directory navigation
71+
Get-ChildItem -Path . -Recurse -Name "*.cs" | Select-String "pattern"
72+
73+
# Find files
74+
Get-ChildItem -Path . -Recurse -Filter "*.csproj"
75+
76+
# Git operations
77+
git status
78+
git add .
79+
git commit -m "message"
80+
git push
81+
82+
# Process management
83+
Get-Process dotnet
84+
Stop-Process -Name dotnet
85+
```
86+
87+
## Solution Management
88+
```powershell
89+
# List projects in solution
90+
dotnet sln list
91+
92+
# Add new project to solution
93+
dotnet sln add path/to/new.csproj
94+
95+
# Remove project from solution
96+
dotnet sln remove path/to/project.csproj
97+
```

0 commit comments

Comments
 (0)