Merge pull request #1791 from vweijsters/fix-1781

SA1633 now accepts leading whitespace (incl. end-of-line)

Author: sharwell

StyleCop.Analyzers/StyleCop.Analyzers.Test/DocumentationRules/SA1633UnitTests.cs

@@ -14,6 +14,20 @@ namespace StyleCop.Analyzers.Test.DocumentationRules
     /// </summary>
     public class SA1633UnitTests : FileHeaderTestBase
     {
+        private const string NoXmlMultiLineHeaderTestSettings = @"
+{
+  ""settings"": {
+    ""documentationRules"": {
+      ""companyName"": ""FooCorp"",
+      ""copyrightText"": ""copyright (c) {companyName}. All rights reserved."",
+      ""xmlHeader"": false
+    }
+  }
+}
+";
+
+        private bool useNoXmlSettings;
+
         /// <summary>
         /// Verifies that the analyzer will report <see cref="FileHeaderAnalyzers.SA1633DescriptorMissing"/> for
         /// projects using XML headers (the default) when the file is completely missing a header.
@@ -241,6 +255,62 @@ namespace Foo
             await this.VerifyCSharpFixAsync(testCode, fixedCode).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Verifies that blank lines before a valid XML header will not produce a diagnostic message.
+        /// This is a regression test for #1781.
+        /// </summary>
+        /// <param name="prefix">The string to add before the header.</param>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Theory]
+        [InlineData("  ")]
+        [InlineData("\t\t")]
+        [InlineData(" \t")]
+        [InlineData("  \r\n\t\r\n")]
+        [InlineData("\r\n")]
+        [InlineData("\r\n\r\n")]
+        public async Task TestValidXmlFileHeaderWithLeadingBlankLinesAsync(string prefix)
+        {
+            var testCode = $@"{prefix}// <copyright file=""Test0.cs"" company=""FooCorp"">
+//   Copyright (c) FooCorp. All rights reserved.
+// </copyright>
+";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Verifies that blank lines before a valid header will not produce a diagnostic message.
+        /// This is a regression test for #1781.
+        /// </summary>
+        /// <param name="prefix">The string to add before the header.</param>
+        /// <returns>A <see cref="Task"/> representing the asynchronous unit test.</returns>
+        [Theory]
+        [InlineData("  ")]
+        [InlineData("\t\t")]
+        [InlineData(" \t")]
+        [InlineData("  \r\n\t\r\n")]
+        [InlineData("\r\n")]
+        [InlineData("\r\n\r\n")]
+        public async Task TestValidFileHeaderWithLeadingBlankLinesAsync(string prefix)
+        {
+            this.useNoXmlSettings = true;
+            var testCode = $@"{prefix}// copyright (c) FooCorp. All rights reserved.
+";
+
+            await this.VerifyCSharpDiagnosticAsync(testCode, EmptyDiagnosticResults, CancellationToken.None).ConfigureAwait(false);
+        }
+
+        /// <inheritdoc/>
+        protected override string GetSettings()
+        {
+            if (this.useNoXmlSettings)
+            {
+                return NoXmlMultiLineHeaderTestSettings;
+            }
+
+            return base.GetSettings();
+        }
+
         /// <inheritdoc/>
         protected override CodeFixProvider GetCSharpCodeFixProvider()
         {

StyleCop.Analyzers/StyleCop.Analyzers/Helpers/FileHeaderHelpers.cs

@@ -25,8 +25,9 @@ internal static class FileHeaderHelpers
         internal static FileHeader ParseFileHeader(SyntaxNode root)
         {
             var firstToken = root.GetFirstToken(includeZeroWidth: true);
+            var firstNonWhitespaceTrivia = TriviaHelper.IndexOfFirstNonWhitespaceTrivia(firstToken.LeadingTrivia, true);
 
-            if (!firstToken.HasLeadingTrivia)
+            if (firstNonWhitespaceTrivia == -1)
             {
                 return FileHeader.MissingFileHeader;
             }
@@ -37,8 +38,7 @@ internal static FileHeader ParseFileHeader(SyntaxNode root)
             var fileHeaderStart = int.MaxValue;
             var fileHeaderEnd = int.MinValue;
 
-            int i;
-            for (i = 0; !done && (i < firstToken.LeadingTrivia.Count); i++)
+            for (var i = firstNonWhitespaceTrivia; !done && (i < firstToken.LeadingTrivia.Count); i++)
             {
                 var trivia = firstToken.LeadingTrivia[i];
 
@@ -119,7 +119,7 @@ internal static XmlFileHeader ParseXmlFileHeader(SyntaxNode root)
             int fileHeaderStart;
             int fileHeaderEnd;
 
-            var firstNonWhitespaceTrivia = TriviaHelper.IndexOfFirstNonWhitespaceTrivia(firstToken.LeadingTrivia, false);
+            var firstNonWhitespaceTrivia = TriviaHelper.IndexOfFirstNonWhitespaceTrivia(firstToken.LeadingTrivia, true);
             if (firstNonWhitespaceTrivia == -1)
             {
                 return XmlFileHeader.MissingFileHeader;

documentation/SA1633.md

@@ -21,7 +21,11 @@ A C# code file is missing a standard file header.
 
 ## Rule description
 
-A violation of this rule occurs when a C# source file is missing a file header. The file header must begin on the first line of the file, and must be formatted as a block of comments containing Xml, as follows:
+A violation of this rule occurs when a C# source file is missing a file header.
+
+The file header must begin at the start of the file, and it may only be preceded by whitespace.
+
+The file header must be formatted as a block of comments containing either Xml or preconfigured text, as follows:
 
 ```csharp
 //-----------------------------------------------------------------------
@@ -31,6 +35,17 @@ A violation of this rule occurs when a C# source file is missing a file header.
 //-----------------------------------------------------------------------
 ```
 
+or
+
+```csharp
+// 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.
+```
+
+The type of header to use depends on the setting of the `xmlHeader` property. See the [configuration](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/Configuration.md) section for details on how to set this up.
+
+### Examples
+
 For example, a file called Widget.cs from a fictional company called Sprocket Enterprises should contain a file header similar to the following:
 
 ```csharp