feat: Implement pipeline context validation with FluentValidation integration

- Added `PipelineContextValidationGenerationModel` and `PipelineContextValidationGenerationModelBuilder` to handle validation metadata for pipeline contexts.
- Introduced `PipelineContextValidationSourceEmitter` and `PipelineContextValidationSourceGenerator` to generate FluentValidation validators for pipeline contexts.
- Created diagnostics for validation generation, including checks for context type validity and validation method signatures.
- Implemented `IPipelineContextValidationInvoker` and `PipelineContextValidationInvoker` to execute validation for pipeline contexts.
- Added unit tests for validation execution and generator functionality, ensuring proper validation behavior and error reporting.
- Updated existing code to integrate new validation features and ensure compatibility with FluentValidation.

Author: vp

docs/features-pipelines.md

@@ -99,14 +99,15 @@ There are three main ways to define pipelines:
 Packaged definitions are a good default when a pipeline is reusable or belongs clearly to one feature.
 
 ```csharp
-public sealed class OrderImportContext : PipelineContextBase
+public partial class OrderImportContext : PipelineContextBase
 {
+    [ValidateNotEmpty("Source file name is required.")]
     public string SourceFileName { get; set; }
 
     public int ImportedOrderCount { get; set; }
 }
 
-public sealed class OrderImportPipeline : PipelineDefinition<OrderImportContext>
+public class OrderImportPipeline : PipelineDefinition<OrderImportContext>
 {
     protected override void Configure(IPipelineDefinitionBuilder<OrderImportContext> builder)
     {
@@ -120,7 +121,7 @@ public sealed class OrderImportPipeline : PipelineDefinition<OrderImportContext>
     }
 }
 
-public sealed class ValidateOrderImportStep : PipelineStep<OrderImportContext>
+public class ValidateOrderImportStep : PipelineStep<OrderImportContext>
 {
     protected override PipelineControl Execute(
         OrderImportContext context,
@@ -137,7 +138,7 @@ public sealed class ValidateOrderImportStep : PipelineStep<OrderImportContext>
     }
 }
 
-public sealed class LoadOrdersStep : AsyncPipelineStep<OrderImportContext>
+public class LoadOrdersStep : AsyncPipelineStep<OrderImportContext>
 {
     protected override async ValueTask<PipelineControl> ExecuteAsync(
         OrderImportContext context,
@@ -153,6 +154,34 @@ public sealed class LoadOrdersStep : AsyncPipelineStep<OrderImportContext>
 }
 ```
 
+### Context Validation
+
+When the context type declares validation attributes or a static `[Validate]` method, the pipeline engine validates the context before hooks, behaviors, and steps run.
+
+```csharp
+public partial class OrderImportContext : PipelineContextBase
+{
+    [ValidateNotEmpty("Source file name is required.")]
+    public string SourceFileName { get; set; }
+
+    public int ImportedOrderCount { get; set; }
+
+    [Validate]
+    private static void Validate(InlineValidator<OrderImportContext> validator)
+    {
+        validator.RuleFor(x => x.ImportedOrderCount).GreaterThanOrEqualTo(0);
+    }
+}
+```
+
+Add the code-generation analyzer package to the project that contains the pipeline context:
+
+```xml
+<PackageReference Include="BridgingIT.DevKit.Common.Utilities.CodeGen"
+                  Version="x.y.z"
+                  PrivateAssets="all" />
+```
+
 ### Authoring and Registration Options
 
 ```mermaid
@@ -363,7 +392,7 @@ sequenceDiagram
 Use class-based steps for reusable or non-trivial workflow logic.
 
 ```csharp
-public sealed class PersistOrdersStep : AsyncPipelineStep<OrderImportContext>
+public class PersistOrdersStep : AsyncPipelineStep<OrderImportContext>
 {
     protected override async ValueTask<PipelineControl> ExecuteAsync(
         OrderImportContext context,
@@ -492,7 +521,7 @@ Use hooks for:
 - step lifecycle observation
 
 ```csharp
-public sealed class PipelineAuditHook : PipelineHook<PipelineContextBase>
+public class PipelineAuditHook : PipelineHook<PipelineContextBase>
 {
     public override ValueTask OnPipelineStartingAsync(
         PipelineContextBase context,

src/Common.Utilities.CodeGen/Pipelines/PipelineContextValidationGenerationModel.cs

@@ -0,0 +1,60 @@
+// MIT-License
+// Copyright BridgingIT GmbH - All Rights Reserved
+// Use of this source code is governed by an MIT-style license that can be
+// found in the LICENSE file at https://github.com/bridgingit/bitdevkit/license
+
+namespace BridgingIT.DevKit.Common;
+
+using System.Collections.Immutable;
+using Microsoft.CodeAnalysis;
+
+/// <summary>
+/// Represents the validated source-generation model for a pipeline context validator.
+/// </summary>
+public sealed class PipelineContextValidationGenerationModel(
+    INamedTypeSymbol classSymbol,
+    IMethodSymbol validateMethod,
+    ImmutableArray<ValidationPropertyRuleModel> propertyValidationRules,
+    string namespaceName,
+    string accessibilityKeyword)
+{
+    /// <summary>
+    /// Gets the authored pipeline context type.
+    /// </summary>
+    public INamedTypeSymbol ClassSymbol { get; } = classSymbol;
+
+    /// <summary>
+    /// Gets the optional explicit <c>[Validate]</c> method.
+    /// </summary>
+    public IMethodSymbol ValidateMethod { get; } = validateMethod;
+
+    /// <summary>
+    /// Gets the property-validation rules inferred from validation attributes.
+    /// </summary>
+    public ImmutableArray<ValidationPropertyRuleModel> PropertyValidationRules { get; } = propertyValidationRules;
+
+    /// <summary>
+    /// Gets the namespace of the authored pipeline context.
+    /// </summary>
+    public string NamespaceName { get; } = namespaceName;
+
+    /// <summary>
+    /// Gets the generated accessibility keyword mirrored from the authored pipeline context.
+    /// </summary>
+    public string AccessibilityKeyword { get; } = accessibilityKeyword;
+
+    /// <summary>
+    /// Gets a value indicating whether the generated partial class should also include the <c>sealed</c> modifier.
+    /// </summary>
+    public bool IsSealed { get; } = classSymbol.IsSealed;
+
+    /// <summary>
+    /// Gets the fully qualified pipeline-context type name.
+    /// </summary>
+    public string ContextTypeName => this.ClassSymbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
+
+    /// <summary>
+    /// Gets a value indicating whether any generated validation metadata exists for the pipeline context.
+    /// </summary>
+    public bool HasValidation => this.ValidateMethod is not null || this.PropertyValidationRules.Length > 0;
+}

src/Common.Utilities.CodeGen/Pipelines/PipelineContextValidationGenerationModelBuilder.cs

@@ -0,0 +1,237 @@
+// MIT-License
+// Copyright BridgingIT GmbH - All Rights Reserved
+// Use of this source code is governed by an MIT-style license that can be
+// found in the LICENSE file at https://github.com/bridgingit/bitdevkit/license
+
+namespace BridgingIT.DevKit.Common;
+
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+/// <summary>
+/// Builds validated semantic models for pipeline-context validation source generation.
+/// </summary>
+public static class PipelineContextValidationGenerationModelBuilder
+{
+    private const string PipelineContextBaseName = "BridgingIT.DevKit.Common.PipelineContextBase";
+    private const string ValidateAttributeName = "BridgingIT.DevKit.Common.ValidateAttribute";
+    private const string InlineValidatorOfTName = "FluentValidation.InlineValidator`1";
+
+    /// <summary>
+    /// Returns the context type symbol when the current syntax node is a pipeline-context validation candidate.
+    /// </summary>
+    /// <param name="context">The generator syntax context for the candidate node.</param>
+    /// <returns>The pipeline-context type symbol, or <see langword="null"/> when the node is not a candidate.</returns>
+    public static INamedTypeSymbol GetCandidate(GeneratorSyntaxContext context)
+    {
+        if (context.Node is not ClassDeclarationSyntax classDeclaration)
+        {
+            return null;
+        }
+
+        if (context.SemanticModel.GetDeclaredSymbol(classDeclaration) is not INamedTypeSymbol classSymbol)
+        {
+            return null;
+        }
+
+        return InheritsFrom(classSymbol, context.SemanticModel.Compilation.GetTypeByMetadataName(PipelineContextBaseName))
+            ? classSymbol
+            : null;
+    }
+
+    /// <summary>
+    /// Creates a validated generation model for a pipeline context with source-generated validation metadata.
+    /// </summary>
+    /// <param name="context">The source-production context used to report diagnostics.</param>
+    /// <param name="compilation">The current compilation.</param>
+    /// <param name="classSymbol">The pipeline-context type candidate.</param>
+    /// <returns>A generation model when the context is valid; otherwise <see langword="null"/>.</returns>
+    public static PipelineContextValidationGenerationModel Create(
+        SourceProductionContext context,
+        Compilation compilation,
+        INamedTypeSymbol classSymbol)
+    {
+        if (!IsValidContextType(context, compilation, classSymbol))
+        {
+            return null;
+        }
+
+        if (!TryGetValidateMethod(context, compilation, classSymbol, out var validateMethod))
+        {
+            return null;
+        }
+
+        if (!ValidationGenerationModelBuilder.TryCreate(
+                context,
+                classSymbol,
+                PipelineContextValidationSourceGeneratorDiagnostics.ValidationGeneration,
+                out var propertyValidationRules))
+        {
+            return null;
+        }
+
+        if (validateMethod is null && propertyValidationRules.Length == 0)
+        {
+            return null;
+        }
+
+        if (HasTypeNameCollision(classSymbol, "Validator"))
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.GeneratedNameCollision,
+                classSymbol.Locations.FirstOrDefault(),
+                classSymbol.Name,
+                "Validator"));
+            return null;
+        }
+
+        return new PipelineContextValidationGenerationModel(
+            classSymbol,
+            validateMethod,
+            propertyValidationRules,
+            classSymbol.ContainingNamespace.IsGlobalNamespace ? string.Empty : classSymbol.ContainingNamespace.ToDisplayString(),
+            RequesterGeneratorSymbolHelper.GetAccessibilityKeyword(classSymbol));
+    }
+
+    private static bool IsValidContextType(SourceProductionContext context, Compilation compilation, INamedTypeSymbol classSymbol)
+    {
+        if (classSymbol.ContainingType is not null)
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.NestedContextsNotSupported,
+                classSymbol.Locations.FirstOrDefault(),
+                classSymbol.Name));
+            return false;
+        }
+
+        if (classSymbol.Arity > 0)
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.GenericContextsNotSupported,
+                classSymbol.Locations.FirstOrDefault(),
+                classSymbol.Name));
+            return false;
+        }
+
+        if (classSymbol.IsStatic || classSymbol.IsAbstract ||
+            !InheritsFrom(classSymbol, compilation.GetTypeByMetadataName(PipelineContextBaseName)))
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.InvalidAttributedType,
+                classSymbol.Locations.FirstOrDefault(),
+                classSymbol.Name));
+            return false;
+        }
+
+        if (!IsPartial(classSymbol))
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.ContextMustBePartial,
+                classSymbol.Locations.FirstOrDefault(),
+                classSymbol.Name));
+            return false;
+        }
+
+        return true;
+    }
+
+    private static bool TryGetValidateMethod(
+        SourceProductionContext context,
+        Compilation compilation,
+        INamedTypeSymbol classSymbol,
+        out IMethodSymbol validateMethod)
+    {
+        var validateMethods = classSymbol.GetMembers()
+            .OfType<IMethodSymbol>()
+            .Where(static method => method.GetAttributes().Any(attribute => attribute.AttributeClass?.ToDisplayString() == ValidateAttributeName))
+            .ToArray();
+
+        validateMethod = null;
+        if (validateMethods.Length == 0)
+        {
+            return true;
+        }
+
+        if (validateMethods.Length > 1)
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.DuplicateValidateMethod,
+                validateMethods[1].Locations.FirstOrDefault() ?? classSymbol.Locations.FirstOrDefault(),
+                classSymbol.Name));
+            return false;
+        }
+
+        var method = validateMethods[0];
+        if (!method.IsStatic)
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.ValidateMethodMustBeStatic,
+                method.Locations.FirstOrDefault(),
+                method.Name));
+            return false;
+        }
+
+        if (!method.ReturnsVoid)
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.InvalidValidateReturnType,
+                method.Locations.FirstOrDefault(),
+                method.Name));
+            return false;
+        }
+
+        if (method.Parameters.Length != 1 || method.Parameters[0].RefKind != RefKind.None)
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.InvalidValidateParameter,
+                method.Locations.FirstOrDefault(),
+                method.Name,
+                classSymbol.Name));
+            return false;
+        }
+
+        var inlineValidatorType = compilation.GetTypeByMetadataName(InlineValidatorOfTName);
+        var parameterType = method.Parameters[0].Type as INamedTypeSymbol;
+        if (parameterType is null ||
+            !parameterType.IsGenericType ||
+            !SymbolEqualityComparer.Default.Equals(parameterType.OriginalDefinition, inlineValidatorType) ||
+            !SymbolEqualityComparer.Default.Equals(parameterType.TypeArguments[0], classSymbol))
+        {
+            context.ReportDiagnostic(Diagnostic.Create(
+                PipelineContextValidationSourceGeneratorDiagnostics.InvalidValidateParameter,
+                method.Locations.FirstOrDefault(),
+                method.Name,
+                classSymbol.Name));
+            return false;
+        }
+
+        validateMethod = method;
+        return true;
+    }
+
+    private static bool HasTypeNameCollision(INamedTypeSymbol classSymbol, string typeName)
+    {
+        return classSymbol.GetTypeMembers(typeName).Length > 0;
+    }
+
+    private static bool InheritsFrom(INamedTypeSymbol symbol, INamedTypeSymbol baseType)
+    {
+        for (var current = symbol; current is not null; current = current.BaseType)
+        {
+            if (SymbolEqualityComparer.Default.Equals(current, baseType))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private static bool IsPartial(INamedTypeSymbol classSymbol)
+    {
+        return classSymbol.DeclaringSyntaxReferences
+            .Select(static reference => reference.GetSyntax())
+            .OfType<ClassDeclarationSyntax>()
+            .All(static declaration => declaration.Modifiers.Any(modifier => modifier.IsKind(Microsoft.CodeAnalysis.CSharp.SyntaxKind.PartialKeyword)));
+    }
+}