🚀[Feature]: Linting and Documentation Improvements with Conditional Summary Option (#226)

MariusStorhaug · Copilot · web-flow · commit ea29e6bb28e3 · 2025-10-08T22:25:07.000+02:00
This pull request introduces improvements to the linting workflows and
documentation, adds new configuration options for linter summary
reporting, and updates test scripts for better visibility. The main
focus is on allowing users to optionally display the super-linter
summary even when no issues are found, and on clarifying documentation
and prompts related to repository operations.

**Workflow and Linter Enhancements:**

* Added `ShowSummaryOnSuccess` option for both documentation and
codebase linting workflows, allowing the super-linter summary to be
displayed even on successful runs. Updated the workflows to post the
summary conditionally based on this setting.
(`.github/workflows/Build-Docs.yml`, `.github/workflows/workflow.yml`,
[[1]](diffhunk://#diff-126bf89616b7daa3d14ebc882ad18666aaf1c3dae888c4ba306a66ec80758bc1R135-R155)
[[2]](diffhunk://#diff-126bf89616b7daa3d14ebc882ad18666aaf1c3dae888c4ba306a66ec80758bc1R189)
[[3]](diffhunk://#diff-7671544ba08199b4a27426300b58127b470b79b74ee36d823dacd165a01036eeR35-R39)
[[4]](diffhunk://#diff-7671544ba08199b4a27426300b58127b470b79b74ee36d823dacd165a01036eeR104-L106)
[[5]](diffhunk://#diff-7671544ba08199b4a27426300b58127b470b79b74ee36d823dacd165a01036eeR122-R136)
* Extended the settings parsing logic to support the new
`ShowSummaryOnSuccess` option for both `Build.Docs` and `Linter`
configurations. (`.github/workflows/Get-Settings.yml`,
[[1]](diffhunk://#diff-68f351d419a9b4db4797434891d5dfad44d83de65bfee7ba1c60badae369dbefR213)
[[2]](diffhunk://#diff-68f351d419a9b4db4797434891d5dfad44d83de65bfee7ba1c60badae369dbefR236)

**Documentation Updates:**

* Updated `README.md` to document the new `ShowSummaryOnSuccess` options
for both documentation and linter workflows, including example
configuration and explanation of its usage. (`README.md`,
[[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R252)
[[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R265)
[[3]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R280)
[[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R338)
[[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R426-R436)
* Added a new section to `.github/copilot-instructions.md` for
process-related Copilot instructions.

**Prompt and Command Improvements:**

* Clarified execution steps in `.github/prompts/pr.prompt.md` to specify
changing directory to the root of the attached git folder, and updated
references to GitHub MCP tool commands to use simplified names.
[[1]](diffhunk://#diff-3f8b5491849b0980eb754bd1a7323ca0fbd2d76dee5d0ae0aad303f07768d291L27-R28)
[[2]](diffhunk://#diff-3f8b5491849b0980eb754bd1a7323ca0fbd2d76dee5d0ae0aad303f07768d291L136-R139)

**Test Script Output Improvements:**

* Changed test setup and teardown scripts (`BeforeAll.ps1`,
`AfterAll.ps1`) in both test repositories to use `Write-Warning` instead
of `Write-Host` for better visibility of important messages.
(`tests/srcTestRepo/tests/BeforeAll.ps1`,
[[1]](diffhunk://#diff-194f79f552d669f15c73686eb90d586526eeee16a80ffe29c59dc5bd2697d77cL1-R2)
[[2]](diffhunk://#diff-194f79f552d669f15c73686eb90d586526eeee16a80ffe29c59dc5bd2697d77cL11-R12);
`tests/srcTestRepo/tests/AfterAll.ps1`,
[[3]](diffhunk://#diff-cfa4b632600f9dd5021c13fd59ae56acc5beb93769f64e5837c2b1a4bfa6d181L1-R2)
[[4]](diffhunk://#diff-cfa4b632600f9dd5021c13fd59ae56acc5beb93769f64e5837c2b1a4bfa6d181L11-R12);
`tests/srcWithManifestTestRepo/tests/BeforeAll.ps1`,
[[5]](diffhunk://#diff-4cc16ad5f540b198000f334246b4076322e9c2ecc00a8d5cd76a8d7f8f2d7cd4L1-R8);
`tests/srcWithManifestTestRepo/tests/AfterAll.ps1`,
[[6]](diffhunk://#diff-14dad688a5e209acb84a45277e1c27d98f241cbe994c8450450edfae4e2f6449L1-R8)

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,3 +1,5 @@
+# GitHub Copilot Instructions for Process-PSModule
+
 ## Terminal Commands
 
 When executing terminal commands (using `run_in_terminal` or similar tools):
diff --git a/.github/prompts/pr.prompt.md b/.github/prompts/pr.prompt.md
@@ -24,7 +24,8 @@ $ARGUMENTS
 
 ## Execution Steps
 
-0. Change directory to the repository root if not already there.
+0. If a folder is **explicitly attached to this chat** (“references”), you **must** change directory to the root of the git folder it is in. If there are no git folders you can change to the provided folder.
+
 1. **Detect repository mode**:
    - Run `git remote -v` to check configured remotes.
    - **If `upstream` remote exists**: Fork mode
@@ -133,9 +134,9 @@ $ARGUMENTS
    - Set PR to target the default branch (main/master) of the target repository
    - Open as a **draft PR** (or keep as draft if updating)
    - **Use GitHub MCP tools** to perform these operations in the **target repository**:
-     - Create PR (if not exists) - owner/repo should be target repository, use `mcp_github_github_create_pull_request`
-     - Update PR (if exists) - owner/repo should be target repository, use `mcp_github_github_update_pull_request`
-     - Add labels to PR - owner/repo should be target repository, use `mcp_github_github_add_labels_to_issue` (PRs are issues in GitHub API)
+     - Create PR (if not exists) - owner/repo should be target repository, use `create_pull_request`
+     - Update PR (if exists) - owner/repo should be target repository, use `update_pull_request`
+     - Add labels to PR - owner/repo should be target repository, use `update_issue` (PRs are issues in GitHub API)
 
 8. **Apply labels to the PR**:
    - Add the **change type label** based on the type specified (Major, Minor, Patch, Fix, or Docs)
diff --git a/.github/workflows/Build-Docs.yml b/.github/workflows/Build-Docs.yml
@@ -32,6 +32,11 @@ on:
         description: The working directory where the script will run from.
         required: false
         default: '.'
+      ShowSummaryOnSuccess:
+        type: boolean
+        description: Whether to show the super-linter summary on success.
+        required: false
+        default: false
 
 permissions:
   contents: read # to checkout the repo
@@ -96,14 +101,15 @@ jobs:
             }
 
       - name: Lint documentation
+        id: super-linter
         uses: super-linter/super-linter/slim@7bba2eeb89d01dc9bfd93c497477a57e72c83240 # v8.2.0
         env:
-          FILTER_REGEX_INCLUDE: outputs/docs
+          RUN_LOCAL: true
           DEFAULT_BRANCH: main
           DEFAULT_WORKSPACE: ${{ inputs.WorkingDirectory }}
+          FILTER_REGEX_INCLUDE: ${{ inputs.WorkingDirectory }}/outputs/docs
           ENABLE_GITHUB_ACTIONS_GROUP_TITLE: true
           GITHUB_TOKEN: ${{ github.token }}
-          RUN_LOCAL: true
           VALIDATE_ALL_CODEBASE: true
           VALIDATE_BIOME_FORMAT: false
           VALIDATE_BIOME_LINT: false
@@ -113,3 +119,18 @@ jobs:
           VALIDATE_JSON_PRETTIER: false
           VALIDATE_MARKDOWN_PRETTIER: false
           VALIDATE_YAML_PRETTIER: false
+          ENABLE_GITHUB_ACTIONS_STEP_SUMMARY: false
+          SAVE_SUPER_LINTER_SUMMARY: true
+
+      - name: Post super-linter summary
+        if: failure() || inputs.ShowSummaryOnSuccess == true
+        shell: pwsh
+        run: |
+          $summaryPath = Join-Path $env:GITHUB_WORKSPACE 'super-linter-output' 'super-linter-summary.md'
+          Get-Content $summaryPath | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8
+
+          $failed = '${{ steps.super-linter.outcome }}' -eq 'failure'
+          if ($failed) {
+              Write-Host "::error::Super-linter found issues. Please review the summary above."
+              exit 1
+          }
diff --git a/.github/workflows/Get-Settings.yml b/.github/workflows/Get-Settings.yml
@@ -209,7 +209,8 @@ jobs:
                         Skip = $settings.Build.Module.Skip ?? $false
                     }
                     Docs   = [pscustomobject]@{
-                        Skip = $settings.Build.Docs.Skip ?? $false
+                        Skip                 = $settings.Build.Docs.Skip ?? $false
+                        ShowSummaryOnSuccess = $settings.Build.Docs.ShowSummaryOnSuccess ?? $false
                     }
                     Site = [pscustomobject]@{
                         Skip = $settings.Build.Site.Skip ?? $false
@@ -231,8 +232,9 @@ jobs:
 
                 }
                 Linter  = [pscustomobject]@{
-                    Skip = $settings.Linter.Skip ?? $false
-                    env  = $settings.Linter.env ?? @{}
+                    Skip                 = $settings.Linter.Skip ?? $false
+                    ShowSummaryOnSuccess = $settings.Linter.ShowSummaryOnSuccess ?? $false
+                    env                  = $settings.Linter.env ?? @{}
                 }
             }
             LogGroup "Final settings" {
diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -132,9 +132,27 @@ jobs:
           }
 
       - name: Lint code base
+        id: super-linter
         uses: super-linter/super-linter@7bba2eeb89d01dc9bfd93c497477a57e72c83240 # v8.2.0
         env:
           GITHUB_TOKEN: ${{ github.token }}
+          DEFAULT_WORKSPACE: ${{ inputs.WorkingDirectory }}
+          FILTER_REGEX_INCLUDE: ${{ inputs.WorkingDirectory }}
+          ENABLE_GITHUB_ACTIONS_STEP_SUMMARY: false
+          SAVE_SUPER_LINTER_SUMMARY: true
+
+      - name: Post super-linter summary
+        if: failure() || fromJson(needs.Get-Settings.outputs.Settings).Linter.ShowSummaryOnSuccess == true
+        shell: pwsh
+        run: |
+          $summaryPath = Join-Path $env:GITHUB_WORKSPACE 'super-linter-output' 'super-linter-summary.md'
+          Get-Content $summaryPath | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8
+
+          $failed = '${{ steps.super-linter.outcome }}' -eq 'failure'
+          if ($failed) {
+              Write-Host "::error::Super-linter found issues. Please review the summary above."
+              exit 1
+          }
 
   # Runs on:
   # - ✅ Open/Updated PR - Builds module for testing
@@ -168,6 +186,7 @@ jobs:
       Verbose: ${{ inputs.Verbose }}
       Version: ${{ inputs.Version }}
       WorkingDirectory: ${{ inputs.WorkingDirectory }}
+      ShowSummaryOnSuccess: ${{ fromJson(needs.Get-Settings.outputs.Settings).Build.Docs.ShowSummaryOnSuccess }}
 
   # Runs on:
   # - ✅ Open/Updated PR - Builds site for preview
diff --git a/README.md b/README.md
@@ -249,6 +249,7 @@ The following settings are available in the settings file:
 | `Build.Skip`                           | `Boolean` | Skip all build tasks                                                                                     | `false`             |
 | `Build.Module.Skip`                    | `Boolean` | Skip module build                                                                                        | `false`             |
 | `Build.Docs.Skip`                      | `Boolean` | Skip documentation build                                                                                 | `false`             |
+| `Build.Docs.ShowSummaryOnSuccess`      | `Boolean` | Show super-linter summary on success for documentation linting                                           | `false`             |
 | `Build.Site.Skip`                      | `Boolean` | Skip site build                                                                                          | `false`             |
 | `Publish.Module.Skip`                  | `Boolean` | Skip module publishing                                                                                   | `false`             |
 | `Publish.Module.AutoCleanup`           | `Boolean` | Automatically cleanup old prerelease module versions                                                     | `true`              |
@@ -261,6 +262,7 @@ The following settings are available in the settings file:
 | `Publish.Module.PatchLabels`           | `String`  | Labels indicating a patch version bump                                                                   | `'patch, fix'`      |
 | `Publish.Module.IgnoreLabels`          | `String`  | Labels indicating no release                                                                             | `'NoRelease'`       |
 | `Linter.Skip`                          | `Boolean` | Skip repository linting                                                                                  | `false`             |
+| `Linter.ShowSummaryOnSuccess`          | `Boolean` | Show super-linter summary on success for repository linting                                              | `false`             |
 | `Linter.env`                           | `Object`  | Environment variables for super-linter configuration                                                     | `{}`                |
 
 <details>
@@ -275,6 +277,7 @@ Build:
     Skip: false
   Docs:
     Skip: false
+    ShowSummaryOnSuccess: false
   Site:
     Skip: false
 
@@ -332,6 +335,7 @@ Publish:
 
 Linter:
   Skip: false
+  ShowSummaryOnSuccess: false
   env: {}
 
 ```
@@ -419,6 +423,17 @@ Linter:
     VALIDATE_ALL_CODEBASE: false
 ```
 
+#### Showing Linter Summary on Success
+
+By default, the linter only shows a summary when it finds issues. You can enable summary display on successful runs:
+
+```yaml
+Linter:
+  ShowSummaryOnSuccess: true
+```
+
+This is useful for reviewing what was checked even when no issues are found.
+
 **Note:** The `GITHUB_TOKEN` is automatically provided by the workflow to enable status updates in pull requests.
 
 For a complete list of available environment variables and configuration options, see the
diff --git a/tests/srcTestRepo/tests/AfterAll.ps1 b/tests/srcTestRepo/tests/AfterAll.ps1
@@ -1,5 +1,5 @@
-Write-Host "=== AFTERALL TEARDOWN SCRIPT EXECUTING ==="
-Write-Host "Tearing down test environment..."
+Write-Warning "=== AFTERALL TEARDOWN SCRIPT EXECUTING ==="
+Write-Warning "Tearing down test environment..."
 
 # Example teardown tasks:
 # - Clean up test infrastructure
@@ -8,5 +8,5 @@ Write-Host "Tearing down test environment..."
 # - Drop test databases
 # - Stop test services
 
-Write-Host "Test environment teardown completed successfully!"
-Write-Host "=== AFTERALL TEARDOWN SCRIPT COMPLETED ==="
+Write-Warning "Test environment teardown completed successfully!"
+Write-Warning "=== AFTERALL TEARDOWN SCRIPT COMPLETED ==="
diff --git a/tests/srcTestRepo/tests/BeforeAll.ps1 b/tests/srcTestRepo/tests/BeforeAll.ps1
@@ -1,5 +1,5 @@
-Write-Host "=== BEFOREALL SETUP SCRIPT EXECUTING ==="
-Write-Host "Setting up test environment..."
+Write-Warning "=== BEFOREALL SETUP SCRIPT EXECUTING ==="
+Write-Warning "Setting up test environment..."
 
 # Example setup tasks:
 # - Deploy test infrastructure
@@ -8,5 +8,5 @@ Write-Host "Setting up test environment..."
 # - Set up test databases
 # - Configure test services
 
-Write-Host "Test environment setup completed successfully!"
-Write-Host "=== BEFOREALL SETUP SCRIPT COMPLETED ==="
+Write-Warning "Test environment setup completed successfully!"
+Write-Warning "=== BEFOREALL SETUP SCRIPT COMPLETED ==="
diff --git a/tests/srcWithManifestTestRepo/tests/AfterAll.ps1 b/tests/srcWithManifestTestRepo/tests/AfterAll.ps1
@@ -1,8 +1,8 @@
-Write-Host "=== AFTERALL TEARDOWN SCRIPT (Environments) EXECUTING ==="
-Write-Host "Tearing down test environment for Environments..."
+Write-Warning "=== AFTERALL TEARDOWN SCRIPT (Environments) EXECUTING ==="
+Write-Warning "Tearing down test environment for Environments..."
 
 # Example teardown tasks for Environments directory:
-Write-Host "Cleaning up Environments test environment..."
+Write-Warning "Cleaning up Environments test environment..."
 
-Write-Host "Environments environment teardown completed successfully!"
-Write-Host "=== AFTERALL TEARDOWN SCRIPT (Environments) COMPLETED ==="
+Write-Warning "Environments environment teardown completed successfully!"
+Write-Warning "=== AFTERALL TEARDOWN SCRIPT (Environments) COMPLETED ==="
diff --git a/tests/srcWithManifestTestRepo/tests/BeforeAll.ps1 b/tests/srcWithManifestTestRepo/tests/BeforeAll.ps1
@@ -1,8 +1,8 @@
-Write-Host "=== BEFOREALL SETUP SCRIPT EXECUTING ==="
-Write-Host "Setting up test environment..."
+Write-Warning "=== BEFOREALL SETUP SCRIPT EXECUTING ==="
+Write-Warning "Setting up test environment..."
 
 # Example setup tasks for test environment:
-Write-Host "Initializing test environment..."
+Write-Warning "Initializing test environment..."
 
-Write-Host "Test environment setup completed successfully!"
-Write-Host "=== BEFOREALL SETUP SCRIPT COMPLETED ==="
+Write-Warning "Test environment setup completed successfully!"
+Write-Warning "=== BEFOREALL SETUP SCRIPT COMPLETED ==="

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# GitHub Copilot Instructions for Process-PSModule`
	`2`	`+`
`1`	`3`	`## Terminal Commands`
`2`	`4`
`3`	`5`	When executing terminal commands (using `run_in_terminal` or similar tools):
Original file line number	Diff line number	Diff line change
`@@ -209,7 +209,8 @@ jobs:`
`209`	`209`	`Skip = $settings.Build.Module.Skip ?? $false`
`210`	`210`	`}`
`211`	`211`	`Docs = [pscustomobject]@{`
`212`		`- Skip = $settings.Build.Docs.Skip ?? $false`
	`212`	`+ Skip = $settings.Build.Docs.Skip ?? $false`
	`213`	`+ ShowSummaryOnSuccess = $settings.Build.Docs.ShowSummaryOnSuccess ?? $false`
`213`	`214`	`}`
`214`	`215`	`Site = [pscustomobject]@{`
`215`	`216`	`Skip = $settings.Build.Site.Skip ?? $false`
`@@ -231,8 +232,9 @@ jobs:`
`231`	`232`
`232`	`233`	`}`
`233`	`234`	`Linter = [pscustomobject]@{`
`234`		`- Skip = $settings.Linter.Skip ?? $false`
`235`		`- env = $settings.Linter.env ?? @{}`
	`235`	`+ Skip = $settings.Linter.Skip ?? $false`
	`236`	`+ ShowSummaryOnSuccess = $settings.Linter.ShowSummaryOnSuccess ?? $false`
	`237`	`+ env = $settings.Linter.env ?? @{}`
`236`	`238`	`}`
`237`	`239`	`}`
`238`	`240`	`LogGroup "Final settings" {`