@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

package/framework/standards/backend/dotnet/fluent-validation-vsa.md

@@ -0,0 +1,200 @@
+# FluentValidation in VSA Pipelines
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** fluent-validation, validation, decorator, pipeline, vsa
+> **Load When:** dotnet VSA projects
+
+## Overview
+
+FluentValidation integrates into VSA via the decorator pattern. Validators are auto-discovered per assembly, and the `ValidationDecorator<TRequest, TResponse>` runs all matching validators before the handler executes. Failed validation short-circuits to `Result.Failure` without touching the handler.
+
+---
+
+## Validator Structure
+
+One validator per request DTO. Lives in the same feature folder as the handler:
+
+```csharp
+// Features/BookFeature/CreateBook/CreateBookValidator.cs
+public class CreateBookValidator : AbstractValidator<CreateBookRequest>
+{
+    public CreateBookValidator()
+    {
+        RuleFor(c => c.Title)
+            .NotEmpty().WithMessage("Title is required")
+            .MaximumLength(200).WithMessage("Title must not exceed 200 characters");
+
+        RuleFor(c => c.Author)
+            .NotEmpty().WithMessage("Author is required")
+            .MaximumLength(100).WithMessage("Author must not exceed 100 characters");
+
+        RuleFor(c => c.ISBN)
+            .NotEmpty().WithMessage("ISBN is required");
+
+        RuleFor(c => c.Price)
+            .GreaterThan(0).WithMessage("Price must be greater than 0");
+
+        RuleFor(c => c.PublishedYear)
+            .GreaterThan(1000).WithMessage("Published year must be a valid year")
+            .LessThanOrEqualTo(DateTime.UtcNow.Year)
+            .WithMessage("Published year cannot be in the future");
+    }
+}
+```
+
+---
+
+## Auto-Discovery
+
+Register all validators from the assembly in `Program.cs`. This must happen **before** handler registration so the `ValidationDecorator` can resolve them:
+
+```csharp
+// Program.cs
+builder.Services.AddValidatorsFromAssembly(typeof(CreateBookValidator).Assembly);
+builder.Services.AddHandlersFromAssembly(typeof(Program).Assembly);
+```
+
+---
+
+## ValidationDecorator Pattern
+
+The decorator wraps every `IHandler<TRequest, TResponse>` via Scrutor. It collects all `IValidator<TRequest>` from DI, runs them in parallel, and short-circuits on failure:
+
+```csharp
+public sealed class ValidationDecorator<TRequest, TResponse>(
+    IEnumerable<IValidator<TRequest>> validators,
+    IHandler<TRequest, TResponse> innerHandler) : IHandler<TRequest, TResponse>
+{
+    public async Task<TResponse> HandleAsync(
+        TRequest command, CancellationToken cancellationToken)
+    {
+        // No validators registered for this request — pass through
+        if (!validators.Any())
+        {
+            return await innerHandler.HandleAsync(command, cancellationToken);
+        }
+
+        var context = new ValidationContext<TRequest>(command);
+
+        // Run all validators in parallel
+        ValidationFailure[] failures = (await Task.WhenAll(
+                validators.Select(v => v.ValidateAsync(context, cancellationToken))))
+            .SelectMany(r => r.Errors)
+            .Where(f => f is not null)
+            .ToArray();
+
+        if (failures.Length == 0)
+        {
+            return await innerHandler.HandleAsync(command, cancellationToken);
+        }
+
+        // Short-circuit: convert to Result failure
+        return CreateFailureResponse(failures);
+    }
+}
+```
+
+---
+
+## FluentValidation to ValidationError Conversion
+
+`ValidationFailure[]` from FluentValidation is converted to the Result pattern's `ValidationError`:
+
+```csharp
+private static ValidationError CreateValidationError(ValidationFailure[] validationFailures) =>
+    new(validationFailures
+        .Select(f => Error.Validation(f.ErrorCode, f.ErrorMessage))
+        .ToArray());
+```
+
+This produces a `ValidationError` containing an array of typed `Error` records, each with `ErrorType.Validation`.
+
+---
+
+## Reflection for Typed Failure Responses
+
+The decorator supports both `Result` and `Result<T>` via reflection. This is necessary because the generic `TResponse` type is not known at compile time:
+
+```csharp
+private static TResponse CreateFailureResponse(ValidationFailure[] failures)
+{
+    // Non-generic Result
+    if (typeof(TResponse) == typeof(Result))
+    {
+        return (TResponse)(object)Result.Failure(CreateValidationError(failures));
+    }
+
+    // Generic Result<T> — use reflection to call Result.Failure<T>()
+    if (typeof(TResponse).IsGenericType &&
+        typeof(TResponse).GetGenericTypeDefinition() == typeof(Result<>))
+    {
+        var valueType = typeof(TResponse).GetGenericArguments()[0];
+        var failureMethod = typeof(Result)
+            .GetMethods()
+            .First(m =>
+                m.Name == nameof(Result.Failure) &&
+                m.IsGenericMethodDefinition &&
+                m.GetParameters().Length == 1);
+
+        var typedFailure = failureMethod
+            .MakeGenericMethod(valueType)
+            .Invoke(null, [CreateValidationError(failures)]);
+
+        return (TResponse)typedFailure!;
+    }
+
+    throw new InvalidOperationException(
+        $"ValidationDecorator supports only Result and Result<T> responses.");
+}
+```
+
+---
+
+## RuleFor Chain Reference
+
+Common FluentValidation rules used in VSA:
+
+| Rule | Purpose |
+|------|---------|
+| `.NotEmpty()` | Non-null and non-whitespace for strings |
+| `.MaximumLength(n)` | String max length |
+| `.GreaterThan(n)` | Numeric minimum (exclusive) |
+| `.LessThanOrEqualTo(n)` | Numeric maximum (inclusive) |
+| `.Must(predicate)` | Custom inline validation |
+| `.WithMessage("...")` | Human-readable error message |
+| `.WithErrorCode("...")` | Machine-readable error code |
+| `.When(condition)` | Conditional rule application |
+
+---
+
+## File Placement
+
+```
+Features/
+  BookFeature/
+    CreateBook/
+      CreateBookRequest.cs      (or inline in handler)
+      CreateBookResponse.cs     (or inline in handler)
+      CreateBookHandler.cs
+      CreateBookValidator.cs    <-- one validator per request
+      CreateBookEndpoint.cs
+```
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Validate inside the handler | Use `AbstractValidator<T>` + decorator |
+| Throw `ValidationException` | Return `Result.Failure(ValidationError)` |
+| Register validators after handlers | Register validators first: `AddValidatorsFromAssembly()` before `AddHandlersFromAssembly()` |
+| Put validation logic in endpoints | Endpoints only do `Match()` — validation is automatic |
+| Use `IValidateOptions<T>` | Use `AbstractValidator<T>` (FluentValidation, not Microsoft) |
+| Skip `.WithMessage()` | Always provide user-facing messages |
+| Use `RuleSet` grouping | One validator per request DTO — no rulesets needed in VSA |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/backend/dotnet/result-pattern.md

@@ -0,0 +1,213 @@
+# Result Pattern — Railway-Oriented Programming
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** result, error-handling, railway, match, monadic
+> **Load When:** dotnet VSA projects
+
+## Overview
+
+The Result pattern replaces exceptions for expected failures. Every handler returns `Result` or `Result<T>`, and endpoints use `Match()` to map success/failure to HTTP responses. No try-catch in business logic.
+
+---
+
+## Result Anatomy
+
+```csharp
+public class Result
+{
+    protected internal Result(bool isSuccess, Error error) { ... }
+
+    public bool IsSuccess { get; }
+    public bool IsFailure => !IsSuccess;
+    public Error Error { get; }
+
+    // Factory methods
+    public static Result Success() => new(true, Error.None);
+    public static Result<TValue> Success<TValue>(TValue value) => new(value, true, Error.None);
+    public static Result Failure(Error error) => new(false, error);
+    public static Result<TValue> Failure<TValue>(Error error) => new(default, false, error);
+    public static Result<TValue> Create<TValue>(TValue? value) =>
+        value is not null ? Success(value) : Failure<TValue>(Error.Null);
+}
+```
+
+---
+
+## Result\<T\> with Implicit Conversions
+
+```csharp
+public class Result<TValue> : Result
+{
+    public TValue Value => IsSuccess
+        ? _value!
+        : throw new InvalidOperationException(
+            "The value of a failure result can not be accessed.");
+
+    // Implicit: value -> Result<T> (success)
+    public static implicit operator Result<TValue>(TValue? value) => Create(value);
+
+    // Implicit: Error -> Result<T> (failure)
+    public static implicit operator Result<TValue>(Error error) => Failure<TValue>(error);
+}
+```
+
+This allows handlers to return values or errors directly:
+
+```csharp
+// Both are valid return statements in a handler returning Result<BookResponse>
+return new BookResponse(book.Id, book.Title);    // implicit success
+return BookErrors.NotFound(bookId);               // implicit failure
+```
+
+---
+
+## Error Types (7 + Custom)
+
+```csharp
+public record Error(string Code, string? Description = default, ErrorType Type = ErrorType.Failure)
+{
+    public static readonly Error None = new(string.Empty);
+    public static readonly Error Null = new("Error.NullValue", "The specified result value is null.");
+
+    // Factory methods
+    public static Error Failure(string code, string description) =>
+        new(code, description, ErrorType.Failure);
+    public static Error Unexpected(string code, string description) =>
+        new(code, description, ErrorType.Unexpected);
+    public static Error Validation(string code, string description) =>
+        new(code, description, ErrorType.Validation);
+    public static Error Conflict(string code, string description) =>
+        new(code, description, ErrorType.Conflict);
+    public static Error NotFound(string code, string description) =>
+        new(code, description, ErrorType.NotFound);
+    public static Error Unauthorized(string code, string description) =>
+        new(code, description, ErrorType.Unauthorized);
+    public static Error Forbidden(string code, string description) =>
+        new(code, description, ErrorType.Forbidden);
+
+    // Implicit: Error -> Result (failure)
+    public static implicit operator Result(Error error) => Result.Failure(error);
+}
+
+public enum ErrorType
+{
+    Failure,      // General business rule violation
+    Unexpected,   // Unrecoverable system error
+    Validation,   // Input validation failure (often aggregated)
+    Conflict,     // Duplicate / concurrency conflict
+    NotFound,     // Entity does not exist
+    Unauthorized, // Missing credentials
+    Forbidden,    // Insufficient permissions
+    Custom        // Domain-specific extensions
+}
+```
+
+### When to Use Which Error Type
+
+| Error Type | HTTP Status | Use Case |
+|------------|-------------|----------|
+| `Failure` | 400 | Business rule violation (e.g., insufficient balance) |
+| `Unexpected` | 500 | System error (e.g., external service down) |
+| `Validation` | 400 | Input validation (FluentValidation aggregated) |
+| `Conflict` | 409 | Duplicate key, concurrency conflict |
+| `NotFound` | 404 | Entity lookup returned null |
+| `Unauthorized` | 401 | Missing or invalid auth token |
+| `Forbidden` | 403 | Authenticated but lacks permission |
+
+---
+
+## ValidationError (Aggregated)
+
+Wraps multiple `Error` instances from FluentValidation:
+
+```csharp
+public sealed record ValidationError : Error
+{
+    public ValidationError(Error[] errors)
+        : base("Validation.General", "One or more validation errors occurred", ErrorType.Validation)
+    {
+        Errors = errors;
+    }
+
+    public Error[] Errors { get; }
+
+    public static ValidationError FromResults(IEnumerable<Result> results) =>
+        new(results.Where(r => r.IsFailure).Select(r => r.Error).ToArray());
+}
+```
+
+---
+
+## Match() Pattern
+
+Endpoints use `Match()` to convert `Result<T>` into HTTP responses — never access `.Value` directly:
+
+```csharp
+public static class ResultExtensions
+{
+    // For Result (no value)
+    public static TOut Match<TOut>(
+        this Result result,
+        Func<TOut> onSuccess,
+        Func<Error, TOut> onFailure)
+    {
+        return result.IsSuccess ? onSuccess() : onFailure(result.Error);
+    }
+
+    // For Result<T> (with value)
+    public static TOut Match<TIn, TOut>(
+        this Result<TIn> result,
+        Func<TIn, TOut> onSuccess,
+        Func<Error, TOut> onFailure)
+    {
+        return result.IsSuccess ? onSuccess(result.Value) : onFailure(result.Error);
+    }
+}
+```
+
+Usage in an endpoint:
+
+```csharp
+var result = await handler.HandleAsync(command, cancellationToken);
+return result.Match(
+    onSuccess: () => Results.Ok(result.Value),
+    onFailure: error => Results.BadRequest(error));
+```
+
+---
+
+## Defining Feature Errors
+
+Each feature defines its own static error factory class:
+
+```csharp
+public static class BookErrors
+{
+    public static Error NotFound(Guid bookId) =>
+        Error.NotFound("Book.NotFound", $"Book with ID '{bookId}' was not found.");
+
+    public static Error DuplicateIsbn(string isbn) =>
+        Error.Conflict("Book.DuplicateIsbn", $"A book with ISBN '{isbn}' already exists.");
+
+    public static Error InvalidPrice =>
+        Error.Failure("Book.InvalidPrice", "Book price must be greater than zero.");
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Throw exceptions for expected failures | Return `Result.Failure(error)` |
+| Access `.Value` without checking `IsSuccess` | Use `Match()` |
+| Use string error messages without codes | Use `Error.NotFound("Code", "Description")` |
+| Catch exceptions in handlers | Let unexpected exceptions bubble to `CustomExceptionHandler` |
+| Return `null` from handlers | Return `Result.Failure<T>(error)` |
+| Use generic `Error.Failure` for everything | Choose the correct `ErrorType` for proper HTTP mapping |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/backend/dotnet/scalar-ui.md

@@ -0,0 +1,172 @@
+# Scalar.AspNetCore — API Documentation UI
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** scalar, openapi, swagger, api-docs, documentation
+> **Load When:** dotnet VSA projects
+
+## Overview
+
+Scalar replaces Swagger UI as the API documentation frontend. It provides a modern UI with built-in request testing, client code generation, and dark themes. Works with ASP.NET Core's native OpenAPI support (`Microsoft.AspNetCore.OpenApi`).
+
+---
+
+## Package Setup
+
+```xml
+<!-- .csproj -->
+<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+<PackageReference Include="Scalar.AspNetCore" Version="2.12.40" />
+```
+
+No Swashbuckle needed. ASP.NET Core 9+ has built-in OpenAPI document generation.
+
+---
+
+## Program.cs Configuration
+
+```csharp
+using Scalar.AspNetCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Enable OpenAPI document generation
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+// Map the OpenAPI JSON endpoint (dev only)
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi();
+}
+
+// Map Scalar UI at /scalar/v1
+app.MapScalarApiReference(options =>
+{
+    options.WithTheme(ScalarTheme.DeepSpace);
+
+    // Enable Developer Tools (request + client code panel)
+    options.WithDefaultHttpClient(
+        ScalarTarget.CSharp,
+        ScalarClient.HttpClient);
+});
+```
+
+**Access URL:** `https://localhost:{port}/scalar/v1`
+
+---
+
+## Available Themes
+
+| Theme | Description |
+|-------|-------------|
+| `ScalarTheme.Default` | Light theme |
+| `ScalarTheme.DeepSpace` | Dark blue (recommended) |
+| `ScalarTheme.Purple` | Purple accent |
+| `ScalarTheme.Moon` | Dark grey |
+| `ScalarTheme.Saturn` | Warm dark |
+| `ScalarTheme.Mars` | Red accent |
+
+---
+
+## ApiTags Organization
+
+Group endpoints by feature using a constants class and `.WithTags()`:
+
+```csharp
+// Constants/ApiTags.cs
+public static class ApiTags
+{
+    public const string Books = "books";
+    public const string Authors = "authors";
+    public const string Orders = "orders";
+}
+```
+
+Apply tags in endpoints:
+
+```csharp
+internal sealed class CreateBookEndpoint : IApiEndpoint
+{
+    public void MapEndpoint(WebApplication app)
+    {
+        app.MapPost("books", async (
+            IHandler<CreateBookRequest, Result<CreateBookResponse>> handler,
+            CreateBookRequest command,
+            CancellationToken cancellationToken) =>
+        {
+            var result = await handler.HandleAsync(command, cancellationToken);
+            return result.Match(
+                onSuccess: () => Results.Ok(result.Value),
+                onFailure: error => Results.BadRequest(error));
+        })
+        .WithTags(ApiTags.Books)
+        .Produces<CreateBookResponse>(StatusCodes.Status200OK)
+        .Produces(StatusCodes.Status400BadRequest);
+    }
+}
+```
+
+---
+
+## Endpoint Metadata
+
+Use `.Produces<T>()` to document response types for OpenAPI:
+
+```csharp
+app.MapGet("books/{id:guid}", async (...) => { ... })
+    .WithTags(ApiTags.Books)
+    .WithName("GetBookById")
+    .WithSummary("Get a book by its unique identifier")
+    .Produces<GetBookResponse>(StatusCodes.Status200OK)
+    .Produces(StatusCodes.Status404NotFound);
+
+app.MapDelete("books/{id:guid}", async (...) => { ... })
+    .WithTags(ApiTags.Books)
+    .Produces(StatusCodes.Status204NoContent)
+    .Produces(StatusCodes.Status404NotFound);
+```
+
+### Common Metadata Methods
+
+| Method | Purpose |
+|--------|---------|
+| `.WithTags("tag")` | Group in Scalar sidebar |
+| `.WithName("OperationId")` | Unique operation identifier |
+| `.WithSummary("...")` | Short description in endpoint list |
+| `.WithDescription("...")` | Long description in detail panel |
+| `.Produces<T>(statusCode)` | Document success response type |
+| `.Produces(statusCode)` | Document error response (no body) |
+| `.ProducesProblem(statusCode)` | Document ProblemDetails response |
+| `.RequireAuthorization()` | Marks as requiring auth in docs |
+
+---
+
+## Client Code Generation
+
+Scalar auto-generates client code for API calls. The `WithDefaultHttpClient` option selects the default language:
+
+| Target | Client | Description |
+|--------|--------|-------------|
+| `ScalarTarget.CSharp` | `ScalarClient.HttpClient` | .NET HttpClient |
+| `ScalarTarget.JavaScript` | `ScalarClient.Fetch` | Browser fetch() |
+| `ScalarTarget.Python` | `ScalarClient.Requests` | Python requests |
+| `ScalarTarget.Shell` | `ScalarClient.Curl` | cURL command |
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Install Swashbuckle | Use `Microsoft.AspNetCore.OpenApi` + `Scalar.AspNetCore` |
+| Expose OpenAPI in production | Guard with `IsDevelopment()` check |
+| Skip `.WithTags()` on endpoints | Every endpoint needs a tag for organized docs |
+| Skip `.Produces<T>()` | Always document response types for accurate API docs |
+| Use magic strings for tags | Define tags in `Constants/ApiTags.cs` |
+| Map Scalar before `MapOpenApi()` | `MapOpenApi()` first, then `MapScalarApiReference()` |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*