@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

package/framework/standards/backend/dotnet/scrutor.md

@@ -0,0 +1,158 @@
+# Scrutor 7.0.0 — Auto-Discovery & Decorator Registration
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** scrutor, di, decorators, auto-discovery, assembly-scanning
+> **Load When:** dotnet VSA projects
+
+## Overview
+
+Scrutor provides assembly-scanning and decoration extensions for `IServiceCollection`. In VSA, it replaces manual DI registration with convention-based auto-discovery for handlers, validators, and endpoints.
+
+---
+
+## Handler Auto-Discovery
+
+Scan the assembly for all concrete classes implementing `IHandler<TRequest, TResponse>` and register them as scoped services:
+
+```csharp
+public static class HandlerRegistrationExtensions
+{
+    public static IServiceCollection AddHandlersFromAssembly(
+        this IServiceCollection services,
+        Assembly assembly)
+    {
+        var handlerTypes = assembly.GetTypes()
+            .Where(t =>
+                t.IsClass &&
+                !t.IsAbstract &&
+                !t.ContainsGenericParameters)
+            .ToList();
+
+        foreach (var implementation in handlerTypes)
+        {
+            var handlerInterfaces = implementation
+                .GetInterfaces()
+                .Where(i =>
+                    i.IsGenericType &&
+                    i.GetGenericTypeDefinition() == typeof(IHandler<,>));
+
+            foreach (var handlerInterface in handlerInterfaces)
+            {
+                services.AddScoped(handlerInterface, implementation);
+            }
+        }
+
+        // Decorators: last registered = outermost in pipeline
+        services.Decorate(typeof(IHandler<,>), typeof(ValidationDecorator<,>));
+        services.Decorate(typeof(IHandler<,>), typeof(LoggingDecorator<,>));
+
+        return services;
+    }
+}
+```
+
+---
+
+## Decorator Order
+
+Scrutor applies decorators as a **stack** — last registered wraps outermost:
+
+```
+services.Decorate(typeof(IHandler<,>), typeof(ValidationDecorator<,>));  // inner
+services.Decorate(typeof(IHandler<,>), typeof(LoggingDecorator<,>));     // outer
+```
+
+**Execution order:** `LoggingDecorator` -> `ValidationDecorator` -> `Handler`
+
+This means logging captures validation failures too. Always register validation before logging.
+
+---
+
+## Endpoint Auto-Discovery
+
+Register all `IApiEndpoint` implementations for minimal API mapping:
+
+```csharp
+public static IServiceCollection RegisterApiEndpointsFromAssembly(
+    this IServiceCollection services, Assembly assembly)
+{
+    var endpointTypes = assembly.GetTypes()
+        .Where(t => t.IsAssignableTo(typeof(IApiEndpoint))
+            && t is { IsClass: true, IsAbstract: false, IsInterface: false });
+
+    var serviceDescriptors = endpointTypes
+        .Select(type => ServiceDescriptor.Transient(typeof(IApiEndpoint), type))
+        .ToArray();
+
+    services.TryAddEnumerable(serviceDescriptors);
+    return services;
+}
+
+// In Program.cs — map all discovered endpoints
+public static WebApplication MapApiEndpoints(this WebApplication app)
+{
+    var endpoints = app.Services
+        .GetRequiredService<IEnumerable<IApiEndpoint>>();
+
+    foreach (var endpoint in endpoints)
+    {
+        endpoint.MapEndpoint(app);
+    }
+    return app;
+}
+```
+
+---
+
+## Validator Auto-Discovery
+
+FluentValidation provides its own assembly scanner. Register it **before** handlers so the `ValidationDecorator` can resolve validators:
+
+```csharp
+// Program.cs — registration order matters
+builder.Services.AddValidatorsFromAssembly(typeof(CreateBookValidator).Assembly);
+builder.Services.AddHandlersFromAssembly(typeof(Program).Assembly);
+```
+
+---
+
+## Program.cs Registration Order
+
+The full DI registration sequence in VSA:
+
+```csharp
+// 1. Infrastructure
+builder.Services.AddScoped(typeof(IRepository<>), typeof(Repository<>));
+builder.Services.AddScoped(typeof(IUnitOfWork), typeof(UnitOfWork));
+builder.Services.AddSQLDatabaseConfiguration(builder.Configuration);
+
+// 2. Endpoints (auto-discovery)
+builder.Services.RegisterApiEndpointsFromAssembly(Assembly.GetExecutingAssembly());
+
+// 3. Validators (must be before handlers)
+builder.Services.AddValidatorsFromAssembly(typeof(CreateBookValidator).Assembly);
+
+// 4. Handlers + Decorators (Scrutor)
+builder.Services.AddHandlersFromAssembly(typeof(Program).Assembly);
+
+// 5. Cross-cutting
+builder.Services.AddExceptionHandler<CustomExceptionHandler>()
+    .AddProblemDetails();
+```
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Register handlers manually one-by-one | Use `AddHandlersFromAssembly()` |
+| Use `AddSingleton` for handlers | Use `AddScoped` — handlers access DbContext |
+| Register decorators before handlers | Decorators go inside `AddHandlersFromAssembly()` after handler scanning |
+| Register validators after handlers | Validators must be registered before `AddHandlersFromAssembly()` |
+| Forget `!t.ContainsGenericParameters` filter | Open generics (decorators) must be excluded from handler scan |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/backend/dotnet/vsa-handler-patterns.md

@@ -0,0 +1,274 @@
+# VSA Handler Patterns — Complete Feature Slice Guide
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** vsa, handler, feature-slice, vertical-slice, minimal-api, endpoint
+> **Load When:** dotnet VSA projects
+
+## Overview
+
+Each feature in VSA is a self-contained slice with 5 files in a feature folder. Handlers implement `IHandler<TRequest, TResponse>` (not MediatR). Dependencies use primary constructors. The data path is `Handler -> Repository -> UnitOfWork` with no service layer in between.
+
+---
+
+## IHandler\<TRequest, TResponse\>
+
+A single-method interface — intentionally minimal:
+
+```csharp
+public interface IHandler<in TRequest, TResponse>
+{
+    Task<TResponse> HandleAsync(TRequest command, CancellationToken cancellationToken);
+}
+```
+
+**Why not MediatR:** No `IRequest`/`INotification` marker interfaces, no `Send()` indirection, no service locator. Handlers are resolved directly from DI by their interface type. Decorators (validation, logging) are applied via Scrutor, not MediatR pipeline behaviors.
+
+---
+
+## Feature Folder Structure (5 Files Per Slice)
+
+```
+Features/
+  BookFeature/
+    CreateBook/
+      CreateBookRequest.cs       (sealed record — can be inline in handler)
+      CreateBookResponse.cs      (sealed record — can be inline in handler)
+      CreateBookHandler.cs       (business logic)
+      CreateBookValidator.cs     (FluentValidation)
+      CreateBookEndpoint.cs      (minimal API mapping)
+    GetBookById/
+      ...
+    UpdateBook/
+      ...
+    DeleteBook/
+      ...
+    BookErrors.cs                (shared error factory for the feature)
+```
+
+Request/Response DTOs can be defined inline in the handler file for simple slices:
+
+```csharp
+namespace ProjectName.Features.BookFeature.CreateBook;
+
+// Sealed records for DTOs — immutable, structural equality
+public sealed record CreateBookRequest(
+    string Title, string Author, string ISBN, decimal Price, int PublishedYear);
+
+public sealed record CreateBookResponse(
+    Guid Id, string Title, string Author, string ISBN, decimal Price, int PublishedYear);
+```
+
+---
+
+## Complete Handler Example
+
+```csharp
+namespace ProjectName.Features.BookFeature.CreateBook;
+
+using ProjectName.Abstractions;
+using ProjectName.Entities;
+using ProjectName.Repository;
+
+public sealed record CreateBookRequest(
+    string Title, string Author, string ISBN, decimal Price, int PublishedYear);
+
+public sealed record CreateBookResponse(
+    Guid Id, string Title, string Author, string ISBN, decimal Price, int PublishedYear);
+
+// Primary constructor for DI — no field declarations needed
+public sealed class CreateBookHandler(
+    IRepository<Book> bookRepo,
+    IUnitOfWork unitOfWork) : IHandler<CreateBookRequest, Result<CreateBookResponse>>
+{
+    public async Task<Result<CreateBookResponse>> HandleAsync(
+        CreateBookRequest command, CancellationToken cancellationToken)
+    {
+        var book = new Book
+        {
+            Id = Guid.CreateVersion7(),   // .NET 9+ — time-sortable UUID
+            Title = command.Title,
+            Author = command.Author,
+            ISBN = command.ISBN,
+            Price = command.Price,
+            PublishedYear = command.PublishedYear
+        };
+
+        await bookRepo.AddAsync(book, cancellationToken);
+        await unitOfWork.CommitAsync(cancellationToken);
+
+        return Result.Success(new CreateBookResponse(
+            book.Id, book.Title, book.Author, book.ISBN, book.Price, book.PublishedYear));
+    }
+}
+```
+
+### Key Patterns
+
+- **`sealed class`** — handlers are never inherited
+- **`sealed record`** — DTOs are immutable value types
+- **Primary constructors** — `(IRepository<Book> bookRepo, IUnitOfWork unitOfWork)` replaces field + constructor boilerplate
+- **`Guid.CreateVersion7()`** — time-sortable, index-friendly UUID (not `Guid.NewGuid()`)
+- **`CancellationToken`** — passed through every async call
+- **`Result<T>` return** — never throw for expected failures
+
+---
+
+## Complete Endpoint Example
+
+```csharp
+namespace ProjectName.Features.BookFeature.CreateBook;
+
+using ProjectName.Abstractions;
+using ProjectName.Constants;
+using ProjectName.Extensions;
+
+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 Conventions
+
+- **`internal sealed`** — endpoints are not public API
+- **`IApiEndpoint`** — single interface for auto-discovery
+- **Handler injected via DI** — resolved as `IHandler<TReq, TRes>` parameter
+- **`Match()` for responses** — never access `.Value` directly
+- **`.WithTags()`** — always tag for Scalar API docs
+- **`.Produces<T>()`** — always document response types
+
+---
+
+## IApiEndpoint Interface
+
+```csharp
+public interface IApiEndpoint
+{
+    void MapEndpoint(WebApplication app);
+}
+```
+
+All endpoint classes implementing this interface are auto-discovered and mapped via `MapApiEndpoints()` in Program.cs.
+
+---
+
+## Repository + UnitOfWork (No Service Layer)
+
+Handlers call repositories directly. There is no service/manager layer:
+
+```csharp
+public interface IRepository<T> where T : class
+{
+    Task<IEnumerable<T>> GetAllAsync(CancellationToken cancellationToken = default);
+    Task<T?> GetByIdAsync(object id, CancellationToken cancellationToken = default);
+    Task<T> AddAsync(T entity, CancellationToken cancellationToken = default);
+    Task UpdateAsync(T entity, CancellationToken cancellationToken = default);
+    Task DeleteAsync(T entity, CancellationToken cancellationToken = default);
+    Task AddRangeAsync(IEnumerable<T> entities, CancellationToken cancellationToken = default);
+    void RemoveRange(IEnumerable<T> entities);
+}
+
+public interface IUnitOfWork
+{
+    Task<int> CommitAsync(CancellationToken cancellationToken);
+    Task RollbackAsync();
+}
+```
+
+**Pattern:** `Repository.AddAsync()` -> `UnitOfWork.CommitAsync()` — always commit explicitly.
+
+---
+
+## Feature Error Factory
+
+Each feature defines its own error constants:
+
+```csharp
+// Features/BookFeature/BookErrors.cs
+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 readonly Error InvalidPrice =
+        Error.Failure("Book.InvalidPrice", "Book price must be greater than zero.");
+}
+```
+
+Usage in handler:
+
+```csharp
+var existing = await bookRepo.GetByIdAsync(command.BookId, cancellationToken);
+if (existing is null)
+    return BookErrors.NotFound(command.BookId);  // implicit conversion to Result<T>
+```
+
+---
+
+## Program.cs DI Registration Order
+
+```csharp
+// 1. OpenAPI
+builder.Services.AddOpenApi();
+
+// 2. Infrastructure (Repository, UnitOfWork, DbContext)
+builder.Services.AddScoped(typeof(IRepository<>), typeof(Repository<>));
+builder.Services.AddScoped(typeof(IUnitOfWork), typeof(UnitOfWork));
+builder.Services.AddSQLDatabaseConfiguration(builder.Configuration);
+
+// 3. Endpoint auto-discovery
+builder.Services.RegisterApiEndpointsFromAssembly(Assembly.GetExecutingAssembly());
+
+// 4. Health checks
+builder.Services.AddHealthChecksConfiguration();
+
+// 5. Validators (MUST be before handlers)
+builder.Services.AddValidatorsFromAssembly(typeof(CreateBookValidator).Assembly);
+
+// 6. Handlers + Decorators (Scrutor auto-discovery)
+builder.Services.AddHandlersFromAssembly(typeof(Program).Assembly);
+
+// 7. Exception handling
+builder.Services.AddExceptionHandler<CustomExceptionHandler>()
+    .AddProblemDetails();
+```
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Use MediatR `IRequest`/`Send()` | Use `IHandler<TReq, TRes>` resolved directly from DI |
+| Create a service/manager layer | Handler calls Repository + UnitOfWork directly |
+| Use `Guid.NewGuid()` | Use `Guid.CreateVersion7()` for time-sortable IDs |
+| Make handler classes non-sealed | Always `sealed class` |
+| Use mutable DTOs (class with setters) | Always `sealed record` with positional parameters |
+| Omit `CancellationToken` from async methods | Pass `CancellationToken` through every async call |
+| Put business logic in endpoints | Endpoints only map HTTP and call `Match()` |
+| Share handlers across features | Each feature has its own handler, even if similar |
+| Use constructor + field for DI | Use primary constructors: `class Handler(IDep dep)` |
+| Group by technical concern (Controllers/, Services/) | Group by feature: `Features/BookFeature/CreateBook/` |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -2,7 +2,7 @@
 scope: frontend-nextjs-ui
 layer: 3
 keywords: framer-motion, animation, motion, transition, variants, gesture, scroll
-load_when: nextjs-ui-specialist active
+load_when: nextjs-expert active
 ---
 
 # Motion Patterns — Framer Motion