feat: FirstClassErrors Roslyn analyzers (FCE001–FCE016)

.github/workflows/analyzers.yml

@@ -0,0 +1,38 @@
+name: analyzers
+
+on:
+  push:
+    branches:
+      - analyzers
+      - 'claude/**'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-test:
+    name: Build & test analyzers
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Restore
+        run: dotnet restore FirstClassErrors.Analyzers.UnitTests/FirstClassErrors.Analyzers.UnitTests.csproj
+
+      - name: Build
+        run: dotnet build FirstClassErrors.Analyzers.UnitTests/FirstClassErrors.Analyzers.UnitTests.csproj -c Release --no-restore
+
+      - name: Test
+        run: dotnet test FirstClassErrors.Analyzers.UnitTests/FirstClassErrors.Analyzers.UnitTests.csproj -c Release --no-build --logger "console;verbosity=detailed"
+
+      # Dogfood: build the sample with the analyzers wired in. Fails on any Error-severity FCExxx and surfaces
+      # the warnings in the log. Doc generation is off here so this stays a pure analyzer check.
+      - name: Build usage (dogfood analyzers)
+        run: dotnet build FirstClassErrors.Usage/FirstClassErrors.Usage.csproj -c Release -p:GenerateErrorDocumentation=false

FirstClassErrors.Analyzers.UnitTests/AnalyzerTestHarness.cs

@@ -0,0 +1,66 @@
+using System.Collections.Immutable;
+
+using FirstClassErrors;
+
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace FirstClassErrors.Analyzers.UnitTests;
+
+/// <summary>
+///     Minimal in-process harness: compiles a C# snippet against the running runtime plus the FirstClassErrors core,
+///     runs a single analyzer over it, and returns the analyzer diagnostics. Deliberately dependency-free (no
+///     Microsoft.CodeAnalysis.Testing) so it composes cleanly with xUnit v3 and NFluent.
+/// </summary>
+internal static class AnalyzerTestHarness {
+
+    private static readonly ImmutableArray<MetadataReference> BaseReferences = BuildBaseReferences();
+
+    public static async Task<ImmutableArray<Diagnostic>> GetDiagnosticsAsync(
+        DiagnosticAnalyzer  analyzer,
+        string              source,
+        params string[]     enabledDiagnosticIds) {
+
+        SyntaxTree syntaxTree = CSharpSyntaxTree.ParseText(source);
+
+        CSharpCompilationOptions options = new(OutputKind.DynamicallyLinkedLibrary);
+        if (enabledDiagnosticIds.Length > 0) {
+            // Force otherwise opt-in (isEnabledByDefault: false) rules on for the test, as an .editorconfig would.
+            ImmutableDictionary<string, ReportDiagnostic>.Builder specific = ImmutableDictionary.CreateBuilder<string, ReportDiagnostic>();
+            foreach (string id in enabledDiagnosticIds) { specific[id] = ReportDiagnostic.Info; }
+            options = options.WithSpecificDiagnosticOptions(specific.ToImmutable());
+        }
+
+        CSharpCompilation compilation = CSharpCompilation.Create(
+            assemblyName: "FirstClassErrors.Analyzers.TestSnippet",
+            syntaxTrees: new[] { syntaxTree },
+            references: BaseReferences,
+            options: options);
+
+        CompilationWithAnalyzers withAnalyzers = compilation.WithAnalyzers(ImmutableArray.Create(analyzer));
+
+        return await withAnalyzers.GetAnalyzerDiagnosticsAsync();
+    }
+
+    private static ImmutableArray<MetadataReference> BuildBaseReferences() {
+        List<MetadataReference> references = new();
+
+        // Reference the running runtime's assemblies so snippets resolve System types without pinning a ref pack.
+        string trustedAssemblies = AppContext.GetData("TRUSTED_PLATFORM_ASSEMBLIES") as string ?? string.Empty;
+        foreach (string path in trustedAssemblies.Split(Path.PathSeparator)) {
+            if (string.IsNullOrEmpty(path)) { continue; }
+            try {
+                references.Add(MetadataReference.CreateFromFile(path));
+            } catch {
+                // Skip any native or otherwise unloadable entry in the TPA list.
+            }
+        }
+
+        // The FirstClassErrors core, so ErrorCode / DomainError / DescribeError resolve inside the snippet.
+        references.Add(MetadataReference.CreateFromFile(typeof(ErrorCode).Assembly.Location));
+
+        return references.ToImmutableArray();
+    }
+
+}

FirstClassErrors.Analyzers.UnitTests/Fce001DuplicateErrorCodeTests.cs

@@ -0,0 +1,98 @@
+using System.Collections.Immutable;
+using System.Linq;
+
+using FirstClassErrors.Analyzers;
+
+using Microsoft.CodeAnalysis;
+
+using NFluent;
+
+namespace FirstClassErrors.Analyzers.UnitTests;
+
+public class Fce001DuplicateErrorCodeTests {
+
+    [Fact]
+    public async Task Reports_each_site_when_same_code_is_created_twice() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class First {
+                public static readonly ErrorCode A = ErrorCode.Create("DUP");
+            }
+
+            public static class Second {
+                public static readonly ErrorCode B = ErrorCode.Create("DUP");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new DuplicateErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(2);
+        Check.That(diagnostics.All(d => d.Id == "FCE001")).IsTrue();
+    }
+
+    [Fact]
+    public async Task Does_not_report_for_distinct_codes() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                public static readonly ErrorCode A = ErrorCode.Create("ONE");
+                public static readonly ErrorCode B = ErrorCode.Create("TWO");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new DuplicateErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+    [Fact]
+    public async Task Does_not_report_for_a_single_use() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                public static readonly ErrorCode A = ErrorCode.Create("ONLY");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new DuplicateErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+    [Fact]
+    public async Task Ignores_duplicate_empty_codes_which_belong_to_FCE002() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                public static readonly ErrorCode A = ErrorCode.Create("");
+                public static readonly ErrorCode B = ErrorCode.Create("");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new DuplicateErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+    [Fact]
+    public async Task Ignores_non_literal_codes() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                private static string Build() => "DYNAMIC";
+                public static readonly ErrorCode A = ErrorCode.Create(Build());
+                public static readonly ErrorCode B = ErrorCode.Create(Build());
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new DuplicateErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+}

FirstClassErrors.Analyzers.UnitTests/Fce002EmptyErrorCodeTests.cs

@@ -0,0 +1,76 @@
+using System.Collections.Immutable;
+
+using FirstClassErrors.Analyzers;
+
+using Microsoft.CodeAnalysis;
+
+using NFluent;
+
+namespace FirstClassErrors.Analyzers.UnitTests;
+
+public class Fce002EmptyErrorCodeTests {
+
+    [Fact]
+    public async Task Reports_on_empty_string_literal() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Sample {
+                public static readonly ErrorCode Code = ErrorCode.Create("");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new EmptyErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(1);
+        Check.That(diagnostics[0].Id).IsEqualTo("FCE002");
+    }
+
+    [Fact]
+    public async Task Reports_on_whitespace_string_literal() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Sample {
+                public static readonly ErrorCode Code = ErrorCode.Create("   ");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new EmptyErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(1);
+        Check.That(diagnostics[0].Id).IsEqualTo("FCE002");
+    }
+
+    [Fact]
+    public async Task Does_not_report_on_valid_literal() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Sample {
+                public static readonly ErrorCode Code = ErrorCode.Create("VALID_CODE");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new EmptyErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+    [Fact]
+    public async Task Does_not_report_on_non_literal_argument() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Sample {
+                private static string Build() => "DYNAMIC_CODE";
+                public static readonly ErrorCode Code = ErrorCode.Create(Build());
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new EmptyErrorCodeAnalyzer(), source);
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+}

FirstClassErrors.Analyzers.UnitTests/Fce003NonLiteralErrorCodeTests.cs

@@ -0,0 +1,61 @@
+using System.Collections.Immutable;
+
+using FirstClassErrors.Analyzers;
+
+using Microsoft.CodeAnalysis;
+
+using NFluent;
+
+namespace FirstClassErrors.Analyzers.UnitTests;
+
+public class Fce003NonLiteralErrorCodeTests {
+
+    [Fact]
+    public async Task Reports_when_code_is_computed_at_runtime() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                private static string Build() => "DYNAMIC";
+                public static readonly ErrorCode A = ErrorCode.Create(Build());
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new NonLiteralErrorCodeAnalyzer(), source, "FCE003");
+
+        Check.That(diagnostics.Length).IsEqualTo(1);
+        Check.That(diagnostics[0].Id).IsEqualTo("FCE003");
+    }
+
+    [Fact]
+    public async Task Does_not_report_for_a_literal_code() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                public static readonly ErrorCode A = ErrorCode.Create("LITERAL_CODE");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new NonLiteralErrorCodeAnalyzer(), source, "FCE003");
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+    [Fact]
+    public async Task Does_not_report_for_a_constant_reference() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                private const string Value = "CONST_CODE";
+                public static readonly ErrorCode A = ErrorCode.Create(Value);
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new NonLiteralErrorCodeAnalyzer(), source, "FCE003");
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+}

FirstClassErrors.Analyzers.UnitTests/Fce004InvalidErrorCodeFormatTests.cs

@@ -0,0 +1,44 @@
+using System.Collections.Immutable;
+
+using FirstClassErrors.Analyzers;
+
+using Microsoft.CodeAnalysis;
+
+using NFluent;
+
+namespace FirstClassErrors.Analyzers.UnitTests;
+
+public class Fce004InvalidErrorCodeFormatTests {
+
+    [Fact]
+    public async Task Reports_when_code_is_not_upper_snake_case() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                public static readonly ErrorCode A = ErrorCode.Create("moneyTransferInvalid");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new InvalidErrorCodeFormatAnalyzer(), source, "FCE004");
+
+        Check.That(diagnostics.Length).IsEqualTo(1);
+        Check.That(diagnostics[0].Id).IsEqualTo("FCE004");
+    }
+
+    [Fact]
+    public async Task Does_not_report_for_upper_snake_case() {
+        const string source = """
+            using FirstClassErrors;
+
+            public static class Codes {
+                public static readonly ErrorCode A = ErrorCode.Create("MONEY_TRANSFER_INVALID");
+            }
+            """;
+
+        ImmutableArray<Diagnostic> diagnostics = await AnalyzerTestHarness.GetDiagnosticsAsync(new InvalidErrorCodeFormatAnalyzer(), source, "FCE004");
+
+        Check.That(diagnostics.Length).IsEqualTo(0);
+    }
+
+}