…zation (#150)

The **PSModule v4 release** is a major overhaul of the PowerShell module
workflow, introducing significant architectural changes to improve
speed, modularity, and maintainability. This update continues on the
goal to split the once-monolithic process into distinct GitHub Actions
for building, testing, documenting, and publishing modules. By
refactoring the workflow into isolated steps and enabling parallel
execution, v4 dramatically optimizes build and test times while ensuring
a more reliable and customizable process for module developers.


![image](https://github.com/user-attachments/assets/a583c4bd-e8ea-45dc-9164-a254f4764fa5)

<details><summary>Diagram - Old version</summary>
<p>


![image](https://github.com/user-attachments/assets/679bc459-44cd-4f50-8a98-e70bb4977068)

</p>
</details>

## Features

### Parallel Testing & Results Aggregation

The workflow has been reworked to support flexible, parallelizable test
runs. The `Test-PSModule` action will now execute tests in parallel via
matrix jobs (e.g. across multiple OSes or test stages). Separate helper
actions (`Get-PesterTestResults` and `Get-PesterCodeCoverage`) have been
introduced to aggregate Pester test outcomes and code coverage from
those parallel jobs, providing unified reporting and enforcing test
success and coverage thresholds across the matrix.

- Fixes #78
- Fixes #119

### Central Configuration File

A new configuration hierarchy allows customizing the process through a
YAML (JSON or PSD1) settings file. Users can include a
`.github/PSModule.yml` in their module repo to override defaults. This
centralized config makes the pipeline more flexible and eliminates the
need for hard-coded inputs in workflow files.

- Fixes #144
- Fixes #81
- Fixes #159

### Dedicated Documentation Step

Documentation generation is now handled by a new `Document-PSModule`
action. This step automatically builds the module's documentation (using
PlatyPS) and uploads as an artifact, so that other steps can build a
site and publish it to GitHub Pages. By isolating documentation in its
own action, v4 ensures that doc-specific tools (e.g. PlatyPS and MkDocs)
run without interference from build or test modules, and documentation
is kept up-to-date with each release.

- Fixes #148
- Fixes #77
- Fixes #95

### Shared Helper Module Action

A new `Install-PSModuleHelpers` action has been introduced as a
foundational setup step. It installs and configures common helper
functions used by the pipeline (for example, version specification
conversion, module dependency resolution, and module installation
utilities). This ensures all subsequent actions operate with a
consistent environment and shared logic. Common functionality like
resolving module dependencies (`Resolve-PSModuleDependency`) and version
parsing has been consolidated here, reducing duplication across the
build/test/publish steps.

### Enhanced Platform and Compatibility Support

The v4 workflow expands support and testing across platforms and
PowerShell versions. The Test-PSModule action runs on Windows, Linux,
and macOS with PowerShell Core (and includes light support for Windows
PowerShell 5.1 for basic compatibility).

- Fixes #146

### New test actions

Static analysis is performed via a dedicated `Invoke-ScriptAnalyzer`
GitHub action, and Pester tests are executed in an isolated context via
the `Invoke-Pester` GitHub action, ensuring consistent behavior across
different environments and increases the reusability of the automation
we built around Pester. The new design also honors repository-specific
analyzer settings (automatically picking up settings from
`.github/linters/.powershell-psscriptanalyzer.psd1` in the repo for
static code analysis), allowing module developers to customize linting
rules.

- Fixes #108
- Fixes #130

### Modular Workflows

By splitting the CI/CD process into discrete actions and enabling
concurrency, the overall pipeline runtime is greatly reduced. Linting,
unit tests, and integration tests can run in parallel, and the build
step no longer blocks documentation or analysis. This *time-optimized
process* means quicker feedback on pull requests and faster delivery of
new module releases.

### Simplified Build & Publish Process

The `Build-PSModule` action has been refactored into a pure module
builder. New inputs like `ArtifactName` and `WorkingDirectory` give more
control over build output naming and source path. The build step now
produces a clean module package and uploads it as an artifact called
`module`. Likewise, the **Publish-PSModule** action has been bumped to
v2 with a clearer interface – it removes the old monolithic
`ConfigurationFile` input in favor of explicit inputs and the new
central settings file. The publish logic now uses the repository’s
context (working directory defaulting to `.`) and respects the unified
settings, simplifying how modules are published to the PowerShell
Gallery.

### Robust Dependency Handling

Module dependency resolution during builds is now more reliable and
up-to-date. The pipeline switched to using **PSResourceGet** for
installing required module dependencies, replacing the legacy
PowerShellGet v2 approach. This change ensures compatibility with the
latest PowerShell module packaging standards and improves the speed and
success of acquiring dependencies. The helper scripts
(`Convert-VersionSpec` and `Resolve-PSModuleDependency`) were moved into
the shared helpers module, and their logic was hardened with better
retry and null-check mechanisms when querying the PowerShell Gallery.

- Fixes #62

### Better Logging and Diagnostics

Each action now provides more transparent logging and output for easier
troubleshooting. The Publish step, for example, now logs all input
parameters at the start of execution for traceability. Verbose logging
in dependency resolution has been replaced with clear console output to
ensure important information is always visible. The
`Get-PesterTestResults` action prints a detailed summary of test suites
executed, including counts of passed/failed/skipped tests, and will mark
the workflow as failed if any tests did not run or failed – giving
immediate feedback if something went wrong in the parallel test jobs.

- Fixes #91

### Other smaller issues

- Fixes #82

## Related actions and PRs

-
[Install-PSModuleHelpers](https://github.com/PSModule/Install-PSModuleHelpers)
| PSModule/Install-PSModuleHelpers#2
- [Test-PSModule](https://github.com/PSModule/Test-PSModule) |
PSModule/Test-PSModule#98
-
[Get-PesterTestResults](https://github.com/PSModule/Get-PesterTestResults)
| PSModule/Get-PesterTestResults#2
-
[Get-PesterCodeCoverage](https://github.com/PSModule/Get-PesterCodeCoverage)
| PSModule/Get-PesterCodeCoverage#1
- [Invoke-Pester](https://github.com/PSModule/Invoke-Pester)
-
[Invoke-ScriptAnalyzer](https://github.com/PSModule/Invoke-ScriptAnalyzer)
- [Document-PSModule](https://github.com/PSModule/Document-PSModule) |
PSModule/Document-PSModule#16
- [Build-PSModule](https://github.com/PSModule/Build-PSModule) |
PSModule/Build-PSModule#108
- [Publish-PSModule](https://github.com/PSModule/Publish-PSModule) |
PSModule/Publish-PSModule#49