Restore and lock the analyzer's Roslyn floor

.github/dependabot.yml

@@ -9,6 +9,14 @@ updates:
     open-pull-requests-limit: 10
     commit-message:
       prefix: "build"
+    ignore:
+      # The analyzer's Roslyn floor (RoslynFloorVersion in Directory.Build.props) is a product decision,
+      # not routine maintenance: bumping Microsoft.CodeAnalysis.* raises the minimum host compiler able to
+      # load the shipped analyzer and breaks it (CS8032) on older SDKs/IDEs. Real enforcement is
+      # RoslynFloorTests plus the floor CI job; this only stops Dependabot re-proposing the bump. A single
+      # nuget config cannot scope the rule to one project, so these also freeze in the analyzer test project.
+      - dependency-name: "Microsoft.CodeAnalysis.CSharp"
+      - dependency-name: "Microsoft.CodeAnalysis.Common"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/analyzers.yml

@@ -43,3 +43,33 @@ jobs:
       # workflow, which builds and tests the whole solution.
       - name: Build usage (dogfood analyzers)
         run: dotnet build FirstClassErrors.Usage/FirstClassErrors.Usage.csproj -c Release
+
+  floor:
+    name: Dogfood analyzers on the Roslyn floor
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup floor .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Build on the floor SDK
+        # tools/floor-check/global.json selects the .NET 8 (Roslyn 4.8) SDK: the repo-root global.json pins
+        # .NET 10 and rollForward: latestFeature never rolls down to a lower major, so building from this
+        # directory is what makes the CLI pick the nested pin. ReportAnalyzer AND detailed verbosity are both
+        # required for Roslyn's per-analyzer table to reach the log (it is silent at default verbosity);
+        # --no-incremental guarantees a real compilation so that table is always produced. The (verbose) log
+        # is echoed only on failure to keep a green run readable.
+        working-directory: tools/floor-check
+        run: dotnet build -c Release --no-incremental -p:ReportAnalyzer=true -v detailed > build.log 2>&1 || { cat build.log; exit 1; }
+
+      - name: Prove the analyzer actually loaded
+        # A never-loaded analyzer would otherwise leave the build green: CS8032 is emitted only when loading
+        # is attempted. The assembly name alone appears in ordinary build lines ("FirstClassErrors.Analyzers ->
+        # ...dll"), so match a FCE analyzer *type* — it exists only in the ReportAnalyzer table, i.e. only if
+        # the analyzer really loaded and ran. This is what keeps the floor check from passing vacuously.
+        working-directory: tools/floor-check
+        run: grep -qE 'FirstClassErrors\.Analyzers\.[A-Za-z]+Analyzer \(FCE[0-9]' build.log

Directory.Build.props

@@ -22,4 +22,15 @@
     <ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
   </PropertyGroup>
 
+  <!--
+    The Roslyn floor for the shipped analyzer. FirstClassErrors.Analyzers is compiled against this version
+    of Microsoft.CodeAnalysis.*, which is the MINIMUM host compiler able to load it once it is packed into
+    FirstClassErrors and delivered to consumers. A higher version makes the analyzer fail to load (CS8032)
+    on older SDKs/IDEs. Kept here as the single source of truth so the analyzer csproj (the pin) and the
+    guarding test (RoslynFloorTests, via AssemblyMetadata) can never diverge. 4.8.0 == VS 2022 17.8 / .NET 8 SDK.
+  -->
+  <PropertyGroup>
+    <RoslynFloorVersion>4.8.0</RoslynFloorVersion>
+  </PropertyGroup>
+
 </Project>

FirstClassErrors.Analyzers.UnitTests/RoslynFloorTests.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Linq;
+using System.Reflection;
+
+using NFluent;
+
+namespace FirstClassErrors.Analyzers.UnitTests;
+
+/// <summary>
+///     Enforces the analyzer's Roslyn load contract. The analyzer ships inside the FirstClassErrors package
+///     and is loaded by each consumer's host compiler, so the Microsoft.CodeAnalysis version it is compiled
+///     against is the minimum Roslyn able to load it; a higher one makes it fail to load (CS8032) on older
+///     SDKs/IDEs. The floor is defined once in Directory.Build.props and surfaced here through assembly
+///     metadata, so the csproj pin and this test can never diverge.
+/// </summary>
+public sealed class RoslynFloorTests {
+
+    [Fact]
+    public void Analyzer_stays_on_the_supported_Roslyn_floor() {
+        Assembly analyzerAssembly = typeof(DuplicateErrorCodeAnalyzer).Assembly;
+        Version  floor            = ReadFloor(analyzerAssembly);
+
+        // The analyzers use only the language-agnostic API (IOperation), so the compiler emits a reference
+        // to Microsoft.CodeAnalysis but not necessarily to Microsoft.CodeAnalysis.CSharp — only *used*
+        // references are recorded. Bound the whole family rather than one assembly name.
+        AssemblyName[] roslynReferences = analyzerAssembly
+           .GetReferencedAssemblies()
+           .Where(reference => reference.Name is not null
+                            && reference.Name.StartsWith("Microsoft.CodeAnalysis", StringComparison.Ordinal))
+           .ToArray();
+
+        // If the family ever disappears from the metadata this test proves nothing: fail loudly rather
+        // than pass vacuously.
+        Check.That(roslynReferences).Not.IsEmpty();
+
+        string[] offenders = roslynReferences
+           .Where(reference => OnMajorMinorBuild(reference.Version) > floor)
+           .Select(reference => $"{reference.Name} {reference.Version}")
+           .ToArray();
+
+        Check.That(offenders).IsEmpty();
+    }
+
+    private static Version ReadFloor(Assembly analyzerAssembly) {
+        AssemblyMetadataAttribute floor = analyzerAssembly
+           .GetCustomAttributes<AssemblyMetadataAttribute>()
+           .Single(metadata => metadata.Key == "RoslynFloorVersion");
+
+        return OnMajorMinorBuild(Version.Parse(floor.Value!));
+    }
+
+    // Roslyn assemblies carry a four-part version (x.y.z.0) while the floor is written as x.y.z; comparing on
+    // major.minor.build only keeps a raw 4.8.0.0 from reading as newer than the 4.8.0 floor.
+    private static Version OnMajorMinorBuild(Version? version) =>
+        new(version?.Major ?? 0, version?.Minor ?? 0, version is { Build: >= 0 } ? version.Build : 0);
+}

FirstClassErrors.Analyzers/FirstClassErrors.Analyzers.csproj

@@ -16,13 +16,24 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <!-- Pinned to a low floor so the shipped analyzer loads in older SDKs too. Not flowed to consumers. -->
-    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="5.6.0" PrivateAssets="all" />
+    <!-- LOAD CONTRACT — do not bump. Microsoft.CodeAnalysis.CSharp is pinned to $(RoslynFloorVersion), the
+         minimum Roslyn (host compiler) able to load the shipped analyzer: it is packed inside FirstClassErrors
+         and loaded by each consumer's compiler, so a higher version makes it silently fail to load (CS8032)
+         on older SDKs/IDEs. The floor lives once in Directory.Build.props and is enforced by RoslynFloorTests.
+         Microsoft.CodeAnalysis.Analyzers is only a build-time authoring analyzer (PrivateAssets=all), not part
+         of the load contract, so it is free to move. -->
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="$(RoslynFloorVersion)" PrivateAssets="all" />
     <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="5.6.0" PrivateAssets="all">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
 
+  <ItemGroup>
+    <!-- Surface the floor to RoslynFloorTests as assembly metadata so the test asserts against the same
+         single value defined in Directory.Build.props, never a second hard-coded copy. -->
+    <AssemblyMetadata Include="RoslynFloorVersion" Value="$(RoslynFloorVersion)" />
+  </ItemGroup>
+
   <ItemGroup>
     <!-- Release tracking (RS2008): declared rules live here, verified at build time. -->
     <AdditionalFiles Include="AnalyzerReleases.Shipped.md" />

README.md

@@ -197,6 +197,8 @@ FirstClassErrors is especially useful if:
 
 FirstClassErrors ships with a set of Roslyn analyzers (rule ids `FCExxx`) **bundled in the NuGet package** — reference the package and they run at build time, no extra install. They catch, before you run anything, the mistakes the runtime or the documentation pipeline would otherwise surface late or silently: duplicate error codes, `[DocumentedBy]` references that don't resolve, documented errors that never reach the catalog, and more.
 
+> **Compiler requirement:** the bundled analyzers are compiled against Roslyn 4.8, so they load in any host from **.NET 8 SDK / Visual Studio 2022 17.8** onward. Older SDKs/IDEs cannot load them.
+
 See the [analyzer rules reference](doc/analyzers/README.md).
 
 ## 📚 Next steps

doc/README.fr.md

@@ -197,6 +197,8 @@ FirstClassErrors est particulièrement utile si :
 
 FirstClassErrors est livré avec un ensemble d’analyseurs Roslyn (identifiants de règle `FCExxx`) **inclus dans le package NuGet** — référencez le package et ils s’exécutent au build, sans installation supplémentaire. Ils détectent, avant toute exécution, les erreurs que le runtime ou le pipeline de documentation ne feraient sinon apparaître que tard, voire silencieusement : codes d’erreur dupliqués, références `[DocumentedBy]` qui ne résolvent pas, erreurs documentées qui n’atteignent jamais le catalogue, et plus encore.
 
+> **Prérequis compilateur :** les analyseurs inclus sont compilés contre Roslyn 4.8 ; ils se chargent donc dans tout hôte à partir du **SDK .NET 8 / Visual Studio 2022 17.8**. Les SDK/IDE plus anciens ne peuvent pas les charger.
+
 Voir la [référence des règles d’analyse](analyzers/README.fr.md).
 
 ## 📚 Étapes suivantes

tools/floor-check/FloorCheck.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- Floor-SDK dogfood consumer. Deliberately NOT part of FirstClassErrors.sln: ci.yml would build it
+       under the .NET 10 SDK, which proves nothing and only causes confusion. It is built solely by the
+       "floor" job in .github/workflows/analyzers.yml, whose nested tools/floor-check/global.json selects
+       the .NET 8 (Roslyn 4.8) SDK. It recompiles the real Usage sources with the analyzer wired in, so if
+       FirstClassErrors.Analyzers ever references a newer Roslyn the analyzer fails to load on the floor
+       host (CS8032) and this build turns red. -->
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <!-- An analyzer that fails to load (CS8032) or throws while loading (AD0001) must break the build,
+         not merely warn. That failure is the entire signal this project exists to produce. -->
+    <WarningsAsErrors>$(WarningsAsErrors);CS8032;AD0001</WarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Reuse the dogfood sample's sources verbatim (no duplication); skip its own build output. -->
+    <Compile Include="../../FirstClassErrors.Usage/**/*.cs"
+             Exclude="../../FirstClassErrors.Usage/obj/**/*.cs;../../FirstClassErrors.Usage/bin/**/*.cs" />
+    <ProjectReference Include="../../FirstClassErrors/FirstClassErrors.csproj" />
+    <ProjectReference Include="../../FirstClassErrors.Analyzers/FirstClassErrors.Analyzers.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false" />
+  </ItemGroup>
+
+</Project>

tools/floor-check/global.json

@@ -0,0 +1,6 @@
+{
+  "sdk": {
+    "version": "8.0.100",
+    "rollForward": "latestFeature"
+  }
+}