Move version calculation to a Plan job (Resolve-PSModuleVersion) so Build and Publish never calculate or mutate versions #326

Problem

Build-PSModule stamps every built module manifest with ModuleVersion = '999.0.0' as a placeholder.
The artifact is uploaded with this fake version, and all tests run against 999.0.0.
Later, Publish-PSModule (publish.ps1) calls Set-ModuleManifest to patch the real version into the manifest after all tests have passed.

# publish.ps1 mutates the artifact that was tested
Set-ModuleManifest -Path $manifestFilePath -ModuleVersion $manifestNewVersion
Set-ModuleManifest -Path $manifestFilePath -Prerelease $($newVersion.Prerelease)

This means the artifact that was tested (999.0.0) is not the artifact that ships (for example 1.4.0).
That violates a core CI/CD principle: test what you ship.

Version calculation is also duplicated across Publish-PSModule/init.ps1 and Publish-PSModule/publish.ps1.
Moving version decision logic into one planning point simplifies maintenance and clarifies responsibilities.

Current Pipeline

Get-Settings
  - reads configuration
  - outputs settings

Build-PSModule
  - stamps ModuleVersion = '999.0.0' (placeholder)
  - uploads artifact

Test-Module / Test-ModuleLocal
  - tests the 999.0.0 artifact (not the version that ships)

Publish-PSModule (init.ps1)
  - queries GitHub Releases + PSGallery
  - reads PR labels
  - calculates new version (for example v1.4.0)

Publish-PSModule (publish.ps1)
  - downloads artifact
  - patches ModuleVersion in manifest (mutates tested artifact)
  - publishes mutated artifact to PSGallery
  - creates GitHub release

Desired Pipeline

Plan (single job, two steps)
  - Get-PSModuleSettings
      reads configuration and emits settings
  - Resolve-PSModuleVersion
      reads settings + PR labels
      queries GitHub Releases + PSGallery
      outputs Version / Prerelease / FullVersion / ReleaseType / CreateRelease

Build-PSModule
  - receives Version + Prerelease from Plan
  - stamps real version into manifest
  - uploads immutable artifact

Test-Module / Test-ModuleLocal
  - tests the same artifact that will be shipped

Publish-PSModule
  - downloads artifact (already correctly versioned)
  - publishes to PSGallery as-is
  - creates GitHub release

flowchart LR
  A[Plan<br/>Get-Settings + Resolve-PSModuleVersion] --> B[Build-Module<br/>stamps version into manifest]
  B --> C[Test-* / Coverage]
  C --> D[Publish-Module<br/>publishes artifact + uploads zip to release]

Why This Matters

Technical Decisions

Inputs Are Available At Planning Time

Everything needed to calculate the next version is available in the Plan job:

• PR labels (major / minor / patch)
• ReleaseType (Release / Prerelease / None) from settings
• Latest GitHub release (gh release list)
• Latest PSGallery version (Find-PSResource)

Single Decision Point In One Job

The Plan job contains two steps:

1. Get-PSModuleSettings loads and resolves settings.
2. Resolve-PSModuleVersion consumes settings + GitHub context and outputs:
   • Version
   • Prerelease
   • FullVersion
   • ReleaseType
   • CreateRelease

The Plan job surfaces both settings and version outputs for downstream jobs.

Build And Publish Become Executors

• Build-PSModule stamps version information into the manifest and uploads the artifact.
• Publish-PSModule publishes that artifact without mutating version metadata.

Consumer Compatibility

Process-PSModule/.github/workflows/workflow.yml keeps the same public input/output contract for external consumers.
This refactor is internal wiring.

Action-Level Breaking Change

Publish-PSModule removes version-calculation inputs and becomes a publish-only action.
That action receives a major version bump.
Direct users of Publish-PSModule must run Resolve-PSModuleVersion first.

Prerelease Counter

Prerelease sequencing keeps the same race characteristics as current behavior (no regression introduced by this plan).

Implementation Plan

Resolve-PSModuleVersion (new action repo)

Implemented in PSModule/Resolve-PSModuleVersion#1 ΓÇö merged.

• Create PSModule/Resolve-PSModuleVersion (LICENSE, README, action.yml, src/main.ps1, tests).
• Inputs: Settings, Name, WorkingDirectory.
• Outputs: Version, Prerelease, FullVersion, ReleaseType, CreateRelease.
• Port logic from Publish-PSModule/src/init.ps1:
  • Install PSSemVer.
  • Query GitHub releases.
  • Query PSGallery.
  • Parse PR labels (major/minor/patch/ignore).
  • Apply bump logic.
  • Handle incremental prerelease numbering.
  • Honor DatePrereleaseFormat and VersionPrefix.
• Add Pester tests for label parsing, bump selection, and prerelease sequencing.

Build-PSModule changes

Implemented in PSModule/Build-PSModule#136 ΓÇö merged.

• Accept Version and Prerelease inputs.
• Replace placeholder-only ModuleVersion behavior with:
  • passed-in version when provided
  • '999.0.0' fallback when not provided
• Stamp prerelease metadata when provided.
• Release as additive change (minor bump).

Publish-PSModule changes

Implemented in PSModule/Publish-PSModule#71 ΓÇö merged.

• Remove src/init.ps1.
• Remove manifest mutation (Set-ModuleManifest) from src/publish.ps1.
• Read version from downloaded manifest (Test-ModuleManifest + prerelease metadata).
• Remove version-calculation inputs from action.yml.
• Fix cleanup regression: snapshot gh release list before publish.ps1 runs so the just-published release tag is not included in $tagsToDelete (PSModule/Publish-PSModule#71 review).
• Fix Compress-Archive path: zip $modulePath (the folder) not $modulePath/* (its contents) so the archive extracts to a <Name>/ directory (PSModule/Publish-PSModule#71 review).
• Guard Compress-Archive inside if (-not $whatIf) so WhatIf mode does not write a real zip file (PSModule/Publish-PSModule#71 review).
• Validate $manifest.Version.Build -ge 0 before constructing the release tag to catch 2-part version strings (PSModule/Publish-PSModule#71 review).
• Keep cleanup.ps1 behavior unchanged (gate cleanup on stable-release-only runs, not every invocation).
• Release as major bump.

Process-PSModule workflow changes

Work in progress in PSModule/Process-PSModule#342 ΓÇö draft, awaiting end-to-end validation.

• Rename Get-Settings job to Plan.
• Keep Get-PSModuleSettings as first step in Plan.
• Add Resolve-PSModuleVersion as second step in Plan.
• Expose Plan outputs: Settings, Version, Prerelease, FullVersion, ReleaseType, CreateRelease.
• Update Build-Module.yml to pass Version and Prerelease into Build-PSModule.
• Update Publish-Module.yml to remove version-calculation inputs.
• Update needs and with wiring for downstream jobs to consume Plan outputs.
• Repin @main references in Build-Module.yml, Plan.yml, and Publish-Module.yml to released SHAs once all companion repos are released.

Documentation

• Update Process-PSModule/README.md:
  • show Plan job with two steps
  • move version-bump explanation into Plan section
  • document artifact-integrity guarantee
• [ ] Add Resolve-PSModuleVersion/README.md with inputs, outputs, and examples. (not needed ΓÇö all changes are internal to the packaged workflow)
• [ ] Update Publish-PSModule/README.md migration notes for removed inputs. (not needed ΓÇö all changes are internal to the packaged workflow)

Test harness version-awareness (discovered 2026-07-08)

Because the built artifact now carries the real resolved version instead of the fixed 999.0.0 placeholder, the shared test and coverage tooling must stop assuming 999.0.0. On #342 the Plan and Build-Module jobs already succeed (the manifest is correctly stamped with the resolved version), but Test-Module, Test-ModuleLocal, Get-TestResults, and Build-Docs fail because the built module is installed into a 999.0.0 folder that no longer matches its manifest, so Import-Module rejects it as an invalid manifest.

End-to-end status (2026-07-08): with all four companion changes temporarily branch-pinned, the full Workflow-Test suite on #342 is green (Plan, Build-Module, Test-Module, Test-ModuleLocal, Get-CodeCoverage, Get-TestResults, Build-Docs — 61 pass / 7 publish-skipped / 0 fail). Remaining work is to merge + release the companion PRs and repin #342 to the released tags.

Merge order (post-approval — nothing merges without sign-off):

1. PSModule/Test-PSModule#120 — Pester 6 -ForEach fix. Independent (fixes Test-PSModule main, no version coupling); merge first.
2. PSModule/Install-PSModuleHelpers#19 — root install-version fix. Merge + release → new tag.
3. PSModule/Test-PSModule#119 — after Post test result summary as PR comment #120 is merged and 🪲 [Fix]: Setting PowerShellVersion correctly after tests #19 is released: repin Install-PSModuleHelpers to the release, then merge + release → new tag.
4. PSModule/Document-PSModule#52 — after 🪲 [Fix]: Setting PowerShellVersion correctly after tests #19 is released: repin Install-PSModuleHelpers to the release, then merge + release → new tag.
5. PSModule/Process-PSModule#342 — after 🚀[Feature]: Merge results on module tests to get correct coverage stats #119/Support passing arbitrary secrets as environment variables to test jobs #52/🪲 [Fix]: Setting PowerShellVersion correctly after tests #19 are released: repin Test-Module.yml → Test-PSModule release, Build-Docs.yml → Document-PSModule release, Test-ModuleLocal.yml → Install-PSModuleHelpers release. Review + merge, then close this issue.

• Adapt Plan.yml to the Resolve-PSModuleVersion v1.1.0 interface (v1.1.0 dropped the Version/Prerelease inputs and added Name) and repin it to v1.1.0. (done in 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342)
• Install-PSModuleHelpers: Install-PSModule (src/Helpers/Helpers.psm1) copies the built module into a hard-coded .../<name>/999.0.0 folder before Import-Module, which fails once the manifest carries the real version. Install into the folder that matches the manifest ModuleVersion (via the existing Get-ModuleManifest), then release and repin. Blocks Test-Module and Test-ModuleLocal. Status (2026-07-08): implemented in PSModule/Install-PSModuleHelpers#19 (own CI green; Copilot review converged; also hardened against path traversal from a malformed manifest version). Validated end-to-end on 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342 via a temporary branch pin — Test-ModuleLocal is green. Awaiting merge + release, then repin to the released tag.
• Process-PSModule/.github/workflows/Test-ModuleLocal.yml: replace the hard-coded Import-Module -RequiredVersion 999.0.0 with the resolved version from the Plan settings. Status (2026-07-08): done on 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342 (the Prescript now imports fromJson(Settings).Module.Version); Install-PSModuleHelpers is temporarily pinned to the 🪲 [Fix]: Setting PowerShellVersion correctly after tests #19 branch until it releases.
• Get-PesterCodeCoverage: coverage file paths are normalized by splitting on 999.0.0; derive the version dynamically so coverage paths resolve with real versions, then release and repin. Status (2026-07-08): likely not required for green — Get-CodeCoverage and Get-TestResults pass on 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342 with real versions. The split just no longer strips a prefix, so coverage file paths may be absolute rather than module-relative (cosmetic). To confirm/clean up as a follow-up.
• Test-PSModule: re-release and repin if required after the Install-PSModuleHelpers fix (it depends on Install-PSModule). Status (2026-07-08): implemented in PSModule/Test-PSModule#119 (bumps the Install-PSModuleHelpers pin). Test-Module (and Get-TestResults/Get-CodeCoverage) validated green on 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342 via a temporary branch pin; Copilot review converged. Test-PSModule's own Action-Test-outputs was pre-existing red on main (a Pester 6 empty -ForEach in PSModule.Tests.ps1, unrelated to this refactor); fixed separately in PSModule/Test-PSModule#120, which must merge before 🚀[Feature]: Merge results on module tests to get correct coverage stats #119.
• Document-PSModule: repin Install-PSModuleHelpers (it also installs the built module via Install-PSModule, for Build-Docs). Status (2026-07-08): implemented in PSModule/Document-PSModule#52; own CI green; Copilot review converged; Build-Docs validated green on 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342 via a temporary branch pin. Awaiting merge + release, then repin.

Validation

• Verify built artifact manifest contains final version before publish.
• Verify publish logs contain no manifest mutation.
• Verify prerelease cleanup behavior is unchanged.
• Run end-to-end in Process-PSModule with a labeled PR.
• Smoke test one downstream consumer workflow.
• Verify the built module installs into a version folder that matches its stamped manifest version (no 999.0.0 mismatch).
• Confirm Test-Module, Test-ModuleLocal, Get-TestResults, and Build-Docs pass end-to-end on 🚀 [Feature]: Plan job decides version before build so tested artifact equals published artifact #342.