🌟 [Major]: Introducing Get-PesterCodeCoverage (#1)

## Description

This pull request introduces the `Get-PesterCodeCoverage` GitHub Action
that aggregates Pester code coverage reports and generates a detailed
summary with coverage statistics.

### Core functionality

* `scripts/main.ps1`: Added functionality to aggregate Pester code
coverage reports, normalize file paths, and compute aggregate coverage
statistics. The action now enforces a coverage threshold and generates
detailed GitHub step summaries with expandable sections for missed and
executed commands.

### Tests
* `.github/workflows/Action-Test.yml`: Updated the `Action-Test.yml`
workflow to upload multiple code coverage artifacts for macOS and
Windows environments and added new parameters (`StepSummary_Mode` and
`CodeCoveragePercentTarget`) to control reporting behavior.
* `tests/*`: Added tests reports to use for the Action-Test workflow.

### Documentation
* `README.md`: Updated README to reflect the new functionality,
including detailed usage instructions, input descriptions, and example
workflows. Added a comprehensive explanation of outputs and behavior.

### Action Metadata

* `action.yml`: Updated to align with the new functionality. Added new
inputs (`StepSummary_Mode`, `CodeCoveragePercentTarget`) for
customization.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [x] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

Diff for: .github/workflows/Action-Test.yml

@@ -25,8 +25,57 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v4
 
+      # Upload artifact from tests:
+      - name: Upload artifact [Environments-macOS-CodeCoverage]
+        uses: actions/upload-artifact@v4
+        with:
+          name: Environments-macOS-CodeCoverage
+          path: ./tests/CodeCoverage/Environments-macOS-CodeCoverage
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Upload artifact [Environments-Windows-CodeCoverage]
+        uses: actions/upload-artifact@v4
+        with:
+          name: Environments-Windows-CodeCoverage
+          path: ./tests/CodeCoverage/Environments-Windows-CodeCoverage
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Upload artifact [Module-macOS-CodeCoverage]
+        uses: actions/upload-artifact@v4
+        with:
+          name: Module-macOS-CodeCoverage
+          path: ./tests/CodeCoverage/Module-macOS-CodeCoverage
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Upload artifact [Module-Windows-CodeCoverage]
+        uses: actions/upload-artifact@v4
+        with:
+          name: Module-Windows-CodeCoverage
+          path: ./tests/CodeCoverage/Module-Windows-CodeCoverage
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Upload artifact [MyTests-macOS-CodeCoverage]
+        uses: actions/upload-artifact@v4
+        with:
+          name: MyTests-macOS-CodeCoverage
+          path: ./tests/CodeCoverage/MyTests-macOS-CodeCoverage
+          retention-days: 1
+          if-no-files-found: error
+
+      - name: Upload artifact [MyTests-Windows-CodeCoverage]
+        uses: actions/upload-artifact@v4
+        with:
+          name: MyTests-Windows-CodeCoverage
+          path: ./tests/CodeCoverage/MyTests-Windows-CodeCoverage
+          retention-days: 1
+          if-no-files-found: error
+
       - name: Action-Test
         uses: ./
         with:
-          working-directory: ./tests
-          subject: PSModule
+          StepSummary_Mode: Full
+          CodeCoveragePercentTarget: 50

Diff for: .github/workflows/Auto-Release.yml

@@ -30,5 +30,3 @@ jobs:
 
       - name: Auto-Release
         uses: PSModule/Auto-Release@v1
-        env:
-          GITHUB_TOKEN: ${{ github.token }}

Diff for: README.md

@@ -1,17 +1,112 @@
-# Template-Action
+# Get-PesterCodeCoverage
 
-A template repository for GitHub Actions
+A GitHub Action that aggregates Pester code coverage reports and generates a detailed summary with coverage statistics.
+Fails the workflow if coverage falls below specified targets.
+
+This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the
+[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module.
+
+## Features
+
+- Combines multiple code coverage reports from parallel test runs
+- Generates markdown/HTML tables showing missed & executed commands
+- Displays analyzed files and coverage statistics
+- Configurable step summary sections
+- Threshold enforcement for minimum code coverage
 
 ## Usage
 
 ### Inputs
 
-### Secrets
+| Name | Description | Required | Default |
+|------|-------------|----------|---------|
+| `Debug` | Enable debug output | No | `false` |
+| `Verbose` | Enable verbose output | No | `false` |
+| `Version` | Exact version of GitHub module to install | No | Latest |
+| `Prerelease` | Allow prerelease versions | No | `false` |
+| `WorkingDirectory` | Working directory for the action | No | `.` |
+| `StepSummary_Mode` | Controls which sections to show in the GitHub step summary. Use 'Full' for all sections, 'None' to disable, or a comma-separated list of 'Missed, Executed, Files'. | No | `Missed, Files` |
+| `CodeCoveragePercentTarget` | Target code coverage percentage | No | Max target from individual reports |
+
+### Example Workflow
+
+```yaml
+    - name: Process Code Coverage
+      uses: PSModule/Get-PesterCodeCoverage@v1
+      with:
+        StepSummary_Mode: Full
+        CodeCoveragePercentTarget: 80
+```
+
+## Outputs
+
+### GitHub Step Summary
+
+The action generates a detailed summary visible in the GitHub Actions UI:
+
+1. **Coverage Overview Table**
+   - Coverage percentage vs target
+   - Analyzed/executed/missed command counts
+   - Number of files analyzed
+
+2. **Expandable Sections**
+   - **Missed Commands**: HTML table with code snippets
+   - **Executed Commands**: HTML table with code snippets
+   - **Analyzed Files**: List of covered files
+
+Example summary:
+
+```markdown
+✅ Code Coverage Report
+
+Summary:
+| Coverage | Target | Analyzed      | Executed      | Missed        | Files         |
+|----------|--------|---------------|---------------|---------------|---------------|
+| 85%      | 80%    | 1000 commands | 850 commands  | 150 commands  | 15 files      |
+
+▶️ Missed commands [150] (click to expand)
+▶️ Executed commands [850] (click to expand)
+▶️ Files analyzed [15] (click to expand)
+```
+
+## Requirements
+
+1. **Pester Code Coverage Reports**
+   Preceding steps must generate JSON coverage reports named `*-CodeCoverage*.json`
+
+2. **GitHub CLI**
+   The action uses `gh run download` to fetch artifacts from the current workflow run
+
+## Behavior
+
+1. **Coverage Calculation**
+   - Combines multiple coverage reports
+   - Removes duplicate entries
+   - Calculates aggregate coverage percentage
+
+2. **Threshold Enforcement**
+   Fails the workflow if coverage is below either:
+   - Explicitly specified `CodeCoveragePercentTarget`
+   - Highest target from individual reports (if no target specified)
+
+3. **Output Control**
+   Configure visibility of sections using `StepSummary_Mode`:
+   ```yaml
+   # Show all sections
+   StepSummary_Mode: Full
+
+   # Disable summary
+   StepSummary_Mode: None
 
-### Outputs
+   # Custom selection
+   StepSummary_Mode: Missed, Files
+   ```
 
-### Example
+## Troubleshooting
 
+Enable debugging by setting inputs:
 ```yaml
-Example here
+with:
+  Debug: true
+  Verbose: true
 ```

Diff for: action.yml

@@ -1,15 +1,11 @@
-name: {{ NAME }}
-description: {{ DESCRIPTION }}
+name: Get-PesterCodeCoverage
+description: A GitHub Action that is used to gather Code Coverage for the PSModule process.
 author: PSModule
 branding:
   icon: upload-cloud
   color: white
 
 inputs:
-  subject:
-    description: The subject to greet
-    required: false
-    default: World
   Debug:
     description: Enable debug output.
     required: false
@@ -28,21 +24,31 @@ inputs:
   WorkingDirectory:
     description: The working directory where the script will run from.
     required: false
-    default: ${{ github.workspace }}
+    default: '.'
+  StepSummary_Mode:
+    description: |
+      Controls which sections to show in the GitHub step summary.
+      Use 'Full' for all sections, 'None' to disable, or a comma-separated list of 'Missed, Executed, Files'.
+    required: false
+    default: Missed, Files
+  CodeCoveragePercentTarget:
+    description: The target for code coverage.
+    required: false
 
 runs:
   using: composite
   steps:
-    - name: {{ NAME }}
+    - name: Get-PesterCodeCoverage
       uses: PSModule/GitHub-Script@v1
       env:
-        {{ ORG }}_{{ NAME }}_INPUT_subject: ${{ inputs.subject }}
+        PSMODULE_GET_PESTERCODECOVERAGE_INPUT_StepSummary_Mode: ${{ inputs.StepSummary_Mode }}
+        PSMODULE_GET_PESTERCODECOVERAGE_INPUT_CodeCoveragePercentTarget: ${{ inputs.CodeCoveragePercentTarget }}
       with:
+        Name: Get-PesterCodeCoverage
         Debug: ${{ inputs.Debug }}
         Prerelease: ${{ inputs.Prerelease }}
         Verbose: ${{ inputs.Verbose }}
         Version: ${{ inputs.Version }}
         WorkingDirectory: ${{ inputs.WorkingDirectory }}
-        Script: |
-          # {{ NAME }}
-          ${{ github.action_path }}/scripts/main.ps1
+        ShowInfo: false
+        Script: ${{ github.action_path }}/scripts/main.ps1

Diff for: scripts/Helpers.psm1

@@ -0,0 +1,68 @@
+function Normalize-IndentationExceptFirst {
+    <#
+    .SYNOPSIS
+    Normalizes the indentation of a multi-line string, except for the first line.
+
+    .DESCRIPTION
+    This function takes a multi-line string and normalizes the indentation of all lines except the first one.
+    It removes the minimum leading whitespace from all subsequent lines.
+
+    .PARAMETER Code
+    The multi-line string to normalize.
+
+    .OUTPUTS
+    Returns the normalized multi-line string.
+    s#>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseApprovedVerbs', '', Scope = 'Function', Justification = 'Function isnt exported.')]
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Code
+    )
+
+    # Split the code into lines
+    $lines = $Code -split "`r?`n"
+
+    # If there's 0 or 1 line, there's nothing special to do
+    if ($lines.Count -le 1) {
+        return $Code
+    }
+
+    # The first line stays as-is; we skip it for indentation measurement
+    $firstLine = $lines[0]
+    $subsequentLines = $lines[1..($lines.Count - 1)]
+
+    # Find the minimum leading indentation among the *subsequent* lines
+    $minIndent = ($subsequentLines | Where-Object { $_ -match '\S' } | ForEach-Object {
+            # If the line starts with whitespace, capture how many characters
+            if ($_ -match '^(\s+)') {
+                $matches[1].Length
+            } else {
+                0
+            }
+        } | Measure-Object -Minimum).Minimum
+
+    # Remove that leading indentation from each subsequent line
+    for ($i = 0; $i -lt $subsequentLines.Count; $i++) {
+        $line = $subsequentLines[$i]
+
+        # Only attempt to remove indentation if we actually have some whitespace
+        if ($line -match '^(\s+)(.*)$') {
+            # $matches[1] = leading whitespace; $matches[2] = the rest
+            $leading = $matches[1]
+            $rest = $matches[2]
+
+            # If we have enough whitespace to remove $minIndent worth, do it
+            if ($leading.Length -ge $minIndent) {
+                $leading = $leading.Substring($minIndent)
+            }
+            # Recombine
+            $subsequentLines[$i] = $leading + $rest
+        }
+    }
+
+    $newLine = [Environment]::NewLine
+    # Reconstruct the final code: first line + adjusted subsequent lines
+    return ($firstLine + $newLine + ($subsequentLines -join $newLine))
+}