* Fix: XPC4003 has been reduced to Warning to allow initial build to succeed

* Add: New rule XPC4006 (Error) to enforce handler signature correctness once generated types exist

Author: mkholt

XrmPluginCore.SourceGenerator.Tests/DiagnosticTests/DiagnosticReportingTests.cs

@@ -211,7 +211,8 @@ public void Process() { }
             .ToArray();
 
         errorDiagnostics.Should().NotBeEmpty("XPC4003 should be reported when handler is missing PreImage parameter");
-        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Error);
+        // XPC4003 is Warning when generated types don't exist yet (allows initial build to succeed)
+        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Warning);
     }
 
     [Fact]
@@ -265,7 +266,8 @@ public void Process() { }
             .ToArray();
 
         errorDiagnostics.Should().NotBeEmpty("XPC4003 should be reported when handler is missing PostImage parameter");
-        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Error);
+        // XPC4003 is Warning when generated types don't exist yet (allows initial build to succeed)
+        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Warning);
     }
 
     [Fact]
@@ -320,7 +322,8 @@ public void Process() { }
             .ToArray();
 
         errorDiagnostics.Should().NotBeEmpty("XPC4003 should be reported when handler is missing both image parameters");
-        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Error);
+        // XPC4003 is Warning when generated types don't exist yet (allows initial build to succeed)
+        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Warning);
     }
 
     [Fact]
@@ -376,7 +379,8 @@ public void Process(PostImage post, PreImage pre) { }
             .ToArray();
 
         errorDiagnostics.Should().NotBeEmpty("XPC4003 should be reported when handler has wrong parameter order");
-        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Error);
+        // XPC4003 is Warning when generated types don't exist yet (allows initial build to succeed)
+        errorDiagnostics.Should().OnlyContain(d => d.Severity == DiagnosticSeverity.Warning);
     }
 
     [Fact]

XrmPluginCore.SourceGenerator/AnalyzerReleases.Shipped.md

@@ -20,3 +20,17 @@ XPC5000 | XrmPluginCore.SourceGenerator | Error    | XPC5000 Failed to generate
 Rule ID | Category | Severity | Notes
 --------|----------|----------|-------
 XPC4005 | XrmPluginCore.SourceGenerator | Info     | XPC4005 Consider using modern image registration API
+
+## Release 1.2.2
+
+### New Rules
+
+Rule ID | Category | Severity | Notes
+--------|----------|----------|-------
+XPC4006 | XrmPluginCore.SourceGenerator | Error    | XPC4006 Handler signature mismatch (generated types exist)
+
+### Changed Rules
+
+Rule ID | New Category | New Severity | Old Category | Old Severity | Notes
+--------|--------------|--------------|--------------|--------------|-------|-------
+XPC4003 | XrmPluginCore.SourceGenerator | Warning | XrmPluginCore.SourceGenerator | Error | Handler signature does not match registered images (generated types don't exist)

XrmPluginCore.SourceGenerator/AnalyzerReleases.Unshipped.md

@@ -3,3 +3,12 @@
 Rule ID | Category | Severity | Notes
 --------|----------|----------|-------
 
+### Removed Rules
+
+Rule ID | Category | Severity | Notes
+--------|----------|----------|-------
+
+### Changed Rules
+
+Rule ID | New Category | New Severity | Old Category | Old Severity | Notes
+--------|--------------|--------------|--------------|--------------|-------

XrmPluginCore.SourceGenerator/Analyzers/HandlerSignatureMismatchAnalyzer.cs

@@ -9,13 +9,16 @@
 namespace XrmPluginCore.SourceGenerator.Analyzers;
 
 /// <summary>
-/// Analyzer that reports an error when a handler method signature does not match the registered images.
+/// Analyzer that reports when a handler method signature does not match the registered images.
+/// Reports XPC4003 (Warning) when generated types don't exist yet, XPC4006 (Error) when they do.
 /// </summary>
 [DiagnosticAnalyzer(LanguageNames.CSharp)]
 public class HandlerSignatureMismatchAnalyzer : DiagnosticAnalyzer
 {
 	public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics =>
-		ImmutableArray.Create(DiagnosticDescriptors.HandlerSignatureMismatch);
+		ImmutableArray.Create(
+			DiagnosticDescriptors.HandlerSignatureMismatch,
+			DiagnosticDescriptors.HandlerSignatureMismatchError);
 
 	public override void Initialize(AnalysisContext context)
 	{
@@ -92,6 +95,19 @@ private void AnalyzeInvocation(SyntaxNodeAnalysisContext context)
 		// Build expected signature description
 		var expectedSignature = SyntaxFactoryHelper.BuildSignatureDescription(hasPreImage, hasPostImage);
 
+		// Determine if generated types exist to choose appropriate diagnostic severity
+		var generatedTypesExist = DoGeneratedTypesExist(
+			context,
+			invocation,
+			genericName,
+			hasPreImage,
+			hasPostImage);
+
+		// Choose diagnostic: XPC4006 (Error) if types exist, XPC4003 (Warning) if they don't
+		var descriptor = generatedTypesExist
+			? DiagnosticDescriptors.HandlerSignatureMismatchError
+			: DiagnosticDescriptors.HandlerSignatureMismatch;
+
 		// Create diagnostic properties for the code fix
 		var properties = ImmutableDictionary.CreateBuilder<string, string>();
 		properties.Add("ServiceType", serviceType.Name);
@@ -100,7 +116,7 @@ private void AnalyzeInvocation(SyntaxNodeAnalysisContext context)
 		properties.Add("HasPostImage", hasPostImage.ToString());
 
 		var diagnostic = Diagnostic.Create(
-			DiagnosticDescriptors.HandlerSignatureMismatch,
+			descriptor,
 			handlerArgument.GetLocation(),
 			properties.ToImmutable(),
 			methodName,
@@ -109,6 +125,97 @@ private void AnalyzeInvocation(SyntaxNodeAnalysisContext context)
 		context.ReportDiagnostic(diagnostic);
 	}
 
+	private static bool DoGeneratedTypesExist(
+		SyntaxNodeAnalysisContext context,
+		InvocationExpressionSyntax invocation,
+		GenericNameSyntax genericName,
+		bool hasPreImage,
+		bool hasPostImage)
+	{
+		// Get plugin class info
+		var pluginClass = invocation.Ancestors().OfType<ClassDeclarationSyntax>().FirstOrDefault();
+		if (pluginClass == null)
+		{
+			return false;
+		}
+
+		var pluginClassName = pluginClass.Identifier.Text;
+		var pluginNamespace = GetNamespace(pluginClass);
+
+		// Get entity type name
+		var entityTypeSyntax = genericName.TypeArgumentList.Arguments[0];
+		var entityTypeInfo = context.SemanticModel.GetTypeInfo(entityTypeSyntax);
+		var entityTypeName = entityTypeInfo.Type?.Name ?? "Unknown";
+
+		// Get operation and stage from arguments
+		var arguments = invocation.ArgumentList.Arguments;
+		var operation = ExtractEnumValue(arguments[0].Expression);
+		var stage = ExtractEnumValue(arguments[1].Expression);
+
+		// Build expected namespace: {Namespace}.PluginRegistrations.{PluginClass}.{Entity}{Op}{Stage}
+		var expectedNamespace = $"{pluginNamespace}.PluginRegistrations.{pluginClassName}.{entityTypeName}{operation}{stage}";
+
+		// Check if the required generated types exist
+		var compilation = context.SemanticModel.Compilation;
+
+		if (hasPreImage)
+		{
+			var preImageType = compilation.GetTypeByMetadataName($"{expectedNamespace}.PreImage");
+			if (preImageType == null)
+			{
+				return false;
+			}
+		}
+
+		if (hasPostImage)
+		{
+			var postImageType = compilation.GetTypeByMetadataName($"{expectedNamespace}.PostImage");
+			if (postImageType == null)
+			{
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	private static string GetNamespace(SyntaxNode node)
+	{
+		while (node != null)
+		{
+			if (node is NamespaceDeclarationSyntax namespaceDecl)
+			{
+				return namespaceDecl.Name.ToString();
+			}
+
+			if (node is FileScopedNamespaceDeclarationSyntax fileScopedNs)
+			{
+				return fileScopedNs.Name.ToString();
+			}
+
+			node = node.Parent;
+		}
+
+		return string.Empty;
+	}
+
+	private static string ExtractEnumValue(ExpressionSyntax expression)
+	{
+		// Handle direct enum access like EventOperation.Update
+		if (expression is MemberAccessExpressionSyntax memberAccess)
+		{
+			return memberAccess.Name.Identifier.Text;
+		}
+
+		// Handle string literal for custom messages
+		if (expression is LiteralExpressionSyntax literal)
+		{
+			return literal.Token.ValueText;
+		}
+
+		return "Unknown";
+	}
+
 	private static bool SignatureMatches(IMethodSymbol method, bool hasPreImage, bool hasPostImage)
 	{
 		var parameters = method.Parameters;

XrmPluginCore.SourceGenerator/CHANGELOG.md

@@ -1,3 +1,7 @@
+### v1.2.2 - 27 November 2025
+* Fix: XPC4003 has been reduced to Warning to allow initial build to succeed
+* Add: New rule XPC4006 (Error) to enforce handler signature correctness once generated types exist
+
 ### v1.0.1 - 27 November 2025
 * Fix: Analyzer for XPC4005 to correctly identify lambda expressions in AddImage calls
 

XrmPluginCore.SourceGenerator/DiagnosticDescriptors.cs

@@ -58,7 +58,7 @@ internal static class DiagnosticDescriptors
 		title: "Handler signature does not match registered images",
 		messageFormat: "Handler method '{0}' does not have expected signature. Expected parameters in order: {1}. PreImage must be the first parameter, followed by PostImage if both are used.",
 		category: Category,
-		defaultSeverity: DiagnosticSeverity.Error,
+		defaultSeverity: DiagnosticSeverity.Warning,
 		isEnabledByDefault: true,
 		helpLinkUri: "https://github.com/delegateas/XrmPluginCore/blob/main/XrmPluginCore.SourceGenerator/rules/XPC4003.md");
 
@@ -80,6 +80,15 @@ internal static class DiagnosticDescriptors
 		isEnabledByDefault: true,
 		helpLinkUri: "https://github.com/delegateas/XrmPluginCore/blob/main/XrmPluginCore.SourceGenerator/rules/XPC4005.md");
 
+	public static readonly DiagnosticDescriptor HandlerSignatureMismatchError = new(
+		id: "XPC4006",
+		title: "Handler signature does not match registered images",
+		messageFormat: "Handler method '{0}' does not have expected signature. Expected parameters in order: {1}. PreImage must be the first parameter, followed by PostImage if both are used.",
+		category: Category,
+		defaultSeverity: DiagnosticSeverity.Error,
+		isEnabledByDefault: true,
+		helpLinkUri: "https://github.com/delegateas/XrmPluginCore/blob/main/XrmPluginCore.SourceGenerator/rules/XPC4006.md");
+
 	public static readonly DiagnosticDescriptor GenerationError = new(
 		id: "XPC5000",
 		title: "Failed to generate wrapper classes",

XrmPluginCore.SourceGenerator/rules/XPC4003.md

@@ -2,11 +2,13 @@
 
 ## Severity
 
-Error
+Warning
 
 ## Description
 
-This rule reports when a handler method's signature does not match the images registered with `WithPreImage()`, `WithPostImage()`, or `AddImage()`. The handler method must accept parameters in a specific order: `PreImage` first (if registered), then `PostImage` (if registered).
+This rule reports when a handler method's signature does not match the images registered with `WithPreImage()`, `WithPostImage()`, or `AddImage()`, **and** the generated `PreImage`/`PostImage` types don't exist yet. The handler method must accept parameters in a specific order: `PreImage` first (if registered), then `PostImage` (if registered).
+
+This is a **warning** to allow the initial build to succeed so that the source generator can create the wrapper types. Once the types exist, this diagnostic escalates to [XPC4006](XPC4006.md) (Error).
 
 ## ❌ Examples of violations
 
@@ -126,7 +128,13 @@ public interface IAccountService
 
 Visual Studio and other IDEs supporting Roslyn analyzers will offer a code fix to update the method signature to match the registered images.
 
+## Relationship with XPC4006
+
+- **XPC4003 (Warning)**: Reported when the generated types don't exist yet. This allows the initial build to succeed so the types can be generated.
+- **XPC4006 (Error)**: Reported when the generated types exist but the signature is still wrong. This prevents runtime failures.
+
 ## See also
 
+- [XPC4006: Handler signature does not match registered images (types exist)](XPC4006.md)
 - [XPC4002: Handler method not found](XPC4002.md)
 - [XPC4004: Image registration without method reference](XPC4004.md)

XrmPluginCore.SourceGenerator/rules/XPC4006.md

@@ -0,0 +1,94 @@
+# XPC4006: Handler signature does not match registered images (types exist)
+
+## Severity
+
+Error
+
+## Description
+
+This rule reports when a handler method signature does not match the registered images **and** the generated `PreImage`/`PostImage` types already exist. This is the escalated version of [XPC4003](XPC4003.md) that becomes an error once the types have been generated.
+
+When you register images with `WithPreImage()` or `WithPostImage()`, the source generator creates type-safe wrapper classes. Your handler method must accept these wrapper types as parameters in the correct order.
+
+## ❌ Example of violation
+
+```csharp
+using MyNamespace.PluginRegistrations.AccountPlugin.AccountUpdatePostOperation;
+
+public class AccountPlugin : Plugin
+{
+    public AccountPlugin()
+    {
+        RegisterStep<Account, IAccountService>(
+            EventOperation.Update,
+            ExecutionStage.PostOperation,
+            nameof(IAccountService.HandleUpdate))
+            .WithPreImage(x => x.Name);
+    }
+}
+
+public interface IAccountService
+{
+    // XPC4006: Missing PreImage parameter
+    void HandleUpdate();
+}
+```
+
+## ✅ How to fix
+
+Update the handler method signature to match the registered images:
+
+```csharp
+using MyNamespace.PluginRegistrations.AccountPlugin.AccountUpdatePostOperation;
+
+public class AccountPlugin : Plugin
+{
+    public AccountPlugin()
+    {
+        RegisterStep<Account, IAccountService>(
+            EventOperation.Update,
+            ExecutionStage.PostOperation,
+            nameof(IAccountService.HandleUpdate))
+            .WithPreImage(x => x.Name);
+    }
+}
+
+public interface IAccountService
+{
+    // Correct: PreImage parameter matches the registered image
+    void HandleUpdate(PreImage preImage);
+}
+```
+
+## Parameter Order
+
+When both images are registered, they must appear in this order:
+1. `PreImage` (first)
+2. `PostImage` (second)
+
+```csharp
+// Both images registered
+.WithPreImage(x => x.Name)
+.WithPostImage(x => x.AccountNumber);
+
+// Handler must accept them in order: PreImage first, PostImage second
+void HandleUpdate(PreImage preImage, PostImage postImage);
+```
+
+## Why this is an Error
+
+This rule is an error (not a warning) because:
+
+1. **The generated types exist**: The source generator has already created the `PreImage`/`PostImage` wrapper classes
+2. **Runtime failure**: Without the correct signature, the plugin execution will fail at runtime
+3. **Fix is available**: You can add the correct using statement and update the method signature
+
+## Relationship with XPC4003
+
+- **XPC4003 (Warning)**: Reported when the generated types don't exist yet. This allows the initial build to succeed so the types can be generated.
+- **XPC4006 (Error)**: Reported when the generated types exist but the signature is still wrong. This prevents runtime failures.
+
+## See also
+
+- [XPC4003: Handler signature does not match registered images (types don't exist)](XPC4003.md)
+- [XPC4004: Image registration without method reference](XPC4004.md)

XrmPluginCore/CHANGELOG.md

@@ -1,3 +1,7 @@
+### v1.2.2 - 27 November 2025
+* Fix: XPC4003 has been reduced to Warning to allow initial build to succeed
+* Add: New rule XPC4006 (Error) to enforce handler signature correctness once generated types exist
+
 ### v1.2.1 - 27 November 2025
 * Fix: Analyzer for XPC4005 to correctly identify lambda expressions in AddImage calls