Finalize emitter updates #2752 #2753 (#2754)

.vscode/settings.json

@@ -129,7 +129,6 @@
   "[csharp]": {
     "editor.tabSize": 4
   },
-  "omnisharp.organizeImportsOnFormat": true,
   "omnisharp.enableEditorConfigSupport": true,
   "omnisharp.enableRoslynAnalyzers": true,
   "git.branchProtection": [
@@ -138,5 +137,6 @@
   ],
   "dotnet.completion.showCompletionItemsFromUnimportedNamespaces": true,
   "PSRule.options.path": "ps-rule-ci.yaml",
-  "PSRule.lock.restore": true
+  "PSRule.lock.restore": true,
+  "dotnet.formatting.organizeImportsOnFormat": true
 }

README.md

@@ -307,7 +307,7 @@ The following conceptual topics exist in the `PSRule` module:
   - [Include.Module](https://aka.ms/ps-rule/options#includemodule)
   - [Include.Path](https://aka.ms/ps-rule/options#includepath)
   - [Input.FileObjects](https://aka.ms/ps-rule/options#inputfileobjects)
-  - [Input.Format](https://aka.ms/ps-rule/options#inputformat)
+  - [Input.StringFormat](https://aka.ms/ps-rule/options#inputstringformat)
   - [Input.IgnoreGitPath](https://aka.ms/ps-rule/options#inputignoregitpath)
   - [Input.IgnoreObjectSource](https://aka.ms/ps-rule/options#inputignoreobjectsource)
   - [Input.IgnoreRepositoryCommon](https://aka.ms/ps-rule/options#inputignorerepositorycommon)

docs/CHANGELOG-v3.md

@@ -34,6 +34,15 @@ What's changed since pre-release v3.0.0-B0390:
     [#2734](https://github.com/microsoft/PSRule/issues/2734)
     - Code lens in `ps-rule.lock.json` allows you to upgrade all or specific modules to the latest version.
     - The command `Upgrade dependency` allows you to upgrade all or specific modules to the latest version.
+  - Added support for enabling/ disabling emitters by @BernieWhite.
+    [#2752](https://github.com/microsoft/PSRule/issues/2752)
+    - Emitters can be enabled or disabled by setting the `enabled` property on each format.
+    - Additionally, the `formats` parameter/ input can be set on the command-line and CI to enable emitters for a run.
+  - Added support for configuring replacement string for each format by @BernieWhite.
+    [#2753](https://github.com/microsoft/PSRule/issues/2753)
+    - Replacement strings allow common literal tokens to be replaced when processed by PSRule.
+      i.e. `{{environment}}` replaced with `dev`.
+    - All built-in emitters now support replacement strings, by configuring the `replace` property on each format.
 - Bug fixes:
   - Fixed upgrade dependency could use pre-release version by @BernieWhite.
     [#2726](https://github.com/microsoft/PSRule/issues/2726)

docs/commands/PSRule/en-US/Assert-PSRule.md

@@ -16,22 +16,23 @@ Evaluate objects against matching rules and assert any failures.
 ### Input (Default)
 
 ```text
-Assert-PSRule [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]
- [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
- [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
+Assert-PSRule [-Module <String[]>] [-Formats <String[]>] [-InputStringFormat <String>]
+ [-Baseline <BaselineOption>] [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>]
+ [-As <ResultFormat>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
  [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
- [-Culture <String[]>] -InputObject <PSObject> [-ResultVariable <String>] [-WhatIf] [-Confirm]
- [<CommonParameters>]
+ [-Culture <String[]>] -InputObject <PSObject> [-ResultVariable <String>] [-ProgressAction <ActionPreference>]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
-Assert-PSRule -InputPath <String[]> [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]
- [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
- [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
+Assert-PSRule -InputPath <String[]> [-Module <String[]>] [-Formats <String[]>] [-InputStringFormat <String>]
+ [-Baseline <BaselineOption>] [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>]
+ [-As <ResultFormat>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
  [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
- [-Culture <String[]>] [-ResultVariable <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-Culture <String[]>] [-ResultVariable <String>] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -120,6 +121,47 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Formats
+
+Enables one or more formats by name to process files and deserialized objects.
+Parameter is equivalent to setting `Format.<name>.Enabled` = `true` for each of the specified formats.
+
+This parameter takes precedence over the `Format.<name>.Enabled` option if set.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -InputStringFormat
+
+Configures the input format for when a string is passed in as a target object.
+This parameter also enables the format if it is not already enabled.
+
+When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default.
+Set this option to an available format for example: `yaml`, `json`, `markdown`, `powershell_data`.
+
+This parameter takes precedence over the `Input.StringFormat` option if set.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Format
 
 Configures the input format for when a string is passed in as a target object.

docs/commands/PSRule/en-US/Get-PSRuleTarget.md

@@ -16,15 +16,17 @@ Get a list of target objects.
 ### Input (Default)
 
 ```text
-Get-PSRuleTarget [-Format <InputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>]
- -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]
+Get-PSRuleTarget [-Formats <String[]>] [-InputStringFormat <String>] [-Option <PSRuleOption>]
+ [-ObjectPath <String>] -InputObject <PSObject> [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
-Get-PSRuleTarget -InputPath <String[]> [-Format <InputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>]
- [-WhatIf] [-Confirm] [<CommonParameters>]
+Get-PSRuleTarget -InputPath <String[]> [-Formats <String[]>] [-InputStringFormat <String>]
+ [-Option <PSRuleOption>] [-ObjectPath <String>] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -59,30 +61,43 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Format
+### -Formats
 
-Configures the input format for when a string is passed in as a target object.
+Enables one or more formats by name to process files and deserialized objects.
+Parameter is equivalent to setting `Format.<name>.Enabled` = `true` for each of the specified formats.
 
-When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default.
-Set this option to either `Yaml`, `Json`, `Markdown`, `PowerShellData` to have PSRule deserialize the object.
+This parameter takes precedence over the `Format.<name>.Enabled` option if set.
 
-When the `-InputPath` parameter is used with a file path or URL.
-If the `Detect` format is used, the file extension will be used to automatically detect the format.
-When `-InputPath` is not used, `Detect` is the same as `None`.
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
 
-See `about_PSRule_Options` for details.
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
 
-This parameter takes precedence over the `Input.Format` option if set.
+### -InputStringFormat
+
+Configures the input format for when a string is passed in as a target object.
+This parameter also enables the format if it is not already enabled.
+
+When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default.
+Set this option to an available format for example: `yaml`, `json`, `markdown`, `powershell_data`.
+
+This parameter takes precedence over the `Input.StringFormat` option if set.
 
 ```yaml
-Type: InputFormat
+Type: String
 Parameter Sets: (All)
 Aliases:
-Accepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect
 
 Required: False
 Position: Named
-Default value: Detect
+Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```

docs/commands/PSRule/en-US/Invoke-PSRule.md

@@ -16,21 +16,22 @@ Evaluate objects against matching rules and output the results.
 ### Input (Default)
 
 ```text
-Invoke-PSRule [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>] [-Format <InputFormat>]
- [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>] [-Convention <String[]>]
- [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>]
- [-TargetType <String[]>] [-Culture <String[]>] -InputObject <PSObject> [-WhatIf] [-Confirm]
+Invoke-PSRule [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>] [-Formats <String[]>]
+ [-InputStringFormat <String>] [-OutputPath <String>] [-OutputFormat <OutputFormat>]
+ [-Baseline <BaselineOption>] [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>]
+ [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
+ [-Culture <String[]>] -InputObject <PSObject> [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm]
  [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
 Invoke-PSRule -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
- [-Format <InputFormat>] [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>]
- [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]
- [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String[]>] [-WhatIf] [-Confirm]
- [<CommonParameters>]
+ [-Formats <String[]>] [-InputStringFormat <String>] [-OutputPath <String>] [-OutputFormat <OutputFormat>]
+ [-Baseline <BaselineOption>] [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>]
+ [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
+ [-Culture <String[]>] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -259,35 +260,43 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Format
+### -Formats
 
-Configures the input format for when a string is passed in as a target object.
+Enables one or more formats by name to process files and deserialized objects.
+Parameter is equivalent to setting `Format.<name>.Enabled` = `true` for each of the specified formats.
 
-When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default.
-Set this option to either `Yaml`, `Json`, `Markdown`, `PowerShellData` to have PSRule deserialize the object.
+This parameter takes precedence over the `Format.<name>.Enabled` option if set.
 
-When the `-InputPath` parameter is used with a file path or URL.
-If the `Detect` format is used, the file extension will be used to automatically detect the format.
-When `-InputPath` is not used, `Detect` is the same as `None`.
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
 
-When this option is set to `File` PSRule scans the path and subdirectories specified by `-InputPath`.
-Files are treated as objects instead of being deserialized.
-Additional, PSRule uses the file extension as the object type.
-When files have no extension the whole file name is used.
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
 
-See `about_PSRule_Options` for details.
+### -InputStringFormat
 
-This parameter takes precedence over the `Input.Format` option if set.
+Configures the input format for when a string is passed in as a target object.
+This parameter also enables the format if it is not already enabled.
+
+When the `-InputObject` parameter or pipeline input is used, strings are treated as plain text by default.
+Set this option to an available format for example: `yaml`, `json`, `markdown`, `powershell_data`.
+
+This parameter takes precedence over the `Input.StringFormat` option if set.
 
 ```yaml
-Type: InputFormat
+Type: String
 Parameter Sets: (All)
 Aliases:
-Accepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect
 
 Required: False
 Position: Named
-Default value: Detect
+Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```