Updating export-docs (#2156)

* Updating export-docs command

* fixing order

* fixing new line

* updating release history

* fixing sarif1001 resource name

* merging rules and updating tests

* updating markdown

* updating release history

docs/ValidationRules.md

@@ -146,6 +146,8 @@ If an 'artifactLocation' object has a 'uriBaseId' property, its 'uri' property m
 
 Every URI reference in 'originalUriBaseIds' must resolve to an absolute URI in the manner described in the SARIF specification [3.14.14](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317498).
 
+Finally, a relative reference in 'artifactLocation.uri' must not begin with a slash, because that prevents it from combining properly with the absolute URI specified by a 'uriBaseId'.
+
 ### Messages
 
 #### `UriBaseIdRequiresRelativeUri`: Error
@@ -168,6 +170,10 @@ Every URI reference in 'originalUriBaseIds' must resolve to an absolute URI in t
 
 {0}: The '{1}' element of 'originalUriBaseIds' has a 'uri' property '{2}' that contains a query or a fragment. This is not valid because the purpose of the 'uriBaseId' property is to help resolve a relative reference to an absolute URI by concatenating the relative reference to the absolute base URI. This won't work if the base URI contains a query or a fragment.
 
+#### `RelativeReferenceMustNotBeginWithSlash`: Error
+
+The relative reference '{0}' begins with a slash, which will prevent it from combining properly with the absolute URI specified by a 'uriBaseId'.
+
 ---
 
 ## Rule `SARIF1005.UriMustBeAbsolute`

src/ReleaseHistory.md

@@ -2,6 +2,7 @@
 
 ## **Unreleased**
 * FEATURE: Multitool SARIF rewrite accepts `remove` parameter[#2160](https://github.com/microsoft/sarif-sdk/pull/2160)
+* BREAKING: Remove command `export-validation-docs` and extend `export-validation-rules` command to export markdown file [#2156](https://github.com/microsoft/sarif-sdk/pull/2156)
 
 ## **v2.3.8** [Sdk](https://www.nuget.org/packages/Sarif.Sdk/2.3.8) | [Driver](https://www.nuget.org/packages/Sarif.Driver/2.3.8) | [Converters](https://www.nuget.org/packages/Sarif.Converters/2.3.8) | [Multitool](https://www.nuget.org/packages/Sarif.Multitool/2.3.8) | [Multitool Library](https://www.nuget.org/packages/Sarif.Multitool.Library/2.3.8)
 * FEATURE: PACKAGE BREAKING: Upgrade from .NET Framework 4.5 to .NET Framework 4.5.2 [#2135](https://github.com/microsoft/sarif-sdk/pull/2135)

src/Sarif.Driver/Sdk/ExportRulesMetadataCommandBase.cs

@@ -6,13 +6,17 @@
 using System.Collections.Immutable;
 using System.IO;
 using System.Text;
+using System.Text.RegularExpressions;
 
 using Newtonsoft.Json;
 
 namespace Microsoft.CodeAnalysis.Sarif.Driver
 {
     public abstract class ExportRulesMetadataCommandBase : PlugInDriverCommand<ExportRulesMetadataOptions>
     {
+        private readonly string[] _levels = new string[] { "Error", "Warning", "Note", "None", "Pass", "NotApplicable" };
+        private static readonly Regex s_friendlyNameRegex = new Regex("(?<level>Error|Warning|Note|None|Pass|NotApplicable)_(?<friendlyName>[^_]+)$", RegexOptions.Compiled | RegexOptions.IgnoreCase);
+
         public override int Run(ExportRulesMetadataOptions exportOptions)
         {
             int result = FAILURE;
@@ -31,14 +35,21 @@ public override int Run(ExportRulesMetadataOptions exportOptions)
                     case (SarifConstants.SarifFileExtension):
                     {
                         format = "SARIF";
-                        OutputSarifRulesMetada(outputFilePath, skimmers);
+                        OutputSarifRulesMetadata(outputFilePath, skimmers);
                         break;
                     }
 
                     case (".xml"):
                     {
                         format = "SonarQube";
-                        OutputSonarQubeRulesMetada(outputFilePath, skimmers);
+                        OutputSonarQubeRulesMetadata(outputFilePath, skimmers);
+                        break;
+                    }
+
+                    case (".md"):
+                    {
+                        format = "Markdown";
+                        OutputMarkdownRulesMetadata(outputFilePath, skimmers);
                         break;
                     }
 
@@ -59,7 +70,7 @@ public override int Run(ExportRulesMetadataOptions exportOptions)
             return result;
         }
 
-        private void OutputSonarQubeRulesMetada(string outputFilePath, ImmutableArray<ReportingDescriptor> skimmers)
+        private void OutputSonarQubeRulesMetadata(string outputFilePath, ImmutableArray<ReportingDescriptor> skimmers)
         {
             const string TAB = "   ";
             var sb = new StringBuilder();
@@ -97,7 +108,7 @@ private void OutputSonarQubeRulesMetada(string outputFilePath, ImmutableArray<Re
             File.WriteAllText(outputFilePath, sb.ToString());
         }
 
-        private void OutputSarifRulesMetada(string outputFilePath, ImmutableArray<ReportingDescriptor> skimmers)
+        private void OutputSarifRulesMetadata(string outputFilePath, ImmutableArray<ReportingDescriptor> skimmers)
         {
             var log = new SarifLog();
 
@@ -136,6 +147,19 @@ private void OutputSarifRulesMetada(string outputFilePath, ImmutableArray<Report
             File.WriteAllText(outputFilePath, JsonConvert.SerializeObject(log, settings));
         }
 
+        private void OutputMarkdownRulesMetadata(string outputFilePath, ImmutableArray<ReportingDescriptor> skimmers)
+        {
+            var sb = new StringBuilder();
+            sb.Append("# Rules").AppendLine(Environment.NewLine);
+
+            foreach (ReportingDescriptor rule in skimmers)
+            {
+                BuildRule(rule, sb);
+            }
+
+            File.WriteAllText(outputFilePath, sb.ToString());
+        }
+
         private int GetIdIntegerSuffix(string id)
         {
             int alphaCount = 0;
@@ -151,5 +175,43 @@ private int GetIdIntegerSuffix(string id)
             }
             return int.Parse(id.Substring(alphaCount));
         }
+
+        internal void BuildRule(ReportingDescriptor rule, StringBuilder sb)
+        {
+            sb.Append("## Rule `").Append(rule.Moniker).Append('`').AppendLine(Environment.NewLine);
+            sb.Append("### Description").AppendLine(Environment.NewLine);
+            sb.Append(rule.FullDescription?.Markdown
+                ?? rule.FullDescription?.Text
+                ?? rule.ShortDescription?.Markdown
+                ?? rule.ShortDescription?.Text
+                ?? DriverResources.NoRuleDescription).AppendLine(Environment.NewLine);
+            sb.Append("### Messages").AppendLine(Environment.NewLine);
+
+            foreach (KeyValuePair<string, MultiformatMessageString> message in rule.MessageStrings)
+            {
+                string ruleName = message.Key;
+                string ruleLevel;
+                Match match = s_friendlyNameRegex.Match(message.Key);
+                if (match.Success)
+                {
+                    ruleName = match.Groups["friendlyName"].Value;
+                    ruleLevel = match.Groups["level"].Value;
+                }
+                else
+                {
+                    ruleLevel = GetLevelFromRuleName(ruleName);
+                }
+
+                sb.Append("#### `").Append(ruleName).Append("`: ").Append(ruleLevel).AppendLine(Environment.NewLine);
+                sb.Append(message.Value.Markdown ?? message.Value.Text).AppendLine(Environment.NewLine);
+            }
+
+            sb.Append("---").AppendLine(Environment.NewLine);
+        }
+
+        private string GetLevelFromRuleName(string ruleName)
+        {
+            return Array.Find(_levels, level => ruleName.IndexOf(level, StringComparison.OrdinalIgnoreCase) >= 0);
+        }
     }
 }

src/Sarif.Driver/Sdk/ExportRulesMetadataOptions.cs

@@ -8,7 +8,10 @@ namespace Microsoft.CodeAnalysis.Sarif.Driver
     [Verb("export-rules", HelpText = "Export rules metadata to a SARIF or SonarQube XML file.")]
     public class ExportRulesMetadataOptions
     {
-        [Value(0, HelpText = "Output path for exported analysis options. Use a .json or .sarif extension to produce SARIF. Use .xml to produce a SonarQube rule descriptor file.", Required = true)]
+        [Value(0, HelpText = "Output path for exported analysis options.\r\n" +
+            "Use a .json or .sarif extension to produce SARIF.\r\n" +
+            "Use .xml to produce a SonarQube rule descriptor file.\r\n" +
+            "Use .md to produce a markdow rule descriptor file.", Required = true)]
         public string OutputFilePath { get; set; }
     }
 }

src/Sarif.Multitool.Library/Rules/RuleResources.resx

@@ -117,7 +117,7 @@
   <resheader name="writer">
     <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
   </resheader>
-  <data name="SARIF1001_RuleIdentifiersMustBeValid_Error_Default_Text" xml:space="preserve">
+  <data name="SARIF1001_RuleIdentifiersMustBeValid_Warning_Default_Text" xml:space="preserve">
     <value>{0}: The rule '{1}' has a 'name' property that is identical to its 'id' property. The required 'id' property must be a "stable, opaque identifier" (the SARIF specification ([3.49.3](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317839)) explains the reasons for this). The optional 'name' property ([3.49.7](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317843)) is an identifer that is understandable to an end user. Therefore if both 'id' and 'name' are present, they must be different. If they are identical, the tool must omit the 'name' property.</value>
   </data>
   <data name="SARIF1001_RuleIdentifiersMustBeValid_FullDescription_Text" xml:space="preserve">

src/Sarif.Multitool.Library/Rules/SARIF1001.RuleIdentifiersMustBeValid.cs

@@ -28,7 +28,7 @@ public class RuleIdentifiersMustBeValid : SarifValidationSkimmerBase
         public override MultiformatMessageString FullDescription => new MultiformatMessageString { Text = RuleResources.SARIF1001_RuleIdentifiersMustBeValid_FullDescription_Text };
 
         protected override IEnumerable<string> MessageResourceNames => new string[] {
-            nameof(RuleResources.SARIF1001_RuleIdentifiersMustBeValid_Error_Default_Text)
+            nameof(RuleResources.SARIF1001_RuleIdentifiersMustBeValid_Warning_Default_Text)
         };
 
         public override FailureLevel DefaultLevel => FailureLevel.Warning;
@@ -49,7 +49,7 @@ protected override void Analyze(ReportingDescriptor reportingDescriptor, string
                 // omit the 'name' property.
                 LogResult(
                     reportingDescriptorPointer,
-                    nameof(RuleResources.SARIF1001_RuleIdentifiersMustBeValid_Error_Default_Text),
+                    nameof(RuleResources.SARIF1001_RuleIdentifiersMustBeValid_Warning_Default_Text),
                     reportingDescriptor.Id);
             }
         }