🪲 [Fix]: Version resolution no longer fails on repositories without releases (#432)

A module repository that has not published its first release no longer
breaks. Previously the `Plan` job failed on any repository with zero
GitHub releases, which meant every brand-new module created from the
template was blocked on its very first pull request — a chicken-and-egg
problem where the framework could not run until a release existed, and a
release could not be created until the framework ran.

## Fixed: Version resolution works before the first release exists

A repository with no GitHub releases, and a module that has never been
published to the PowerShell Gallery, now resolve cleanly to a `0.0.0`
baseline. The first labelled pull request produces the expected first
version — `0.0.1` for a patch, `0.1.0` for a minor, `1.0.0` for a major
— instead of failing the `Plan` job with:

```text
Cannot bind argument to parameter 'Releases' because it is null.
```

Because every downstream job depends on `Plan`, that failure skipped the
whole run and made the pull request unmergeable. Nothing needs to change
in consuming repositories; bumping to the released version is enough.

---
<details>
<summary>Technical details</summary>

- Verified the reported diagnosis before changing anything. Both
`Get-LatestGitHubVersion -Releases $null` **and**
`Get-LatestGitHubVersion -Releases @()` failed. `[Parameter(Mandatory)]
[array]` rejects an empty collection as well as `$null`, so normalising
at the call site with `@(Get-GitHubRelease)` alone would have turned the
null error into an "empty collection" error. The parameter declarations
had to be relaxed too.
- `Resolve-PSModuleVersion.Helpers.psm1`: `Releases` on
`Get-LatestGitHubVersion`, `Get-NextPrereleaseNumber`, and
`Get-NextModuleVersion` is now optional with `[AllowNull()]`,
`[AllowEmptyCollection()]`, and an `@()` default, so each function is
individually robust rather than depending on a careful caller.
- New `ConvertFrom-GitHubReleaseJson` owns the normalisation of the `gh
release list` output into a flat array, including the case where the
command produced no output at all (the second reproduction in #381,
where a repository with five releases still yielded `$null`).
`Get-GitHubRelease` delegates to it and `src/main.ps1` normalises with
`$releases = @(Get-GitHubRelease)`.
- `Get-LatestPublishedVersion` accepts null versions and filters empty
candidates before sorting, warning and flooring to `0.0.0` when neither
source has a version. `Get-NextModuleVersion` accepts a null
`LatestVersion` and floors it to `0.0.0`.
- The downstream fallback logic was already correct — only parameter
binding, null handling, and the array shape changed. Version resolution
was not redesigned.
- Tests:
`.github/actions/Resolve-PSModuleVersion/tests/Resolve-PSModuleVersion.Helpers.Tests.ps1`
adds 36 Pester tests following the [test
specification](https://psmodule.io/docs/Modules/Test-Specification/). 21
of them fail against the previous parameter declarations. They cover a
null releases list, an empty releases list, releases with none marked
`isLatest`, prerelease-only repositories, the release-JSON
normalisation, and the full brand-new-module chain for major, minor, and
patch decisions.
- CI: `.github/workflows/Test-Actions.yml` runs every
`.github/actions/*/tests` folder with Pester on pull requests that touch
an action, so the repository now has a unit-test surface for its own
actions.
- Standards and framework alignment:

| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/actions/Resolve-PSModuleVersion/src/**` | PSScriptAnalyzer
via `.github/linters/.powershell-psscriptanalyzer.psd1` | PSModule
function/parameter conventions | Aligned |
| `.github/actions/Resolve-PSModuleVersion/tests/**` | PSScriptAnalyzer
| [Test
Specification](https://psmodule.io/docs/Modules/Test-Specification/) |
Aligned |
| `.github/workflows/Test-Actions.yml` | Pinned action SHAs,
least-privilege permissions | Reusable workflow contract | Aligned —
repository-internal workflow, not consumer-facing |

</details>

<details>
<summary>Relevant issues (or links)</summary>

- Fixes #381
- #433 — follow-up for end-to-end coverage of a
repository with zero releases
- Reproduction: PSModule/Lovdata#1 — [failing run
30743884958](https://github.com/PSModule/Lovdata/actions/runs/30743884958/job/91486012154)

</details>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.github/actions/Resolve-PSModuleVersion/src/Resolve-PSModuleVersion.Helpers.psm1

@@ -277,16 +277,52 @@ function Resolve-ReleaseDecision {
     }
 }
 
+function ConvertFrom-GitHubReleaseJson {
+    <#
+        .SYNOPSIS
+        Converts the JSON output of 'gh release list' into a flat array of release objects.
+
+        .DESCRIPTION
+        Normalizes the release listing so a repository with no releases, or a command that
+        produced no output at all, yields an empty array instead of $null.
+
+        .OUTPUTS
+        Array of release objects. Empty when there are no releases.
+
+        .EXAMPLE
+        $releases = ConvertFrom-GitHubReleaseJson -Json '[{"tagName":"v1.0.0"}]'
+    #>
+    [CmdletBinding()]
+    [OutputType([object[]], [array])]
+    param(
+        # The raw JSON returned by 'gh release list'. Empty or null when the command produced no output.
+        [Parameter()]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Json
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Json)) {
+        return @()
+    }
+
+    @($Json | ConvertFrom-Json)
+}
+
 function Get-GitHubRelease {
     <#
         .SYNOPSIS
         Retrieves all releases from the current GitHub repository.
 
+        .DESCRIPTION
+        Lists the releases of the current repository. A repository that has no releases yet
+        produces no output, so callers normalize the result with @() before using it.
+
         .OUTPUTS
-        Array of release objects.
+        Array of release objects. Nothing when the repository has no releases.
 
         .EXAMPLE
-        $releases = Get-GitHubRelease
+        $releases = @(Get-GitHubRelease)
     #>
     [CmdletBinding()]
     [OutputType([array])]
@@ -298,9 +334,10 @@ function Get-GitHubRelease {
             Write-Error 'Failed to list releases for the repo.'
             exit $LASTEXITCODE
         }
-        $releases = $releasesJson | ConvertFrom-Json
+        $releases = ConvertFrom-GitHubReleaseJson -Json $releasesJson
 
         Write-Host '-------------------------------------------------'
+        Write-Host "Found [$($releases.Count)] releases."
         Write-Host ($releases | Select-Object -Property name, isPrerelease, isLatest, publishedAt |
                 Format-Table | Out-String)
         Write-Host '-------------------------------------------------'
@@ -314,6 +351,11 @@ function Get-LatestGitHubVersion {
         .SYNOPSIS
         Extracts the latest stable version from a GitHub releases list.
 
+        .DESCRIPTION
+        Returns the version of the release marked as latest. A repository that has no releases
+        yet - or that has releases but none marked as latest - resolves to '0.0.0' so a brand-new
+        module can still be versioned before its first release exists.
+
         .OUTPUTS
         PSSemVer representing the latest GitHub release version.
 
@@ -325,9 +367,11 @@ function Get-LatestGitHubVersion {
     [CmdletBinding()]
     [OutputType([object])]
     param(
-        # The GitHub releases array to search.
-        [Parameter(Mandatory)]
-        [array] $Releases
+        # The GitHub releases array to search. Empty or null when the repository has no releases.
+        [Parameter()]
+        [AllowNull()]
+        [AllowEmptyCollection()]
+        [array] $Releases = @()
     )
 
     LogGroup 'Get latest version - GitHub' {
@@ -409,6 +453,11 @@ function Get-LatestPublishedVersion {
         .SYNOPSIS
         Returns the highest version between GitHub and the PowerShell Gallery.
 
+        .DESCRIPTION
+        Compares the two known published versions and returns the highest one. A missing
+        (null) version is treated as '0.0.0', so a module that has never been released to
+        GitHub or published to the PowerShell Gallery resolves to a '0.0.0' baseline.
+
         .OUTPUTS
         PSSemVer representing the highest known published version.
 
@@ -420,19 +469,27 @@ function Get-LatestPublishedVersion {
     [CmdletBinding()]
     [OutputType([object])]
     param(
-        # The latest version found in GitHub releases.
-        [Parameter(Mandatory)]
+        # The latest version found in GitHub releases. Null when the repository has no releases.
+        [Parameter()]
+        [AllowNull()]
         [object] $GitHubVersion,
 
-        # The latest version found in the PowerShell Gallery.
-        [Parameter(Mandatory)]
+        # The latest version found in the PowerShell Gallery. Null when the module is unpublished.
+        [Parameter()]
+        [AllowNull()]
         [object] $PSGalleryVersion
     )
 
     LogGroup 'Latest version' {
-        $latestVersion = New-PSSemVer -Version (
-            $PSGalleryVersion, $GitHubVersion | Sort-Object -Descending | Select-Object -First 1
-        )
+        $candidates = @($PSGalleryVersion, $GitHubVersion) |
+            Where-Object { $null -ne $_ -and -not [string]::IsNullOrWhiteSpace([string]$_) }
+
+        $latestVersion = if ($candidates.Count -gt 0) {
+            New-PSSemVer -Version ($candidates | Sort-Object -Descending | Select-Object -First 1)
+        } else {
+            Write-Warning "No published version found in GitHub or the PowerShell Gallery. Using '0.0.0'."
+            New-PSSemVer -Version '0.0.0'
+        }
         Write-Host "Latest version: [$($latestVersion.ToString())]"
         $latestVersion
     }
@@ -472,9 +529,11 @@ function Get-NextPrereleaseNumber {
         [ValidateNotNullOrEmpty()]
         [string] $PrereleaseName,
 
-        # The GitHub releases list.
-        [Parameter(Mandatory)]
-        [array] $Releases
+        # The GitHub releases list. Empty or null when the repository has no releases.
+        [Parameter()]
+        [AllowNull()]
+        [AllowEmptyCollection()]
+        [array] $Releases = @()
     )
 
     $params = @{
@@ -532,8 +591,9 @@ function Get-NextModuleVersion {
     [CmdletBinding()]
     [OutputType([object])]
     param(
-        # The current latest published version.
-        [Parameter(Mandatory)]
+        # The current latest published version. Null resolves to a '0.0.0' baseline.
+        [Parameter()]
+        [AllowNull()]
         [object] $LatestVersion,
 
         # The release decision object.
@@ -550,12 +610,21 @@ function Get-NextModuleVersion {
         [string] $ModuleName,
 
         # The GitHub releases list, used for incremental prerelease calculation.
-        [Parameter(Mandatory)]
-        [array] $Releases
+        # Empty or null when the repository has no releases.
+        [Parameter()]
+        [AllowNull()]
+        [AllowEmptyCollection()]
+        [array] $Releases = @()
     )
 
     LogGroup 'Calculate new version' {
-        $newVersion = New-PSSemVer -Version $LatestVersion
+        $baseVersion = if ($null -eq $LatestVersion -or [string]::IsNullOrWhiteSpace([string]$LatestVersion)) {
+            Write-Warning "No latest version was resolved. Using '0.0.0' as the baseline."
+            '0.0.0'
+        } else {
+            $LatestVersion
+        }
+        $newVersion = New-PSSemVer -Version $baseVersion
         $newVersion.Prefix = $Configuration.VersionPrefix
 
         if ($Decision.MajorRelease) {

.github/actions/Resolve-PSModuleVersion/src/main.ps1

@@ -28,7 +28,7 @@ $decision = if ($null -eq $pullRequest) {
     Resolve-ReleaseDecision -Configuration $config -PullRequest $pullRequest
 }
 
-$releases = Get-GitHubRelease
+$releases = @(Get-GitHubRelease)
 $ghVersion = Get-LatestGitHubVersion -Releases $releases
 $psGalleryVersion = Get-LatestPSGalleryVersion -ModuleName $actionInput.Name
 $latestVersion = Get-LatestPublishedVersion -GitHubVersion $ghVersion -PSGalleryVersion $psGalleryVersion