Refactoring for splitting runs #2611 (#2695)

microsoft · Jan 5, 2025 · db490dd · db490dd
1 parent cfc6575
commit db490dd
Show file tree

Hide file tree

Showing 45 changed files with 1,832 additions and 810 deletions.
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -27,8 +27,8 @@ env:
 permissions: {}
 
 jobs:
-  build:
-    name: Build
+  build_module:
+    name: Build module
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -76,10 +76,10 @@ jobs:
           retention-days: 3
           if-no-files-found: error
 
-  test:
-    name: 🧪 Test (${{ matrix.rid }}-${{ matrix.shell }})
+  test_module:
+    name: 🧪 Test module (${{ matrix.rid }}-${{ matrix.shell }})
     runs-on: ${{ matrix.os }}
-    needs: build
+    needs: build_module
     permissions:
       contents: read
 

diff --git a/README.md b/README.md
@@ -339,6 +339,9 @@ The following conceptual topics exist in the `PSRule` module:
   - [Rule.IncludeLocal](https://aka.ms/ps-rule/options#ruleincludelocal)
   - [Rule.Exclude](https://aka.ms/ps-rule/options#ruleexclude)
   - [Rule.Tag](https://aka.ms/ps-rule/options#ruletag)
+  - [Run.Category](https://aka.ms/ps-rule/options##runcategory)
+  - [Run.Description](https://aka.ms/ps-rule/options##rundescription)
+  - [Run.Instance](https://aka.ms/ps-rule/options##runinstance)
   - [Suppression](https://aka.ms/ps-rule/options#suppression)
 - [Rules](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Rules/)
 - [Selectors](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Selectors/)

diff --git a/docs/concepts/PSRule/en-US/about_PSRule_Options.md b/docs/concepts/PSRule/en-US/about_PSRule_Options.md
@@ -64,6 +64,9 @@ The following workspace options are available for use:
 - [Repository.BaseRef](#repositorybaseref)
 - [Repository.Url](#repositoryurl)
 - [Requires](#requires)
+- [Run.Category](#runcategory)
+- [Run.Description](#rundescription)
+- [Run.Instance](#runinstance)
 - [Suppression](#suppression)
 
 Additionally the following baseline options can be included:
@@ -3442,6 +3445,95 @@ rule:
 
 In the example above, rules must have a tag of `severity` set to either `Critical` or `Warning` to be included.
 
+### Run.Category
+
+<!-- module:version 3.0.0 -->
+
+Configures the run category that is used as an identifier for output results.
+By default, the run category is set to `PSRule`.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the Run.Category hashtable key
+$option = New-PSRuleOption -Option @{ 'Run.Category' = 'Custom run' };
+```
+
+```yaml
+# YAML: Using the run/category property
+run:
+  category: Custom run
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_RUN_CATEOGRY='Custom run'
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_RUN_CATEOGRY: 'Custom run'
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_RUN_CATEOGRY
+  value: 'Custom run'
+```
+
+### Run.Description
+
+<!-- module:version 3.0.0 -->
+
+Configure the run description that is displayed in output.
+By default, the run description is not set.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the Run.Description hashtable key
+$option = New-PSRuleOption -Option @{ 'Run.Description' = 'Custom run description.' };
+```
+
+```yaml
+# YAML: Using the run/description property
+run:
+  description: Custom run description.
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_RUN_DESCRIPTION='Custom run description.'
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_RUN_DESCRIPTION: 'Custom run description.'
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_RUN_DESCRIPTION
+  value: 'Custom run description.'
+```
+
+### Run.Instance
+
+<!-- module:version 3.0.0 -->
+
+An unique identifier for the current parent environment instance that is displayed in output as a component of the run ID.
+This is automatically set by PSRule when running in a GitHub Actions or Azure Pipeline pipeline.
+Alternatively, this option can be set using environment variables.
+
+```bash
+# Bash: Using environment variable
+export PSRULE_RUN_INSTANCE='12345678'
+```
+
 ### Suppression
 
 In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.

diff --git a/docs/concepts/runs.md b/docs/concepts/runs.md
@@ -0,0 +1,18 @@
+---
+title: About runs
+description: This article describes how PSRule organizes and manages each logical run.
+module: 3.0.0
+---
+
+# Runs
+
+This article describes how PSRule organizes and manages each logical run.
+
+When PSRule is executed one or more runs will be automatically created.
+
+## Configuring runs
+
+PSRule allows the following options to be configured that affects runs:
+
+- [Execution.Category]
+- [Execution.Description]
diff --git a/docs/concepts/sarif-format.md b/docs/concepts/sarif-format.md
@@ -12,8 +12,75 @@ When running PSRule executed a run will be generated in `runs` containing detail
 
 ## Invocation
 
-The `invocation` property reports runtime information about how the run started.
+The `invocations` property reports runtime information about how the run started.
 
 ### RuleConfigurationOverrides
 
 When a rule has been overridden in configuration this invocation property will contain any level overrides.
+
+## Examples
+
+### Successful result
+
+```json
+{
+  "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
+  "version": "2.1.0",
+  "runs": [
+    {
+      "tool": {
+        "driver": {
+          "guid": "0130215d-58eb-4887-b6fa-31ed02500569",
+          "name": "PSRule",
+          "organization": "Microsoft Corporation",
+          "semanticVersion": "2.9.0",
+          "informationUri": "https://aka.ms/ps-rule"
+        },
+        "extensions": [
+          {
+            "guid": "7bfb5234-1648-4e52-956c-42f303d416cb",
+            "name": "PSRule.Rules.MSFT.OSS",
+            "organization": "Microsoft Corporation",
+            "version": "1.1.0",
+            "informationUri": "https://github.com/microsoft/PSRule.Rules.MSFT.OSS",
+            "associatedComponent": {
+              "name": "PSRule"
+            }
+          }
+        ]
+      },
+      "automationDetails": {
+        "id": "CI repository scan/workspace/1",
+        "description": {
+          "text": "An analysis scan that checks repository files."
+        },
+        "correlationGuid": "00000000-0000-0000-0000-000000000000"
+      },
+      "invocations": [
+        {
+          "executionSuccessful": true
+        }
+      ],
+      "versionControlProvenance": [
+        {
+          "repositoryUri": "https://github.com/microsoft/PSRule",
+          "revisionId": "2a3671213e5768aad6af7f132e418d1a4368a3c5",
+          "branch": "main",
+          "mappedTo": {
+            "uriBaseId": "REPO_ROOT"
+          }
+        }
+      ],
+      "originalUriBaseIds": {
+        "REPO_ROOT": {
+          "description": {
+            "text": "The directory into which the repo was cloned."
+          }
+        }
+      },
+      "results": [],
+      "columnKind": "utf16CodeUnits"
+    }
+  ]
+}
+```
diff --git a/docs/examples/baseline/Baseline.Rule.yaml b/docs/examples/baseline/Baseline.Rule.yaml
@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+---
+# Synopsis: An example baseline.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Baseline
+metadata:
+  name: Baseline.Rule
+  displayName: Baseline.Rule
+  description: An example baseline.
+spec: {}
diff --git a/docs/examples/sarif/basic-1.sarif b/docs/examples/sarif/basic-1.sarif
@@ -0,0 +1,60 @@
+{
+  "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
+  "version": "2.1.0",
+  "runs": [
+    {
+      "automationDetails": {
+        "id": "CI repository scan/workspace/1",
+        "description": {
+          "text": "An analysis scan that checks repository files."
+        },
+        "correlationGuid": "00000000-0000-0000-0000-000000000000"
+      },
+      "tool": {
+        "driver": {
+          "guid": "0130215d-58eb-4887-b6fa-31ed02500569",
+          "name": "PSRule",
+          "organization": "Microsoft Corporation",
+          "semanticVersion": "2.9.0",
+          "informationUri": "https://aka.ms/ps-rule"
+        },
+        "extensions": [
+          {
+            "guid": "7bfb5234-1648-4e52-956c-42f303d416cb",
+            "name": "PSRule.Rules.MSFT.OSS",
+            "organization": "Microsoft Corporation",
+            "version": "1.1.0",
+            "informationUri": "https://github.com/microsoft/PSRule.Rules.MSFT.OSS",
+            "associatedComponent": {
+              "name": "PSRule"
+            }
+          }
+        ]
+      },
+      "invocations": [
+        {
+          "executionSuccessful": true
+        }
+      ],
+      "versionControlProvenance": [
+        {
+          "repositoryUri": "https://github.com/microsoft/PSRule",
+          "revisionId": "2a3671213e5768aad6af7f132e418d1a4368a3c5",
+          "branch": "main",
+          "mappedTo": {
+            "uriBaseId": "REPO_ROOT"
+          }
+        }
+      ],
+      "originalUriBaseIds": {
+        "REPO_ROOT": {
+          "description": {
+            "text": "The directory into which the repo was cloned."
+          }
+        }
+      },
+      "results": [],
+      "columnKind": "utf16CodeUnits"
+    }
+  ]
+}
diff --git a/ps-rule-ci.yaml b/ps-rule-ci.yaml
@@ -9,6 +9,10 @@ repository:
   url: https://github.com/microsoft/PSRule
   baseRef: main
 
+run:
+  category: CI repository scan
+  description: An analysis scan that checks repository files aligned to expected format requirements.
+
 output:
   culture:
     - en-US

diff --git a/ps-rule.yaml b/ps-rule.yaml
@@ -9,6 +9,10 @@ repository:
   url: https://github.com/microsoft/PSRule
   baseRef: main
 
+run:
+  category: Scan for tests
+  description: This is used for unit testing and should not be used directly.
+
 output:
   culture:
     - en-US

diff --git a/schemas/PSRule-options.schema.json b/schemas/PSRule-options.schema.json
@@ -784,6 +784,29 @@
       },
       "additionalProperties": false
     },
+    "run-option": {
+      "type": "object",
+      "title": "Run",
+      "description": "Configures run options.",
+      "markdownDescription": "Configures run options.",
+      "properties": {
+        "category": {
+          "type": "string",
+          "title": "Category",
+          "description": "Configures the run category that is used as an identifier for output results. By default, the category is PSRule.",
+          "markdownDescription": "Configures the run category that is used as an identifier for output results. By default, the category is `PSRule`.\n\n[See help](https://microsoft.github.io/PSRule/v3/concepts/PSRule/en-US/about_PSRule_Options/#executioncategory)",
+          "default": "PSRule"
+        },
+        "description": {
+          "type": "string",
+          "title": "Description",
+          "description": "Configure the run description that is displayed in output. By default, the description is empty.",
+          "markdownDescription": "Configure the run description that is displayed in output. By default, the description is empty.\n\n[See help](https://microsoft.github.io/PSRule/v3/concepts/PSRule/en-US/about_PSRule_Options/#executiondescription)",
+          "default": ""
+        }
+      },
+      "additionalProperties": false
+    },
     "suppression-option": {
       "type": "object",
       "title": "Suppress rules",
@@ -1123,6 +1146,10 @@
             }
           ]
         },
+        "run": {
+          "type": "object",
+          "$ref": "#/definitions/run-option"
+        },
         "suppression": {
           "type": "object",
           "oneOf": [

diff --git a/src/PSRule.Types/Environment.cs b/src/PSRule.Types/Environment.cs
@@ -163,17 +163,13 @@ public static bool IsVisualStudioCode()
     }
 
     /// <summary>
-    /// Get the run identifier for the current environment.
+    /// Get the run instance identifier for the current environment.
     /// </summary>
-    public static string? GetRunId()
+    public static string? GetRunInstance()
     {
-        if (TryString("PSRULE_RUN_ID", out var runId) && runId != null)
-            return runId;
-
-        return TryString("BUILD_REPOSITORY_NAME", out var prefix) && TryString("BUILD_BUILDID", out var suffix) ||
-            TryString("GITHUB_REPOSITORY", out prefix) && TryString("GITHUB_RUN_ID", out suffix)
-            ? string.Concat(prefix, "/", suffix)
-            : null;
+        return TryString("PSRULE_RUN_INSTANCE", out var runId) ||
+            TryString("BUILD_BUILDID", out runId) ||
+            TryString("GITHUB_RUN_ID", out runId) ? runId : null;
     }
 
     /// <summary>