Feature/validation final touches (#3)

* Rename ValidationBehavior to ValidationBehaviour

Renamed all instances of 'ValidationBehavior' to 'ValidationBehaviour' for consistency with British English spelling across documentation, implementation, and tests. Updated usage examples and references accordingly.

* Add common validation rules and tests

Introduces new validation rule helpers: PhoneE164, UrlAbsoluteHttpHttps, CultureCode, and SortExpression in CommonRules.cs. Updates documentation to list these new rules. Adds unit tests in CommonRulesTests.cs to verify their behavior.

* Add LegacyResult adapters for template compatibility

Introduces LegacyResult and LegacyResult<T> classes to provide compatibility with the Jason Taylor template's Result shape. Includes mapping methods to convert between the new core Result types and the legacy format, as well as tests and documentation updates to guide migration and usage.

* Add net8.0 target to test project

Updated the test project's configuration to target both net8.0 and net10.0 frameworks, improving compatibility and test coverage across multiple .NET versions.

Author: mheidari988

docs/extensions/core-result-primitives.md

@@ -38,8 +38,8 @@ The extension keeps the success/failure semantics but adds the capabilities team
 
 ## Compatibility and migration from the template
 You can start with the template’s existing patterns and layer Core Results gradually:
-- **Mapping template → Core:** `Result.Success()` becomes `Result.Success(traceId)`; `Result.Failure(strings)` can be projected to `Result.Failure(strings.Select(s => new Error("identity", s)))`.
-- **Mapping Core → template:** `Result.Success(traceId)` can return `CleanArchitecture.Application.Common.Models.Result.Success()`. Failures can flatten via `Errors.Select(e => $"{e.Code}: {e.Message}")`.
+- **Mapping template → Core:** `Result.Success()` becomes `Result.Success(traceId)`; `Result.Failure(strings)` can be projected to `Result.Failure(strings.Select(s => new Error("identity", s)))` or use `LegacyResult.Failure(strings).ToResult(traceId)`.
+- **Mapping Core → template:** `Result.Success(traceId)` can return `CleanArchitecture.Application.Common.Models.Result.Success()` or `LegacyResult.FromResult(result)`. Failures can flatten via `Errors.Select(e => $"{e.Code}: {e.Message}")` or rely on the adapter’s default formatter.
 - **Handlers:** Keep return types as your feature needs (DTOs, primitives). Introduce `Result<T>` where you want richer errors without throwing. You can adopt it per handler; nothing requires a big bang change.
 - **Pipelines:** Core Results do not change pipeline signatures; they work with the template’s behaviors. Validation that throws still bubbles through `UnhandledExceptionBehaviour`; you can prefer guard/result composition to avoid exceptions when appropriate.
 

docs/extensions/validation.md

@@ -1,7 +1,7 @@
 # Extension: Validation
 
 ## Overview
-Validation pipeline and helpers built on FluentValidation for Clean Architecture solutions. Ships a configurable MediatR behavior, a template-shaped `ValidationException`, rule helpers, and a base validator that applies common conventions. Designed to be drop-in compatible with Jason Taylor’s template while enabling Result-based short-circuiting when desired.
+Validation pipeline and helpers built on FluentValidation for Clean Architecture solutions. Ships a configurable MediatR behaviour, a template-shaped `ValidationException`, rule helpers, and a base validator that applies common conventions. Designed to be drop-in compatible with Jason Taylor’s template while enabling Result-based short-circuiting when desired.
 
 ## When to use
 - You follow the template’s MediatR pipeline and want richer control over how validation failures surface (throw vs Result vs notify).
@@ -20,10 +20,10 @@ dotnet add src/YourProject/YourProject.csproj package CleanArchitecture.Extensio
 
 ## Usage
 
-### Wire up validators and behavior (DI)
+### Wire up validators and behaviour (DI)
 ```csharp
 services.AddValidatorsFromAssemblyContaining<Startup>(); // or your Application assembly marker
-services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
+services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehaviour<,>));
 
 // Optional: configure strategy/options
 services.Configure<ValidationOptions>(options =>
@@ -54,12 +54,17 @@ Key options: `MaxFailures`, `IncludePropertyName`, `IncludeAttemptedValue`, `Inc
   - `PositiveId`
   - `PageNumber`
   - `PageSize`
+  - `PhoneE164`
+  - `UrlAbsoluteHttpHttps`
+  - `CultureCode`
+  - `SortExpression` (whitelist allowed fields)
+  - Tenant-aware rules (planned with the Multitenancy module)
 
 ### Result short-circuit example
 ```csharp
 var options = new ValidationOptions { Strategy = ValidationStrategy.ReturnResult };
-var behavior = new ValidationBehavior<CreateTodo, Result<TodoVm>>(validators, options);
-// When validation fails, the behavior returns Result<T>.Failure(errors) instead of throwing.
+var behavior = new ValidationBehaviour<CreateTodo, Result<TodoVm>>(validators, options);
+// When validation fails, the behaviour returns Result<T>.Failure(errors) instead of throwing.
 ```
 
 ## Troubleshooting

src/CleanArchitecture.Extensions.Core/README.md

@@ -5,6 +5,7 @@ Core primitives for Clean Architecture apps built on MediatR.
 - Pipeline behaviors for logging, performance timing, and correlation IDs.
 - Result model with trace identifiers, error aggregation, and success/failure helpers.
 - Domain event support, guard helpers, and clock abstractions for deterministic tests.
+- Legacy template shims (`LegacyResult`/`LegacyResult<T>`) to ease migration from Jason Taylor’s `Result` shape.
 - Ships with SourceLink, XML docs, and snupkg symbols for a smooth debugging experience.
 
 ## Install
@@ -37,6 +38,10 @@ if (result.IsFailure)
 {
     return Results.BadRequest(result.Errors);
 }
+
+// Map to/from template-style Result shape during migration.
+var legacy = LegacyResult.FromResult(result);
+var backToRich = legacy.ToResult(result.TraceId);
 ```
 
 ## Target frameworks

src/CleanArchitecture.Extensions.Core/Result/LegacyResult.cs

@@ -0,0 +1,143 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace CleanArchitecture.Extensions.Core.Results;
+
+/// <summary>
+/// Compatibility result that mirrors the Jason Taylor template shape (Succeeded + string[] Errors) for drop-in use.
+/// </summary>
+public class LegacyResult
+{
+    /// <summary>
+    /// Gets a value indicating whether the operation succeeded.
+    /// </summary>
+    public bool Succeeded { get; init; }
+
+    /// <summary>
+    /// Gets the error messages when the operation failed.
+    /// </summary>
+    public string[] Errors { get; init; } = Array.Empty<string>();
+
+    /// <summary>
+    /// Creates a successful result.
+    /// </summary>
+    public static LegacyResult Success() => new() { Succeeded = true };
+
+    /// <summary>
+    /// Creates a failed result with the provided errors.
+    /// </summary>
+    /// <param name="errors">Error messages describing the failure.</param>
+    public static LegacyResult Failure(params string[] errors) =>
+        new() { Succeeded = false, Errors = errors ?? Array.Empty<string>() };
+
+    /// <summary>
+    /// Creates a failed result with the provided errors.
+    /// </summary>
+    /// <param name="errors">Error messages describing the failure.</param>
+    public static LegacyResult Failure(IEnumerable<string> errors) =>
+        new() { Succeeded = false, Errors = errors?.ToArray() ?? Array.Empty<string>() };
+
+    /// <summary>
+    /// Creates a legacy result from a rich core <see cref="Result"/>, mapping errors with an optional formatter.
+    /// </summary>
+    /// <param name="result">Core result to convert.</param>
+    /// <param name="errorFormatter">Optional formatter for converting <see cref="Error"/> to string messages.</param>
+    public static LegacyResult FromResult(Result result, Func<Error, string>? errorFormatter = null)
+    {
+        ArgumentNullException.ThrowIfNull(result);
+        var formatter = errorFormatter ?? DefaultFormatter;
+        return result.IsSuccess ? Success() : Failure(result.Errors.Select(formatter));
+    }
+
+    /// <summary>
+    /// Converts this legacy result into a rich core <see cref="Result"/>.
+    /// </summary>
+    /// <param name="traceId">Optional trace identifier to attach to errors.</param>
+    /// <param name="errorCode">Error code to apply when mapping string messages to <see cref="Error"/>.</param>
+    public Result ToResult(string? traceId = null, string errorCode = "legacy.failure")
+    {
+        if (Succeeded)
+        {
+            return Result.Success(traceId);
+        }
+
+        var errors = Errors.Length == 0
+            ? new[] { new Error(errorCode, "An error occurred.", traceId) }
+            : Errors.Select(message => new Error(errorCode, message, traceId));
+
+        return Result.Failure(errors, traceId);
+    }
+
+    /// <summary>
+    /// Default mapping from structured <see cref="Error"/> to legacy string message.
+    /// </summary>
+    /// <param name="error">Error to map.</param>
+    /// <returns>Error message when present; otherwise the error code.</returns>
+    protected internal static string DefaultFormatter(Error error) =>
+        string.IsNullOrWhiteSpace(error.Message) ? error.Code : error.Message;
+}
+
+/// <summary>
+/// Compatibility result with value payload mirroring the Jason Taylor template shape.
+/// </summary>
+/// <typeparam name="T">Type of the value returned on success.</typeparam>
+public sealed class LegacyResult<T> : LegacyResult
+{
+    /// <summary>
+    /// Gets the value when the operation succeeds.
+    /// </summary>
+    [AllowNull]
+    public T Value { get; init; } = default!;
+
+    /// <summary>
+    /// Creates a successful result with a value.
+    /// </summary>
+    /// <param name="value">Value to return.</param>
+    public static LegacyResult<T> Success(T value) => new() { Succeeded = true, Value = value };
+
+    /// <summary>
+    /// Creates a failed result with the provided errors.
+    /// </summary>
+    /// <param name="errors">Error messages describing the failure.</param>
+    public new static LegacyResult<T> Failure(params string[] errors) =>
+        new() { Succeeded = false, Errors = errors ?? Array.Empty<string>() };
+
+    /// <summary>
+    /// Creates a failed result with the provided errors.
+    /// </summary>
+    /// <param name="errors">Error messages describing the failure.</param>
+    public new static LegacyResult<T> Failure(IEnumerable<string> errors) =>
+        new() { Succeeded = false, Errors = errors?.ToArray() ?? Array.Empty<string>() };
+
+    /// <summary>
+    /// Creates a legacy result from a rich core <see cref="Result{T}"/>, mapping errors with an optional formatter.
+    /// </summary>
+    /// <param name="result">Core result to convert.</param>
+    /// <param name="errorFormatter">Optional formatter for converting <see cref="Error"/> to string messages.</param>
+    public static LegacyResult<T> FromResult(Result<T> result, Func<Error, string>? errorFormatter = null)
+    {
+        ArgumentNullException.ThrowIfNull(result);
+        var formatter = errorFormatter ?? DefaultFormatter;
+        return result.IsSuccess
+            ? Success(result.Value)
+            : Failure(result.Errors.Select(formatter));
+    }
+
+    /// <summary>
+    /// Converts this legacy result into a rich core <see cref="Result{T}"/>.
+    /// </summary>
+    /// <param name="traceId">Optional trace identifier to attach to errors.</param>
+    /// <param name="errorCode">Error code to apply when mapping string messages to <see cref="Error"/>.</param>
+    public new Result<T> ToResult(string? traceId = null, string errorCode = "legacy.failure")
+    {
+        if (Succeeded)
+        {
+            return Result.Success(Value, traceId);
+        }
+
+        var errors = Errors.Length == 0
+            ? new[] { new Error(errorCode, "An error occurred.", traceId) }
+            : Errors.Select(message => new Error(errorCode, message, traceId));
+
+        return Result.Failure<T>(errors, traceId);
+    }
+}

…lidation/Behaviors/ValidationBehavior.cs …idation/Behaviors/ValidationBehaviour.cssrc/CleanArchitecture.Extensions.Validation/Behaviors/ValidationBehavior.cs renamed to src/CleanArchitecture.Extensions.Validation/Behaviors/ValidationBehaviour.cs src/CleanArchitecture.Extensions.Validation/Behaviors/ValidationBehavior.cs renamed to src/CleanArchitecture.Extensions.Validation/Behaviors/ValidationBehaviour.cs

@@ -15,11 +15,11 @@
 namespace CleanArchitecture.Extensions.Validation.Behaviors;
 
 /// <summary>
-/// MediatR pipeline behavior that executes FluentValidation validators and surfaces failures using configured strategy.
+/// MediatR pipeline behaviour that executes FluentValidation validators and surfaces failures using configured strategy.
 /// </summary>
 /// <typeparam name="TRequest">Request type.</typeparam>
 /// <typeparam name="TResponse">Response type.</typeparam>
-public sealed class ValidationBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
+public sealed class ValidationBehaviour<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
     where TRequest : notnull
 {
     private readonly IReadOnlyCollection<IValidator<TRequest>> _validators;
@@ -30,15 +30,15 @@ public sealed class ValidationBehavior<TRequest, TResponse> : IPipelineBehavior<
     private readonly IAppLogger<TRequest>? _logger;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="ValidationBehavior{TRequest, TResponse}"/> class.
+    /// Initializes a new instance of the <see cref="ValidationBehaviour{TRequest, TResponse}"/> class.
     /// </summary>
     /// <param name="validators">Validators to execute.</param>
     /// <param name="options">Validation behavior options.</param>
     /// <param name="notificationPublisher">Optional publisher for validation notifications.</param>
     /// <param name="logContext">Optional log context providing correlation identifiers.</param>
     /// <param name="coreOptions">Optional shared core options for default trace identifiers.</param>
     /// <param name="logger">Optional logger for emitting validation summaries.</param>
-    public ValidationBehavior(
+    public ValidationBehaviour(
         IEnumerable<IValidator<TRequest>> validators,
         IOptions<ValidationOptions>? options = null,
         IValidationNotificationPublisher? notificationPublisher = null,
@@ -131,7 +131,7 @@ private TResponse CreateResultOrThrow(IReadOnlyCollection<ValidationError> error
         }
 
         throw new InvalidOperationException(
-            "ValidationBehavior is configured to return a Result, but TResponse is not a Result or Result<T>. " +
+            "ValidationBehaviour is configured to return a Result, but TResponse is not a Result or Result<T>. " +
             "Use ValidationStrategy.Throw for non-Result handlers or update handlers to return Result.");
     }
 

src/CleanArchitecture.Extensions.Validation/README.md

@@ -24,7 +24,7 @@ using FluentValidation;
 using MediatR;
 
 services.AddValidatorsFromAssemblyContaining<CreateOrderValidator>();
-services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
+services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehaviour<,>));
 
 services.Configure<ValidationOptions>(options =>
 {
@@ -37,6 +37,20 @@ services.Configure<ValidationOptions>(options =>
 
 Implement `IValidationNotificationPublisher` if you want to capture validation failures without throwing.
 
+## Rule helpers
+
+- `NotEmptyTrimmed`
+- `EmailAddressBasic`
+- `OptionalEmailAddress`
+- `PositiveId`
+- `PageNumber`
+- `PageSize`
+- `PhoneE164`
+- `UrlAbsoluteHttpHttps`
+- `CultureCode`
+- `SortExpression` (allowed field whitelist)
+- Tenant-aware rules (planned alongside the Multitenancy module)
+
 ## Target frameworks
 
 - net8.0