fix(#155): finalize existing prerelease versions during bump planning (#156)

* fix(#155): finalize existing prerelease versions during bump planning
- Update `Update-NovaModuleVersion` to finalize current prerelease versions before incrementing.
- Adjust tests to reflect changes in version resolution logic.

* fix(#155): update PR description generation requirements
- clarify steps for reading prompt and template files
- enforce structure for PR description output
- ensure creation of output folder if missing

Author: stiwicourage

.github/prompts/pr-description.prompt.md

@@ -28,12 +28,22 @@ Analyze the provided input and:
 
 Be pragmatic: if information is missing, make reasonable assumptions but call them out briefly.
 
----
+Before generating the PR description, you MUST:
 
-## Output format
+- Read this prompt file from `.github/prompts/pr-description.prompt.md` directly, even if hidden folders were not
+  surfaced by an earlier search.
+- Read `.github/pull_request_template.md` directly and treat it as authoritative.
+- Resolve all relative paths from the repository root.
+- Treat `./pr-descriptions/` as a repository-root-relative output folder.
+- Never assume `.github/` content is missing just because a previous listing or glob search did not show hidden folders.
 
-You MUST return the PR description using this exact structure:
+---
 
-### Pull Request Template
+## Output format
 
-.github/pull_request_template.md
+You MUST return the PR description using this exact structure, you will find the template in
+`.github/pull_request_template.md`:
+You MUST fill in all sections, and you MUST NOT modify the template structure.
+You MUST create a *.md file in the `./pr-descriptions/` folder with the same name as the PR title, and write the
+generated description there.
+If the folder does not exist yet, you MUST create it under the repository root before writing the file.

CHANGELOG.md

@@ -34,6 +34,10 @@ Keep stable `Update-NovaModuleVersion` / `% nova bump` releases on the SemVer ma
 
 ### Fixed
 
+- Fix stable `Update-NovaModuleVersion` / `% nova bump` prerelease planning so existing prerelease versions finalize
+  their current semantic core before any later semantic bump is considered.
+    - `nova bump --what-if` now plans `2.0.0-preview01 -> 2.0.0` instead of `2.1.0` when commit history resolves to a
+      `Minor` label.
 - Fix `Invoke-NovaBuild` help discovery so it only scans `docs/<ProjectName>/` for PlatyPS
   markdown.
     - Regular markdown elsewhere under `docs/` no longer breaks the help-generation step.

README.md

@@ -211,6 +211,9 @@ These switches keep the behavior explicit and opt-in:
 - `Update-NovaModuleVersion -ContinuousIntegration` also falls back to a patch bump when the current `HEAD` already
   matches the latest tag, so release automation can seed the next prerelease line without requiring an extra commit
   first
+- Stable `Update-NovaModuleVersion` / `% nova bump` finalizes any existing prerelease by removing its suffix before
+  planning a new semantic-core increment, so `2.0.0-preview01` becomes `2.0.0` unless you explicitly pass
+  `-Preview` / `--preview`
 - `Update-NovaModuleVersion` and `% nova bump` treat stable `0.y.z` versions as the SemVer initial-development phase,
   so breaking-change bumps stay on the `0.y.z` line by planning the next minor version instead of jumping to `1.0.0`
 - `Publish-NovaModule -ContinuousIntegration` restores the built module after publish completes

docs/NovaModuleTools/en-US/Update-NovaModuleVersion.md

@@ -59,9 +59,9 @@ calculated release label and the exact next version without changing the stored
 Use `-ContinuousIntegration` when the same session should first re-activate the built `dist/` module before the version
 bump workflow starts. This is useful in CI/self-hosting flows where an earlier command changed the active module state.
 
-When the current version is already a prerelease for the selected release line, Nova finalizes that same semantic
-version instead of incrementing again. For example, a `Major` bump from `2.0.0-preview7` resolves to `2.0.0`, not
-`3.0.0-preview7`.
+When the current version is already a prerelease, Nova finalizes that same semantic version by default instead of
+incrementing to the next semantic core. For example, a `Minor` bump from `2.0.0-preview7` resolves to `2.0.0`, not
+`2.1.0`. Use `-Preview` when you want to continue the prerelease sequence instead.
 
 
 ## EXAMPLES

src/private/release/GetNovaVersionPartForLabel.ps1

@@ -6,7 +6,7 @@ function Get-NovaVersionPartForLabel {
         [string]$Label = 'Patch'
     )
 
-    if (Test-NovaVersionShouldFinalizePrereleaseTarget -CurrentVersion $CurrentVersion -Label $Label) {
+    if (Test-NovaVersionShouldFinalizePrereleaseTarget -CurrentVersion $CurrentVersion) {
         return Get-NovaVersionPartObject -CurrentVersion $CurrentVersion
     }
 
@@ -36,34 +36,12 @@ function Get-NovaVersionPartForLabel {
 }
 
 function Test-NovaVersionShouldFinalizePrereleaseTarget {
-    [CmdletBinding()]
-    param(
-        [Parameter(Mandatory)][semver]$CurrentVersion,
-        [Parameter(Mandatory)][string]$Label
-    )
-
-    if ( [string]::IsNullOrWhiteSpace($CurrentVersion.PreReleaseLabel)) {
-        return $false
-    }
-
-    return (Get-NovaVersionTargetLabelForPrerelease -CurrentVersion $CurrentVersion) -eq $Label
-}
-
-function Get-NovaVersionTargetLabelForPrerelease {
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)][semver]$CurrentVersion
     )
 
-    if ($CurrentVersion.Patch -gt 0) {
-        return 'Patch'
-    }
-
-    if ($CurrentVersion.Minor -gt 0) {
-        return 'Minor'
-    }
-
-    return 'Major'
+    return -not [string]::IsNullOrWhiteSpace($CurrentVersion.PreReleaseLabel)
 }
 
 function Get-NovaVersionPartObject {

tests/CoverageGaps.ReleaseInternals.Tests.ps1

@@ -55,13 +55,11 @@ Describe 'Coverage gaps for release and git internals' {
         }
     }
 
-    It 'Get-NovaVersionPartForLabel finalizes prerelease targets or advances to the next stable core when <Name>' -ForEach @(
-        @{Name = 'major prerelease already targets the current release line'; CurrentVersion = '2.0.0-preview7'; Label = 'Major'; Expected = '2.0.0'}
-        @{Name = 'minor prerelease already targets the current release line'; CurrentVersion = '1.3.0-preview7'; Label = 'Minor'; Expected = '1.3.0'}
-        @{Name = 'patch prerelease already targets the current release line'; CurrentVersion = '1.2.4-preview7'; Label = 'Patch'; Expected = '1.2.4'}
-        @{Name = 'major prerelease on a lower release line advances to the next major'; CurrentVersion = '1.2.3-preview7'; Label = 'Major'; Expected = '2.0.0'}
-        @{Name = 'minor prerelease on a lower release line advances to the next minor'; CurrentVersion = '1.2.3-preview7'; Label = 'Minor'; Expected = '1.3.0'}
-        @{Name = 'patch prerelease on the current patch line finalizes that line'; CurrentVersion = '1.2.3-preview7'; Label = 'Patch'; Expected = '1.2.3'}
+    It 'Get-NovaVersionPartForLabel finalizes any existing prerelease on the current semantic core when <Name>' -ForEach @(
+        @{Name = 'a breaking-change label targets a major prerelease'; CurrentVersion = '2.0.0-preview7'; Label = 'Major'; Expected = '2.0.0'}
+        @{Name = 'a feature label still finalizes a major prerelease'; CurrentVersion = '2.0.0-preview7'; Label = 'Minor'; Expected = '2.0.0'}
+        @{Name = 'a patch label still finalizes a minor prerelease'; CurrentVersion = '1.3.0-preview7'; Label = 'Patch'; Expected = '1.3.0'}
+        @{Name = 'a breaking-change label still finalizes a patch prerelease'; CurrentVersion = '1.2.4-preview7'; Label = 'Major'; Expected = '1.2.4'}
     ) {
         InModuleScope $script:moduleName -Parameters @{TestCase = $_} {
             param($TestCase)
@@ -109,11 +107,11 @@ Describe 'Coverage gaps for release and git internals' {
         }
     }
 
-    It 'Get-NovaVersionUpdatePlan resolves prerelease versions to the expected next stable target when <Name>' -ForEach @(
-        @{Name = 'finalizing a major prerelease line'; CurrentVersion = '2.0.0-preview7'; Label = 'Major'; ExpectedVersion = '2.0.0'}
-        @{Name = 'finalizing a minor prerelease line'; CurrentVersion = '1.3.0-preview7'; Label = 'Minor'; ExpectedVersion = '1.3.0'}
-        @{Name = 'finalizing a patch prerelease line'; CurrentVersion = '1.2.4-preview7'; Label = 'Patch'; ExpectedVersion = '1.2.4'}
-        @{Name = 'advancing from an earlier prerelease line to the next minor'; CurrentVersion = '1.2.3-preview7'; Label = 'Minor'; ExpectedVersion = '1.3.0'}
+    It 'Get-NovaVersionUpdatePlan resolves prerelease versions to the current stable target when <Name>' -ForEach @(
+        @{Name = 'finalizing a major prerelease after a breaking change'; CurrentVersion = '2.0.0-preview7'; Label = 'Major'; ExpectedVersion = '2.0.0'}
+        @{Name = 'finalizing a major prerelease after a feature change'; CurrentVersion = '2.0.0-preview7'; Label = 'Minor'; ExpectedVersion = '2.0.0'}
+        @{Name = 'finalizing a minor prerelease after a patch change'; CurrentVersion = '1.3.0-preview7'; Label = 'Patch'; ExpectedVersion = '1.3.0'}
+        @{Name = 'finalizing a patch prerelease after a breaking change'; CurrentVersion = '1.2.4-preview7'; Label = 'Major'; ExpectedVersion = '1.2.4'}
     ) {
         InModuleScope $script:moduleName -Parameters @{TestCase = $_} {
             param($TestCase)

tests/NovaCommandModel.BumpAndCli.Tests.ps1

@@ -491,7 +491,7 @@ Describe 'Nova command model - bump and CLI confirmation behavior' {
         }
     }
 
-    It 'Update-NovaModuleVersion preserves nested package repository objects when writing the bumped version' {
+    It 'Update-NovaModuleVersion finalizes an existing prerelease while preserving nested package repository objects' {
         InModuleScope $script:moduleName {
             $projectRoot = Join-Path $TestDrive 'package-repository-bump-project'
             New-Item -ItemType Directory -Path $projectRoot -Force | Out-Null
@@ -531,9 +531,9 @@ Describe 'Nova command model - bump and CLI confirmation behavior' {
             $updatedProject = Get-Content -LiteralPath $projectJsonPath -Raw | ConvertFrom-Json
 
             $result.PreviousVersion | Should -Be '1.5.2-preview'
-            $result.NewVersion | Should -Be '2.0.0'
+            $result.NewVersion | Should -Be '1.5.2'
             $result.Label | Should -Be 'Major'
-            $updatedProject.Version | Should -Be '2.0.0'
+            $updatedProject.Version | Should -Be '1.5.2'
             ($updatedProject.Package.Repositories[0] -is [string]) | Should -BeFalse
             $updatedProject.Package.Repositories[0].Name | Should -Be 'staging'
             $updatedProject.Package.Repositories[0].Auth.TokenEnvironmentVariable | Should -Be 'NEXUS_STAGING_TOKEN'

tests/NovaCommandModel.StandaloneCli.Tests.ps1

@@ -338,6 +338,29 @@ Describe '$projectName tests' {
         }
     }
 
+    It 'Install-NovaCli finalizes prerelease versions during stable what-if bumps' {
+        Assert-TestInstalledNovaCliBumpBehavior -DistModuleDir $script:distModuleDir -TestDriveRoot $TestDrive -TestCase @{
+            TargetDirectory = 'prerelease-finalize-bin'
+            ProjectName = 'CliPrereleaseFinalizeProject'
+            ProjectGuid = '45444444-4444-4444-4444-444444444444'
+            FunctionName = 'Invoke-TestCliPrereleaseFinalize'
+            CurrentVersion = '2.0.0-preview01'
+            CommitMessage = 'feat: finalize prerelease stable bump planning'
+            Arguments = @('bump', '--what-if')
+            ExpectedPatterns = @(
+                'What if:'
+                'Version plan: 2\.0\.0-preview01 -> 2\.0\.0 \| Label: Minor \| Commits: 1'
+            )
+            UnexpectedPatterns = @(
+                'Version plan: 2\.0\.0-preview01 -> 2\.1\.0'
+                'Unknown argument:'
+                'Version bumped to :'
+            )
+            ExpectedWarningCount = 0
+            ExpectedVersionAfterBump = '2.0.0-preview01'
+        }
+    }
+
     It 'Install-NovaCli rejects unsupported nova init invocations with clear migration guidance' -ForEach @(
         @{
             Name = 'WhatIf'