(#2591) Add headers to limit output commands

When a user asks for limited output from Chocolatey, it is not uncommon
to pipe that output to `ConvertFrom-String` or `ConvertFrom-Csv` and
manually add headers to get back an object. This allows for getting a
header row back so that the end user doesn't need to add their own
headers and discern what they are.

This also adds a StringResources static class that allows us to store
constant strings in and use them across the code to reduce duplication.

A new OutputHelpers class has been introduced in an attempt to simplify
the concatenation of the limited output, when a collection of strings
are joined to the "|" character.

Some new Pester tests have also been added to verify the output from the
commands, both when the new '--include-headers' option is used, as well
as the 'alwaysIncludeHeaders' feature.

Author: corbob

src/chocolatey.resources/helpers/ChocolateyTabExpansion.ps1

@@ -38,7 +38,7 @@ function script:chocoCmdOperations($commands, $command, $filter, $currentArgumen
 $script:chocoCommands = @('apikey','cache','config','export','feature','help','info','install','license','list','new','outdated','pack','pin','push','rule','search','source','support','template','uninstall','upgrade','--help','--version')
 
 # ensure these all have a space to start, or they will cause issues
-$allCommands = " --accept-license --cache-location='' --debug --fail-on-standard-error --force --help --ignore-http-cache --limit-output --log-file='' --no-color --no-progress --noop --online --proxy='' --proxy-bypass-list='' --proxy-bypass-on-local --proxy-password='' --proxy-user='' --skip-compatibility-checks --timeout='' --trace --use-system-powershell --verbose --yes"
+$allCommands = " --accept-license --cache-location='' --debug --fail-on-standard-error --force --help --ignore-http-cache --include-headers --limit-output --log-file='' --no-color --no-progress --noop --online --proxy='' --proxy-bypass-list='' --proxy-bypass-on-local --proxy-password='' --proxy-user='' --skip-compatibility-checks --timeout='' --trace --use-system-powershell --verbose --yes"
 
 $commandOptions = @{
     apikey    = "--api-key='' --source=''"

src/chocolatey/OutputHelpers.cs

@@ -0,0 +1,17 @@
+using chocolatey.infrastructure.app.configuration;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace chocolatey
+{
+    public static class OutputHelpers
+    {
+        public static void LimitedOutput(params string[] output)
+        {
+            "chocolatey".Log().Info(output.Join("|"));
+        }
+    }
+}

src/chocolatey/StringResources.cs

@@ -655,5 +655,15 @@ public static class ErrorMessages
             internal const string UnableToDowngrade = "A newer version of {0} (v{1}) is already installed.{2} Use --allow-downgrade or --force to attempt to install older versions.";
             internal const string DependencyFailedToInstall = "Failed to install {0} because a previous dependency failed.";
         }
+
+        public static class OptionDescriptions
+        {
+            public const string IncludeHeaders = "Include header names when --limit-output is used. Requires Chocolatey CLI 2.5.0+";
+        }
+
+        public static class Options
+        {
+            public const string IncludeHeaders = "include-headers";
+        }
     }
-}
+}

src/chocolatey/chocolatey.csproj

@@ -459,6 +459,7 @@
     <Compile Include="LogExtensions.cs" />
     <Compile Include="NuGetVersionExtensions.cs" />
     <Compile Include="ObjectExtensions.cs" />
+    <Compile Include="OutputHelpers.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="RuleResultExtensions.cs" />
     <Compile Include="StringExtensions.cs" />

src/chocolatey/infrastructure.app/ApplicationParameters.cs

@@ -275,6 +275,7 @@ public static class Features
             public static readonly string UsePackageRepositoryOptimizations = "usePackageRepositoryOptimizations";
             public static readonly string DisableCompatibilityChecks = "disableCompatibilityChecks";
             public static readonly string UsePackageHashValidation = "usePackageHashValidation";
+            public static readonly string AlwaysIncludeHeaders = "alwaysIncludeHeaders";
         }
 
         public static class Messages

src/chocolatey/infrastructure.app/builders/ConfigurationBuilder.cs

@@ -341,7 +341,8 @@ private static void SetAllFeatureFlags(ChocolateyConfiguration config, ConfigFil
             config.Features.UsePackageRepositoryOptimizations = SetFeatureFlag(ApplicationParameters.Features.UsePackageRepositoryOptimizations, configFileSettings, defaultEnabled: true, description: "Use Package Repository Optimizations - Turn on optimizations for reducing bandwidth with repository queries during package install/upgrade/outdated operations. Should generally be left enabled, unless a repository needs to support older methods of query. When disabled, this makes queries similar to the way they were done in earlier versions of Chocolatey.");
             config.Features.UsePackageHashValidation = SetFeatureFlag(ApplicationParameters.Features.UsePackageHashValidation, configFileSettings, defaultEnabled: false, description: "Use Package Hash Validation - Check the hash of the downloaded package file against the source provided hash. Only supports sources that provide SHA512 hashes. Disabled by default. Available in 2.3.0+");
             config.PromptForConfirmation = !SetFeatureFlag(ApplicationParameters.Features.AllowGlobalConfirmation, configFileSettings, defaultEnabled: false, description: "Prompt for confirmation in scripts or bypass.");
-            config.DisableCompatibilityChecks = SetFeatureFlag(ApplicationParameters.Features.DisableCompatibilityChecks, configFileSettings, defaultEnabled: false, description: "Disable Compatibility Checks - Disable showing a warning when there is an incompatibility between Chocolatey CLI and Chocolatey Licensed Extension.");
+            config.DisableCompatibilityChecks = SetFeatureFlag(ApplicationParameters.Features.DisableCompatibilityChecks, configFileSettings, defaultEnabled: false, description: "Disable Compatibility Checks - Disable showing a warning when there is an incompatibility between Chocolatey CLI and Chocolatey Licensed Extension. Available in 1.1.0+");
+            config.IncludeHeaders = SetFeatureFlag(ApplicationParameters.Features.AlwaysIncludeHeaders, configFileSettings, defaultEnabled: false, description: StringResources.OptionDescriptions.IncludeHeaders);
         }
 
         private static bool SetFeatureFlag(string featureName, ConfigFileSettings configFileSettings, bool defaultEnabled, string description)
@@ -411,6 +412,9 @@ private static void SetGlobalOptions(IList<string> args, ChocolateyConfiguration
                         .Add("r|limitoutput|limit-output",
                              "LimitOutput - Limit the output to essential information",
                              option => config.RegularOutput = option == null)
+                        .Add(StringResources.Options.IncludeHeaders,
+                            StringResources.OptionDescriptions.IncludeHeaders,
+                            option => config.IncludeHeaders = true)
                         .Add("timeout=|execution-timeout=",
                              "CommandExecutionTimeout (in seconds) - The time to allow a command to finish before timing out. Overrides the default execution timeout in the configuration of {0} seconds. Supply '0' to disable the timeout.".FormatWith(config.CommandExecutionTimeoutSeconds.ToStringSafe()),
                             option =>
@@ -453,7 +457,7 @@ private static void SetGlobalOptions(IList<string> args, ChocolateyConfiguration
                         .Add("proxy-bypass-on-local",
                              "Proxy Bypass On Local - Bypass proxy for local connections. Requires explicit proxy (`--proxy` or config setting). Overrides the default proxy bypass on local setting of '{0}'.".FormatWith(config.Proxy.BypassOnLocal),
                              option => config.Proxy.BypassOnLocal = option != null)
-                         .Add("log-file=",
+                        .Add("log-file=",
                              "Log File to output to in addition to regular loggers.",
                              option => config.AdditionalLogFileLocation = option.UnquoteSafe())
                         .Add("skipcompatibilitychecks|skip-compatibility-checks",

src/chocolatey/infrastructure.app/commands/ChocolateyApiKeyCommand.cs

@@ -197,6 +197,10 @@ public virtual void Run(ChocolateyConfiguration configuration)
                     _configSettingsService.SetApiKey(configuration);
                     break;
                 default:
+                    // This is required, since we only want to show the header if there are any ApiKeys
+                    // to be shown, which will be when we are printing the first ApiKey
+                    var hasHeaderRowBeenOutput = false;
+
                     _configSettingsService.GetApiKey(configuration, (key) =>
                     {
                         var authenticatedString = string.IsNullOrWhiteSpace(key.Key) ? string.Empty : "(Authenticated)";
@@ -207,7 +211,13 @@ public virtual void Run(ChocolateyConfiguration configuration)
                         }
                         else
                         {
-                            this.Log().Info(() => "{0}|{1}".FormatWith(key.Source, authenticatedString));
+                            if (configuration.IncludeHeaders && !hasHeaderRowBeenOutput)
+                            {
+                                OutputHelpers.LimitedOutput("Source", "ApiKey");
+                                hasHeaderRowBeenOutput = true;
+                            }
+
+                            OutputHelpers.LimitedOutput(key.Source, authenticatedString);
                         }
                     });
                     break;

src/chocolatey/infrastructure.app/commands/ChocolateyLicenseCommand.cs

@@ -116,8 +116,14 @@ private void GetLicense(ChocolateyConfiguration config)
             }
             else
             {
-                // Headers: Name, LicenseType, ExpirationDate, NodeCount
-                this.Log().Info("{0}|{1}|{2}|{3}".FormatWith(ourLicense.Name, ourLicense.LicenseType, ourLicense.ExpirationDate?.ToString("yyyy-MM-dd"), nodeCount));
+                // This if we get here, there is a license to display, it is "safe" to always
+                // output the header row
+                if (config.IncludeHeaders)
+                {
+                    OutputHelpers.LimitedOutput("Name", "Type", "ExpirationDate", "NodeCount");
+                }
+
+                OutputHelpers.LimitedOutput(ourLicense.Name, ourLicense.LicenseType.ToString(), ourLicense.ExpirationDate?.ToString("yyyy-MM-dd"), nodeCount.ToString());
             }
         }
 

src/chocolatey/infrastructure.app/commands/ChocolateyPinCommand.cs

@@ -178,12 +178,22 @@ public virtual void ListPins(ChocolateyConfiguration config)
             config.QuietOutput = quiet;
             config.Input = input;
 
+            // This is required, since we only want to show the header if there are any Pinned Packages
+            // to be shown, which will be when we are printing the first Pinned Package
+            var hasHeaderRowBeenOutput = false;
+
             foreach (var pkg in packages.OrEmpty())
             {
                 var pkgInfo = _packageInfoService.Get(pkg.PackageMetadata);
                 if (pkgInfo != null && pkgInfo.IsPinned)
                 {
-                    this.Log().Info(() => "{0}|{1}".FormatWith(pkgInfo.Package.Id, pkgInfo.Package.Version));
+                    if (!config.RegularOutput && config.IncludeHeaders && !hasHeaderRowBeenOutput)
+                    {
+                        OutputHelpers.LimitedOutput("Id", "Version");
+                        hasHeaderRowBeenOutput = true;
+                    }
+
+                    OutputHelpers.LimitedOutput(pkgInfo.Package.Id, pkgInfo.Package.Version.ToNormalizedStringChecked());
                 }
             }
         }

src/chocolatey/infrastructure.app/commands/ChocolateyRuleCommand.cs

@@ -185,6 +185,10 @@ protected virtual void OutputRules(string type, ChocolateyConfiguration config,
                 }
             }
 
+            // This is required, since we only want to show the header if there are any Rules
+            // to be shown, which will be when we are printing the first Rule
+            var hasHeaderRowBeenOutput = false;
+
             foreach (var rule in rules)
             {
                 if (config.RegularOutput)
@@ -193,7 +197,13 @@ protected virtual void OutputRules(string type, ChocolateyConfiguration config,
                 }
                 else
                 {
-                    this.Log().Info("{0}|{1}|{2}|{3}", rule.Severity, rule.Id, rule.Summary, rule.HelpUrl);
+                    if (config.IncludeHeaders && !hasHeaderRowBeenOutput)
+                    {
+                        OutputHelpers.LimitedOutput("Severity", "Id", "Summary", "HelpUrl");
+                        hasHeaderRowBeenOutput = true;
+                    }
+
+                    OutputHelpers.LimitedOutput(rule.Severity.ToString(), rule.Id, rule.Summary, rule.HelpUrl);
                 }
             }
         }