Resolve the open SonarCloud issues across the codebase

.github/workflows/scorecard.yml

@@ -21,8 +21,10 @@ concurrency:
   group: scorecard-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-# Read-only by default; the single job widens only the two write scopes it needs.
-permissions: read-all
+# Minimal read at the workflow level; the single job overrides with only the two write scopes it
+# needs. Enumerated rather than `read-all` so the default token grants exactly one explicit scope.
+permissions:
+  contents: read
 
 jobs:
   analysis:

.github/workflows/sonar.yml

@@ -66,6 +66,9 @@ jobs:
 
       # The build must sit between `begin` and `end`: the scanner hooks MSBuild to
       # observe the compilation, so it cannot use a pre-built or --no-build output.
+      # *.verified.* are Verify snapshot oracles — generated test fixtures, not production source. Excluding them
+      # keeps Sonar from analysing the emitted HTML/JS/Markdown as if it were hand-written code (and from counting
+      # the near-identical snapshots as duplication).
       - name: Begin analysis
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
@@ -76,6 +79,7 @@ jobs:
           /d:sonar.token="$SONAR_TOKEN"
           /d:sonar.host.url="https://sonarcloud.io"
           /d:sonar.cs.opencover.reportsPaths="artifacts/coverage/**/coverage.opencover.xml"
+          /d:sonar.exclusions="**/*.verified.*"
 
       - name: Build
         # Disable the CI warning ratchet (Directory.Build.props) for the analysis build only. The scanner

Directory.Packages.props

@@ -24,6 +24,7 @@
   -->
 
   <ItemGroup>
+    <PackageVersion Include="AngleSharp" Version="1.5.2" />
     <PackageVersion Include="coverlet.collector" Version="10.0.1" />
     <PackageVersion Include="FsCheck" Version="3.3.3" />
     <PackageVersion Include="JetBrains.Annotations" Version="2026.2.0" />

FirstClassErrors.Analyzers/Descriptors.cs

@@ -17,7 +17,7 @@ internal static class Descriptors {
         isEnabledByDefault: true,
         description: "An ErrorCode is compared by value, so the same literal code created more than once yields equal instances that documentation extraction and lookups collapse into a single identity. Detection is per-compilation and limited to literal codes.",
         helpLinkUri: HelpLinks.For(DiagnosticIds.DuplicateErrorCode),
-        customTags: new[] { WellKnownDiagnosticTags.CompilationEnd });
+        WellKnownDiagnosticTags.CompilationEnd);
 
     public static readonly DiagnosticDescriptor EmptyErrorCode = new(
         id: DiagnosticIds.EmptyErrorCode,
@@ -138,7 +138,7 @@ internal static class Descriptors {
         isEnabledByDefault: true,
         description: "Documentation extraction groups by error code and keeps a single entry per code. Two documented factories that share the same code field silently collapse to one in the catalog.",
         helpLinkUri: HelpLinks.For(DiagnosticIds.DuplicateDocumentedCode),
-        customTags: new[] { WellKnownDiagnosticTags.CompilationEnd });
+        WellKnownDiagnosticTags.CompilationEnd);
 
     public static readonly DiagnosticDescriptor ExampleDoesNotCallDocumentedFactory = new(
         id: DiagnosticIds.ExampleDoesNotCallDocumentedFactory,

FirstClassErrors.Analyzers/DuplicateDocumentedCodeAnalyzer.cs

@@ -47,21 +47,35 @@ private static void Collect(
         if (context.OwningSymbol is not IMethodSymbol method) { return; }
         if (!SymbolFacts.HasAttribute(method, symbols.DocumentedByAttribute!)) { return; }
 
-        foreach (IOperation block in context.OperationBlocks) {
-            foreach (IOperation operation in OperationFacts.EnumerateOperations(block)) {
-                if (operation is not IInvocationOperation invocation) { continue; }
-                if (invocation.TargetMethod.Name != CreateMethodName) { continue; }
-                if (!SymbolFacts.IsOrInheritsFrom(invocation.TargetMethod.ContainingType, symbols.Error!)) { continue; }
-                if (invocation.Arguments.Length == 0) { continue; }
+        // The outermost error-factory Create identifies the produced code.
+        IInvocationOperation? create = FindErrorFactoryCreate(context.OperationBlocks, symbols);
+        if (create is null) { return; }
 
-                if (TryGetCodeField(invocation.Arguments[0].Value, out ISymbol? codeField)) {
-                    usagesByCodeField.GetOrAdd(codeField!, _ => new ConcurrentBag<Location>())
-                                     .Add(method.Locations.FirstOrDefault() ?? Location.None);
-                }
+        if (TryGetCodeField(create.Arguments[0].Value, out ISymbol? codeField)) {
+            usagesByCodeField.GetOrAdd(codeField!, _ => new ConcurrentBag<Location>())
+                             .Add(method.Locations.FirstOrDefault() ?? Location.None);
+        }
+    }
 
-                return; // the outermost error-factory Create identifies the produced code
+    /// <summary>Finds the first <c>Error.Create(...)</c> invocation carrying at least one argument, across the blocks.</summary>
+    private static IInvocationOperation? FindErrorFactoryCreate(ImmutableArray<IOperation> blocks, KnownSymbols symbols) {
+        foreach (IOperation block in blocks) {
+            foreach (IOperation operation in OperationFacts.EnumerateOperations(block)) {
+                IInvocationOperation? create = AsErrorFactoryCreate(operation, symbols);
+                if (create is not null) { return create; }
             }
         }
+
+        return null;
+    }
+
+    /// <summary>Returns <paramref name="operation" /> as an <c>Error.Create(...)</c> invocation with arguments, or <c>null</c>.</summary>
+    private static IInvocationOperation? AsErrorFactoryCreate(IOperation operation, KnownSymbols symbols) {
+        if (operation is not IInvocationOperation invocation) { return null; }
+        if (invocation.TargetMethod.Name != CreateMethodName) { return null; }
+        if (!SymbolFacts.IsOrInheritsFrom(invocation.TargetMethod.ContainingType, symbols.Error!)) { return null; }
+
+        return invocation.Arguments.Length == 0 ? null : invocation;
     }
 
     private static bool TryGetCodeField(IOperation codeArgument, out ISymbol? codeField) {

FirstClassErrors.Analyzers/ExampleDoesNotCallDocumentedFactoryAnalyzer.cs

@@ -46,10 +46,8 @@ private static void Analyze(OperationAnalysisContext context, INamedTypeSymbol e
         INamedTypeSymbol? documentingType = context.ContainingSymbol.ContainingType;
         if (documentingType is null) { return; }
 
-        foreach (IOperation example in GetExampleOperations(invocation)) {
-            if (!ExampleInvokesMemberOf(example, documentingType)) {
-                context.ReportDiagnostic(Diagnostic.Create(Descriptors.ExampleDoesNotCallDocumentedFactory, example.Syntax.GetLocation(), documentingType.Name));
-            }
+        foreach (IOperation example in GetExampleOperations(invocation).Where(example => !ExampleInvokesMemberOf(example, documentingType))) {
+            context.ReportDiagnostic(Diagnostic.Create(Descriptors.ExampleDoesNotCallDocumentedFactory, example.Syntax.GetLocation(), documentingType.Name));
         }
     }
 

FirstClassErrors.Analyzers/SymbolFacts.cs

@@ -17,15 +17,15 @@ public static bool TryGetDocumentedBy(
         out AttributeData? attribute,
         out string?        targetMethodName) {
 
-        foreach (AttributeData candidate in method.GetAttributes()) {
-            if (SymbolEqualityComparer.Default.Equals(candidate.AttributeClass, documentedByAttributeType)) {
-                attribute        = candidate;
-                targetMethodName = candidate.ConstructorArguments.Length == 1
-                    ? candidate.ConstructorArguments[0].Value as string
-                    : null;
-
-                return true;
-            }
+        AttributeData? candidate = method.GetAttributes()
+                                         .FirstOrDefault(a => SymbolEqualityComparer.Default.Equals(a.AttributeClass, documentedByAttributeType));
+        if (candidate is not null) {
+            attribute        = candidate;
+            targetMethodName = candidate.ConstructorArguments.Length == 1
+                ? candidate.ConstructorArguments[0].Value as string
+                : null;
+
+            return true;
         }
 
         attribute        = null;
@@ -35,13 +35,7 @@ public static bool TryGetDocumentedBy(
     }
 
     public static bool HasAttribute(ISymbol symbol, INamedTypeSymbol attributeType) {
-        foreach (AttributeData attribute in symbol.GetAttributes()) {
-            if (SymbolEqualityComparer.Default.Equals(attribute.AttributeClass, attributeType)) {
-                return true;
-            }
-        }
-
-        return false;
+        return symbol.GetAttributes().Any(attribute => SymbolEqualityComparer.Default.Equals(attribute.AttributeClass, attributeType));
     }
 
     public static bool IsOrInheritsFrom(ITypeSymbol type, INamedTypeSymbol target) {

FirstClassErrors.Cli.UnitTests/ConfigurationStoreTests.cs

@@ -0,0 +1,45 @@
+#region Usings declarations
+
+using JetBrains.Annotations;
+
+using NFluent;
+
+#endregion
+
+namespace FirstClassErrors.Cli.UnitTests;
+
+[TestSubject(typeof(ConfigurationStore))]
+public sealed class ConfigurationStoreTests {
+
+    [Fact(DisplayName = "Loading a configuration from a missing file returns an empty configuration.")]
+    public void LoadingAMissingFileReturnsAnEmptyConfiguration() {
+        // Setup: a path guaranteed not to exist.
+        string path = CliTestHelpers.NonExistentConfigPath();
+
+        // Exercise
+        CliConfiguration configuration = ConfigurationStore.Load(path);
+
+        // Verify: a fresh configuration carries none of the persisted defaults.
+        Check.That(configuration.Solution).IsNull();
+        Check.That(configuration.Format).IsNull();
+        Check.That(configuration.NoBuild).IsNull();
+    }
+
+    [Fact(DisplayName = "Loading a configuration from a blank file returns an empty configuration.")]
+    public void LoadingABlankFileReturnsAnEmptyConfiguration() {
+        // Setup: an existing but blank file exercises the whitespace short-circuit rather than the missing-file one.
+        string path = Path.Combine(Path.GetTempPath(), $"fce-blank-config-{Guid.NewGuid():N}.json");
+        File.WriteAllText(path, "   \n");
+
+        try {
+            // Exercise
+            CliConfiguration configuration = ConfigurationStore.Load(path);
+
+            // Verify
+            Check.That(configuration.Solution).IsNull();
+        } finally {
+            File.Delete(path);
+        }
+    }
+
+}

FirstClassErrors.Cli.UnitTests/ConsoleAndFileOutputSinkTests.cs

@@ -0,0 +1,33 @@
+#region Usings declarations
+
+using JetBrains.Annotations;
+
+using NFluent;
+
+#endregion
+
+namespace FirstClassErrors.Cli.UnitTests;
+
+[TestSubject(typeof(ConsoleAndFileOutputSink))]
+public sealed class ConsoleAndFileOutputSinkTests {
+
+    [Fact(DisplayName = "Writing a file into a not-yet-existing nested directory creates the directory and the file.")]
+    public void WritingIntoANestedDirectoryCreatesItAndTheFile() {
+        // Setup: a target whose parent directory does not exist yet, so WriteFile must create it.
+        ConsoleAndFileOutputSink sink     = new();
+        string                   rootDir  = Path.Combine(Path.GetTempPath(), $"fce-sink-{Guid.NewGuid():N}");
+        string                   filePath = Path.Combine(rootDir, "nested", "out.txt");
+
+        try {
+            // Exercise
+            sink.WriteFile(filePath, "content");
+
+            // Verify: the nested directory was created and the content written.
+            Check.That(File.Exists(filePath)).IsTrue();
+            Check.That(File.ReadAllText(filePath)).IsEqualTo("content");
+        } finally {
+            if (Directory.Exists(rootDir)) { Directory.Delete(rootDir, recursive: true); }
+        }
+    }
+
+}

FirstClassErrors.Cli/ConfigShowCommand.cs

@@ -12,7 +12,7 @@ internal sealed class ConfigShowCommand : Command<ConfigScopedSettings> {
     protected override int Execute(CommandContext context, ConfigScopedSettings settings, CancellationToken cancellationToken) {
         string path = ConfigurationStore.Resolve(settings.ConfigPath);
 
-        if (ConfigurationStore.Exists(path) is false) {
+        if (!ConfigurationStore.Exists(path)) {
             Console.Out.WriteLine($"No configuration at '{path}'. Run 'fce config init' to create one.");
 
             return 0;

FirstClassErrors.Cli/ConfigurationStore.cs

@@ -38,7 +38,7 @@ public static bool Exists(string path) {
 
     /// <summary>Loads the configuration, returning an empty one when the file is missing or blank.</summary>
     public static CliConfiguration Load(string path) {
-        if (File.Exists(path) is false) { return new CliConfiguration(); }
+        if (!File.Exists(path)) { return new CliConfiguration(); }
 
         string json = File.ReadAllText(path);
         if (string.IsNullOrWhiteSpace(json)) { return new CliConfiguration(); }
@@ -58,7 +58,7 @@ public static CliConfiguration Load(string path) {
     /// </summary>
     public static void Save(string path, CliConfiguration configuration) {
         string? directory = Path.GetDirectoryName(path);
-        if (string.IsNullOrEmpty(directory) is false) { Directory.CreateDirectory(directory); }
+        if (!string.IsNullOrEmpty(directory)) { Directory.CreateDirectory(directory); }
 
         string json     = JsonSerializer.Serialize(configuration, SerializerOptions);
         string tempPath = path + ".tmp";

FirstClassErrors.Cli/ConsoleAndFileOutputSink.cs

@@ -13,7 +13,7 @@ public void WriteStandardOutput(string content) {
 
     public void WriteFile(string fullPath, string content) {
         string? directory = Path.GetDirectoryName(fullPath);
-        if (string.IsNullOrEmpty(directory) is false) {
+        if (!string.IsNullOrEmpty(directory)) {
             Directory.CreateDirectory(directory);
         }
 

FirstClassErrors.Cli/DocumentationOutputWriter.cs

@@ -36,10 +36,10 @@ public void Write(IReadOnlyList<RenderedDocument> documents, string format, stri
             throw new InvalidOperationException($"The '{format}' renderer produced no documents; a renderer must return at least one document.");
         }
 
-        bool hasOutput = string.IsNullOrWhiteSpace(outputPath) is false;
+        bool hasOutput = !string.IsNullOrWhiteSpace(outputPath);
 
         // No target: only a single document can go to standard output.
-        if (hasOutput is false) {
+        if (!hasOutput) {
             if (documents.Count > 1) {
                 throw new InvalidOperationException("This layout produces several files; specify an output directory with --output (or 'output' in the configuration).");
             }
@@ -54,7 +54,7 @@ public void Write(IReadOnlyList<RenderedDocument> documents, string format, stri
         // Treat the target as a directory when there are several files, when it already exists as one, or when the
         // path ends with a separator. Otherwise a single document is written to the given file path verbatim.
         bool asDirectory = documents.Count > 1 || Directory.Exists(fullOutput) || EndsWithSeparator(outputPath!);
-        if (asDirectory is false) {
+        if (!asDirectory) {
             _sink.WriteFile(fullOutput, documents[0].Content);
             logger.Info($"Documentation written to '{fullOutput}'.");
 
@@ -86,7 +86,7 @@ internal static string ResolveWithinOutput(string outputDirectory, string relati
                           ? outputDirectory
                           : outputDirectory + Path.DirectorySeparatorChar;
 
-        if (target.StartsWith(root, StringComparison.Ordinal) is false) {
+        if (!target.StartsWith(root, StringComparison.Ordinal)) {
             throw new InvalidOperationException(
                 $"The renderer produced a document whose path '{relativePath}' escapes the output directory '{outputDirectory}'.");
         }

FirstClassErrors.Cli/GenerateCommand.cs

@@ -68,7 +68,7 @@ internal int Run(GenerateSettings settings, CancellationToken cancellationToken)
                 return 1;
             }
 
-            if (resolved.HasSolution is false && resolved.HasAssemblies is false) {
+            if (!resolved.HasSolution && !resolved.HasAssemblies) {
                 logger.Error("No source: pass --solution/--assemblies, or set 'solution'/'assemblies' in the configuration.");
 
                 return 1;
@@ -84,7 +84,7 @@ internal int Run(GenerateSettings settings, CancellationToken cancellationToken)
             IReadOnlyList<IErrorDocumentationRenderer> customRenderers = RendererLoader.Load(configuration.Renderers, configDir, logger);
             IErrorDocumentationRenderer                renderer        = RendererCatalog.Create(resolved.Format, customRenderers);
 
-            if (renderer.SupportedLayouts.Contains(resolved.Layout, StringComparer.OrdinalIgnoreCase) is false) {
+            if (!renderer.SupportedLayouts.Contains(resolved.Layout, StringComparer.OrdinalIgnoreCase)) {
                 logger.Error($"The '{resolved.Format}' format does not support the '{resolved.Layout}' layout. Supported layouts: {string.Join(", ", renderer.SupportedLayouts)}.");
 
                 return 1;
@@ -100,7 +100,7 @@ internal int Run(GenerateSettings settings, CancellationToken cancellationToken)
             }
 
             SolutionGenerationOptions options = new() {
-                BuildSolution      = resolved.NoBuild is false,
+                BuildSolution      = !resolved.NoBuild,
                 Configuration      = resolved.BuildConfiguration,
                 TargetFramework    = resolved.Framework,
                 FailureBehavior    = resolved.Strict ? FailureBehavior.Stop : FailureBehavior.Continue,

FirstClassErrors.Cli/GenerateOptionsResolver.cs

@@ -36,7 +36,7 @@ public static ResolvedGenerateOptions Resolve(GenerateSettings settings, CliConf
         // combine with a configured 'solution').
         string?  solution;
         string[] assemblies;
-        if (string.IsNullOrWhiteSpace(settings.SolutionPath) is false || settings.AssemblyPaths.Length > 0) {
+        if (!string.IsNullOrWhiteSpace(settings.SolutionPath) || settings.AssemblyPaths.Length > 0) {
             solution   = settings.SolutionPath;
             assemblies = settings.AssemblyPaths;
         } else {
@@ -47,7 +47,7 @@ public static ResolvedGenerateOptions Resolve(GenerateSettings settings, CliConf
         return new ResolvedGenerateOptions(
             Solution:           solution,
             Assemblies:         assemblies,
-            HasSolution:        string.IsNullOrWhiteSpace(solution) is false,
+            HasSolution:        !string.IsNullOrWhiteSpace(solution),
             HasAssemblies:      assemblies.Length > 0,
             Format:             NormalizeFormat(FirstNonEmpty(settings.Format, configuration.Format) ?? "json"),
             Layout:             (FirstNonEmpty(settings.Layout, configuration.Layout) ?? "single").Trim().ToLowerInvariant(),
@@ -62,8 +62,8 @@ public static ResolvedGenerateOptions Resolve(GenerateSettings settings, CliConf
     }
 
     internal static string? FirstNonEmpty(string? primary, string? fallback) {
-        if (string.IsNullOrWhiteSpace(primary) is false) { return primary; }
-        if (string.IsNullOrWhiteSpace(fallback) is false) { return fallback; }
+        if (!string.IsNullOrWhiteSpace(primary)) { return primary; }
+        if (!string.IsNullOrWhiteSpace(fallback)) { return fallback; }
 
         return null;
     }

FirstClassErrors.Cli/InitCommand.cs

@@ -25,7 +25,7 @@ internal sealed class InitCommand : Command<InitSettings> {
     protected override int Execute(CommandContext context, InitSettings settings, CancellationToken cancellationToken) {
         string path = ConfigurationStore.Resolve(settings.ConfigPath);
 
-        if (ConfigurationStore.Exists(path) && settings.Force is false) {
+        if (ConfigurationStore.Exists(path) && !settings.Force) {
             Console.Error.WriteLine($"error: a configuration already exists at '{path}'. Use --force to overwrite.");
 
             return 1;

FirstClassErrors.Cli/Program.cs

@@ -30,4 +30,4 @@
 
 // Spectre handles argument parsing, validation errors and --help. Runtime failures are handled inside each command
 // so the tool reports them as a terse "error: …" line rather than a stack trace.
-return app.Run(args);
+return await app.RunAsync(args);