Expose format options to emitters #1838 (#2623)

* Expose format options to emitters #1838

* Fixes for validation

.github/workflows/analyze.yaml

@@ -39,6 +39,7 @@ jobs:
           prerelease: true
           outputFormat: Sarif
           outputPath: reports/ps-rule-results.sarif
+          option: ps-rule-ci.yaml
         env:
           PSRULE_INPUT_FILEOBJECTS: true
 

.markdownlint.json

@@ -23,7 +23,7 @@
     "line_length": 120,
     "code_blocks": false,
     "tables": false,
-    "headers": true
+    "headings": true
   },
   "commands-show-output": true,
   "no-missing-space-atx": true,
@@ -64,5 +64,6 @@
     "code_blocks": false
   },
   "no-alt-text": true,
-  "code-block-style": false
+  "code-block-style": false,
+  "MD025": false
 }

README.md

@@ -302,6 +302,7 @@ The following conceptual topics exist in the `PSRule` module:
   - [Execution.RuleInconclusive](https://aka.ms/ps-rule/options#executionruleinconclusive)
   - [Execution.SuppressionGroupExpired](https://aka.ms/ps-rule/options#executionsuppressiongroupexpired)
   - [Execution.UnprocessedObject](https://aka.ms/ps-rule/options#executionunprocessedobject)
+  - [Format](https://aka.ms/ps-rule/options#format)
   - [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)

docs/CHANGELOG-v3.md

@@ -27,6 +27,12 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 ## Unreleased
 
+What's changed since pre-release v3.0.0-B0315:
+
+- General improvements:
+  - Expose format options to emitters by @BernieWhite.
+    [#1838](https://github.com/microsoft/PSRule/issues/1838)
+
 ## v3.0.0-B0315 (pre-release)
 
 What's changed since pre-release v3.0.0-B0275:

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

@@ -33,6 +33,7 @@ The following workspace options are available for use:
 - [Execution.RuleInconclusive](#executionruleinconclusive)
 - [Execution.SuppressionGroupExpired](#executionsuppressiongroupexpired)
 - [Execution.UnprocessedObject](#executionunprocessedobject)
+- [Format](#format)
 - [Include.Module](#includemodule)
 - [Include.Path](#includepath)
 - [Input.FileObjects](#inputfileobjects)
@@ -1470,6 +1471,64 @@ variables:
   value: Ignore
 ```
 
+### Format
+
+:octicons-milestone-24: v3.0.0
+
+Configures each format by setting mapped types.
+The following built-in types can be configured:
+
+- `yaml`
+- `json`
+- `markdown`
+- `powershell_data`
+
+The following is the default configuration for each format:
+
+```yaml
+format:
+  yaml:
+    types:
+      - .yaml
+      - .yml
+  json:
+    types:
+      - .json
+      - .jsonc
+      - .sarif
+  markdown:
+    types:
+      - .md
+      - .markdown
+  powershell_data:
+    types:
+      - .psd1
+```
+
+The configuration for each built-in or custom format a hashtable key by using the name:
+
+```powershell
+$option = New-PSRuleOption -Option @{ 'Format.<FORMAT>.Type' = value };
+```
+
+For example:
+
+```powershell
+$option = New-PSRuleOption -Option @{ 'Format.Yaml.Type' = @('.yaml', '.yml') };
+```
+
+The configuration for each built-in or custom format can be set by environment variable by using the name:
+
+```text
+PSRULE_FORMAT_<FORMAT>_TYPE='<value>'
+```
+
+For example:
+
+```bash
+export PSRULE_FORMAT_YAML_TYPES='.yaml;.yml'
+```
+
 ### Include.Module
 
 Automatically include rules and resources from the specified module.
@@ -3588,6 +3647,25 @@ execution:
   suppressionGroupExpired: Warn
   unprocessedObject: Warn
 
+# Configure formats
+format:
+  yaml:
+    types:
+      - .yaml
+      - .yml
+  json:
+    types:
+      - .json
+      - .jsonc
+      - .sarif
+  markdown:
+    types:
+      - .md
+      - .markdown
+  powershell_data:
+    types:
+      - .psd1
+
 # Configure include options
 include:
   module: [ ]

docs/concepts/emitters.md

@@ -0,0 +1,56 @@
+---
+title: About emitters
+module: 3.0.0
+---
+
+# Emitters
+
+Emitters allows complex structures and files types (formats) to be pre-processed and resulting objects extracted.
+Once processed, the resulting objects can be evaluated by rules.
+
+## Built-in emitters
+
+PSRule ships with several built-in emitters for common formats, including:
+
+- YAML (`yaml`)
+- JSON (`json`)
+- Markdown (`markdown`)
+- PowerShell Data (`powershell_data`)
+
+The following file extensions are configured by default for each format.
+
+Name              | Default file extensions      | Configurable
+----              | -----------------------      | :----------:
+`yaml`            | `.yaml`, `.yml`              | Yes
+`json`            | `.json`, `.jsonc`, `.sarif`  | Yes
+`markdown`        | `.md`, `.markdown`           | Yes
+`powershell_data` | `.psd1`                      | Yes
+
+## Custom emitters
+
+Custom emitters are a planned feature in PSRule v3.
+
+## Configuring formats
+
+The file or object types that each emitter processes is configurable by setting the [Format option](PSRule/en-US/about_PSRule_Options.md#format).
+This allows custom types and file extensions to be easily added or removed to a compatible emitter.
+
+For example, many configuration files use JSON but may end with a different file extension.
+The extensions that will be processed can be overridden by setting the `format.json.types` key in `ps-rule.yaml`.
+To change the file extension to be processed as JSON the following option can be set:
+
+```yaml
+format:
+  json:
+    types:
+      - .json
+      - .jsonc
+      - .jsn
+```
+
+### Advanced configuration
+
+Emitters may support additional options or feature flags for configuration.
+Set these, by using the [Configuration](PSRule/en-US/about_PSRule_Options.md#configuration) option.
+
+Currently there is no advanced configuration options for built-in emitters.

mkdocs.yml

@@ -65,6 +65,7 @@ nav:
           - Using PSRule from a Container: scenarios/containers/container-execution.md
       - Concepts:
           - Baselines: concepts/baselines.md
+          - Emitters: concepts/emitters.md
           - Functions: expressions/functions.md
           - Grouping rules: concepts/grouping-rules.md
           - Sub-selectors: expressions/sub-selectors.md

pipeline.build.ps1

@@ -341,7 +341,7 @@ task Rules {
         As = 'Summary'
     }
     Import-Module (Join-Path -Path $PWD -ChildPath out/modules/PSRule) -Force;
-    Assert-PSRule @assertParams -OutputPath reports/ps-rule-file.xml -InputPath $PWD -ErrorAction Stop -Option @{ 'Input.FileObjects' = $True };
+    Assert-PSRule @assertParams -OutputPath reports/ps-rule-file.xml -InputPath $PWD -ErrorAction Stop -Option ./ps-rule-ci.yaml;
 }
 
 task Benchmark {

ps-rule-ci.yaml

@@ -0,0 +1,28 @@
+#
+# PSRule configuration for CI of PSRule repo.
+#
+
+# Please see the documentation for all configuration options:
+# https://microsoft.github.io/PSRule/
+
+repository:
+  url: https://github.com/microsoft/PSRule
+  baseRef: main
+
+output:
+  culture:
+    - en-US
+
+format:
+  powershell_data:
+    type: []
+
+input:
+  fileObjects: true
+  pathIgnore:
+    - '**'
+    - '!**/*.cs'
+    - '!**/*.ps1'
+    - '!**/*.psd1'
+    - '!**/*.psm1'
+    - '*.Designer.cs'