Rename and improvement of logging options #1456 (#1513)

README.md

@@ -26,7 +26,7 @@ PSRule works great and integrates with popular continuous integration (CI) syste
 - [Maintainers](#maintainers)
 - [License](#license)
 
-### Features of PSRule include:
+### Features of PSRule include
 
 - [DevOps][2] - Built to support DevOps culture and tools.
 - [Extensible][3] - Define tests using YAML, JSON, or PowerShell format.
@@ -290,15 +290,19 @@ The following conceptual topics exist in the `PSRule` module:
   - [Binding.UseQualifiedName](https://aka.ms/ps-rule/options#bindingusequalifiedname)
   - [Configuration](https://aka.ms/ps-rule/options#configuration)
   - [Convention.Include](https://aka.ms/ps-rule/options#conventioninclude)
+  - [Execution.AliasReference](https://aka.ms/ps-rule/options#executionaliasreference)
   - [Execution.AliasReferenceWarning](https://aka.ms/ps-rule/options#executionaliasreferencewarning)
   - [Execution.DuplicateResourceId](https://aka.ms/ps-rule/options#executionduplicateresourceid)
   - [Execution.LanguageMode](https://aka.ms/ps-rule/options#executionlanguagemode)
   - [Execution.InconclusiveWarning](https://aka.ms/ps-rule/options#executioninconclusivewarning)
+  - [Execution.InvariantCulture](https://aka.ms/ps-rule/options#executioninvariantculture)
   - [Execution.InvariantCultureWarning](https://aka.ms/ps-rule/options#executioninvariantculturewarning)
   - [Execution.InitialSessionState](https://aka.ms/ps-rule/options#executioninitialsessionstate)
   - [Execution.NotProcessedWarning](https://aka.ms/ps-rule/options#executionnotprocessedwarning)
+  - [Execution.RuleInconclusive](https://aka.ms/ps-rule/options#executionruleinconclusive)
   - [Execution.SuppressedRuleWarning](https://aka.ms/ps-rule/options#executionsuppressedrulewarning)
   - [Execution.SuppressionGroupExpired](https://aka.ms/ps-rule/options#executionsuppressiongroupexpired)
+  - [Execution.UnprocessedObject](https://aka.ms/ps-rule/options#executionunprocessedobject)
   - [Include.Module](https://aka.ms/ps-rule/options#includemodule)
   - [Include.Path](https://aka.ms/ps-rule/options#includepath)
   - [Input.Format](https://aka.ms/ps-rule/options#inputformat)

docs/CHANGELOG-v2.md

@@ -33,6 +33,17 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 What's changed since release v2.8.1:
 
 - General improvements:
+  - **Important change**: Rename of execution options by @BernieWhite.
+    [#1456](https://github.com/microsoft/PSRule/issues/1456)
+    - Renamed options allow configuration of output level as `Ignore`, `Warn`, `Error`, or `Debug`.
+    - `Execution.AliasReferenceWarning` is replaced with `Execution.AliasReference`.
+    - `Execution.InconclusiveWarning` is replaced with `Execution.RuleInconclusive`.
+    - `Execution.InvariantCultureWarning` is replaced with `Execution.InvariantCulture`.
+    - `Execution.NotProcessedWarning` is replaced with `Execution.UnprocessedObject`.
+    - Deprecated `AliasReferenceWarning` option, which will be removed in v3.
+    - Deprecated `InconclusiveWarning` option, which will be removed in v3.
+    - Deprecated `InvariantCultureWarning` option, which will be removed in v3.
+    - Deprecated `NotProcessedWarning` option, which will be removed in v3.
   - Improved schema display names by @BernieWhite.
     [#1488](https://github.com/microsoft/PSRule/issues/1488)
 - Engineering:

docs/concepts/PSRule/en-US/about_PSRule_Options.md

@@ -14,15 +14,19 @@ This topic describes what options are available, when to and how to use them.
 The following workspace options are available for use:
 
 - [Convention.Include](#conventioninclude)
+- [Execution.AliasReference](#executionaliasreference)
 - [Execution.AliasReferenceWarning](#executionaliasreferencewarning)
 - [Execution.DuplicateResourceId](#executionduplicateresourceid)
 - [Execution.LanguageMode](#executionlanguagemode)
 - [Execution.InconclusiveWarning](#executioninconclusivewarning)
+- [Execution.InvariantCulture](#executioninvariantculture)
 - [Execution.InvariantCultureWarning](#executioninvariantculturewarning)
 - [Execution.InitialSessionState](#executioninitialsessionstate)
 - [Execution.NotProcessedWarning](#executionnotprocessedwarning)
+- [Execution.RuleInconclusive](#executionruleinconclusive)
 - [Execution.SuppressedRuleWarning](#executionsuppressedrulewarning)
 - [Execution.SuppressionGroupExpired](#executionsuppressiongroupexpired)
+- [Execution.UnprocessedObject](#executionunprocessedobject)
 - [Include.Module](#includemodule)
 - [Include.Path](#includepath)
 - [Input.Format](#inputformat)
@@ -673,8 +677,69 @@ variables:
   value: 'Convention1;Convention2'
 ```
 
+### Execution.AliasReference
+
+Determines how to handle when an alias to a resource is used.
+By defaut, a warning is generated, however this behaviour can be modified by this option.
+
+This option replaces `AliasReferenceWarning`.
+You do not need to configure both options.
+If `AliasReferenceWarning` is configured, it will override `AliasReference` with `Warn` or `Ignore` until removal in PSRule v3.
+
+The following preferences are available:
+
+- `None` (0) - No preference.
+  Inherits the default of `Warn`.
+- `Ignore` (1) - Continue to execute silently.
+- `Warn` (2) - Continue to execute but log a warning.
+  This is the default.
+- `Error` (3) - Abort and throw an error.
+- `Debug` (4) - Continue to execute but log a debug message.
+
+```powershell
+# PowerShell: Using the ExecutionAliasReference parameter
+$option = New-PSRuleOption -ExecutionAliasReference 'Error';
+```
+
+```powershell
+# PowerShell: Using the Execution.AliasReference hashtable key
+$option = New-PSRuleOption -Option @{ 'Execution.AliasReference' = 'Error' };
+```
+
+```powershell
+# PowerShell: Using the ExecutionAliasReference parameter to set YAML
+Set-PSRuleOption -ExecutionAliasReference 'Error';
+```
+
+```yaml
+# YAML: Using the execution/aliasReference property
+execution:
+  aliasReference: Error
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_EXECUTION_ALIASREFERENCE=Error
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_EXECUTION_ALIASREFERENCE: Error
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_EXECUTION_ALIASREFERENCE
+  value: Error
+```
+
 ### Execution.AliasReferenceWarning
 
+This option has been deprecated and will be removed from v3 in favor of `aliasReference`.
+Use `aliasReference` instead.
+
 Rules may define one or more aliases.
 These aliases are alternative names to identify the rule.
 An alias may be used to reference the rule anywhere a rule name is used.
@@ -828,6 +893,9 @@ variables:
 
 ### Execution.InconclusiveWarning
 
+This option has been deprecated and will be removed from v3 in favor of `ruleInconclusive`.
+Use `ruleInconclusive` instead.
+
 When defining rules, it is possible not return a valid `$True` or `$False` result within the definition script block.
 
 Rule authors should not intentionally avoid returning a result, however a possible cause for not returning a result may be a rule logic error.
@@ -882,8 +950,69 @@ variables:
   value: false
 ```
 
+### Execution.InvariantCulture
+
+Determines how to report when an invariant culture is used.
+By defaut, a warning is generated, however this behaviour can be modified by this option.
+
+This option replaces `InvariantCultureWarning`.
+You do not need to configure both options.
+If `InvariantCultureWarning` is configured, it will override `InvariantCulture` with `Warn` or `Ignore` until removal in PSRule v3.
+
+The following preferences are available:
+
+- `None` (0) - No preference.
+  Inherits the default of `Warn`.
+- `Ignore` (1) - Continue to execute silently.
+- `Warn` (2) - Continue to execute but log a warning.
+  This is the default.
+- `Error` (3) - Abort and throw an error.
+- `Debug` (4) - Continue to execute but log a debug message.
+
+```powershell
+# PowerShell: Using the ExecutionInvariantCulture parameter
+$option = New-PSRuleOption -ExecutionInvariantCulture 'Error';
+```
+
+```powershell
+# PowerShell: Using the Execution.InvariantCulture hashtable key
+$option = New-PSRuleOption -Option @{ 'Execution.InvariantCulture' = 'Error' };
+```
+
+```powershell
+# PowerShell: Using the ExecutionInvariantCulture parameter to set YAML
+Set-PSRuleOption -ExecutionInvariantCulture 'Error';
+```
+
+```yaml
+# YAML: Using the execution/invariantCulture property
+execution:
+  invariantCulture: Error
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_EXECUTION_INVARIANTCULTURE=Error
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_EXECUTION_INVARIANTCULTURE: Error
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_EXECUTION_INVARIANTCULTURE
+  value: Error
+```
+
 ### Execution.InvariantCultureWarning
 
+This option has been deprecated and will be removed from v3 in favor of `invariantCulture`.
+Use `invariantCulture` instead.
+
 When evaluating rules inside a CI host, if invariant culture is used, a warning is shown by default.
 You can suppress this warning if you set the culture with `-Culture` or the `Output.Culture` option.
 
@@ -979,6 +1108,9 @@ variables:
 
 ### Execution.NotProcessedWarning
 
+This option has been deprecated and will be removed from v3 in favor of `unprocessedObject`.
+Use `unprocessedObject` instead.
+
 When evaluating rules, it is possible to incorrectly select a path with rules that use pre-conditions that do not accept the pipeline object.
 In this case the object has not been processed by any rule.
 
@@ -1028,6 +1160,64 @@ variables:
   value: false
 ```
 
+### Execution.RuleInconclusive
+
+Determines how to handle rules that generate inconclusive results.
+By defaut, a warning is generated, however this behaviour can be modified by this option.
+
+This option replaces `InconclusiveWarning`.
+You do not need to configure both options.
+If `InconclusiveWarning` is configured, it will override `RuleInconclusive` with `Warn` or `Ignore` until removal in PSRule v3.
+
+The following preferences are available:
+
+- `None` (0) - No preference.
+  Inherits the default of `Warn`.
+- `Ignore` (1) - Continue to execute silently.
+- `Warn` (2) - Continue to execute but log a warning.
+  This is the default.
+- `Error` (3) - Abort and throw an error.
+- `Debug` (4) - Continue to execute but log a debug message.
+
+```powershell
+# PowerShell: Using the ExecutionRuleInconclusive parameter
+$option = New-PSRuleOption -ExecutionRuleInconclusive 'Error';
+```
+
+```powershell
+# PowerShell: Using the Execution.RuleInconclusive hashtable key
+$option = New-PSRuleOption -Option @{ 'Execution.RuleInconclusive' = 'Error' };
+```
+
+```powershell
+# PowerShell: Using the ExecutionRuleInconclusive parameter to set YAML
+Set-PSRuleOption -ExecutionRuleInconclusive 'Error';
+```
+
+```yaml
+# YAML: Using the execution/ruleInconclusive property
+execution:
+  ruleInconclusive: Error
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_EXECUTION_RULEINCONCLUSIVE=Error
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_EXECUTION_RULEINCONCLUSIVE: Error
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_EXECUTION_RULEINCONCLUSIVE
+  value: Error
+```
+
 ### Execution.SuppressedRuleWarning
 
 This option has been deprecated and will be removed from v3 in favor of `ruleSuppressed`.
@@ -1251,6 +1441,64 @@ variables:
   value: Error
 ```
 
+### Execution.UnprocessedObject
+
+Determines how to report objects that are not processed by any rule.
+By defaut, a warning is generated, however this behaviour can be modified by this option.
+
+This option replaces `NotProcessedWarning`.
+You do not need to configure both options.
+If `NotProcessedWarning` is configured, it will override `UnprocessedObject` with `Warn` or `Ignore` until removal in PSRule v3.
+
+The following preferences are available:
+
+- `None` (0) - No preference.
+  Inherits the default of `Warn`.
+- `Ignore` (1) - Continue to execute silently.
+- `Warn` (2) - Continue to execute but log a warning.
+  This is the default.
+- `Error` (3) - Abort and throw an error.
+- `Debug` (4) - Continue to execute but log a debug message.
+
+```powershell
+# PowerShell: Using the ExecutionUnprocessedObject parameter
+$option = New-PSRuleOption -ExecutionUnprocessedObject 'Error';
+```
+
+```powershell
+# PowerShell: Using the Execution.UnprocessedObject hashtable key
+$option = New-PSRuleOption -Option @{ 'Execution.UnprocessedObject' = 'Error' };
+```
+
+```powershell
+# PowerShell: Using the ExecutionUnprocessedObject parameter to set YAML
+Set-PSRuleOption -ExecutionUnprocessedObject 'Error';
+```
+
+```yaml
+# YAML: Using the execution/unprocessedObject property
+execution:
+  unprocessedObject: Error
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_EXECUTION_UNPROCESSEDOBJECT=Error
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_EXECUTION_UNPROCESSEDOBJECT: Error
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_EXECUTION_UNPROCESSEDOBJECT
+  value: Error
+```
+
 ### Include.Module
 
 Automatically include rules and resources from the specified module.
@@ -3256,13 +3504,14 @@ convention:
 
 # Configure execution options
 execution:
-  aliasReferenceWarning: true
+  aliasReference: Warn
   duplicateResourceId: Error
+  invariantCulture: Warn
   languageMode: FullLanguage
-  inconclusiveWarning: true
-  notProcessedWarning: true
-  suppressedRuleWarning: true
+  ruleInconclusive: Warn
+  ruleSuppressed: Warn
   suppressionGroupExpired: Warn
+  unprocessedObject: Warn
 
 # Configure include options
 include:

docs/deprecations.md

@@ -26,6 +26,18 @@ The following execution options have been deprecated and will be removed from _v
 - `Execution.SuppressedRuleWarning` is replaced with `Execution.RuleSuppressed`.
   Set `Execution.RuleSuppressed` to `Warn` to log a warning from _v2.8.0_.
   If both options are set, `Execution.SuppressedRuleWarning` takes precedence until _v3_.
+- `Execution.AliasReferenceWarning` is replaced with `Execution.AliasReference`.
+  Set `Execution.AliasReference` to `Warn` to log a warning from _v2.9.0_.
+  If both options are set, `Execution.AliasReferenceWarning` takes precedence until _v3_.
+- `Execution.InconclusiveWarning` is replaced with `Execution.RuleInconclusive`.
+  Set `Execution.RuleInconclusive` to `Warn` to log a warning from _v2.9.0_.
+  If both options are set, `Execution.InconclusiveWarning` takes precedence until _v3_.
+- `Execution.InvariantCultureWarning` is replaced with `Execution.InvariantCulture`.
+  Set `Execution.InvariantCulture` to `Warn` to log a warning from _v2.9.0_.
+  If both options are set, `Execution.InvariantCultureWarning` takes precedence until _v3_.
+- `Execution.NotProcessedWarning` is replaced with `Execution.UnprocessedObject`.
+  Set `Execution.UnprocessedObject` to `Warn` to log a warning from _v2.9.0_.
+  If both options are set, `Execution.NotProcessedWarning` takes precedence until _v3_.
 
 !!! Tip
     You do not need to configure both options.