Implement SA0002 (InvalidSettingsFile)

Fixes #2029

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers/Settings/DeserializationFailureBehavior.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Tunnel Vision Laboratories, LLC. All Rights Reserved.
+// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
+
+namespace StyleCop.Analyzers
+{
+    using Newtonsoft.Json;
+    using StyleCop.Analyzers.Settings.ObjectModel;
+
+    /// <summary>
+    /// Defines the behavior of various <see cref="SettingsHelper"/> methods in the event of a deserialization error.
+    /// </summary>
+    internal enum DeserializationFailureBehavior
+    {
+        /// <summary>
+        /// When deserialization fails, return a default <see cref="StyleCopSettings"/> instance.
+        /// </summary>
+        ReturnDefaultSettings,
+
+        /// <summary>
+        /// When deserialization fails, throw a <see cref="JsonException"/> containing details about the error.
+        /// </summary>
+        ThrowException
+    }
+}

StyleCop.Analyzers/StyleCop.Analyzers/Settings/SettingsHelper.cs

@@ -41,6 +41,10 @@ static SettingsHelper()
         /// <summary>
         /// Gets the StyleCop settings.
         /// </summary>
+        /// <remarks>
+        /// <para>If a <see cref="JsonException"/> occurs while deserializing the settings file, a default settings
+        /// instance is returned.</para>
+        /// </remarks>
         /// <param name="context">The context that will be used to determine the StyleCop settings.</param>
         /// <param name="cancellationToken">The cancellation token that the operation will observe.</param>
         /// <returns>A <see cref="StyleCopSettings"/> instance that represents the StyleCop settings for the given context.</returns>
@@ -52,15 +56,32 @@ internal static StyleCopSettings GetStyleCopSettings(this SyntaxTreeAnalysisCont
         /// <summary>
         /// Gets the StyleCop settings.
         /// </summary>
+        /// <remarks>
+        /// <para>If a <see cref="JsonException"/> occurs while deserializing the settings file, a default settings
+        /// instance is returned.</para>
+        /// </remarks>
         /// <param name="options">The analyzer options that will be used to determine the StyleCop settings.</param>
         /// <param name="cancellationToken">The cancellation token that the operation will observe.</param>
         /// <returns>A <see cref="StyleCopSettings"/> instance that represents the StyleCop settings for the given context.</returns>
         internal static StyleCopSettings GetStyleCopSettings(this AnalyzerOptions options, CancellationToken cancellationToken)
         {
-            return GetStyleCopSettings(options != null ? options.AdditionalFiles : ImmutableArray.Create<AdditionalText>(), cancellationToken);
+            return GetStyleCopSettings(options, DeserializationFailureBehavior.ReturnDefaultSettings, cancellationToken);
         }
 
-        private static StyleCopSettings GetStyleCopSettings(ImmutableArray<AdditionalText> additionalFiles, CancellationToken cancellationToken)
+        /// <summary>
+        /// Gets the StyleCop settings.
+        /// </summary>
+        /// <param name="options">The analyzer options that will be used to determine the StyleCop settings.</param>
+        /// <param name="failureBehavior">The behavior of the method when a <see cref="JsonException"/> occurs while
+        /// deserializing the settings file.</param>
+        /// <param name="cancellationToken">The cancellation token that the operation will observe.</param>
+        /// <returns>A <see cref="StyleCopSettings"/> instance that represents the StyleCop settings for the given context.</returns>
+        internal static StyleCopSettings GetStyleCopSettings(this AnalyzerOptions options, DeserializationFailureBehavior failureBehavior, CancellationToken cancellationToken)
+        {
+            return GetStyleCopSettings(options != null ? options.AdditionalFiles : ImmutableArray.Create<AdditionalText>(), failureBehavior, cancellationToken);
+        }
+
+        private static StyleCopSettings GetStyleCopSettings(ImmutableArray<AdditionalText> additionalFiles, DeserializationFailureBehavior failureBehavior, CancellationToken cancellationToken)
         {
             try
             {
@@ -74,7 +95,7 @@ private static StyleCopSettings GetStyleCopSettings(ImmutableArray<AdditionalTex
                     }
                 }
             }
-            catch (JsonException)
+            catch (JsonException) when (failureBehavior == DeserializationFailureBehavior.ReturnDefaultSettings)
             {
                 // The settings file is invalid -> return the default settings.
             }

StyleCop.Analyzers/StyleCop.Analyzers/SpecialRules/SA0002InvalidSettingsFile.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Tunnel Vision Laboratories, LLC. All Rights Reserved.
+// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
+
+namespace StyleCop.Analyzers.SpecialRules
+{
+    using System;
+    using System.Collections.Immutable;
+    using System.Globalization;
+    using Microsoft.CodeAnalysis;
+    using Microsoft.CodeAnalysis.Diagnostics;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// The <em>stylecop.json</em> settings file could not be loaded due to a deserialization failure.
+    /// </summary>
+    [NoCodeFix("No automatic code fix is possible for general JSON syntax errors.")]
+    [DiagnosticAnalyzer(LanguageNames.CSharp)]
+    internal class SA0002InvalidSettingsFile : DiagnosticAnalyzer
+    {
+        /// <summary>
+        /// The ID for diagnostics produced by the <see cref="SA0002InvalidSettingsFile"/> analyzer.
+        /// </summary>
+        public const string DiagnosticId = "SA0002";
+        private const string HelpLink = "https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA0002.md";
+        private static readonly LocalizableString Title = new LocalizableResourceString(nameof(SpecialResources.SA0002Title), SpecialResources.ResourceManager, typeof(SpecialResources));
+        private static readonly LocalizableString MessageFormat = new LocalizableResourceString(nameof(SpecialResources.SA0002MessageFormat), SpecialResources.ResourceManager, typeof(SpecialResources));
+        private static readonly LocalizableString Description = new LocalizableResourceString(nameof(SpecialResources.SA0002Description), SpecialResources.ResourceManager, typeof(SpecialResources));
+
+        private static readonly DiagnosticDescriptor Descriptor =
+            new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.SpecialRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, Description, HelpLink);
+
+        private static readonly Action<CompilationAnalysisContext> CompilationAction = HandleCompilation;
+
+        /// <inheritdoc/>
+        public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } =
+            ImmutableArray.Create(Descriptor);
+
+        /// <inheritdoc/>
+        public override void Initialize(AnalysisContext context)
+        {
+            context.RegisterCompilationAction(CompilationAction);
+        }
+
+        private static void HandleCompilation(CompilationAnalysisContext context)
+        {
+            try
+            {
+                SettingsHelper.GetStyleCopSettings(context.Options, DeserializationFailureBehavior.ThrowException, context.CancellationToken);
+            }
+            catch (JsonException ex)
+            {
+                string details = ex.ToString();
+                string completeDescription = string.Format(Description.ToString(CultureInfo.CurrentCulture), details);
+
+                var completeDescriptor = new DiagnosticDescriptor(DiagnosticId, Title, MessageFormat, AnalyzerCategory.SpecialRules, DiagnosticSeverity.Warning, AnalyzerConstants.EnabledByDefault, completeDescription, HelpLink);
+                context.ReportDiagnostic(Diagnostic.Create(completeDescriptor, Location.None));
+            }
+        }
+    }
+}

StyleCop.Analyzers/StyleCop.Analyzers/SpecialRules/SpecialResources.Designer.cs

@@ -142,4 +142,15 @@ Note that some situations are not affected by the bug:
   <data name="SA0001Title" xml:space="preserve">
     <value>XML comment analysis disabled</value>
   </data>
+  <data name="SA0002Description" xml:space="preserve">
+    <value>Various errors in the stylecop.json file can prevent the file from being loaded by the analyzers. In this case, the default settings are used instead.
+
+{0}</value>
+  </data>
+  <data name="SA0002MessageFormat" xml:space="preserve">
+    <value>The stylecop.json settings file could not be loaded</value>
+  </data>
+  <data name="SA0002Title" xml:space="preserve">
+    <value>Invalid settings file</value>
+  </data>
 </root>

StyleCop.Analyzers/StyleCop.Analyzers/SpecialRules/SpecialResources.resx

@@ -267,6 +267,7 @@
     <Compile Include="ReadabilityRules\SA1133DoNotCombineAttributes.cs" />
     <Compile Include="ReadabilityRules\SA1134AttributesMustNotShareLine.cs" />
     <Compile Include="ReadabilityRules\SX1101DoNotPrefixLocalMembersWithThis.cs" />
+    <Compile Include="Settings\DeserializationFailureBehavior.cs" />
     <Compile Include="Settings\ObjectModel\DocumentationSettings.cs" />
     <Compile Include="Settings\ObjectModel\EndOfFileHandling.cs" />
     <Compile Include="Settings\ObjectModel\FileNamingConvention.cs" />
@@ -323,6 +324,7 @@
     <Compile Include="SpacingRules\TokenSpacingProperties.cs" />
     <Compile Include="SpecialRules\SA0000Roslyn7446Workaround.cs" />
     <Compile Include="SpecialRules\SA0001XmlCommentAnalysisDisabled.cs" />
+    <Compile Include="SpecialRules\SA0002InvalidSettingsFile.cs" />
     <Compile Include="SpecialRules\SpecialResources.Designer.cs">
       <AutoGen>True</AutoGen>
       <DesignTime>True</DesignTime>

StyleCop.Analyzers/StyleCop.Analyzers/StyleCop.Analyzers.csproj

@@ -39,6 +39,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "documentation", "documentat
 		documentation\KnownChanges.md = documentation\KnownChanges.md
 		documentation\SA0000Roslyn7446Workaround.md = documentation\SA0000Roslyn7446Workaround.md
 		documentation\SA0001.md = documentation\SA0001.md
+		documentation\SA0002.md = documentation\SA0002.md
 		documentation\SA1000.md = documentation\SA1000.md
 		documentation\SA1001.md = documentation\SA1001.md
 		documentation\SA1002.md = documentation\SA1002.md

StyleCopAnalyzers.sln

@@ -0,0 +1,40 @@
+# SA0002
+
+<table>
+<tr>
+  <td>TypeName</td>
+  <td>SA0002InvalidSettingsFile</td>
+</tr>
+<tr>
+  <td>CheckId</td>
+  <td>SA0002</td>
+</tr>
+<tr>
+  <td>Category</td>
+  <td>Special Rules</td>
+</tr>
+</table>
+
+:memo: This rule is new for StyleCop Analyzers, and was not present in StyleCop Classic.
+
+## Cause
+
+The <em>stylecop.json</em> settings file could not be loaded due to a deserialization error.
+
+## Rule description
+
+This rule reports cases where the StyleCop Analyzers settings file could not be loaded. When this occurs, the various
+analyzers automatically fall back to using the default settings, which may not match the user's expectations.
+
+## How to fix violations
+
+To fix a violation of this rule, start by checking the following items:
+
+* Ensure <em>stylecop.json</em> contains valid JSON syntax. The file may be opened in Visual Studio 2015 to check for
+  common errors (they are reported by the IDE in the Errors window).
+* Review the [configuration](Configuration.md) documentation and ensure the contents of <em>stylecop.json</em> contain
+  valid settings.
+
+## How to suppress violations
+
+This warning can only be suppressed by disabling the warning in the **ruleset** file for the project.