Merge remote-tracking branch 'origin/main' into github-app-planning

Author: MariusStorhaug

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1

@@ -260,7 +260,8 @@
             Write-Host "Processing required module [$requiredModuleName]"
             $requiredVersion = $group.Group.RequiredVersion | ForEach-Object { [Version]$_ } | Sort-Object -Unique
             $minimumVersion = $group.Group.Version | ForEach-Object { [Version]$_ } | Sort-Object -Unique | Select-Object -Last 1
-            $maximumVersion = $group.Group.MaximumVersion | ForEach-Object { [Version]$_ } | Sort-Object -Unique | Select-Object -First 1
+            $maximumVersion = $group.Group.MaximumVersion | Sort-Object -Unique | Select-Object -First 1
+            $maximumVersionBound = if ($maximumVersion -and ($maximumVersion -notmatch '[*]')) { [Version]$maximumVersion } else { $null }
             Write-Host "RequiredVersion: [$($requiredVersion -join ', ')]"
             Write-Host "ModuleVersion:   [$minimumVersion]"
             Write-Host "MaximumVersion:  [$maximumVersion]"
@@ -274,17 +275,17 @@
             }
 
             if (-not $maximumVersion) {
-                $maximumVersion = [Version]'9999.9999.9999'
+                $maximumVersionBound = [Version]'9999.9999.9999'
             }
 
             if ($requiredVersion -and ($minimumVersion -gt $requiredVersion)) {
                 throw 'ModuleVersion is higher than RequiredVersion.'
             }
 
-            if ($minimumVersion -gt $maximumVersion) {
+            if ($maximumVersionBound -and ($minimumVersion -gt $maximumVersionBound)) {
                 throw 'ModuleVersion is higher than MaximumVersion.'
             }
-            if ($requiredVersion -and ($requiredVersion -gt $maximumVersion)) {
+            if ($requiredVersion -and $maximumVersionBound -and ($requiredVersion -gt $maximumVersionBound)) {
                 throw 'RequiredVersion is higher than MaximumVersion.'
             }
 
@@ -294,15 +295,15 @@
                     ModuleName      = $requiredModuleName
                     RequiredVersion = $requiredVersion
                 }
-            } elseif (($minimumVersion -ne [Version]'0.0.0') -or ($maximumVersion -ne [Version]'9999.9999.9999')) {
+            } elseif (($minimumVersion -ne [Version]'0.0.0') -or ($maximumVersionBound -ne [Version]'9999.9999.9999')) {
                 Write-Host '[RequiredModules] - ModuleVersion/MaximumVersion'
                 $uniqueModule = @{
                     ModuleName = $requiredModuleName
                 }
                 if ($minimumVersion -ne [Version]'0.0.0') {
                     $uniqueModule['ModuleVersion'] = $minimumVersion
                 }
-                if ($maximumVersion -ne [Version]'9999.9999.9999') {
+                if ($maximumVersionBound -ne [Version]'9999.9999.9999') {
                     $uniqueModule['MaximumVersion'] = $maximumVersion
                 }
             } else {

.github/actions/Cleanup-PSModulePrereleases/action.yml

@@ -7,6 +7,10 @@ inputs:
     description: Control whether to automatically delete prerelease tags.
     required: false
     default: 'true'
+  ReleaseTag:
+    description: GitHub release tag to retain during cleanup.
+    required: false
+    default: ''
   WhatIf:
     description: If specified, the action will only log the changes it would make.
     required: false
@@ -29,5 +33,5 @@ runs:
       env:
         GH_TOKEN: ${{ env.GH_TOKEN }}
         PSMODULE_CLEANUP_PSMODULEPRERELEASES_INPUT_WhatIf: ${{ inputs.WhatIf }}
-        PSMODULE_CLEANUP_PSMODULEPRERELEASES_CONTEXT_ReleaseTag: ${{ env.PSMODULE_PUBLISH_PSMODULE_CONTEXT_ReleaseTag }}
+        PSMODULE_CLEANUP_PSMODULEPRERELEASES_CONTEXT_ReleaseTag: ${{ inputs.ReleaseTag }}
       run: ${{ github.action_path }}/src/cleanup.ps1

.github/actions/Get-PesterCodeCoverage/README.md

@@ -9,8 +9,9 @@ This GitHub Action is a part of the [PSModule framework](https://github.com/PSMo
 ## Features
 
 - Combines multiple code coverage reports from parallel test runs
-- Generates markdown/HTML tables showing missed & executed commands
+- Generates Markdown/HTML tables showing missed & executed commands
 - Displays analyzed files and coverage statistics
+- Generates a generic missed-path report (Markdown + JSON)
 - Configurable step summary sections
 - Threshold enforcement for minimum code coverage
 
@@ -40,6 +41,10 @@ This GitHub Action is a part of the [PSModule framework](https://github.com/PSMo
 
 ## Outputs
 
+| Name | Description |
+| ---- | ----------- |
+| `MissedPathReportPath` | Folder path containing `CodeCoverage-MissedPaths.md` and `CodeCoverage-MissedPaths.json` |
+
 ### GitHub Step Summary
 
 The action generates a detailed summary visible in the GitHub Actions UI:
@@ -53,6 +58,7 @@ The action generates a detailed summary visible in the GitHub Actions UI:
    - **Missed Commands**: HTML table with code snippets
    - **Executed Commands**: HTML table with code snippets
    - **Analyzed Files**: List of covered files
+   - **Missed Paths**: Aggregated missed-command counts grouped by file path
 
 Example summary:
 

.github/actions/Get-PesterCodeCoverage/action.yml

@@ -35,6 +35,11 @@ inputs:
     description: The target for code coverage.
     required: false
 
+outputs:
+  MissedPathReportPath:
+    description: Path to the generated missed-path report folder.
+    value: ${{ steps.Get-PesterCodeCoverage.outputs.MissedPathReportPath }}
+
 runs:
   using: composite
   steps:

.github/actions/Get-PesterCodeCoverage/src/main.ps1

@@ -158,6 +158,73 @@ $success = $coveragePercent -ge $coveragePercentTarget
 $statusIcon = $success ? '✅' : '❌'
 $stats | Format-Table -AutoSize | Out-String
 
+$missedPathGroups = $codeCoverage.CommandsMissed |
+    Where-Object { -not [string]::IsNullOrWhiteSpace($_.File) } |
+    Group-Object -Property File |
+    Sort-Object -Property @(
+        @{ Expression = 'Count'; Descending = $true },
+        @{ Expression = 'Name'; Descending = $false }
+    )
+
+$missedPaths = foreach ($group in $missedPathGroups) {
+    $lines = $group.Group |
+        Where-Object { $_.Line -is [ValueType] } |
+        ForEach-Object { [int]$_.Line } |
+        Sort-Object -Unique
+    $missedLines = if ($lines.Count -eq 0) { '' } else { $lines -join ', ' }
+    [pscustomobject]@{
+        Path           = $group.Name
+        MissedCommands = [int]$group.Count
+        MissedLines    = $missedLines
+    }
+}
+
+$missedPathReportPath = 'CodeCoverage-MissedPaths'
+$null = New-Item -Path $missedPathReportPath -ItemType Directory -Force
+
+$missedPathReport = [ordered]@{
+    GeneratedAtUtc  = [DateTime]::UtcNow.ToString('o')
+    CoveragePercent = [double]$coveragePercent
+    CoverageTarget  = [double]$coveragePercentTarget
+    MissedPaths     = @($missedPaths)
+}
+
+$missedPathReportJsonPath = Join-Path -Path $missedPathReportPath -ChildPath 'CodeCoverage-MissedPaths.json'
+$missedPathReportMarkdownPath = Join-Path -Path $missedPathReportPath -ChildPath 'CodeCoverage-MissedPaths.md'
+$missedPathReport | ConvertTo-Json -Depth 10 | Set-Content -Path $missedPathReportJsonPath -Encoding utf8NoBOM
+
+$missedPathMarkdown = [System.Collections.Generic.List[string]]::new()
+$null = $missedPathMarkdown.Add('# Code Coverage Missed Paths')
+$null = $missedPathMarkdown.Add('')
+$null = $missedPathMarkdown.Add("| Coverage | Target | Missed Paths | Missed Commands |")
+$null = $missedPathMarkdown.Add("| --- | --- | --- | --- |")
+$coverageSummaryRow = '| {0}% | {1}% | {2} | {3} |' -f (
+    [Math]::Round($coveragePercent, 2)
+), (
+    [Math]::Round($coveragePercentTarget, 2)
+), $missedPaths.Count, $codeCoverage.CommandsMissedCount
+$null = $missedPathMarkdown.Add($coverageSummaryRow)
+$null = $missedPathMarkdown.Add('')
+$null = $missedPathMarkdown.Add('## Paths')
+$null = $missedPathMarkdown.Add('| Path | Missed Commands | Missed Lines |')
+$null = $missedPathMarkdown.Add('| --- | ---: | --- |')
+if ($missedPaths.Count -eq 0) {
+    $null = $missedPathMarkdown.Add('| _None_ | 0 |  |')
+} else {
+    foreach ($pathEntry in $missedPaths) {
+        $safePath = ([string]$pathEntry.Path).Replace('|', '\|')
+        $safeLines = ([string]$pathEntry.MissedLines).Replace('|', '\|')
+        $null = $missedPathMarkdown.Add("| $safePath | $($pathEntry.MissedCommands) | $safeLines |")
+    }
+}
+
+$missedPathMarkdown | Set-Content -Path $missedPathReportMarkdownPath -Encoding utf8NoBOM
+Write-Output 'Missed path report generated:'
+$missedPaths | Select-Object -First 20 | Format-Table -Property Path, MissedCommands, MissedLines -AutoSize | Out-String
+if ($env:GITHUB_OUTPUT) {
+    "MissedPathReportPath=$missedPathReportPath" >> $env:GITHUB_OUTPUT
+}
+
 # Build HTML table for 'missed' commands
 $tableheader = @'
 <table>
@@ -300,6 +367,18 @@ LogGroup 'Step Summary - Set step summary' {
                     }
                 }
             }
+
+            Details "Missed paths [$($missedPaths.Count)]" {
+                if ($missedPaths.Count -eq 0) {
+                    Paragraph {
+                        Write-Output 'No missed paths were detected.'
+                    }
+                } else {
+                    Table {
+                        $missedPaths | Select-Object -First 100
+                    }
+                }
+            }
         }
     }
 

.github/actions/Install-PSModule/src/PSModule/PSModule.psm1

@@ -87,18 +87,40 @@ function Convert-VersionSpec {
         [string] $RequiredVersion
     )
 
+    $maximumVersionIsWildcard = $MaximumVersion -and ($MaximumVersion -match '[*]')
+    if ($maximumVersionIsWildcard) {
+        $versionParts = @($MaximumVersion -split '\.')
+        $wildcardIndex = [Array]::IndexOf($versionParts, '*')
+        if ($wildcardIndex -lt 0) {
+            throw "MaximumVersion '$MaximumVersion' contains an unsupported wildcard pattern."
+        }
+
+        if ($wildcardIndex -eq 0) {
+            throw "MaximumVersion '$MaximumVersion' contains an unsupported wildcard pattern."
+        }
+
+        $upperBoundParts = @(0, 0, 0)
+        for ($i = 0; $i -lt $wildcardIndex; $i++) {
+            $upperBoundParts[$i] = [int]$versionParts[$i]
+        }
+        $upperBoundParts[$wildcardIndex - 1]++
+        $MaximumVersion = $upperBoundParts -join '.'
+    }
+
     if ($RequiredVersion) {
         # Use exact match in bracket notation.
         return "[$RequiredVersion]"
     } elseif ($MinimumVersion -and $MaximumVersion) {
-        # Both bounds provided; both are inclusive.
-        return "[$MinimumVersion,$MaximumVersion]"
+        # Wildcard maximum versions are translated to an exclusive upper bound.
+        $upperBound = $maximumVersionIsWildcard ? ')' : ']'
+        return "[$MinimumVersion,$MaximumVersion$upperBound"
     } elseif ($MinimumVersion) {
         # Only a minimum is provided. Use a minimum-inclusive range.
         return "[$MinimumVersion, ]"
     } elseif ($MaximumVersion) {
-        # Only a maximum is provided; lower bound open.
-        return "(, $MaximumVersion]"
+        # Only a maximum is provided; lower bound open. Wildcards are exclusive upper bounds.
+        $upperBound = $maximumVersionIsWildcard ? ')' : ']'
+        return "(, $MaximumVersion$upperBound"
     } else {
         return $null
     }

.github/actions/Publish-PSModule/README.md

@@ -0,0 +1,32 @@
+# Publish-PSModule
+
+Publishes a pre-versioned PowerShell module artifact to the PowerShell Gallery. GitHub Release creation is intentionally handled by the separate [Release-PSModule](../Release-PSModule/README.md) action.
+
+## Inputs
+
+| Name | Description | Required | Default |
+| --- | --- | --- | --- |
+| `Name` | Name of the module to publish. | No | Repository name |
+| `ModulePath` | Path containing the built `<Name>/` module directory. | No | `outputs/module` |
+| `ArtifactName` | Name of the module artifact to download. | No | `module` |
+| `APIKey` | PowerShell Gallery API key. | Yes | N/A |
+| `WhatIf` | Logs publishing operations without publishing the module. | No | `false` |
+| `WorkingDirectory` | Directory where the publishing script runs. | No | `.` |
+
+## Outputs
+
+This action does not provide outputs.
+
+## Usage
+
+```yaml
+- name: Publish module
+  uses: ./.github/actions/Publish-PSModule
+  with:
+    Name: ExampleModule
+    ModulePath: outputs/module
+    ArtifactName: module
+    APIKey: ${{ secrets.APIKEY }}
+```
+
+Use [Release-PSModule](../Release-PSModule/README.md) in a separate workflow step to create the GitHub release from the same artifact.

.github/actions/Publish-PSModule/action.yml

@@ -1,5 +1,5 @@
 name: Publish-PSModule
-description: Publish a pre-versioned PowerShell module artifact to the PowerShell Gallery and GitHub Releases.
+description: Publish a pre-versioned PowerShell module artifact to the PowerShell Gallery.
 author: PSModule
 
 inputs:
@@ -14,25 +14,13 @@ inputs:
     description: PowerShell Gallery API Key.
     required: true
   WhatIf:
-    description: If specified, the action will only log the changes it would make, but will not actually create or delete any releases or tags.
+    description: If specified, the action will only log the changes it would make, but will not publish the module.
     required: false
     default: 'false'
   WorkingDirectory:
     description: The working directory where the script will run from.
     required: false
     default: '.'
-  UsePRTitleAsReleaseName:
-    description: When enabled, uses the pull request title as the name for the GitHub release. If not set, the version string is used.
-    required: false
-    default: 'false'
-  UsePRBodyAsReleaseNotes:
-    description: When enabled, uses the pull request body as the release notes for the GitHub release. If not set, the release notes are auto-generated.
-    required: false
-    default: 'true'
-  UsePRTitleAsNotesHeading:
-    description: When enabled along with UsePRBodyAsReleaseNotes, the release notes will begin with the pull request title as a H1 heading followed by the pull request body. The title will reference the pull request number.
-    required: false
-    default: 'true'
   ArtifactName:
     description: Name of the uploaded artifact to download. Must match the name used in the upstream upload-artifact step.
     required: false
@@ -63,7 +51,4 @@ runs:
         PSMODULE_PUBLISH_PSMODULE_INPUT_ModulePath: ${{ inputs.ModulePath }}
         PSMODULE_PUBLISH_PSMODULE_INPUT_APIKey: ${{ inputs.APIKey }}
         PSMODULE_PUBLISH_PSMODULE_INPUT_WhatIf: ${{ inputs.WhatIf }}
-        PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRBodyAsReleaseNotes: ${{ inputs.UsePRBodyAsReleaseNotes }}
-        PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRTitleAsReleaseName: ${{ inputs.UsePRTitleAsReleaseName }}
-        PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRTitleAsNotesHeading: ${{ inputs.UsePRTitleAsNotesHeading }}
       run: ${{ github.action_path }}/src/publish.ps1

.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1

@@ -0,0 +1,45 @@
+function Get-ModuleVersionString {
+    <#
+        .SYNOPSIS
+        Builds the SemVer version string that identifies the module itself.
+
+        .DESCRIPTION
+        Composes the module version and, when there is one, the prerelease label. This is the string the
+        PowerShell Gallery and the module manifest understand: `Major.Minor.Patch` optionally followed by
+        `-<prerelease>`. It never carries the repository's version prefix, because neither the manifest's
+        `ModuleVersion` nor a Gallery package version accepts one.
+
+        .OUTPUTS
+        String with the module version.
+
+        .EXAMPLE
+        Get-ModuleVersionString -ModuleVersion '1.1.10'
+
+        Returns '1.1.10'.
+
+        .EXAMPLE
+        Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+
+        Returns '1.1.10-mybranch001'.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        # The module version from the compiled manifest, in Major.Minor.Patch format.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string] $ModuleVersion,
+
+        # The prerelease label from the compiled manifest. Empty for a stable release.
+        [Parameter()]
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $Prerelease
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Prerelease)) {
+        return $ModuleVersion
+    }
+
+    "$ModuleVersion-$($Prerelease.Trim())"
+}