🩹 [Patch]: Co-locate EVERYTHING :) (#131)

## Description

The actions within the PSModule framework are closely interconnected,
each serving a critical function. However, developing and testing both
individual actions and their integration within the framework has become
increasingly inefficient due to their scattered nature. Additionally,
issue tracking was fragmented across multiple repositories, making
management more cumbersome.

To improve efficiency, I have consolidated everything into a single
reusable workflow repository. This centralization simplifies
development, testing, and issue tracking, providing a unified view of
the entire process.

### Motivation

The actions within the PSModule framework are tightly connected, each
playing a crucial role. However, developing and testing both individual
actions and their integration with the whole has become inefficient due
to their scattered nature. Additionally, issue tracking was spread
across multiple repositories, further complicating the process.

To streamline development, testing, and issue tracking, I’ve opted to
consolidate everything into a single reusable workflow repository. This
will provide a unified view of the entire process and improve
efficiency.

### Documentation

Moving forward, the documentation for the PSModule framework will be
hosted on GitHub Pages using Material for MkDocs. As a result, the
README in this workflow repository will be minimal, serving primarily as
a pointer to the official documentation.

### What has moved where

| Old location | New location |
| - | - |
| [Initialize-PSModule](https://github.com/PSModule/Initialize-PSModule)
| [Initialize](.github/actions/Initialize) |
| [Test-PSModule](https://github.com/PSModule/Test-PSModule) |
[Test](.github/actions/Test)|
| [Publish-PSModule](https://github.com/PSModule/Publish-PSModule) |
[Publish](.github/actions/Publish)|
| [Build-PSModule](https://github.com/PSModule/Build-PSModule) |
[Build](.github/actions/Build)|
| [Document-PSModule](https://github.com/PSModule/Document-PSModule) |
[Document](.github/actions/Document)|

### Testing

All testing workflows have been consolidated into this repository to
ensure that both individual actions and the overall workflow are tested
as changes are developed. This improves cycle time and enhances
confidence in the stability of changes before they are released.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
Here’s an improved version with clearer wording, better structure, and
more fluid readability:

Author: MariusStorhaug

.github/actions/Build/action.yml

@@ -0,0 +1,81 @@
+name: Build-PSModule (by PSModule)
+description: Build a PowerShell module to the PowerShell Gallery.
+author: PSModule
+branding:
+  icon: package
+  color: gray-dark
+
+inputs:
+  Name:
+    description: Name of the module to process.
+    required: false
+  Path:
+    description: Path to the folder where the modules are located.
+    required: false
+    default: src
+  ModulesOutputPath:
+    description: Path to the folder where the built modules are outputted.
+    required: false
+    default: outputs/modules
+  DocsOutputPath:
+    description: Path to the folder where the built docs are outputted.
+    required: false
+    default: outputs/docs
+  ModuleArtifactName:
+    description: Name of the module artifact to upload.
+    required: false
+    default: module
+  DocsArtifactName:
+    description: Name of the docs artifact to upload.
+    required: false
+    default: docs
+  Debug:
+    description: Enable debug output.
+    required: false
+    default: 'false'
+  Verbose:
+    description: Enable verbose output.
+    required: false
+    default: 'false'
+  Version:
+    description: Specifies the version of the GitHub module to be installed. The value must be an exact version.
+    required: false
+  Prerelease:
+    description: Allow prerelease versions if available.
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - name: Run Build-PSModule
+      uses: PSModule/GitHub-Script@v1
+      env:
+        GITHUB_ACTION_INPUT_Name: ${{ inputs.Name }}
+        GITHUB_ACTION_INPUT_Path: ${{ inputs.Path }}
+        GITHUB_ACTION_INPUT_ModulesOutputPath: ${{ inputs.ModulesOutputPath }}
+        GITHUB_ACTION_INPUT_DocsOutputPath: ${{ inputs.DocsOutputPath }}
+      with:
+        Debug: ${{ inputs.Debug }}
+        Prerelease: ${{ inputs.Prerelease }}
+        Verbose: ${{ inputs.Verbose }}
+        Version: ${{ inputs.Version }}
+        Script: |
+          # Build-PSModule
+          . "${{ github.action_path }}\scripts\main.ps1"
+
+    - name: Upload module artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.ModuleArtifactName }}
+        path: ${{ inputs.ModulesOutputPath }}
+        if-no-files-found: error
+        retention-days: 1
+
+    - name: Upload docs artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ inputs.DocsArtifactName }}
+        path: ${{ inputs.DocsOutputPath }}
+        if-no-files-found: error
+        retention-days: 1

.github/actions/Build/scripts/helpers/Build-PSModule.ps1

@@ -0,0 +1,61 @@
+#Requires -Modules @{ ModuleName = 'GitHub'; ModuleVersion = '0.13.2' }
+#Requires -Modules @{ ModuleName = 'Utilities'; ModuleVersion = '0.3.0' }
+
+function Build-PSModule {
+    <#
+        .SYNOPSIS
+        Builds a module.
+
+        .DESCRIPTION
+        Builds a module.
+    #>
+    [CmdletBinding()]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter', '', Scope = 'Function',
+        Justification = 'LogGroup - Scoping affects the variables line of sight.'
+    )]
+    param(
+        # Name of the module.
+        [Parameter(Mandatory)]
+        [string] $ModuleName,
+
+        # Path to the folder where the modules are located.
+        [Parameter(Mandatory)]
+        [string] $ModuleSourceFolderPath,
+
+        # Path to the folder where the built modules are outputted.
+        [Parameter(Mandatory)]
+        [string] $ModulesOutputFolderPath,
+
+        # Path to the folder where the documentation is outputted.
+        [Parameter(Mandatory)]
+        [string] $DocsOutputFolderPath
+    )
+
+    LogGroup "Building module [$ModuleName]" {
+        Write-Host "Source path:          [$ModuleSourceFolderPath]"
+        if (-not (Test-Path -Path $ModuleSourceFolderPath)) {
+            Write-Error "Source folder not found at [$ModuleSourceFolderPath]"
+            exit 1
+        }
+        $moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath
+        Write-Host "Module source folder: [$moduleSourceFolder]"
+
+        $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force
+        Write-Host "Module output folder: [$moduleOutputFolder]"
+
+        $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force
+        Write-Host "Docs output folder:   [$docsOutputFolder]"
+    }
+
+    Build-PSModuleBase -ModuleName $ModuleName -ModuleSourceFolder $moduleSourceFolder -ModuleOutputFolder $moduleOutputFolder
+    Build-PSModuleManifest -ModuleName $ModuleName -ModuleOutputFolder $moduleOutputFolder
+    Build-PSModuleRootModule -ModuleName $ModuleName -ModuleOutputFolder $moduleOutputFolder
+    Update-PSModuleManifestAliasesToExport -ModuleName $ModuleName -ModuleOutputFolder $moduleOutputFolder
+    Build-PSModuleDocumentation -ModuleName $ModuleName -ModuleSourceFolder $moduleSourceFolder -DocsOutputFolder $docsOutputFolder
+
+    LogGroup 'Build manifest file - Final Result' {
+        $outputManifestPath = Join-Path -Path $ModuleOutputFolder -ChildPath "$ModuleName.psd1"
+        Show-FileContent -Path $outputManifestPath
+    }
+}

.github/actions/Build/scripts/helpers/Build/Add-ContentFromItem.ps1

@@ -0,0 +1,66 @@
+function Add-ContentFromItem {
+    <#
+        .SYNOPSIS
+        Add the content of a folder or file to the root module file.
+
+        .DESCRIPTION
+        This function will add the content of a folder or file to the root module file.
+
+        .EXAMPLE
+        Add-ContentFromItem -Path 'C:\MyModule\src\MyModule' -RootModuleFilePath 'C:\MyModule\src\MyModule.psm1' -RootPath 'C:\MyModule\src'
+    #>
+    param(
+        # The path to the folder or file to process.
+        [Parameter(Mandatory)]
+        [string] $Path,
+
+        # The path to the root module file.
+        [Parameter(Mandatory)]
+        [string] $RootModuleFilePath,
+
+        # The root path of the module.
+        [Parameter(Mandatory)]
+        [string] $RootPath
+    )
+    # Get the path separator for the current OS
+    $pathSeparator = [System.IO.Path]::DirectorySeparatorChar
+
+    $relativeFolderPath = $Path -Replace $RootPath, ''
+    $relativeFolderPath = $relativeFolderPath -Replace $file.Extension, ''
+    $relativeFolderPath = $relativeFolderPath.TrimStart($pathSeparator)
+    $relativeFolderPath = $relativeFolderPath -Split $pathSeparator | ForEach-Object { "[$_]" }
+    $relativeFolderPath = $relativeFolderPath -Join ' - '
+
+    Add-Content -Path $RootModuleFilePath -Force -Value @"
+#region    $relativeFolderPath
+Write-Debug "[`$scriptName] - $relativeFolderPath - Processing folder"
+"@
+
+    $files = $Path | Get-ChildItem -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
+    foreach ($file in $files) {
+        $relativeFilePath = $file.FullName -Replace $RootPath, ''
+        $relativeFilePath = $relativeFilePath -Replace $file.Extension, ''
+        $relativeFilePath = $relativeFilePath.TrimStart($pathSeparator)
+        $relativeFilePath = $relativeFilePath -Split $pathSeparator | ForEach-Object { "[$_]" }
+        $relativeFilePath = $relativeFilePath -Join ' - '
+
+        Add-Content -Path $RootModuleFilePath -Force -Value @"
+#region    $relativeFilePath
+Write-Debug "[`$scriptName] - $relativeFilePath - Importing"
+"@
+        Get-Content -Path $file.FullName | Add-Content -Path $RootModuleFilePath -Force
+        Add-Content -Path $RootModuleFilePath -Value @"
+Write-Debug "[`$scriptName] - $relativeFilePath - Done"
+#endregion $relativeFilePath
+"@
+    }
+
+    $subFolders = $Path | Get-ChildItem -Directory -Force | Sort-Object -Property Name
+    foreach ($subFolder in $subFolders) {
+        Add-ContentFromItem -Path $subFolder.FullName -RootModuleFilePath $RootModuleFilePath -RootPath $RootPath
+    }
+    Add-Content -Path $RootModuleFilePath -Force -Value @"
+Write-Debug "[`$scriptName] - $relativeFolderPath - Done"
+#endregion $relativeFolderPath
+"@
+}

.github/actions/Build/scripts/helpers/Build/Build-PSModuleBase.ps1

@@ -0,0 +1,43 @@
+#Requires -Modules @{ ModuleName = 'GitHub'; ModuleVersion = '0.13.2' }
+
+function Build-PSModuleBase {
+    <#
+        .SYNOPSIS
+        Compiles the base module files.
+
+        .DESCRIPTION
+        This function will compile the base module files.
+        It will copy the source files to the output folder and remove the files that are not needed.
+
+        .EXAMPLE
+        Build-PSModuleBase -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
+    #>
+    [CmdletBinding()]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter', '', Scope = 'Function',
+        Justification = 'LogGroup - Scoping affects the variables line of sight.'
+    )]
+    param(
+        # Name of the module.
+        [Parameter(Mandatory)]
+        [string] $ModuleName,
+
+        # Path to the folder where the module source code is located.
+        [Parameter(Mandatory)]
+        [System.IO.DirectoryInfo] $ModuleSourceFolder,
+
+        # Path to the folder where the built modules are outputted.
+        [Parameter(Mandatory)]
+        [System.IO.DirectoryInfo] $ModuleOutputFolder
+    )
+
+    LogGroup 'Build base' {
+        Write-Host "Copying files from [$ModuleSourceFolder] to [$ModuleOutputFolder]"
+        Copy-Item -Path "$ModuleSourceFolder\*" -Destination $ModuleOutputFolder -Recurse -Force -Verbose -Exclude "$ModuleName.psm1"
+        New-Item -Path $ModuleOutputFolder -Name "$ModuleName.psm1" -ItemType File -Force -Verbose
+    }
+
+    LogGroup 'Build base - Result' {
+        (Get-ChildItem -Path $ModuleOutputFolder -Recurse -Force).FullName | Sort-Object
+    }
+}

.github/actions/Build/scripts/helpers/Build/Build-PSModuleDocumentation.ps1

@@ -0,0 +1,110 @@
+#Requires -Modules @{ ModuleName = 'GitHub'; ModuleVersion = '0.13.2' }
+#Requires -Modules @{ ModuleName = 'platyPS'; ModuleVersion = '0.14.2' }
+#Requires -Modules @{ ModuleName = 'Utilities'; ModuleVersion = '0.3.0' }
+
+function Build-PSModuleDocumentation {
+    <#
+        .SYNOPSIS
+        Compiles the module documentation.
+
+        .DESCRIPTION
+        This function will compile the module documentation.
+        It will generate the markdown files for the module help and copy them to the output folder.
+
+        .EXAMPLE
+        Build-PSModuleDocumentation -ModuleOutputFolder 'C:\MyModule\src\MyModule' -DocsOutputFolder 'C:\MyModule\build\MyModule'
+    #>
+    [CmdletBinding()]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSReviewUnusedParameter', '', Scope = 'Function',
+        Justification = 'LogGroup - Scoping affects the variables line of sight.'
+    )]
+    param(
+        # Name of the module.
+        [Parameter(Mandatory)]
+        [string] $ModuleName,
+
+        # Path to the folder where the module source code is located.
+        [Parameter(Mandatory)]
+        [System.IO.DirectoryInfo] $ModuleSourceFolder,
+
+        # Folder where the documentation for the modules should be outputted. 'outputs/docs/MyModule'
+        [Parameter(Mandatory)]
+        [System.IO.DirectoryInfo] $DocsOutputFolder
+    )
+
+    LogGroup 'Build docs - Generate markdown help' {
+        $ModuleName | Remove-Module -Force
+        Import-Module -Name $ModuleName -Force -RequiredVersion '999.0.0'
+        Write-Host ($ModuleName | Get-Module)
+        $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
+    }
+
+    LogGroup 'Build docs - Fix markdown code blocks' {
+        Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+            $content = Get-Content -Path $_.FullName
+            $fixedOpening = $false
+            $newContent = @()
+            foreach ($line in $content) {
+                if ($line -match '^```$' -and -not $fixedOpening) {
+                    $line = $line -replace '^```$', '```powershell'
+                    $fixedOpening = $true
+                } elseif ($line -match '^```.+$') {
+                    $fixedOpening = $true
+                } elseif ($line -match '^```$') {
+                    $fixedOpening = $false
+                }
+                $newContent += $line
+            }
+            $newContent | Set-Content -Path $_.FullName
+        }
+    }
+
+    LogGroup 'Build docs - Fix markdown escape characters' {
+        Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+            $content = Get-Content -Path $_.FullName -Raw
+            $content = $content -replace '\\`', '`'
+            $content = $content -replace '\\\[', '['
+            $content = $content -replace '\\\]', ']'
+            $content = $content -replace '\\\<', '<'
+            $content = $content -replace '\\\>', '>'
+            $content = $content -replace '\\\\', '\'
+            $content | Set-Content -Path $_.FullName
+        }
+    }
+
+    LogGroup 'Build docs - Structure markdown files to match source files' {
+        $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
+        Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+            $file = $_
+            Write-Host "Processing:        $file"
+
+            # find the source code file that matches the markdown file
+            $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
+            Write-Host "Found script path: $scriptPath"
+            $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
+            Write-Host "Doc file path:     $docsFilePath"
+            $docsFolderPath = Split-Path -Path $docsFilePath -Parent
+            New-Item -Path $docsFolderPath -ItemType Directory -Force
+            Move-Item -Path $file.FullName -Destination $docsFilePath -Force
+        }
+        # Get the MD files that are in the public functions folder and move them to the same place in the docs folder
+        Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+            $file = $_
+            Write-Host "Processing:        $file"
+            $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName)
+            Write-Host "Doc file path:     $docsFilePath"
+            $docsFolderPath = Split-Path -Path $docsFilePath -Parent
+            New-Item -Path $docsFolderPath -ItemType Directory -Force
+            Move-Item -Path $file.FullName -Destination $docsFilePath -Force
+        }
+    }
+
+    Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+        $fileName = $_.Name
+        $hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash
+        LogGroup " - [$fileName] - [$hash]" {
+            Show-FileContent -Path $_
+        }
+    }
+}