Added outcome argument for CLI #1706 (#1707)

docs/CHANGELOG-v3.md

@@ -29,6 +29,9 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 What's changed since pre-release v3.0.0-B0093:
 
+- General improvements:
+  - Added `--outcome` argument for CLI to support filtering output by @bernieWhite.
+    [#1706](https://github.com/microsoft/PSRule/issues/1706)
 - Engineering:
   - Bump xunit to v2.6.3.
     [#1699](https://github.com/microsoft/PSRule/pull/1699)

docs/concepts/cli.md

@@ -8,6 +8,22 @@
 
 Run rule analysis.
 
+### `--outcome`
+
+Allows filtering of results by outcome.
+The supported values are:
+
+- `Pass` - Results that passed.
+- `Fail` - Results that did not pass.
+- `Error` - Results that failed to be evaluted correctly due to an error.
+- `Processed` - All results that were processed.
+  This aggregated outcome includes `Pass`, `Fail`, or `Error` results.
+- `Problem` - Processed results that did not pass.
+  This aggregated outcome includes `Fail`, or `Error` results.
+
+To specify multiple values, specify the parameter multiple times.
+For example: `--outcome Pass --Outcome Fail`.
+
 ## `module add`
 
 Add one or more modules to the lock file.

src/PSRule.Tool/AnalyzerOptions.cs

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+using PSRule.Rules;
+
 namespace PSRule.Tool
 {
     internal sealed class AnalyzerOptions
@@ -13,6 +15,8 @@ internal sealed class AnalyzerOptions
 
         public string Baseline { get; set; }
 
+        public RuleOutcome? Outcome { get; set; }
+
         public string[] InputPath { get; set; }
 
         public bool Verbose { get; set; }

src/PSRule.Tool/ClientBuilder.cs

@@ -2,8 +2,8 @@
 // Licensed under the MIT License.
 
 using System.CommandLine;
-using System.CommandLine.Builder;
 using System.Reflection;
+using PSRule.Rules;
 using PSRule.Tool.Resources;
 
 namespace PSRule.Tool
@@ -25,6 +25,7 @@ internal sealed class ClientBuilder
         private readonly Option<string[]> _InputPath;
         private readonly Option<string[]> _Module;
         private readonly Option<string> _Baseline;
+        private readonly Option<string[]> _Outcome;
 
         private ClientBuilder(RootCommand cmd)
         {
@@ -60,8 +61,15 @@ private ClientBuilder(RootCommand cmd)
                 CmdStrings.Options_Module_Description
             );
             _Baseline = new Option<string>(
-                new string[] { "--baseline" }
+                new string[] { "--baseline" },
+                CmdStrings.Analyze_Baseline_Description
             );
+            _Outcome = new Option<string[]>(
+                new string[] { "--outcome" },
+                description: CmdStrings.Analyze_Outcome_Description
+            ).FromAmong("Pass", "Fail", "Error", "Processed", "Problem");
+            _Outcome.Arity = ArgumentArity.ZeroOrMore;
+
             _RestoreForce = new Option<bool>(
                 new string[] { "--force" },
                 CmdStrings.Restore_Force_Description
@@ -109,6 +117,7 @@ private void AddAnalyze()
             cmd.AddOption(_InputPath);
             cmd.AddOption(_Module);
             cmd.AddOption(_Baseline);
+            cmd.AddOption(_Outcome);
             cmd.SetHandler((invocation) =>
             {
                 var option = new AnalyzerOptions
@@ -118,6 +127,7 @@ private void AddAnalyze()
                     Module = invocation.ParseResult.GetValueForOption(_Module),
                     Option = invocation.ParseResult.GetValueForOption(_Option),
                     Baseline = invocation.ParseResult.GetValueForOption(_Baseline),
+                    Outcome = ParseOutcome(invocation.ParseResult.GetValueForOption(_Outcome)),
                     Verbose = invocation.ParseResult.GetValueForOption(_Verbose),
                     Debug = invocation.ParseResult.GetValueForOption(_Debug),
                 };
@@ -233,5 +243,19 @@ private void AddModule()
             cmd.AddOption(_Path);
             Command.AddCommand(cmd);
         }
+
+        /// <summary>
+        /// Convert string arguments to flags of <see cref="RuleOutcome"/>.
+        /// </summary>
+        private static RuleOutcome? ParseOutcome(string[] s)
+        {
+            var result = RuleOutcome.None;
+            for (var i = 0; s != null && i < s.Length; i++)
+            {
+                if (Enum.TryParse(s[i], ignoreCase: true, result: out RuleOutcome flag))
+                    result |= flag;
+            }
+            return result == RuleOutcome.None ? null : result;
+        }
     }
 }

src/PSRule.Tool/ClientHelper.cs

@@ -2,11 +2,8 @@
 // Licensed under the MIT License.
 
 using System.Collections;
-using System.CommandLine;
 using System.CommandLine.Invocation;
-using System.Diagnostics;
 using System.Management.Automation;
-using Microsoft.CodeAnalysis.Sarif;
 using PSRule.Configuration;
 using PSRule.Data;
 using PSRule.Pipeline;
@@ -59,6 +56,9 @@ public static int RunAnalyze(AnalyzerOptions operationOptions, ClientContext cli
             if (operationOptions.Path != null)
                 option.Include.Path = operationOptions.Path;
 
+            if (operationOptions.Outcome != null && operationOptions.Outcome.Value != Rules.RuleOutcome.None)
+                option.Output.Outcome = operationOptions.Outcome;
+
             // Build command
             var builder = CommandLineBuilder.Assert(operationOptions.Module, option, host, file);
             builder.Baseline(BaselineOption.FromString(operationOptions.Baseline));

src/PSRule.Tool/Resources/CmdStrings.resx

@@ -117,9 +117,15 @@
   <resheader name="writer">
     <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
   </resheader>
+  <data name="Analyze_Baseline_Description" xml:space="preserve">
+    <value>The specific baseline to use.</value>
+  </data>
   <data name="Analyze_Description" xml:space="preserve">
     <value>Run rule analysis.</value>
   </data>
+  <data name="Analyze_Outcome_Description" xml:space="preserve">
+    <value>Specifies the rule results to show in output. By default, Pass/ Fail/ Error results are shown.</value>
+  </data>
   <data name="Cmd_Description" xml:space="preserve">
     <value>PSRule CLI</value>
   </data>

src/PSRule.Types/Data/SemanticVersion.cs

@@ -1,9 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using System;
 using System.Diagnostics;
-using YamlDotNet.Core.Tokens;
 
 namespace PSRule.Data
 {

src/PSRule/Configuration/PSRuleOption.cs

@@ -3,7 +3,6 @@
 
 using System.Collections;
 using System.Diagnostics;
-using System.Globalization;
 using System.Management.Automation;
 using Newtonsoft.Json;
 using PSRule.Converters.Yaml;