feat: source generator for Brighter handler/mapper/transform registration

Brighter.slnx

@@ -196,6 +196,7 @@
   <Folder Name="/tests/">
     <File Path="tests/README.md" />
     <Project Path="tests/Paramore.Brighter.Analyzer.Tests/Paramore.Brighter.Analyzer.Tests.csproj" />
+    <Project Path="tests/Paramore.Brighter.SourceGenerators.Tests/Paramore.Brighter.SourceGenerators.Tests.csproj" />
     <Project Path="tests/Paramore.Brighter.AsyncAPI.Tests/Paramore.Brighter.AsyncAPI.Tests.csproj" />
     <Project Path="tests/Paramore.Brighter.AWS.Tests/Paramore.Brighter.AWS.Tests.csproj" />
     <Project Path="tests/Paramore.Brighter.AWS.V4.Tests/Paramore.Brighter.AWS.V4.Tests.csproj" />
@@ -235,6 +236,7 @@
   </Folder>
   <Project Path="src/Paramore.Brighter.Analyzer.Package/Paramore.Brighter.Analyzer.Package.csproj" />
   <Project Path="src/Paramore.Brighter.Analyzer/Paramore.Brighter.Analyzer.csproj" />
+  <Project Path="src/Paramore.Brighter.SourceGenerators/Paramore.Brighter.SourceGenerators.csproj" />
   <Project Path="src/Paramore.Brighter.Archive.Azure/Paramore.Brighter.Archive.Azure.csproj" />
   <Project Path="src/Paramore.Brighter.AsyncAPI.NJsonSchema/Paramore.Brighter.AsyncAPI.NJsonSchema.csproj" />
   <Project Path="src/Paramore.Brighter.AsyncAPI/Paramore.Brighter.AsyncAPI.csproj" />

Directory.Packages.props

@@ -69,6 +69,7 @@
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="5.3.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.3.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing" Version="1.1.3" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.SourceGenerators.Testing" Version="1.1.3" />
     <PackageVersion Include="Microsoft.Bcl.TimeProvider" Version="10.0.7" />
     <PackageVersion Include="Microsoft.Data.SqlClient" Version="7.0.1" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.7" />

samples/CommandProcessor/HelloWorld/HelloWorld.csproj

@@ -2,7 +2,17 @@
   <PropertyGroup>
     <TargetFramework>net9.0</TargetFramework>
     <OutputType>Exe</OutputType>
+    <!--
+      With the NuGet package, build/Paramore.Brighter.SourceGenerators.props sets this and makes
+      it CompilerVisible for direct PackageReferences only (so it doesn't flow to transitive
+      consumers). The sample uses a ProjectReference, so we opt in by hand.
+    -->
+    <BrighterAutoRegistration>true</BrighterAutoRegistration>
   </PropertyGroup>
+
+  <ItemGroup>
+    <CompilerVisibleProperty Include="BrighterAutoRegistration" />
+  </ItemGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
     <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
@@ -12,5 +22,8 @@
   <ItemGroup>
     <ProjectReference Include="..\..\..\src\Paramore.Brighter.Extensions.DependencyInjection\Paramore.Brighter.Extensions.DependencyInjection.csproj" />
     <ProjectReference Include="..\..\..\src\Paramore.Brighter\Paramore.Brighter.csproj" />
+    <ProjectReference Include="..\..\..\src\Paramore.Brighter.SourceGenerators\Paramore.Brighter.SourceGenerators.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
   </ItemGroup>
-</Project>
+</Project>

samples/CommandProcessor/HelloWorld/NoOpTransformer.cs

@@ -0,0 +1,22 @@
+#nullable enable
+using Paramore.Brighter;
+
+namespace HelloWorld;
+
+/// <summary>
+/// A do-nothing transform purely to exercise the source generator's transform discovery.
+/// </summary>
+public sealed class NoOpTransformer : IAmAMessageTransform
+{
+    public IRequestContext? Context { get; set; }
+
+    public void InitializeWrapFromAttributeParams(params object?[] initializerList) { }
+
+    public void InitializeUnwrapFromAttributeParams(params object?[] initializerList) { }
+
+    public Message Wrap(Message message, Publication publication) => message;
+
+    public Message Unwrap(Message message) => message;
+
+    public void Dispose() { }
+}

samples/CommandProcessor/HelloWorld/Program.cs

@@ -30,7 +30,7 @@ THE SOFTWARE. */
 using Paramore.Brighter.Extensions.DependencyInjection;
 
 var builder = Host.CreateApplicationBuilder();
-builder.Services.AddBrighter().AutoFromAssemblies();
+builder.Services.AddBrighter().AddFromThisAssembly();
 var host = builder.Build();
 
 var commandProcessor = host.Services.GetRequiredService<IAmACommandProcessor>();

src/Paramore.Brighter.Extensions.DependencyInjection/BrighterBuilderExtensions.cs

@@ -0,0 +1,60 @@
+#region Licence
+/* The MIT License (MIT)
+Copyright © 2026 Ian Cooper <ian_hammond_cooper@yahoo.co.uk>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE. */
+#endregion
+
+using System;
+
+namespace Paramore.Brighter.Extensions.DependencyInjection
+{
+    /// <summary>
+    /// Extension methods on <see cref="IBrighterBuilder"/> that are deliberately kept off the
+    /// interface so they can be added without making a binary-breaking change to public API for
+    /// downstream implementers.
+    /// </summary>
+    public static class BrighterBuilderExtensions
+    {
+        /// <summary>
+        /// Register transforms with the built-in transformer registry. Symmetric with
+        /// <see cref="IBrighterBuilder.Handlers"/> and <see cref="IBrighterBuilder.MapperRegistry"/>,
+        /// intended for callers that want to add transforms explicitly (for example from a
+        /// source generator) rather than via assembly scanning.
+        /// </summary>
+        /// <param name="builder">The Brighter builder.</param>
+        /// <param name="registerTransforms">A callback to register transforms.</param>
+        /// <returns>The builder, to allow chaining.</returns>
+        /// <exception cref="InvalidOperationException">
+        /// Thrown if <paramref name="builder"/> is not the <see cref="ServiceCollectionBrighterBuilder"/>
+        /// implementation that owns a <see cref="ServiceCollectionTransformerRegistry"/>.
+        /// </exception>
+        public static IBrighterBuilder Transforms(this IBrighterBuilder builder, Action<ServiceCollectionTransformerRegistry> registerTransforms)
+        {
+            if (builder == null) throw new ArgumentNullException(nameof(builder));
+            if (registerTransforms == null) throw new ArgumentNullException(nameof(registerTransforms));
+
+            if (builder is ServiceCollectionBrighterBuilder concrete)
+                return concrete.Transforms(registerTransforms);
+
+            throw new InvalidOperationException(
+                $"The {nameof(Transforms)} extension requires {nameof(ServiceCollectionBrighterBuilder)}; received {builder.GetType().FullName}.");
+        }
+    }
+}

src/Paramore.Brighter.Extensions.DependencyInjection/ServiceCollectionBrighterBuilder.cs

@@ -235,6 +235,21 @@ where typeof(IAmAMessageTransformAsync).IsAssignableFrom(i) || typeof(IAmAMessag
 
             return this;
         }
+
+        /// <summary>
+        /// Register transforms with the built-in transformer registry.
+        /// </summary>
+        /// <param name="registerTransforms">A callback to register transforms</param>
+        /// <returns>This builder, allows chaining calls</returns>
+        public IBrighterBuilder Transforms(Action<ServiceCollectionTransformerRegistry> registerTransforms)
+        {
+            if (registerTransforms == null)
+                throw new ArgumentNullException(nameof(registerTransforms));
+
+            registerTransforms(_transformerRegistry);
+
+            return this;
+        }
 
         private void RegisterHandlersFromAssembly(Type interfaceType, IEnumerable<Assembly> assemblies, Assembly assembly, IEnumerable<Type>? excludeDynamicHandlerTypes)
         {

src/Paramore.Brighter.SourceGenerators/AnalyzerReleases.Shipped.md

@@ -0,0 +1,2 @@
+; Shipped analyzer releases
+; https://github.com/dotnet/roslyn-analyzers/blob/main/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md

src/Paramore.Brighter.SourceGenerators/AnalyzerReleases.Unshipped.md

@@ -0,0 +1,14 @@
+; Unshipped analyzer release
+; https://github.com/dotnet/roslyn-analyzers/blob/main/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md
+
+### New Rules
+
+Rule ID | Category | Severity | Notes
+--------|----------|----------|-------
+BRGEN001 | Brighter | Error | Brighter registration method must be partial
+BRGEN002 | Brighter | Error | Brighter registration method must be static
+BRGEN003 | Brighter | Error | Brighter registration method must return IBrighterBuilder
+BRGEN004 | Brighter | Error | Brighter registration method must take a single IBrighterBuilder parameter
+BRGEN005 | Brighter | Warning | Generic message mappers and transforms are not registered
+BRGEN006 | Brighter | Warning | Types nested in an open generic type are not registered
+BRGEN007 | Brighter | Info | Auto-registration suppressed by a manual registration method