Generalize and harden docs exporter

merge

src/Sarif.Driver/Sdk/ExportRulesDocumentationCommandBase.cs

@@ -5,12 +5,14 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
+using System.Text.RegularExpressions;
 
 namespace Microsoft.CodeAnalysis.Sarif.Driver
 {
     public class ExportRulesDocumentationCommandBase<TContext> : PlugInDriverCommand<ExportRulesDocumentationOptions>
     {
         private readonly IFileSystem _fileSystem;
+        private static readonly Regex s_friendlyNameRegex = new Regex(@"(?<level>Error|Warning|Note|None)_(?<friendlyName>[^_]+)$");
 
         public ExportRulesDocumentationCommandBase(IFileSystem fileSystem = null)
         {
@@ -31,7 +33,7 @@ public override int Run(ExportRulesDocumentationOptions options)
                     BuildRule(rule, sb);
                 }
 
-                _fileSystem.WriteAllText(options.OutputFilePath, sb.ToString());
+                _fileSystem.WriteAllText(options.OutputFilePath ?? "Rules.md", sb.ToString());
             }
             catch (Exception ex)
             {
@@ -46,13 +48,20 @@ internal void BuildRule(Skimmer<TContext> rule, StringBuilder sb)
         {
             sb.AppendLine($"## Rule `{rule.Moniker}`{Environment.NewLine}");
             sb.AppendLine($"### Description{Environment.NewLine}");
-            sb.AppendLine($"{rule.FullDescription.Text}{Environment.NewLine}");
+            sb.AppendLine($"{rule.FullDescription.Text ?? rule.ShortDescription.Text ?? "No description available."}{Environment.NewLine}");
             sb.AppendLine($"### Messages{Environment.NewLine}");
 
             foreach (KeyValuePair<string, MultiformatMessageString> message in rule.MessageStrings)
             {
-                sb.AppendLine($"#### `{message.Key.Split('_').Last()}`: {rule.DefaultLevel}{Environment.NewLine}");
-                sb.AppendLine($"{message.Value.Text}{Environment.NewLine}");
+                string ruleName = message.Key;
+                Match match = s_friendlyNameRegex.Match(message.Key);
+                if (match.Success)
+                {
+                    ruleName = match.Groups[2].Value;
+                }
+
+                sb.AppendLine($"#### `{ruleName}`: {rule.DefaultLevel}{Environment.NewLine}");
+                sb.AppendLine($"{(string.IsNullOrEmpty(message.Value.Markdown) ? message.Value.Text : message.Value.Markdown)}{Environment.NewLine}");
             }
 
             sb.AppendLine($"---{Environment.NewLine}");

src/Test.UnitTests.Sarif.Multitool.Library/ExportValidationRulesDocumentationCommandTests.cs

@@ -14,18 +14,27 @@ public class ExportValidationRulesDocumentationCommandTests
         [Fact]
         public void BuildRule_GeneratesExpectedMarkdown()
         {
+            var tests = new Dictionary<string, SarifValidationSkimmerBase>
+            {
+                { "Test1.md", new TestRule1() },
+                { "Test2.md", new TestRule2() },
+                { "Test3.md", new TestRule3() }
+            };
+
             var resourceExtractor = new ResourceExtractor(this.GetType());
-            var sb = new StringBuilder();
-            var testRule = new TestRule();
-            var command = new ExportValidationRulesDocumentationCommand();
-            command.BuildRule(testRule, sb);
+            foreach (KeyValuePair<string, SarifValidationSkimmerBase> test in tests)
+            {
+                var sb = new StringBuilder();
+                var command = new ExportValidationRulesDocumentationCommand();
+                command.BuildRule(test.Value, sb);
 
-            string expectedMarkdown = resourceExtractor.GetResourceText("Test.md");
+                string expectedMarkdown = resourceExtractor.GetResourceText(test.Key);
 
-            sb.ToString().Should().Be(expectedMarkdown);
+                sb.ToString().Should().Be(expectedMarkdown);
+            }            
         }
 
-        private class TestRule : SarifValidationSkimmerBase
+        private class TestRule1 : SarifValidationSkimmerBase
         {
             public override string Id => "TEST0001";
             public override string Name => "TEST";
@@ -36,5 +45,31 @@ private class TestRule : SarifValidationSkimmerBase
                 { "TEST0001_TEST_Note_Default", new MultiformatMessageString{ Text="default text"} }
             };
         }
+
+        private class TestRule2 : SarifValidationSkimmerBase
+        {
+            public override string Id => "TEST0002";
+            public override string Name => "TEST2";
+            public override FailureLevel DefaultLevel => FailureLevel.Note;
+            public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = null };
+            public override MultiformatMessageString ShortDescription => new MultiformatMessageString { Text = "short description text" };
+            public override IDictionary<string, MultiformatMessageString> MessageStrings => new Dictionary<string, MultiformatMessageString>
+            {
+                { "Default_Note_TEST2_TEST0002", new MultiformatMessageString{ Markdown = "# markdown example" } }
+            };
+        }
+
+        private class TestRule3 : SarifValidationSkimmerBase
+        {
+            public override string Id => "TEST0003";
+            public override string Name => "TEST3";
+            public override FailureLevel DefaultLevel => FailureLevel.Note;
+            public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = null };
+            public override MultiformatMessageString ShortDescription => new MultiformatMessageString { Text = null };
+            public override IDictionary<string, MultiformatMessageString> MessageStrings => new Dictionary<string, MultiformatMessageString>
+            {
+                { "TEST0003_TEST3_Note_Default", new MultiformatMessageString{ Text="default text"} }
+            };
+        }
     }
 }

src/Test.UnitTests.Sarif.Multitool.Library/Test.UnitTests.Sarif.Multitool.Library.csproj

@@ -15,7 +15,9 @@
 
   <ItemGroup>
     <None Remove="TestData\ConvertCommand\SemmleQlSample.csv" />
-    <None Remove="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test.md" />
+    <None Remove="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test1.md" />
+    <None Remove="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test2.md" />
+    <None Remove="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test3.md" />
     <None Remove="TestData\MergeCommand\ExpectedOutputs\NoInputFiles.sarif" />
     <None Remove="TestData\PageCommand\elfie-arriba - Copy.sarif" />
     <None Remove="TestData\PageCommand\elfie-arriba.sarif" />
@@ -25,7 +27,9 @@
 
   <ItemGroup>
     <EmbeddedResource Include="TestData\ConvertCommand\SemmleQlSample.csv" />
-    <EmbeddedResource Include="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test.md" />
+    <EmbeddedResource Include="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test1.md" />
+    <EmbeddedResource Include="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test2.md" />
+    <EmbeddedResource Include="TestData\ExportRuleDocumentationCommand\ExpectedOutputs\Test3.md" />
     <EmbeddedResource Include="TestData\MergeCommand\ExpectedOutputs\NoInputFiles.sarif" />
     <EmbeddedResource Include="TestData\QueryCommand\elfie-arriba.CSCAN0020.sarif" />
     <EmbeddedResource Include="TestData\PageCommand\elfie-arriba.sarif" />

src/Test.UnitTests.Sarif.Multitool.Library/TestData/ExportRuleDocumentationCommand/ExpectedOutputs/Test2.md

@@ -0,0 +1,14 @@
+## Rule `TEST0002.TEST2`
+
+### Description
+
+short description text
+
+### Messages
+
+#### `Default_Note_TEST2_TEST0002`: Note
+
+# markdown example
+
+---
+

src/Test.UnitTests.Sarif.Multitool.Library/TestData/ExportRuleDocumentationCommand/ExpectedOutputs/Test3.md

@@ -0,0 +1,14 @@
+## Rule `TEST0003.TEST3`
+
+### Description
+
+No description available.
+
+### Messages
+
+#### `Default`: Note
+
+default text
+
+---
+