com.wallstop-studios.dxmessaging 2.1.1 → 2.1.3

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators/DxAutoConstructorGenerator.cs

@@ -56,6 +56,10 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             ImmutableArray<IFieldSymbol> FieldsToInject // Public readonly non-static fields
         );
 
+        /// <summary>
+        /// Configures the incremental generator pipeline that discovers annotated types and emits constructors.
+        /// </summary>
+        /// <param name="context">Initialization context provided by Roslyn.</param>
         public void Initialize(IncrementalGeneratorInitializationContext context)
         {
             // Find all class/struct/record declarations that have attribute lists
@@ -208,7 +212,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                         // Location-specific suggestions on each non-partial container
                         foreach (INamedTypeSymbol container in nonPartial)
                         {
-                            SyntaxReference? sr =
+                            SyntaxReference sr =
                                 container.DeclaringSyntaxReferences.FirstOrDefault();
                             if (sr != null && sr.GetSyntax() is TypeDeclarationSyntax tds)
                             {
@@ -258,11 +262,11 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 ? string.Empty
                 : $"namespace {namespaceName}\n{{";
             string namespaceBlockClose = string.IsNullOrEmpty(namespaceName) ? string.Empty : "}";
-            const string indent = "    ";
+            const string Indent = "    ";
 
             // Build container wrappers for nested types so the partial can merge correctly
             var containers = new Stack<INamedTypeSymbol>();
-            INamedTypeSymbol? current = typeSymbol.ContainingType;
+            INamedTypeSymbol current = typeSymbol.ContainingType;
             while (current is not null)
             {
                 containers.Push(current);
@@ -271,7 +275,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
 
             var containersOpen = new StringBuilder();
             var containersClose = new StringBuilder();
-            string currentIndent = indent; // one level inside namespace (or top-level)
+            string currentIndent = Indent; // one level inside namespace (or top-level)
 
             foreach (INamedTypeSymbol container in containers)
             {
@@ -306,7 +310,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                     $"{currentIndent}{containerAccessibility} partial {containerKind} {container.Name}{containerTypeParams}"
                 );
                 containersOpen.Append(currentIndent).AppendLine("{");
-                currentIndent += indent;
+                currentIndent += Indent;
             }
 
             string innerIndent = currentIndent; // indent level for the target (innermost) type
@@ -350,13 +354,8 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                     SymbolDisplayMiscellaneousOptions.EscapeKeywordIdentifiers
                 );
 
-            List<(
-                string Type,
-                string Name,
-                bool IsOptional,
-                string? DefaultExpr
-            )> parameterDetails =
-                new List<(string Type, string Name, bool IsOptional, string? DefaultExpr)>();
+            List<(string Type, string Name, bool IsOptional, string DefaultExpr)> parameterDetails =
+                new List<(string Type, string Name, bool IsOptional, string DefaultExpr)>();
 
             // For validating expressions, use the semantic model for this type's tree
             SemanticModel semanticModel = compilation.GetSemanticModel(
@@ -368,7 +367,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             {
                 string fieldType = field.Type.ToDisplayString(fieldTypeFormat);
                 string fieldName = field.Name;
-                string? defaultExpr = null;
+                string defaultExpr = null;
                 bool isOptional = false;
 
                 foreach (AttributeData attr in field.GetAttributes())
@@ -455,10 +454,10 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                         }
                         else if (arg.Kind == TypedConstantKind.Primitive)
                         {
-                            object? val = arg.Value;
+                            object val = arg.Value;
                             defaultExpr = FormatLiteral(val, arg.Type);
                             // Validate primitive conversion to field type
-                            ITypeSymbol? sourceType = arg.Type;
+                            ITypeSymbol sourceType = arg.Type;
                             if (sourceType != null)
                             {
                                 Conversion conv = compilation.ClassifyConversion(
@@ -489,12 +488,12 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 }
 
                 parameterDetails.Add((fieldType, fieldName, isOptional, defaultExpr));
-                constructorBody.AppendLine($"{indent}{indent}    this.{fieldName} = {fieldName};");
+                constructorBody.AppendLine($"{Indent}{Indent}    this.{fieldName} = {fieldName};");
             }
 
             for (int i = 0; i < parameterDetails.Count; i++)
             {
-                (string Type, string Name, bool IsOptional, string? DefaultExpr) p =
+                (string Type, string Name, bool IsOptional, string DefaultExpr) p =
                     parameterDetails[i];
                 constructorParams.Append($"{p.Type} {p.Name}");
                 if (p.IsOptional)
@@ -520,7 +519,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             {
                 currentIndent = currentIndent.Substring(
                     0,
-                    Math.Max(0, currentIndent.Length - indent.Length)
+                    Math.Max(0, currentIndent.Length - Indent.Length)
                 );
                 containersClose.Append(currentIndent).AppendLine("}");
             }
@@ -533,9 +532,9 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 {{namespaceBlockOpen}}
                 {{containersOpen}}{{innerIndent}}{{typeAccessibility}} partial {{typeKind}} {{typeName}}
                 {{innerIndent}}{
-                {{indent}}    /// <summary>
-                {{indent}}    /// Auto-generated constructor by DxAutoGenConstructorGenerator.
-                {{indent}}    /// </summary>
+                {{Indent}}    /// <summary>
+                {{Indent}}    /// Auto-generated constructor by DxAutoGenConstructorGenerator.
+                {{Indent}}    /// </summary>
                 {{innerIndent}}    {{constructorAccessibility}} {{typeSymbol.Name}}({{constructorParams}})
                 {{innerIndent}}    {
                 {{constructorBody}}
@@ -546,7 +545,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 """;
         }
 
-        private static string FormatLiteral(object? value, ITypeSymbol? type)
+        private static string FormatLiteral(object value, ITypeSymbol type)
         {
             if (value == null)
             {
@@ -635,7 +634,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                     SpeculativeBindingOption.BindAsExpression
                 );
 
-                ITypeSymbol? sourceType = typeInfo.Type;
+                ITypeSymbol sourceType = typeInfo.Type;
                 if (sourceType == null)
                 {
                     // Could not bind; let the compiler decide but report as invalid here
@@ -655,7 +654,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
         private static List<INamedTypeSymbol> GetNonPartialContainers(INamedTypeSymbol typeSymbol)
         {
             List<INamedTypeSymbol> result = new();
-            INamedTypeSymbol? current = typeSymbol.ContainingType;
+            INamedTypeSymbol current = typeSymbol.ContainingType;
             while (current is not null)
             {
                 if (!IsDeclaredFullyPartial(current))

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators/DxMessageIdGenerator.cs

@@ -66,9 +66,14 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
         private record struct MessageToGenerateInfo(
             INamedTypeSymbol TypeSymbol,
             TypeDeclarationSyntax DeclarationSyntax,
-            string TargetInterfaceFullName // The specific interface like IBroadcastMessage
+            string TargetInterfaceFullName,
+            bool HasConflictingMessageAttributes
         );
 
+        /// <summary>
+        /// Configures the incremental generator pipeline that assigns deterministic message identifiers.
+        /// </summary>
+        /// <param name="context">Initialization context provided by Roslyn.</param>
         public void Initialize(IncrementalGeneratorInitializationContext context)
         {
             // Find all class/struct/record declarations with attributes
@@ -143,15 +148,15 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 return null; // Cannot be a concrete message type
             }
 
-            string? foundTargetInterface = null;
+            string foundTargetInterface = null;
             bool multipleAttributes = false;
 
             // Check attributes to find the specific message type (Broadcast, Targeted, etc.)
             foreach (AttributeData attributeData in typeSymbol.GetAttributes())
             {
                 cancellationToken.ThrowIfCancellationRequested();
-                string? currentAttributeFullName = attributeData.AttributeClass?.ToDisplayString();
-                string? targetInterfaceForThisAttribute = null;
+                string currentAttributeFullName = attributeData.AttributeClass?.ToDisplayString();
+                string targetInterfaceForThisAttribute = null;
 
                 switch (currentAttributeFullName)
                 {
@@ -180,17 +185,21 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 }
             }
 
-            if (multipleAttributes || foundTargetInterface == null)
+            if (multipleAttributes)
+            {
+                foundTargetInterface = null;
+            }
+
+            if (foundTargetInterface == null && !multipleAttributes)
             {
-                // Don't return info if multiple different message attrs or none found.
-                // The Execute method will report the error for multiple attributes later.
                 return null;
             }
 
             return new MessageToGenerateInfo(
                 typeSymbol,
                 typeDeclarationSyntax,
-                foundTargetInterface
+                foundTargetInterface,
+                multipleAttributes
             );
         }
 
@@ -206,18 +215,19 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             }
 
             // --- Step 1: Filter out types with multiple attributes applied ---
-            Dictionary<ISymbol, MessageToGenerateInfo> uniqueTypes = new(
+            Dictionary<ISymbol, MessageToGenerateInfo> uniqueTypes = new Dictionary<
+                ISymbol,
+                MessageToGenerateInfo
+            >(SymbolEqualityComparer.Default);
+            HashSet<ISymbol> conflictingTypes = new HashSet<ISymbol>(
                 SymbolEqualityComparer.Default
             );
-            HashSet<ISymbol> typesWithMultipleAttributes = new(SymbolEqualityComparer.Default);
 
             foreach (MessageToGenerateInfo typeInfo in typesToGenerate)
             {
-                if (uniqueTypes.ContainsKey(typeInfo.TypeSymbol))
+                if (typeInfo.HasConflictingMessageAttributes)
                 {
-                    // If adding fails, it means the same TypeSymbol appeared multiple times.
-                    // This implies multiple different valid attributes were found, report error.
-                    if (typesWithMultipleAttributes.Add(typeInfo.TypeSymbol)) // Report only once
+                    if (conflictingTypes.Add(typeInfo.TypeSymbol))
                     {
                         context.ReportDiagnostic(
                             Diagnostic.Create(
@@ -226,7 +236,44 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                                 typeInfo.TypeSymbol.ToDisplayString()
                             )
                         );
-                        // Also report for the one already in the dictionary if needed, but one report per type is usually sufficient.
+                    }
+
+                    continue;
+                }
+
+                if (conflictingTypes.Contains(typeInfo.TypeSymbol))
+                {
+                    continue;
+                }
+
+                if (typeInfo.TargetInterfaceFullName is null)
+                {
+                    continue;
+                }
+
+                if (
+                    uniqueTypes.TryGetValue(
+                        typeInfo.TypeSymbol,
+                        out MessageToGenerateInfo existingInfo
+                    )
+                )
+                {
+                    if (
+                        !string.Equals(
+                            existingInfo.TargetInterfaceFullName,
+                            typeInfo.TargetInterfaceFullName,
+                            StringComparison.Ordinal
+                        ) && conflictingTypes.Add(typeInfo.TypeSymbol)
+                    )
+                    {
+                        context.ReportDiagnostic(
+                            Diagnostic.Create(
+                                MultipleAttributesError,
+                                typeInfo.DeclarationSyntax.Identifier.GetLocation(),
+                                typeInfo.TypeSymbol.ToDisplayString()
+                            )
+                        );
+                        uniqueTypes.Remove(typeInfo.TypeSymbol);
                     }
                 }
                 else
@@ -235,10 +282,21 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 }
             }
 
-            List<MessageToGenerateInfo> validSingleAttrTypes = uniqueTypes
-                .Where(kvp => !typesWithMultipleAttributes.Contains(kvp.Key))
-                .Select(kvp => kvp.Value)
-                .ToList();
+            if (uniqueTypes.Count == 0)
+            {
+                return;
+            }
+
+            List<MessageToGenerateInfo> validSingleAttrTypes = new List<MessageToGenerateInfo>();
+            foreach (KeyValuePair<ISymbol, MessageToGenerateInfo> entry in uniqueTypes)
+            {
+                if (conflictingTypes.Contains(entry.Key))
+                {
+                    continue;
+                }
+
+                validSingleAttrTypes.Add(entry.Value);
+            }
 
             if (validSingleAttrTypes.Count == 0)
             {
@@ -250,6 +308,12 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             {
                 context.CancellationToken.ThrowIfCancellationRequested();
 
+                string targetInterfaceFullName = messageInfo.TargetInterfaceFullName;
+                if (targetInterfaceFullName is null)
+                {
+                    continue;
+                }
+
                 // If nested, ensure all containers are declared partial; otherwise report diagnostic and skip
                 if (messageInfo.TypeSymbol.ContainingType is not null)
                 {
@@ -276,7 +340,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                         );
                         foreach (INamedTypeSymbol container in nonPartial)
                         {
-                            SyntaxReference? sr =
+                            SyntaxReference sr =
                                 container.DeclaringSyntaxReferences.FirstOrDefault();
                             if (sr != null && sr.GetSyntax() is TypeDeclarationSyntax tds)
                             {
@@ -300,7 +364,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
 
                 // Generate the partial IMessage implementation source
                 string implSource = GenerateImplementationSource(
-                    messageInfo.TargetInterfaceFullName,
+                    targetInterfaceFullName,
                     messageInfo.TypeSymbol
                 );
                 string implHintName =
@@ -327,11 +391,11 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                 ? string.Empty
                 : $"namespace {namespaceName}\n{{";
             string namespaceBlockClose = string.IsNullOrEmpty(namespaceName) ? string.Empty : "}";
-            const string indent = "    ";
+            const string Indent = "    ";
 
             // Build container wrappers so partial can merge nested types correctly
             var containers = new Stack<INamedTypeSymbol>();
-            INamedTypeSymbol? current = typeSymbol.ContainingType;
+            INamedTypeSymbol current = typeSymbol.ContainingType;
             while (current is not null)
             {
                 containers.Push(current);
@@ -340,7 +404,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
 
             var containersOpen = new StringBuilder();
             var containersClose = new StringBuilder();
-            string currentIndent = indent;
+            string currentIndent = Indent;
             foreach (INamedTypeSymbol container in containers)
             {
                 string containerAccessibility = container.DeclaredAccessibility switch
@@ -373,7 +437,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
                     $"{currentIndent}{containerAccessibility} partial {containerKind} {container.Name}{containerTypeParams}"
                 );
                 containersOpen.Append(currentIndent).AppendLine("{");
-                currentIndent += indent;
+                currentIndent += Indent;
             }
 
             string innerIndent = currentIndent;
@@ -415,7 +479,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
             {
                 currentIndent = currentIndent.Substring(
                     0,
-                    Math.Max(0, currentIndent.Length - indent.Length)
+                    Math.Max(0, currentIndent.Length - Indent.Length)
                 );
                 containersClose.Append(currentIndent).AppendLine("}");
             }
@@ -440,7 +504,7 @@ namespace WallstopStudios.DxMessaging.SourceGenerators
         private static List<INamedTypeSymbol> GetNonPartialContainers(INamedTypeSymbol typeSymbol)
         {
             List<INamedTypeSymbol> result = new();
-            INamedTypeSymbol? current = typeSymbol.ContainingType;
+            INamedTypeSymbol current = typeSymbol.ContainingType;
             while (current is not null)
             {
                 if (!IsDeclaredFullyPartial(current))

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators.csproj

@@ -2,6 +2,11 @@
   <PropertyGroup>
     <TargetFramework>netstandard2.0</TargetFramework>
     <LangVersion>latest</LangVersion>
+    <MicrosoftCodeAnalysisVersion>4.2.0</MicrosoftCodeAnalysisVersion>
+    <SystemCollectionsImmutableVersion>5.0.0</SystemCollectionsImmutableVersion>
+    <SystemReflectionMetadataVersion>9.0.0</SystemReflectionMetadataVersion>
+    <SystemRuntimeCompilerServicesUnsafeVersion>6.0.0</SystemRuntimeCompilerServicesUnsafeVersion>
+    <SystemTextEncodingsWebVersion>6.0.0</SystemTextEncodingsWebVersion>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.3">
@@ -29,16 +34,31 @@
       <UnityAssetsEditorWallstopStudiosDir>$([System.IO.Path]::Combine('$(UnityAssetsEditorDir)', 'Wallstop Studios'))</UnityAssetsEditorWallstopStudiosDir>
       <UnityAssetsPluginsEditorWallstopDir>$([System.IO.Path]::Combine('$(UnityAssetsDir)', 'Plugins', 'Editor', 'WallstopStudios.DxMessaging'))</UnityAssetsPluginsEditorWallstopDir>
       <AnalyzerDll>$(TargetPath)</AnalyzerDll>
-      <AnalyzerPdb>$(TargetDir)$(TargetName).pdb</AnalyzerPdb>
     </PropertyGroup>
     <ItemGroup>
       <AnalyzerOutput Include="$(AnalyzerDll)" />
-      <AnalyzerOutput Include="$(AnalyzerPdb)" Condition="Exists('$(AnalyzerPdb)')" />
+      <AnalyzerDependency Include="$(NuGetPackageRoot)microsoft.codeanalysis.common\$(MicrosoftCodeAnalysisVersion)\lib\netstandard2.0\Microsoft.CodeAnalysis.dll" />
+      <AnalyzerDependency Include="$(NuGetPackageRoot)microsoft.codeanalysis.csharp\$(MicrosoftCodeAnalysisVersion)\lib\netstandard2.0\Microsoft.CodeAnalysis.CSharp.dll" />
+      <AnalyzerDependency Include="$(NuGetPackageRoot)system.collections.immutable\$(SystemCollectionsImmutableVersion)\lib\netstandard2.0\System.Collections.Immutable.dll" />
+      <AnalyzerDependency
+        Include="$(NuGetPackageRoot)system.reflection.metadata\$(SystemReflectionMetadataVersion)\lib\net6.0\System.Reflection.Metadata.dll"
+        Condition="Exists('$(NuGetPackageRoot)system.reflection.metadata\$(SystemReflectionMetadataVersion)\lib\net6.0\System.Reflection.Metadata.dll')"
+      />
+      <AnalyzerDependency
+        Include="$(NuGetPackageRoot)system.reflection.metadata\$(SystemReflectionMetadataVersion)\lib\netstandard2.0\System.Reflection.Metadata.dll"
+        Condition="Exists('$(NuGetPackageRoot)system.reflection.metadata\$(SystemReflectionMetadataVersion)\lib\netstandard2.0\System.Reflection.Metadata.dll')"
+      />
+      <AnalyzerDependency Include="$(NuGetPackageRoot)system.runtime.compilerservices.unsafe\$(SystemRuntimeCompilerServicesUnsafeVersion)\lib\netstandard2.0\System.Runtime.CompilerServices.Unsafe.dll" />
+      <AllAnalyzerFiles Include="@(AnalyzerOutput)" />
+      <AllAnalyzerFiles
+        Include="@(AnalyzerDependency)"
+        Condition="Exists('%(AnalyzerDependency.Identity)')"
+      />
     </ItemGroup>
     <!-- Copy into package Editor/Analyzers (used by SetupCscRsp and package consumers) -->
     <MakeDir Directories="$(EditorAnalyzersDir)" Condition="!Exists('$(EditorAnalyzersDir)')" />
     <Copy
-      SourceFiles="@(AnalyzerOutput)"
+      SourceFiles="@(AllAnalyzerFiles)"
       DestinationFolder="$(EditorAnalyzersDir)"
       SkipUnchangedFiles="true"
     />
@@ -49,7 +69,7 @@
       Condition="Exists('$(UnityAssetsDir)') AND !Exists('$(UnityAssetsPluginsEditorWallstopDir)')"
     />
     <Copy
-      SourceFiles="@(AnalyzerOutput)"
+      SourceFiles="@(AllAnalyzerFiles)"
       DestinationFolder="$(UnityAssetsPluginsEditorWallstopDir)"
       SkipUnchangedFiles="true"
       Condition="Exists('$(UnityAssetsPluginsEditorWallstopDir)')"

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators.Tests/DocsSnippetCompilationTests.cs

@@ -0,0 +1,193 @@
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using NUnit.Framework;
+
+namespace WallstopStudios.DxMessaging.SourceGenerators.Tests;
+
+[TestFixture]
+public sealed class DocsSnippetCompilationTests
+{
+    private static readonly HashSet<string> IgnoredSnippetDiagnosticIds = new(
+        StringComparer.OrdinalIgnoreCase
+    )
+    {
+        "CS0106", // modifier not valid in script (partial snippets showing members only)
+        "CS1001", // identifier expected (intentionally elided samples)
+        "CS8803", // top-level statements mixed with declarations (visual guide style snippets)
+    };
+
+    [Test]
+    public void QuickStartStep1Compiles()
+    {
+        string docsRoot = ResolveDocsRoot();
+        string quickStartPath = Path.Combine(docsRoot, "QuickStart.md");
+        Assert.That(File.Exists(quickStartPath), Is.True, $"Unable to locate {quickStartPath}.");
+
+        string snippet = ExtractFirstCodeBlock(quickStartPath, "csharp");
+        Assert.That(!string.IsNullOrWhiteSpace(snippet), Is.True, "QuickStart snippet not found.");
+
+        string source = $"""
+using DxMessaging.Core.Messages;
+using DxMessaging.Core.Attributes;
+using UnityEngine;
+
+{snippet}
+""";
+
+        var diagnostics = GeneratorTestUtilities
+            .CompileSnippet(source)
+            .Where(d => d.Severity == Microsoft.CodeAnalysis.DiagnosticSeverity.Error)
+            .ToArray();
+
+        if (diagnostics.Length > 0)
+        {
+            string message = string.Join(
+                System.Environment.NewLine,
+                diagnostics.Select(d => d.ToString())
+            );
+            Assert.Fail(
+                $"QuickStart snippet failed to compile:{System.Environment.NewLine}{message}"
+            );
+        }
+    }
+
+    [TestCaseSource(nameof(GetDocumentationSnippets))]
+    public void DocumentationSnippetsCompile(string markdownPath, string snippet)
+    {
+        Assert.That(
+            snippet,
+            Is.Not.Empty,
+            $"Snippet extracted from {markdownPath} should not be empty."
+        );
+
+        var diagnostics = GeneratorTestUtilities
+            .ParseSnippet(snippet)
+            .Where(d => d.Severity == Microsoft.CodeAnalysis.DiagnosticSeverity.Error)
+            .ToArray();
+
+        var actionableDiagnostics = diagnostics
+            .Where(d => !IgnoredSnippetDiagnosticIds.Contains(d.Id))
+            .ToArray();
+
+        if (actionableDiagnostics.Length > 0)
+        {
+            string message = string.Join(
+                System.Environment.NewLine,
+                actionableDiagnostics.Select(d => d.ToString())
+            );
+            Assert.Fail(
+                $"Documentation snippet in {markdownPath} failed to compile:{System.Environment.NewLine}{message}"
+            );
+        }
+    }
+
+    private static IEnumerable<TestCaseData> GetDocumentationSnippets()
+    {
+        string docsRoot = ResolveDocsRoot();
+        foreach (
+            string markdownPath in Directory.GetFiles(docsRoot, "*.md", SearchOption.AllDirectories)
+        )
+        {
+            foreach (string snippet in ExtractCodeBlocks(markdownPath, "csharp"))
+            {
+                if (ShouldSkipSnippet(snippet))
+                {
+                    continue;
+                }
+
+                yield return new TestCaseData(markdownPath, snippet).SetName(
+                    $"{Path.GetFileName(markdownPath)} compiles"
+                );
+            }
+        }
+    }
+
+    private static string ExtractFirstCodeBlock(string markdownPath, string infoString)
+    {
+        return ExtractCodeBlocks(markdownPath, infoString).FirstOrDefault() ?? string.Empty;
+    }
+
+    private static IEnumerable<string> ExtractCodeBlocks(string markdownPath, string infoString)
+    {
+        string[] lines = File.ReadAllLines(markdownPath);
+        bool inBlock = false;
+        System.Text.StringBuilder builder = new();
+        foreach (string rawLine in lines)
+        {
+            string line = rawLine.TrimEnd();
+            if (!inBlock)
+            {
+                if (line.StartsWith("```") && line.Length > 3 && line[3..].StartsWith(infoString))
+                {
+                    inBlock = true;
+                    builder.Clear();
+                }
+                continue;
+            }
+
+            if (line.StartsWith("```"))
+            {
+                inBlock = false;
+                string snippet = builder.ToString();
+                if (!string.IsNullOrWhiteSpace(snippet))
+                {
+                    yield return snippet;
+                }
+                continue;
+            }
+
+            builder.AppendLine(rawLine);
+        }
+    }
+
+    private static string ResolveDocsRoot()
+    {
+        string currentDirectoryPath = TestContext.CurrentContext.TestDirectory;
+        while (!string.IsNullOrEmpty(currentDirectoryPath))
+        {
+            string docsDirectory = Path.Combine(currentDirectoryPath, "Docs");
+            string candidate = Path.Combine(docsDirectory, "QuickStart.md");
+            if (File.Exists(candidate))
+            {
+                return docsDirectory;
+            }
+
+            string parentDirectoryPath =
+                Path.GetDirectoryName(currentDirectoryPath) ?? string.Empty;
+            if (string.IsNullOrEmpty(parentDirectoryPath))
+            {
+                break;
+            }
+
+            currentDirectoryPath = parentDirectoryPath;
+        }
+
+        throw new FileNotFoundException(
+            "Unable to locate Docs/QuickStart.md from the current test directory."
+        );
+    }
+
+    private static bool ShouldSkipSnippet(string snippet)
+    {
+        if (string.IsNullOrWhiteSpace(snippet))
+        {
+            return true;
+        }
+
+        if (snippet.Contains("..."))
+        {
+            return true;
+        }
+
+        foreach (char c in snippet)
+        {
+            if (c > 127 && !char.IsWhiteSpace(c))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

package/SourceGenerators/WallstopStudios.DxMessaging.SourceGenerators.Tests/DocsSnippetCompilationTests.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: b2dc5639a6d0fde4ba984d60757ff592
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: