Validation📋

// Era 1: Code — manual validation in the controller
public class OrderController
{
    private readonly OrderService _orderService;

    public OrderController(OrderService orderService)
    {
        _orderService = orderService;
    }

    public IActionResult CreateOrder(CreateOrderRequest request)
    {
        // Developer A validates like this
        if (request == null)
        {
            return BadRequest("Request cannot be null");
        }

        if (string.IsNullOrWhiteSpace(request.CustomerId))
        {
            return BadRequest("Customer ID is required");
        }

        if (request.CustomerId.Length > 50)
        {
            return BadRequest("Customer ID cannot exceed 50 characters");
        }

        if (request.ShippingAddress == null)
        {
            return BadRequest("Shipping address is required");
        }

        if (string.IsNullOrWhiteSpace(request.ShippingAddress.Street))
        {
            return BadRequest("Street is required");
        }

        if (string.IsNullOrWhiteSpace(request.ShippingAddress.City))
        {
            return BadRequest("City is required");
        }

        if (string.IsNullOrWhiteSpace(request.ShippingAddress.PostalCode))
        {
            return BadRequest("Postal code is required");
        }

        if (request.ShippingAddress.PostalCode.Length > 10)
        {
            return BadRequest("Postal code cannot exceed 10 characters");
        }

        if (request.Items == null || request.Items.Count == 0)
        {
            return BadRequest("Order must have at least one item");
        }

        foreach (var item in request.Items)
        {
            if (string.IsNullOrWhiteSpace(item.ProductId))
            {
                return BadRequest("Product ID is required for all items");
            }

            if (item.Quantity <= 0)
            {
                return BadRequest("Quantity must be greater than zero");
            }

            if (item.Quantity > 10000)
            {
                return BadRequest("Quantity cannot exceed 10,000");
            }

            if (item.UnitPrice <= 0)
            {
                return BadRequest("Unit price must be greater than zero");
            }

            if (item.UnitPrice > 999999.99m)
            {
                return BadRequest("Unit price cannot exceed 999,999.99");
            }
        }

        if (request.Notes != null && request.Notes.Length > 2000)
        {
            return BadRequest("Notes cannot exceed 2,000 characters");
        }

        if (request.RequestedDeliveryDate.HasValue
            && request.RequestedDeliveryDate.Value < DateTime.UtcNow.Date)
        {
            return BadRequest("Delivery date must be in the future");
        }

        if (request.CouponCode != null && request.CouponCode.Length > 20)
        {
            return BadRequest("Coupon code cannot exceed 20 characters");
        }

        // Validation is done. 50 lines later. Now we can actually do the work.
        var result = _orderService.CreateOrder(request);
        return Ok(result);
    }
}

// Meanwhile, Developer B validates the same kind of request differently
public class InvoiceController
{
    public IActionResult CreateInvoice(CreateInvoiceRequest request)
    {
        // Developer B throws exceptions instead of returning BadRequest
        if (request.CustomerId == null)
            throw new ArgumentNullException(nameof(request.CustomerId));

        if (request.Items.Any(i => i.Quantity < 1))
            throw new ArgumentOutOfRangeException("Quantity must be positive");

        // Developer B forgot to validate the shipping address entirely.
        // This will cause a NullReferenceException in the service layer.

        // Developer B validates the email — but Developer A didn't.
        if (!request.ContactEmail.Contains("@"))
            throw new ArgumentException("Invalid email address");

        // Developer B uses a different error handling pattern than Developer A.
        // Neither is wrong. Both are inconsistent.

        _invoiceService.CreateInvoice(request);
        return Ok();
    }
}

// Developer C doesn't validate at all
public class ShipmentController
{
    public IActionResult CreateShipment(CreateShipmentRequest request)
    {
        // "The service layer handles validation"
        // (It doesn't.)
        return Ok(_shipmentService.CreateShipment(request));
    }
}

// Era 2: Configuration — DataAnnotations
public class CreateOrderRequest
{
    [Required(ErrorMessage = "Customer ID is required")]
    [StringLength(50, ErrorMessage = "Customer ID cannot exceed 50 characters")]
    public string CustomerId { get; set; } = null!;

    [Required(ErrorMessage = "Shipping address is required")]
    public AddressDto ShippingAddress { get; set; } = null!;

    [Required(ErrorMessage = "Order must have at least one item")]
    [MinLength(1, ErrorMessage = "Order must have at least one item")]
    public List<OrderItemDto> Items { get; set; } = new();

    [StringLength(2000, ErrorMessage = "Notes cannot exceed 2,000 characters")]
    public string? Notes { get; set; }

    public DateTime? RequestedDeliveryDate { get; set; }

    [StringLength(20, ErrorMessage = "Coupon code cannot exceed 20 characters")]
    public string? CouponCode { get; set; }
}

public class AddressDto
{
    [Required(ErrorMessage = "Street is required")]
    [StringLength(200)]
    public string Street { get; set; } = null!;

    [Required(ErrorMessage = "City is required")]
    [StringLength(100)]
    public string City { get; set; } = null!;

    [Required(ErrorMessage = "Postal code is required")]
    [StringLength(10, ErrorMessage = "Postal code cannot exceed 10 characters")]
    public string PostalCode { get; set; } = null!;
}

public class OrderItemDto
{
    [Required(ErrorMessage = "Product ID is required")]
    public string ProductId { get; set; } = null!;

    [Range(1, 10000, ErrorMessage = "Quantity must be between 1 and 10,000")]
    public int Quantity { get; set; }

    [Range(0.01, 999999.99, ErrorMessage = "Unit price must be between 0.01 and 999,999.99")]
    public decimal UnitPrice { get; set; }
}

// The controller is clean — but validation is runtime-only
public class OrderController : ControllerBase
{
    [HttpPost]
    public IActionResult CreateOrder([FromBody] CreateOrderRequest request)
    {
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        // But what about "delivery date must be in the future"?
        // DataAnnotations can't express that with built-in attributes.
        // So we're back to manual code for anything beyond simple constraints.

        if (request.RequestedDeliveryDate.HasValue
            && request.RequestedDeliveryDate.Value < DateTime.UtcNow.Date)
        {
            ModelState.AddModelError(
                nameof(request.RequestedDeliveryDate),
                "Delivery date must be in the future");
            return BadRequest(ModelState);
        }

        var result = _orderService.CreateOrder(request);
        return Ok(result);
    }
}

// Custom validation attribute — for rules that don't fit the built-in set
public class FutureDateAttribute : ValidationAttribute
{
    protected override ValidationResult? IsValid(
        object? value, ValidationContext validationContext)
    {
        if (value is DateTime date && date < DateTime.UtcNow.Date)
        {
            return new ValidationResult(
                ErrorMessage ?? "Date must be in the future",
                new[] { validationContext.MemberName! });
        }

        return ValidationResult.Success;
    }
}

// Now you can use [FutureDate] on the property — but this is code, not configuration.
// You are writing validation logic inside an attribute class.
// Custom validation attributes proliferate: [FutureDate], [NotEqual], [RequiredIf],
// [MustBeTrue], [ValidJson], [StrongerPassword]...
// Each is a class. Each must be tested. Each is invisible to anyone who doesn't know it exists.

// Era 3: Convention — FluentValidation
public class CreateOrderCommand : IRequest<OrderResult>
{
    public required string CustomerId { get; init; }
    public required AddressDto ShippingAddress { get; init; }
    public required List<OrderItemDto> Items { get; init; }
    public string? Notes { get; init; }
    public DateTime? RequestedDeliveryDate { get; init; }
    public string? CouponCode { get; init; }
}

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId)
            .NotEmpty()
            .WithMessage("Customer ID is required")
            .MaximumLength(50)
            .WithMessage("Customer ID cannot exceed 50 characters");

        RuleFor(x => x.ShippingAddress)
            .NotNull()
            .WithMessage("Shipping address is required")
            .SetValidator(new AddressDtoValidator());

        RuleFor(x => x.Items)
            .NotEmpty()
            .WithMessage("Order must have at least one item");

        RuleForEach(x => x.Items)
            .SetValidator(new OrderItemDtoValidator());

        RuleFor(x => x.Notes)
            .MaximumLength(2000)
            .WithMessage("Notes cannot exceed 2,000 characters")
            .When(x => x.Notes is not null);

        RuleFor(x => x.RequestedDeliveryDate)
            .GreaterThanOrEqualTo(DateTime.UtcNow.Date)
            .WithMessage("Delivery date must be in the future")
            .When(x => x.RequestedDeliveryDate.HasValue);

        RuleFor(x => x.CouponCode)
            .MaximumLength(20)
            .WithMessage("Coupon code cannot exceed 20 characters")
            .When(x => x.CouponCode is not null);
    }
}

public class AddressDtoValidator : AbstractValidator<AddressDto>
{
    public AddressDtoValidator()
    {
        RuleFor(x => x.Street).NotEmpty().MaximumLength(200);
        RuleFor(x => x.City).NotEmpty().MaximumLength(100);
        RuleFor(x => x.PostalCode).NotEmpty().MaximumLength(10);
    }
}

public class OrderItemDtoValidator : AbstractValidator<OrderItemDto>
{
    public OrderItemDtoValidator()
    {
        RuleFor(x => x.ProductId).NotEmpty();
        RuleFor(x => x.Quantity).InclusiveBetween(1, 10000);
        RuleFor(x => x.UnitPrice).InclusiveBetween(0.01m, 999999.99m);
    }
}

// MediatR validation behavior — runs validators before the handler
public class ValidationBehavior<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)
    {
        _validators = validators;
    }

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        if (!_validators.Any())
        {
            return await next();
        }

        var context = new ValidationContext<TRequest>(request);

        var failures = (await Task.WhenAll(
                _validators.Select(v => v.ValidateAsync(context, cancellationToken))))
            .SelectMany(result => result.Errors)
            .Where(failure => failure is not null)
            .ToList();

        if (failures.Count != 0)
        {
            throw new ValidationException(failures);
        }

        return await next();
    }
}

// DI registration — assembly scanning
builder.Services.AddMediatR(cfg =>
    cfg.RegisterServicesFromAssemblyContaining<CreateOrderCommand>());

builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderCommandValidator>();

builder.Services.AddTransient(
    typeof(IPipelineBehavior<,>),
    typeof(ValidationBehavior<,>));

# Validation Standards

## Overview
All commands and queries are validated using FluentValidation. Validators run
automatically via the MediatR pipeline. Validation errors are returned as
structured error responses.

## Rules

### 1. Every Command Must Have a Validator
- Every class that implements `IRequest<T>` must have a corresponding
  validator class.
- Naming convention: `{CommandName}Validator`
  (e.g., `CreateOrderCommand` → `CreateOrderCommandValidator`).
- Validators must be in the same assembly as the command.

### 2. Validator Implementation
- Validators inherit `AbstractValidator<T>` from FluentValidation.
- Use `RuleFor()` for single-property rules.
- Use `RuleForEach()` for collection item rules.
- Use `.SetValidator()` for nested object validation.
- Use `.When()` for conditional rules (not if-statements in the constructor).

### 3. Error Messages
- Use `.WithMessage()` for user-facing error messages.
- Use `.WithErrorCode()` for machine-readable codes (prefix: `VAL-`).
- Messages must be complete sentences starting with a capital letter.
- Do not include property names in messages — the framework adds them.

### 4. Pipeline Registration
- Validators are auto-discovered by `AddValidatorsFromAssembly()`.
- The `ValidationBehavior<TRequest, TResponse>` is registered as a
  pipeline behavior. It runs validators before the handler.
- **Never validate inside the handler.** Validation belongs in the validator.

### 5. Complex Validation
- Cross-property validation: use `RuleFor(x => x).Must(...)`.
- Async validation (e.g., database uniqueness): use `MustAsync()`.
- Conditional validation: use `.When()` / `.Unless()`.
- Severity: use `.WithSeverity(Severity.Warning)` for non-blocking rules.

### 6. Testing
- Every validator must have unit tests.
- Test both valid and invalid cases.
- Test edge cases: null, empty, boundary values.
- Use `TestValidateAsync()` for async validators.

### 7. Exceptions
- Query validators are optional but recommended.
- Health check endpoints do not require validation.
- Internal commands (no user input) may skip validation with
  `[SkipValidation]` attribute and a code comment explaining why.

// tests/ArchitectureTests/ValidationConventionTests.cs

/// <summary>
/// Convention enforcement: every Command type must have a corresponding Validator.
/// This test exists because the convention is invisible to the compiler.
/// If the compiler knew about it, this test would not need to exist.
/// </summary>
public class ValidationConventionTests
{
    private readonly Assembly _commandAssembly = typeof(CreateOrderCommand).Assembly;
    private readonly Assembly _validatorAssembly = typeof(CreateOrderCommandValidator).Assembly;

    [Fact]
    public void Every_Command_Must_Have_A_Validator()
    {
        var commandTypes = _commandAssembly
            .GetTypes()
            .Where(t => !t.IsAbstract)
            .Where(t => t.GetInterfaces().Any(i =>
                i.IsGenericType &&
                i.GetGenericTypeDefinition() == typeof(IRequest<>)))
            .Where(t => !t.GetCustomAttributes()
                .Any(a => a.GetType().Name == "SkipValidationAttribute"))
            .ToList();

        var validatorTypes = _validatorAssembly
            .GetTypes()
            .Where(t => !t.IsAbstract)
            .Where(t => t.BaseType is { IsGenericType: true } baseType &&
                baseType.GetGenericTypeDefinition() == typeof(AbstractValidator<>))
            .Select(t => t.BaseType!.GetGenericArguments()[0])
            .ToHashSet();

        var commandsWithoutValidators = commandTypes
            .Where(c => !validatorTypes.Contains(c))
            .Select(c => c.Name)
            .ToList();

        commandsWithoutValidators.Should().BeEmpty(
            "every command must have a corresponding AbstractValidator<T>. " +
            "Missing validators for: {0}",
            string.Join(", ", commandsWithoutValidators));
    }

    [Fact]
    public void All_Validators_Are_Registered_In_DI_Container()
    {
        var services = new ServiceCollection();
        services.AddValidatorsFromAssemblyContaining<CreateOrderCommandValidator>();

        var provider = services.BuildServiceProvider();

        var validatorTypes = _validatorAssembly
            .GetTypes()
            .Where(t => !t.IsAbstract)
            .Where(t => t.BaseType is { IsGenericType: true } baseType &&
                baseType.GetGenericTypeDefinition() == typeof(AbstractValidator<>))
            .ToList();

        foreach (var validatorType in validatorTypes)
        {
            var commandType = validatorType.BaseType!.GetGenericArguments()[0];
            var validatorInterfaceType = typeof(IValidator<>).MakeGenericType(commandType);

            var resolved = provider.GetService(validatorInterfaceType);

            resolved.Should().NotBeNull(
                $"Validator {validatorType.Name} must be resolvable from the DI container. " +
                "Ensure AddValidatorsFromAssembly() is called in Startup.");
        }
    }

    [Fact]
    public void MediatR_Pipeline_Includes_ValidationBehavior()
    {
        var services = new ServiceCollection();

        // Reproduce the actual DI registration
        services.AddMediatR(cfg =>
            cfg.RegisterServicesFromAssemblyContaining<CreateOrderCommand>());
        services.AddTransient(
            typeof(IPipelineBehavior<,>),
            typeof(ValidationBehavior<,>));

        var provider = services.BuildServiceProvider();

        var behaviors = provider
            .GetServices<IPipelineBehavior<CreateOrderCommand, OrderResult>>()
            .ToList();

        behaviors.Should().ContainSingle(b => b is ValidationBehavior<CreateOrderCommand, OrderResult>,
            "The MediatR pipeline must include ValidationBehavior. " +
            "Without it, validators are registered but never executed.");
    }

    [Fact]
    public void Validator_Names_Follow_Convention()
    {
        var validatorTypes = _validatorAssembly
            .GetTypes()
            .Where(t => !t.IsAbstract)
            .Where(t => t.BaseType is { IsGenericType: true } baseType &&
                baseType.GetGenericTypeDefinition() == typeof(AbstractValidator<>))
            .ToList();

        foreach (var validator in validatorTypes)
        {
            var commandType = validator.BaseType!.GetGenericArguments()[0];
            var expectedName = commandType.Name + "Validator";

            validator.Name.Should().Be(expectedName,
                $"Validator for {commandType.Name} must be named {expectedName} " +
                "(not {validator.Name}). See wiki/validation-standards.md.");
        }
    }
}

📄 wiki/validation-standards.md                            40 lines — documentation
📄 tests/ValidationConventionTests.cs                      90 lines — enforcement code
📄 ValidationBehavior.cs                                   30 lines — pipeline infrastructure
📄 DI registration (AddValidators + AddBehavior)            5 lines — wiring
────────────────────────────────────────
Convention overhead:                                      165 lines

// Era 4: Contention — attribute-driven validation
[Validated]
public record CreateOrderCommand : IRequest<OrderResult>
{
    public required string CustomerId { get; init; }

    [StringLength(50)]
    public required string CustomerName { get; init; }

    public required AddressDto ShippingAddress { get; init; }

    [MinCount(1)]
    public required List<OrderItemDto> Items { get; init; }

    [StringLength(2000)]
    public string? Notes { get; init; }

    [Rule("Must be a future date", nameof(IsFutureDate))]
    public DateTime? RequestedDeliveryDate { get; init; }

    [StringLength(20)]
    public string? CouponCode { get; init; }

    private static bool IsFutureDate(DateTime? date)
        => date is null || date.Value >= DateTime.UtcNow.Date;
}

[Validated]
public record AddressDto
{
    [StringLength(200)]
    public required string Street { get; init; }

    [StringLength(100)]
    public required string City { get; init; }

    [StringLength(10)]
    public required string PostalCode { get; init; }
}

[Validated]
public record OrderItemDto
{
    public required string ProductId { get; init; }

    [Range(1, 10000)]
    public required int Quantity { get; init; }

    [Range(0.01, 999999.99)]
    public required decimal UnitPrice { get; init; }
}

// ── Generated: CreateOrderCommandValidator.g.cs ──
[GeneratedCode("Cmf.Validation.Generators", "1.0.0")]
internal sealed class CreateOrderCommandValidator
    : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        // From 'required string CustomerId'
        RuleFor(x => x.CustomerId)
            .NotEmpty()
            .WithMessage("Customer ID is required")
            .WithErrorCode("VAL-CreateOrderCommand-CustomerId-Required");

        // From 'required string CustomerName' + [StringLength(50)]
        RuleFor(x => x.CustomerName)
            .NotEmpty()
            .WithMessage("Customer name is required")
            .WithErrorCode("VAL-CreateOrderCommand-CustomerName-Required")
            .MaximumLength(50)
            .WithMessage("Customer name cannot exceed 50 characters")
            .WithErrorCode("VAL-CreateOrderCommand-CustomerName-MaxLength");

        // From 'required AddressDto ShippingAddress' — recursive [Validated]
        RuleFor(x => x.ShippingAddress)
            .NotNull()
            .WithMessage("Shipping address is required")
            .WithErrorCode("VAL-CreateOrderCommand-ShippingAddress-Required")
            .SetValidator(new AddressDtoValidator());

        // From 'required List<OrderItemDto> Items' + [MinCount(1)]
        RuleFor(x => x.Items)
            .NotEmpty()
            .WithMessage("Items is required")
            .WithErrorCode("VAL-CreateOrderCommand-Items-Required");

        RuleFor(x => x.Items)
            .Must(items => items is not null && items.Count >= 1)
            .WithMessage("Items must contain at least 1 element")
            .WithErrorCode("VAL-CreateOrderCommand-Items-MinCount")
            .When(x => x.Items is not null);

        RuleForEach(x => x.Items)
            .SetValidator(new OrderItemDtoValidator());

        // From 'string? Notes' + [StringLength(2000)]
        RuleFor(x => x.Notes)
            .MaximumLength(2000)
            .WithMessage("Notes cannot exceed 2,000 characters")
            .WithErrorCode("VAL-CreateOrderCommand-Notes-MaxLength")
            .When(x => x.Notes is not null);

        // From [Rule("Must be a future date", nameof(IsFutureDate))]
        RuleFor(x => x.RequestedDeliveryDate)
            .Must(value => CreateOrderCommand.IsFutureDate(value))
            .WithMessage("Must be a future date")
            .WithErrorCode("VAL-CreateOrderCommand-RequestedDeliveryDate-Rule")
            .When(x => x.RequestedDeliveryDate is not null);

        // From 'string? CouponCode' + [StringLength(20)]
        RuleFor(x => x.CouponCode)
            .MaximumLength(20)
            .WithMessage("Coupon code cannot exceed 20 characters")
            .WithErrorCode("VAL-CreateOrderCommand-CouponCode-MaxLength")
            .When(x => x.CouponCode is not null);
    }
}

// ── Generated: AddressDtoValidator.g.cs ──
[GeneratedCode("Cmf.Validation.Generators", "1.0.0")]
internal sealed class AddressDtoValidator : AbstractValidator<AddressDto>
{
    public AddressDtoValidator()
    {
        RuleFor(x => x.Street)
            .NotEmpty()
            .WithMessage("Street is required")
            .WithErrorCode("VAL-AddressDto-Street-Required")
            .MaximumLength(200)
            .WithMessage("Street cannot exceed 200 characters")
            .WithErrorCode("VAL-AddressDto-Street-MaxLength");

        RuleFor(x => x.City)
            .NotEmpty()
            .WithMessage("City is required")
            .WithErrorCode("VAL-AddressDto-City-Required")
            .MaximumLength(100)
            .WithMessage("City cannot exceed 100 characters")
            .WithErrorCode("VAL-AddressDto-City-MaxLength");

        RuleFor(x => x.PostalCode)
            .NotEmpty()
            .WithMessage("Postal code is required")
            .WithErrorCode("VAL-AddressDto-PostalCode-Required")
            .MaximumLength(10)
            .WithMessage("Postal code cannot exceed 10 characters")
            .WithErrorCode("VAL-AddressDto-PostalCode-MaxLength");
    }
}

// ── Generated: OrderItemDtoValidator.g.cs ──
[GeneratedCode("Cmf.Validation.Generators", "1.0.0")]
internal sealed class OrderItemDtoValidator : AbstractValidator<OrderItemDto>
{
    public OrderItemDtoValidator()
    {
        RuleFor(x => x.ProductId)
            .NotEmpty()
            .WithMessage("Product ID is required")
            .WithErrorCode("VAL-OrderItemDto-ProductId-Required");

        RuleFor(x => x.Quantity)
            .InclusiveBetween(1, 10000)
            .WithMessage("Quantity must be between 1 and 10,000")
            .WithErrorCode("VAL-OrderItemDto-Quantity-Range");

        RuleFor(x => x.UnitPrice)
            .InclusiveBetween(0.01m, 999999.99m)
            .WithMessage("Unit price must be between 0.01 and 999,999.99")
            .WithErrorCode("VAL-OrderItemDto-UnitPrice-Range");
    }
}

// ── Generated: ValidationServiceRegistration.g.cs ──
[GeneratedCode("Cmf.Validation.Generators", "1.0.0")]
public static class ValidationServiceRegistration
{
    public static IServiceCollection AddGeneratedValidators(
        this IServiceCollection services)
    {
        // All [Validated] types get their generated validator registered
        services.AddScoped<IValidator<CreateOrderCommand>,
            CreateOrderCommandValidator>();
        services.AddScoped<IValidator<AddressDto>,
            AddressDtoValidator>();
        services.AddScoped<IValidator<OrderItemDto>,
            OrderItemDtoValidator>();

        // Pipeline behavior — automatic
        services.AddTransient(
            typeof(IPipelineBehavior<,>),
            typeof(ValidationBehavior<,>));

        return services;
    }
}

// VAL001: Command/Query lacks [Validated]
// Severity: Error
// Trigger: Class implements IRequest<T> but has no [Validated] attribute
//          and no [SkipValidation] attribute.

error VAL001: Type 'UpdateInventoryCommand' implements IRequest<InventoryResult>
              but is not marked [Validated] or [SkipValidation].
              All request types must declare their validation strategy.
              Add [Validated] to generate a validator, or [SkipValidation]
              with a justification comment.
              (UpdateInventoryCommand.cs, line 5)

// VAL002: [Validated] class has unconstrained property
// Severity: Warning
// Trigger: A [Validated] class has a required property with no validation
//          attribute beyond the implicit NotEmpty from 'required'.

warning VAL002: Property 'CreateOrderCommand.CustomerId' is 'required string'
                with no [StringLength], [Range], or [Rule] constraint.
                The generated validator will enforce NotEmpty only.
                Consider adding a [StringLength] constraint.
                (CreateOrderCommand.cs, line 8)

// VAL003: Handler accepts unvalidated request
// Severity: Error
// Trigger: IRequestHandler<T, R> where T lacks [Validated] or [SkipValidation].

error VAL003: Handler 'UpdateInventoryCommandHandler' accepts
              'UpdateInventoryCommand' which is not validated.
              The MediatR pipeline will execute this handler
              without validation. Mark the request type [Validated]
              or [SkipValidation].
              (UpdateInventoryCommandHandler.cs, line 3)

// VAL004: Manually written validator for [Validated] type
// Severity: Warning
// Trigger: A class inherits AbstractValidator<T> where T is marked [Validated].

warning VAL004: Type 'CreateOrderCommandValidator' manually validates
                'CreateOrderCommand', which is marked [Validated].
                A validator is already source-generated.
                The manual validator will be registered alongside the
                generated one, causing duplicate validation.
                Remove the manual validator or remove [Validated].
                (CreateOrderCommandValidator.cs, line 1)

📄 No wiki/validation-standards.md       — [Validated] IS the standard
📄 No ValidationConventionTests.cs       — VAL001/VAL003 enforce at compile time
📄 No manual validator classes            — SG generates them from constraints
📄 No manual DI registration             — SG generates AddGeneratedValidators()
📄 No manual pipeline wiring             — SG includes it in registration
────────────────────────────────────────
Convention overhead: 0 lines
Wiki pages: 0
Enforcement tests: 0

[Validated]
public record TransferFundsCommand : IRequest<TransferResult>
{
    public required string FromAccountId { get; init; }
    public required string ToAccountId { get; init; }

    [Range(0.01, 1_000_000)]
    public required decimal Amount { get; init; }

    [StringLength(500)]
    public string? Memo { get; init; }
}

// ── Generated: TransferFundsCommandValidator.g.cs ──
[GeneratedCode("Cmf.Validation.Generators", "1.0.0")]
internal sealed partial class TransferFundsCommandValidator
    : AbstractValidator<TransferFundsCommand>
{
    public TransferFundsCommandValidator()
    {
        RuleFor(x => x.FromAccountId)
            .NotEmpty()
            .WithErrorCode("VAL-TransferFundsCommand-FromAccountId-Required");

        RuleFor(x => x.ToAccountId)
            .NotEmpty()
            .WithErrorCode("VAL-TransferFundsCommand-ToAccountId-Required");

        RuleFor(x => x.Amount)
            .InclusiveBetween(0.01m, 1_000_000m)
            .WithErrorCode("VAL-TransferFundsCommand-Amount-Range");

        RuleFor(x => x.Memo)
            .MaximumLength(500)
            .When(x => x.Memo is not null);

        // Hook for developer-provided rules
        ConfigureCustomRules();
    }

    partial void ConfigureCustomRules();
}

// Developer writes ONLY the custom part:
internal sealed partial class TransferFundsCommandValidator
{
    partial void ConfigureCustomRules()
    {
        RuleFor(x => x)
            .Must(x => x.FromAccountId != x.ToAccountId)
            .WithMessage("Cannot transfer to the same account")
            .WithErrorCode("VAL-TransferFundsCommand-SameAccount");

        RuleFor(x => x.FromAccountId)
            .MustAsync(async (accountId, ct) =>
            {
                var account = await _accountRepository.GetByIdAsync(accountId, ct);
                return account is { IsActive: true };
            })
            .WithMessage("Source account does not exist or is inactive")
            .WithErrorCode("VAL-TransferFundsCommand-FromAccount-Active");

        RuleFor(x => x)
            .MustAsync(async (cmd, ct) =>
            {
                var balance = await _accountRepository
                    .GetBalanceAsync(cmd.FromAccountId, ct);
                return balance >= cmd.Amount;
            })
            .WithMessage("Insufficient funds")
            .WithErrorCode("VAL-TransferFundsCommand-InsufficientFunds");
    }
}