PSModule · MariusStorhaug · Feb 12, 2025 · Feb 10, 2025 · Feb 10, 2025 · Feb 10, 2025
@@ -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
@@ -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
+    }
+}
@@ -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
+"@
+}
@@ -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
+    }
+}
@@ -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 $_
+        }
+    }
+}