From 29d8cca8a5bf4e9d74f5a1267bd399823dcf30cf Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:28:19 +0100 Subject: [PATCH 1/6] State module build help directly --- .github/actions/Build-PSModule/action.yml | 8 +++--- .../src/helpers/Build-PSModule.ps1 | 10 +++---- .../src/helpers/Build/Add-ContentFromItem.ps1 | 2 +- .../src/helpers/Build/Build-PSModuleBase.ps1 | 10 +++---- .../helpers/Build/Build-PSModuleManifest.ps1 | 7 +++-- .../Build/Build-PSModuleRootModule.ps1 | 27 +++++++++---------- .../Build/Get-PSModuleAliasesToExport.ps1 | 6 ++--- .../Build/Get-PSModuleClassesToExport.ps1 | 4 +-- .../Build/Get-PSModuleCmdletsToExport.ps1 | 6 ++--- .../Build/Get-PSModuleFunctionsToExport.ps1 | 6 ++--- .../Build/Get-PSModuleVariablesToExport.ps1 | 6 ++--- .../helpers/Build/Get-RootLevelVariables.ps1 | 6 ++--- ...Update-PSModuleManifestAliasesToExport.ps1 | 8 +++--- 13 files changed, 52 insertions(+), 54 deletions(-) diff --git a/.github/actions/Build-PSModule/action.yml b/.github/actions/Build-PSModule/action.yml index 54840096..7e5bb5df 100644 --- a/.github/actions/Build-PSModule/action.yml +++ b/.github/actions/Build-PSModule/action.yml @@ -1,5 +1,5 @@ name: Build-PSModule -description: Build a PowerShell module to the PowerShell Gallery. +description: Build a PowerShell module for publication to the PowerShell Gallery. author: PSModule inputs: @@ -7,21 +7,21 @@ inputs: description: Name of the module to build. Defaults to the repository name. required: false OutputFolder: - description: Path to the folder where the built module is outputted. + description: Path to the folder for the built module. required: false default: '.PSModule/module' Version: description: Module version to stamp into the manifest. required: true Prerelease: - description: Prerelease tag to stamp into the manifest's `PrivateData.PSData.Prerelease`. When empty, no prerelease tag is written. + description: Prerelease tag for the manifest's `PrivateData.PSData.Prerelease`. An empty value omits the prerelease tag. required: false ArtifactName: description: Name of the artifact to upload. required: false default: module WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' diff --git a/.github/actions/Build-PSModule/src/helpers/Build-PSModule.ps1 b/.github/actions/Build-PSModule/src/helpers/Build-PSModule.ps1 index f4ee2ba1..d729f930 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build-PSModule.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build-PSModule.ps1 @@ -1,10 +1,10 @@ function Build-PSModule { <# .SYNOPSIS - Builds a module. + Build a PowerShell module from source files. .DESCRIPTION - Builds a module. + Build-PSModule copies the source files, creates the manifest, and combines the scripts into the root module. #> [OutputType([void])] [CmdletBinding()] @@ -21,11 +21,11 @@ [Parameter(Mandatory)] [string] $ModuleName, - # Path to the folder where the modules are located. + # Path to the module source folder. [Parameter(Mandatory)] [string] $ModuleSourceFolderPath, - # Path to the folder where the built modules are outputted. + # Path to the folder for the built module. [Parameter(Mandatory)] [string] $ModuleOutputFolderPath, @@ -33,7 +33,7 @@ [Parameter(Mandatory)] [string] $ModuleVersion, - # Prerelease tag to stamp into the manifest. When empty, no prerelease tag is written. + # Prerelease tag for the manifest. An empty value omits the prerelease tag. [Parameter()] [string] $ModulePrerelease ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1 index 095b7d98..b5364256 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1 @@ -4,7 +4,7 @@ function Add-ContentFromItem { 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. + Add-ContentFromItem adds 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' diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1 index cc95352b..34b866b1 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1 @@ -1,11 +1,11 @@ function Build-PSModuleBase { <# .SYNOPSIS - Compiles the base module files. + Build 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. + Build-PSModuleBase copies source files to the output folder. + It creates an empty root module file. .EXAMPLE Build-PSModuleBase -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule' @@ -24,11 +24,11 @@ [Parameter(Mandatory)] [string] $ModuleName, - # Path to the folder where the module source code is located. + # Path to the module source folder. [Parameter(Mandatory)] [System.IO.DirectoryInfo] $ModuleSourceFolder, - # Path to the folder where the built modules are outputted. + # Path to the folder for the built module. [Parameter(Mandatory)] [System.IO.DirectoryInfo] $ModuleOutputFolder ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1 index 8ea8d93a..25994aca 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1 @@ -1,11 +1,10 @@ function Build-PSModuleManifest { <# .SYNOPSIS - Compiles the module manifest. + Build the module manifest. .DESCRIPTION - This function will compile the module manifest. - It will generate the module manifest file and copy it to the output folder. + Build-PSModuleManifest creates the module manifest in the output folder. .EXAMPLE Build-PSModuleManifest -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule' @@ -28,7 +27,7 @@ [Parameter(Mandatory)] [string] $ModuleName, - # Folder where the built module is outputted. '.PSModule/module/MyModule' + # Folder for the built module files. '.PSModule/module/MyModule' [Parameter(Mandatory)] [System.IO.DirectoryInfo] $ModuleOutputFolder, diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1 index 7a70ee93..7a5af6a1 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1 @@ -1,16 +1,15 @@ function Build-PSModuleRootModule { <# .SYNOPSIS - Compiles the module root module files. + Build the root module file from source scripts. .DESCRIPTION - This function will compile the modules root module from source files. - It will copy the source files to the output folder and start compiling the module. - During compilation, the source files are added to the root module file in the following order: + Build-PSModuleRootModule combines source scripts in the output folder into the root module file. + It adds content in this order: - 1. Module header from header.ps1 file. Usually to suppress code analysis warnings/errors and to add [CmdletBinding()] to the module. - 2. Data loader is added if data files are available. - 3. Combines *.ps1 files from the following folders in alphabetical order from each folder: + 1. The header.ps1 module header, which can suppress code analysis warnings and errors or add [CmdletBinding()]. + 2. A data loader, if data files are available. + 3. The *.ps1 files from these folders, in alphabetical order within each folder: 1. init 2. classes/private 3. classes/public @@ -18,13 +17,13 @@ 5. functions/public 6. variables/private 7. variables/public - 8. Any remaining *.ps1 on module root. - 4. Adds a class loader for classes found in the classes/public folder. - 5. Export-ModuleMember by using the functions, cmdlets, variables and aliases found in the source files. - - `Functions` will only contain functions that are from the `functions/public` folder. + 8. Any remaining *.ps1 files in the module root. + 4. A class loader for classes in the classes/public folder. + 5. An Export-ModuleMember call with the functions, cmdlets, variables, and aliases from the source files. + - `Functions` contains only functions from the `functions/public` folder. - `Cmdlets` will only contain cmdlets that are from the `cmdlets/public` folder. - - `Variables` will only contain variables that are from the `variables/public` folder. - - `Aliases` will only contain aliases that are from the functions from the `functions/public` folder. + - `Variables` contains only variables from the `variables/public` folder. + - `Aliases` contains only aliases from functions in the `functions/public` folder. .EXAMPLE Build-PSModuleRootModule -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule' @@ -43,7 +42,7 @@ [Parameter(Mandatory)] [string] $ModuleName, - # Folder where the built module is outputted. '.PSModule/module/MyModule' + # Folder for the built module files. '.PSModule/module/MyModule' [Parameter(Mandatory)] [System.IO.DirectoryInfo] $ModuleOutputFolder ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleAliasesToExport.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleAliasesToExport.ps1 index adc21d13..b5e38588 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleAliasesToExport.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleAliasesToExport.ps1 @@ -1,10 +1,10 @@ function Get-PSModuleAliasesToExport { <# .SYNOPSIS - Gets the aliases to export from the module manifest. + Get the aliases to export from the module manifest. .DESCRIPTION - This function will get the aliases to export from the module manifest. + Get-PSModuleAliasesToExport reads AliasesToExport from the module manifest. .EXAMPLE Get-PSModuleAliasesToExport -SourceFolderPath 'C:\MyModule\src\MyModule' @@ -13,7 +13,7 @@ [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope = 'Function', Justification = 'Want to just write to the console, not the pipeline.')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')] param( - # Path to the folder where the module source code is located. + # Path to the module source folder. [Parameter(Mandatory)] [string] $SourceFolderPath ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1 index 4b541f63..9cf3394c 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1 @@ -1,10 +1,10 @@ function Get-PSModuleClassesToExport { <# .SYNOPSIS - Gets the classes to export from the module source code. + Get the classes and enums to export from the module source code. .DESCRIPTION - This function will get the classes to export from the module source code. + Get-PSModuleClassesToExport finds class and enum declarations in source files. .EXAMPLE Get-PSModuleClassesToExport -SourceFolderPath 'C:\MyModule\src\MyModule' diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleCmdletsToExport.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleCmdletsToExport.ps1 index 1ac20e65..fe2091e6 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleCmdletsToExport.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleCmdletsToExport.ps1 @@ -1,10 +1,10 @@ function Get-PSModuleCmdletsToExport { <# .SYNOPSIS - Gets the cmdlets to export from the module manifest. + Get the cmdlets to export from the module manifest. .DESCRIPTION - This function will get the cmdlets to export from the module manifest. + Get-PSModuleCmdletsToExport reads CmdletsToExport from the module manifest. .EXAMPLE Get-PSModuleCmdletsToExport -SourceFolderPath 'C:\MyModule\src\MyModule' @@ -13,7 +13,7 @@ [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope = 'Function', Justification = 'Want to just write to the console, not the pipeline.')] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')] param( - # Path to the folder where the module source code is located. + # Path to the module source folder. [Parameter(Mandatory)] [string] $SourceFolderPath ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleFunctionsToExport.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleFunctionsToExport.ps1 index 3d64494d..912c8c39 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleFunctionsToExport.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleFunctionsToExport.ps1 @@ -1,10 +1,10 @@ function Get-PSModuleFunctionsToExport { <# .SYNOPSIS - Gets the functions to export from the module manifest. + Get the functions and filters to export from the module source code. .DESCRIPTION - This function will get the functions to export from the module manifest. + Get-PSModuleFunctionsToExport reads public source files to identify the functions and filters to export. .EXAMPLE Get-PSModuleFunctionsToExport -SourceFolderPath 'C:\MyModule\src\MyModule' @@ -14,7 +14,7 @@ [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')] [OutputType([array])] param( - # Path to the folder where the module source code is located. + # Path to the module source folder. [Parameter(Mandatory)] [string] $SourceFolderPath ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleVariablesToExport.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleVariablesToExport.ps1 index 6649d91b..d7db7f35 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleVariablesToExport.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleVariablesToExport.ps1 @@ -1,10 +1,10 @@ function Get-PSModuleVariablesToExport { <# .SYNOPSIS - Gets the variables to export from the module manifest. + Get the variables to export from the module source code. .DESCRIPTION - This function will get the variables to export from the module manifest. + Get-PSModuleVariablesToExport reads root-level assignments in public variable files. .EXAMPLE Get-PSModuleVariablesToExport -SourceFolderPath 'C:\MyModule\src\MyModule' @@ -17,7 +17,7 @@ [OutputType([Collections.Generic.List[string]])] [CmdletBinding()] param( - # Path to the folder where the module source code is located. + # Path to the module source folder. [Parameter(Mandatory)] [string] $SourceFolderPath ) diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Get-RootLevelVariables.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Get-RootLevelVariables.ps1 index 20daece6..3525e553 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Get-RootLevelVariables.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Get-RootLevelVariables.ps1 @@ -1,19 +1,19 @@ function Get-RootLevelVariable { <# .SYNOPSIS - Get the root-level variables in a ast. + Get the root-level variables in an AST. .EXAMPLE Get-RootLevelVariable -Ast $ast #> [CmdletBinding()] param ( - # The Abstract Syntax Tree (AST) to analyze + # The abstract syntax tree (AST) to analyze. [System.Management.Automation.Language.ScriptBlockAst]$Ast ) # Iterate over the top-level statements in the AST foreach ($statement in $Ast.EndBlock.Statements) { - # Check if the statement is an assignment statement + # Return only variables from root-level assignments. if ($statement -is [System.Management.Automation.Language.AssignmentStatementAst]) { # Get the variable name, removing the scope prefix $statement.Left.VariablePath.UserPath -replace '.*:' diff --git a/.github/actions/Build-PSModule/src/helpers/Build/Update-PSModuleManifestAliasesToExport.ps1 b/.github/actions/Build-PSModule/src/helpers/Build/Update-PSModuleManifestAliasesToExport.ps1 index 5597cd1e..1919de3e 100644 --- a/.github/actions/Build-PSModule/src/helpers/Build/Update-PSModuleManifestAliasesToExport.ps1 +++ b/.github/actions/Build-PSModule/src/helpers/Build/Update-PSModuleManifestAliasesToExport.ps1 @@ -1,7 +1,7 @@ function Update-PSModuleManifestAliasesToExport { <# .SYNOPSIS - Updates the aliases to export in the module manifest. + Update the aliases to export in the module manifest. #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute( 'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function', @@ -21,11 +21,11 @@ [Parameter(Mandatory)] [string] $ModuleName, - # Path to the folder where the module source code is located. + # Path to the module source folder. [Parameter(Mandatory)] [System.IO.DirectoryInfo] $ModuleSourceFolder, - # Path to the folder where the built modules are outputted. + # Path to the folder for the built module. [Parameter(Mandatory)] [System.IO.DirectoryInfo] $ModuleOutputFolder ) @@ -40,7 +40,7 @@ return } - # Get all child items in the module source folder of a powershell file type + # Find PowerShell files in the public functions folder. $files = Get-ChildItem -Path $publicFunctionsPath -Recurse -File -Include '*.ps1', '*.psm1' | Select-Object -ExpandProperty FullName # Initialize an array to store all found aliases From c4319be34771511271f14d001baac44a50a8a028 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:31:28 +0100 Subject: [PATCH 2/6] Describe helper operations in native PowerShell help --- .../helpers/Build-PSModuleDocumentation.ps1 | 31 ++-- .../src/PSModule/PSModule.psm1 | 158 +++++++++--------- 2 files changed, 90 insertions(+), 99 deletions(-) diff --git a/.github/actions/Document-PSModule/src/helpers/Build-PSModuleDocumentation.ps1 b/.github/actions/Document-PSModule/src/helpers/Build-PSModuleDocumentation.ps1 index 5b8ab206..5acb18ce 100644 --- a/.github/actions/Document-PSModule/src/helpers/Build-PSModuleDocumentation.ps1 +++ b/.github/actions/Document-PSModule/src/helpers/Build-PSModuleDocumentation.ps1 @@ -1,10 +1,10 @@ function Build-PSModuleDocumentation { <# .SYNOPSIS - Builds a module. + Build documentation for a PowerShell module. .DESCRIPTION - Builds a module. + Build-PSModuleDocumentation creates Markdown help for exported commands and arranges the pages to match the public source folders. #> [CmdletBinding()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute( @@ -16,19 +16,19 @@ [Parameter(Mandatory)] [string] $ModuleName, - # Path to the folder where the modules are located. + # Path to the module source folder. [Parameter(Mandatory)] [string] $ModuleSourceFolderPath, - # Path to the folder where the built modules are outputted. + # Path to the folder for the built modules. [Parameter(Mandatory)] [string] $ModulesOutputFolderPath, - # Path to the folder where the documentation is outputted. + # Path to the documentation output folder. [Parameter(Mandatory)] [string] $DocsOutputFolderPath, - # Show GitHub Step Summary even when all commands succeed. + # Show the GitHub step summary even when all commands succeed. [Parameter()] [bool] $ShowSummaryOnSuccess = $false ) @@ -95,7 +95,7 @@ $hasFailures = $failedCommands.Count -gt 0 $shouldShowSummary = $hasFailures -or $ShowSummaryOnSuccess - # Generate summary if ShowSummaryOnSuccess is enabled + # Show the summary on failure or when ShowSummaryOnSuccess is enabled. if ($shouldShowSummary) { $statusIcon = $hasFailures ? '❌' : '✅' $statusText = $hasFailures ? 'Failed' : 'Succeeded' @@ -151,7 +151,7 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join Write-Host '::endgroup::' } - # Fail the task if there were any failures (independent of summary display) + # Fail the task on any command failure, independent of the summary display. if ($hasFailures) { Write-Error "Documentation generation failed for $($failedCommands.Count) command(s). See above for details." exit 1 @@ -205,7 +205,7 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join Write-Host " - $relPath" Write-Host " Path: $file" - # find the source code file that matches the markdown file + # Find the source file that matches the Markdown file. $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') } Write-Host " PS1 path: $scriptPath" $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder).Replace('.ps1', '.md') @@ -227,9 +227,8 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join # Enumerate the public markdown once and reuse it (no second tree walk). $publicMarkdownFiles = @(Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -File -Include '*.md') - # Folders that provide an explicit index page. Detected case-insensitively because the runner - # filesystem is case-sensitive. Two index pages that differ only by case (index.md and - # Index.md) are ambiguous, so fail fast instead of silently overwriting one. + # Compare index names without case sensitivity because the runner filesystem is case-sensitive. + # Reject index.md and Index.md in the same folder to prevent an ambiguous section index. $explicitIndexFolders = [System.Collections.Generic.HashSet[string]]::new() $indexGroups = $publicMarkdownFiles | Where-Object { $_.Name -ieq 'index.md' } | Group-Object { $_.Directory.FullName } foreach ($group in $indexGroups) { @@ -247,14 +246,12 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder) - # A group's overview page becomes the section landing page (index.md) so the navigation - # shows it when the group is selected, instead of a page nested under the group. Authors - # can either name it after the folder (e.g. Auth/Auth.md) or provide Auth/index.md directly. + # A group's overview becomes index.md so the navigation opens it as the section landing page. + # Authors can use the folder name (Auth/Auth.md) or provide Auth/index.md. $parentFolder = Split-Path -Path $file.FullName -Parent $parentFolderName = Split-Path -Path $parentFolder -Leaf if ($file.Name -ieq 'index.md') { - # Normalize any casing (Index.md/INDEX.md) to index.md so it is treated as the - # section index on case-sensitive filesystems. + # Normalize Index.md/INDEX.md to index.md for section indexes on case-sensitive filesystems. $docsFilePath = Join-Path -Path (Split-Path -Path $docsFilePath -Parent) -ChildPath 'index.md' Write-Host ' Section index page detected - publishing as index.md' } elseif ($file.BaseName -eq $parentFolderName) { diff --git a/.github/actions/Install-PSModule/src/PSModule/PSModule.psm1 b/.github/actions/Install-PSModule/src/PSModule/PSModule.psm1 index 555be40c..24cf8fca 100644 --- a/.github/actions/Install-PSModule/src/PSModule/PSModule.psm1 +++ b/.github/actions/Install-PSModule/src/PSModule/PSModule.psm1 @@ -8,18 +8,17 @@ param() function Convert-VersionSpec { <# .SYNOPSIS - Converts legacy version parameters into a NuGet version range string. + Convert legacy version parameters to a NuGet version range string. .DESCRIPTION - This function takes minimum, maximum, or required version parameters - and constructs a NuGet-compatible version range string. + Convert-VersionSpec converts minimum, maximum, or required version parameters + to a NuGet version range string. - - If `RequiredVersion` is specified, the output is an exact match range. - - If both `MinimumVersion` and `MaximumVersion` are provided, - an inclusive range is returned. - - If only `MinimumVersion` is provided, it returns a minimum-inclusive range. - - If only `MaximumVersion` is provided, it returns an upper-bound range. - - If no parameters are provided, `$null` is returned. + - With `RequiredVersion`, the function returns an exact-match range. + - With `MinimumVersion` and an explicit `MaximumVersion`, the function returns an inclusive range. + - With only `MinimumVersion`, the function returns a minimum-inclusive range. + - With only `MaximumVersion`, the function returns an upper-bound range. + - With no version parameters, the function returns `$null`. .EXAMPLE Convert-VersionSpec -MinimumVersion "1.0.0" -MaximumVersion "2.0.0" @@ -65,8 +64,7 @@ function Convert-VersionSpec { string .NOTES - The NuGet version range string based on the provided parameters. - The returned string follows NuGet versioning syntax. + The result uses NuGet version range syntax. .LINK https://psmodule.io/Convert/Functions/Convert-VersionSpec @@ -74,15 +72,15 @@ function Convert-VersionSpec { [OutputType([string])] [CmdletBinding()] param( - # The minimum version for the range. If specified alone, the range is open-ended upwards. + # Minimum version for the range. Without a maximum, the range has no upper bound. [Parameter()] [string] $MinimumVersion, - # The maximum version for the range. If specified alone, the range is open-ended downwards. + # Maximum version for the range. Without a minimum, the range has no lower bound. [Parameter()] [string] $MaximumVersion, - # Specifies an exact required version. If set, an exact version range is returned. + # Required version. This value selects an exact-match range. [Parameter()] [string] $RequiredVersion ) @@ -118,7 +116,7 @@ function Convert-VersionSpec { # Only a minimum is provided. Use a minimum-inclusive range. return "[$MinimumVersion, ]" } elseif ($MaximumVersion) { - # Only a maximum is provided; lower bound open. Wildcards are exclusive upper bounds. + # With only a maximum, the lower bound is open. Wildcards select exclusive upper bounds. $upperBound = $maximumVersionIsWildcard ? ')' : ']' return "(, $MaximumVersion$upperBound" } else { @@ -129,10 +127,10 @@ function Convert-VersionSpec { function Import-PSModule { <# .SYNOPSIS - Imports a build PS module. + Import a built PowerShell module. .DESCRIPTION - Imports a build PS module. + Import-PSModule resolves the module dependencies and imports the module from Path. .EXAMPLE Import-PSModule -SourceFolderPath $ModuleFolderPath -ModuleName $moduleName @@ -141,7 +139,7 @@ function Import-PSModule { #> [CmdletBinding()] param( - # Path to the folder where the module source code is located. + # Path to the built module folder. [Parameter(Mandatory)] [string] $Path ) @@ -173,22 +171,21 @@ function Import-PSModule { function Resolve-PSModuleDependency { <# .SYNOPSIS - Resolves module dependencies from a manifest file using Install-PSResource. + Resolve module dependencies from a manifest with Install-PSResource. .DESCRIPTION - Reads a module manifest (PSD1) and for each required module converts the old - Install-Module parameters (MinimumVersion, MaximumVersion, RequiredVersion) - into a single NuGet version range string for Install-PSResource's –Version parameter. - (Note: If RequiredVersion is set, that value takes precedence.) + Resolve-PSModuleDependency reads the required modules from a manifest file (PSD1). + It converts the Install-Module parameters MinimumVersion, MaximumVersion, and RequiredVersion + to a NuGet version range for Install-PSResource's -Version parameter. + RequiredVersion takes precedence. .EXAMPLE Resolve-PSModuleDependency -ManifestFilePath 'C:\MyModule\MyModule.psd1' Installs all modules defined in the manifest file, following PSModuleInfo structure. .NOTES - Should later be adapted to support both pre-reqs, and dependencies. - Should later be adapted to take 4 parameters sets: specific version ("requiredVersion" | "GUID"), latest version ModuleVersion, - and latest version within a range MinimumVersion - MaximumVersion. + The function uses the manifest's RequiredModules entries. + It does not expose separate parameters for prerequisite modules, GUID selection, or version selection. #> [CmdletBinding()] param( @@ -275,10 +272,10 @@ function Resolve-PSModuleDependency { function Show-FileContent { <# .SYNOPSIS - Prints the content of a file with line numbers in front of each line. + Show file content with a line number before each line. .DESCRIPTION - Prints the content of a file with line numbers in front of each line. + Show-FileContent writes each line to the host with a padded line number. .EXAMPLE $Path = 'C:\Utilities\Show-FileContent.ps1' @@ -288,7 +285,7 @@ function Show-FileContent { #> [CmdletBinding()] param ( - # The path to the file to show the content of. + # Path to the file to display. [Parameter(Mandatory)] [string] $Path ) @@ -296,8 +293,7 @@ function Show-FileContent { $content = Get-Content -Path $Path $lineNumber = 1 $columnSize = $content.Count.ToString().Length - # Foreach line print the line number in front of the line with [ ] around it. - # The linenumber should dynamically adjust to the number of digits with the length of the file. + # Pad line numbers to the width of the file's line count. foreach ($line in $content) { $lineNumberFormatted = $lineNumber.ToString().PadLeft($columnSize) Write-Host "[$lineNumberFormatted] $line" @@ -308,10 +304,10 @@ function Show-FileContent { function Install-PSModule { <# .SYNOPSIS - Installs a build PS module. + Install a built PowerShell module. .DESCRIPTION - Installs a build PS module. + Install-PSModule resolves dependencies, copies the module to PSModulePath, and imports the installed manifest. .EXAMPLE Install-PSModule -SourceFolderPath $ModuleFolderPath -ModuleName $moduleName @@ -320,11 +316,11 @@ function Install-PSModule { #> [CmdletBinding()] param( - # Path to the folder where the module source code is located. + # Path to the built module folder. [Parameter(Mandatory)] [string] $Path, - # Return the path of the installed module + # Return the path of the installed module. [Parameter()] [switch] $PassThru ) @@ -335,11 +331,9 @@ function Install-PSModule { Write-Host '::group::Resolving dependencies' Resolve-PSModuleDependency -ManifestFilePath $manifestFilePath Write-Host '::endgroup::' - # Install into a version folder that matches the manifest's ModuleVersion so PowerShell - # accepts the module. Fall back to the 999.0.0 placeholder only when the manifest is - # unstamped (e.g. a build that opted out of version resolution). Validate the version as a - # real [version] so a malformed manifest cannot inject path separators/traversal into the - # install path. + # The installation folder uses ModuleVersion so PowerShell accepts the module. + # If the manifest has no version, use 999.0.0. + # Validate [version] before path construction to prevent path traversal. $manifestVersion = (Import-PowerShellDataFile -Path $manifestFilePath).ModuleVersion if ([string]::IsNullOrWhiteSpace($manifestVersion)) { $moduleVersion = '999.0.0' @@ -357,9 +351,7 @@ function Install-PSModule { Select-Object -ExpandProperty FullName Copy-Item -Path "$Path/*" -Destination $codePath -Recurse -Force Write-Host '::group::Importing module' - # Import the freshly-installed copy explicitly by its manifest path (with -Force) so it is - # not shadowed by another version of the same module that may already be loaded or present - # on $env:PSModulePath. + # Import the installed manifest with -Force so PowerShell loads this copy, not another version on $env:PSModulePath. $installedManifestPath = Join-Path -Path $codePath -ChildPath "$moduleName.psd1" Import-Module -Name $installedManifestPath -Force -Global -Verbose Write-Host '::endgroup::' @@ -374,7 +366,7 @@ function Get-ModuleManifest { Get the module manifest. .DESCRIPTION - Get the module manifest as a path, file info, content, or hashtable. + Get-ModuleManifest returns file information, file content, or an ordered dictionary. .EXAMPLE Get-PSModuleManifest -Path 'src/PSModule/PSModule.psd1' -As Hashtable @@ -493,11 +485,11 @@ function Get-ModuleManifest { filter Set-ModuleManifest { <# .SYNOPSIS - Sets the values of a module manifest file. + Set values in a module manifest file. .DESCRIPTION - This function sets the values of a module manifest file. - Very much like the Update-ModuleManifest function, but allows values to be missing. + Set-ModuleManifest updates the manifest with the supplied values. + Unlike Update-ModuleManifest, it permits missing values. .EXAMPLE Set-ModuleManifest -Path 'C:\MyModule\MyModule.psd1' -ModuleVersion '1.0.0' @@ -618,14 +610,14 @@ filter Set-ModuleManifest { [AllowNull()] [Object[]] $NestedModules, - # Functions to export from this module, for best performance, do not use wildcards and do not - # delete the entry, use an empty array if there are no functions to export. + # Functions to export from this module. For best performance, do not use wildcards. + # Keep this entry. If the module exports no functions, use an empty array. [Parameter()] [AllowNull()] [string[]] $FunctionsToExport, - # Cmdlets to export from this module, for best performance, do not use wildcards and do not - # delete the entry, use an empty array if there are no cmdlets to export. + # Cmdlets to export from this module. For best performance, do not use wildcards. + # Keep this entry. If the module exports no cmdlets, use an empty array. [Parameter()] [AllowNull()] [string[]] $CmdletsToExport, @@ -635,8 +627,8 @@ filter Set-ModuleManifest { [AllowNull()] [string[]] $VariablesToExport, - # Aliases to export from this module, for best performance, do not use wildcards and do not - # delete the entry, use an empty array if there are no aliases to export. + # Aliases to export from this module. For best performance, do not use wildcards. + # Keep this entry. If the module exports no aliases, use an empty array. [Parameter()] [AllowNull()] [string[]] $AliasesToExport, @@ -912,7 +904,8 @@ function Export-PowerShellDataFile { Export a hashtable to a .psd1 file. .DESCRIPTION - This function exports a hashtable to a .psd1 file. It also formats the .psd1 file using the Format-ModuleManifest cmdlet. + Export-PowerShellDataFile writes a hashtable to a .psd1 file. + Format-ModuleManifest formats the file. .EXAMPLE Export-PowerShellDataFile -Hashtable @{ Name = 'MyModule'; ModuleVersion = '1.0.0' } -Path 'MyModule.psd1' @@ -940,11 +933,11 @@ function Export-PowerShellDataFile { function Format-ModuleManifest { <# .SYNOPSIS - Formats a module manifest file. + Format a module manifest file. .DESCRIPTION - This function formats a module manifest file, by removing comments and empty lines, - and then formatting the file using the `Invoke-Formatter` function. + Format-ModuleManifest removes comments and empty lines from the manifest. + The `Invoke-Formatter` function formats the remaining content. .EXAMPLE Format-ModuleManifest -Path 'C:\MyModule\MyModule.psd1' @@ -967,7 +960,7 @@ function Format-ModuleManifest { $content = Invoke-Formatter -ScriptDefinition $manifestContent - # Ensure exactly one empty line at the end + # End the file with one newline. $content = $content.TrimEnd([System.Environment]::NewLine) + [System.Environment]::NewLine [System.IO.File]::WriteAllText($Path, $content, $Utf8BomEncoding) @@ -976,12 +969,11 @@ function Format-ModuleManifest { filter Format-Hashtable { <# .SYNOPSIS - Converts a hashtable to its PowerShell code representation. + Convert a hashtable to PowerShell code. .DESCRIPTION - Recursively converts a hashtable to its PowerShell code representation. - This function is useful for exporting hashtables to `.psd1` files, - making it easier to store and retrieve structured data. + Format-Hashtable converts a hashtable and its nested values to PowerShell code. + The result supports storage in `.psd1` files. .EXAMPLE $hashtable = @{ @@ -1016,8 +1008,7 @@ filter Format-Hashtable { string .NOTES - A string representation of the given hashtable. - Useful for serialization and exporting hashtables to files. + The function returns a string for serialization or export to a file. .LINK https://psmodule.io/Hashtable/Functions/Format-Hashtable @@ -1126,11 +1117,11 @@ filter Format-Hashtable { function Add-PSModulePath { <# .SYNOPSIS - Adds a path to the PSModulePath environment variable. + Add a path to the PSModulePath environment variable. .DESCRIPTION - Adds a path to the PSModulePath environment variable. - For Linux and macOS, the path delimiter is ':' and for Windows it is ';'. + Add-PSModulePath appends a folder to the PSModulePath environment variable. + The path delimiter is ':' on Linux and macOS, and ';' on Windows. .EXAMPLE Add-PSModulePath -Path 'C:\Users\user\Documents\WindowsPowerShell\Modules' @@ -1156,11 +1147,11 @@ function Add-PSModulePath { function Set-GitHubLogGroup { <# .SYNOPSIS - Encapsulates commands with a log group in GitHub Actions + Run commands in a GitHub Actions log group. .DESCRIPTION - DSL approach for GitHub Action commands. - Allows for collapsing of code in IDE for code that belong together. + Set-GitHubLogGroup surrounds the script block output with GitHub Actions log group markers. + The script block keeps related commands together in the editor. .EXAMPLE Set-GitHubLogGroup -Name 'MyGroup' -ScriptBlock { @@ -1193,11 +1184,11 @@ function Set-GitHubLogGroup { )] [CmdletBinding()] param( - # The name of the log group + # The name of the log group. [Parameter(Mandatory)] [string] $Name, - # The script block to execute + # The script block to execute. [Parameter(Mandatory)] [scriptblock] $ScriptBlock ) @@ -1210,14 +1201,17 @@ function Set-GitHubLogGroup { function Import-TestData { <# .SYNOPSIS - Exposes caller-provided TestData as environment variables for later steps in the job. + Expose caller-provided TestData as environment variables for later steps in the job. .DESCRIPTION - Reads the `PSMODULE_TEST_DATA` environment variable, which is expected to contain a single-line - JSON object with optional `secrets` and `variables` maps. Each entry is validated and written to - the file referenced by `GITHUB_ENV` so it becomes available as `$env:` in subsequent steps - of the same job. Values under `secrets` are masked in the logs via `::add-mask::`; values under - `variables` are not. When no test data is provided the function is a no-op. + Import-TestData reads a single-line JSON object from the `PSMODULE_TEST_DATA` environment variable. + The object can contain `secrets` and `variables` maps. + The function validates each entry and writes it to `GITHUB_ENV` for later steps in the same job. + Those steps read each value as `$env:`. + + The function masks `secrets` values in logs with `::add-mask::`. + It does not mask `variables` values. + With no test data, the function makes no changes. .EXAMPLE Import-TestData @@ -1254,7 +1248,7 @@ function Import-TestData { function Assert-EnvironmentName { <# .SYNOPSIS - Validates that a TestData key can safely be written to GITHUB_ENV. + Validate a TestData key for use in GITHUB_ENV. #> param([string] $Name) if ($Name -notmatch '^[A-Za-z_][A-Za-z0-9_]*$') { @@ -1273,7 +1267,7 @@ function Import-TestData { function Assert-Map { <# .SYNOPSIS - Validates that a TestData section is a JSON object map. + Validate a TestData section as a JSON object map. #> param( [object] $Map, @@ -1287,7 +1281,7 @@ function Import-TestData { function Get-EnvironmentValue { <# .SYNOPSIS - Converts a scalar TestData value to an environment variable value. + Convert a scalar TestData value to an environment variable value. #> param( [object] $Value, @@ -1305,7 +1299,7 @@ function Import-TestData { function Add-EnvFromMap { <# .SYNOPSIS - Writes validated TestData entries to GITHUB_ENV. + Write validated TestData entries to GITHUB_ENV. #> param( [object] $Map, From f8a4e0a381fc855d20f059f1b61c664ee95cb07f Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:33:36 +0100 Subject: [PATCH 3/6] State repository index helper contracts directly --- .github/actions/update-index/action.yml | 2 +- .github/actions/update-index/src/Helper.psm1 | 106 +++++++++---------- 2 files changed, 52 insertions(+), 56 deletions(-) diff --git a/.github/actions/update-index/action.yml b/.github/actions/update-index/action.yml index 2eb4c755..64540436 100644 --- a/.github/actions/update-index/action.yml +++ b/.github/actions/update-index/action.yml @@ -1,5 +1,5 @@ name: Update index -description: Run repository index update script via GitHub-Script. +description: Update the repository index through GitHub-Script. inputs: ClientID: description: GitHub App client ID used by GitHub-Script. diff --git a/.github/actions/update-index/src/Helper.psm1 b/.github/actions/update-index/src/Helper.psm1 index 3b768321..7f01e40b 100644 --- a/.github/actions/update-index/src/Helper.psm1 +++ b/.github/actions/update-index/src/Helper.psm1 @@ -10,11 +10,10 @@ param() function Connect-GitHubAppDefaultContext { <# .SYNOPSIS - Ensures a default GitHub App context is active. + Select a default GitHub App context. .DESCRIPTION - Uses Connect-GitHubApp with -Default so subsequent GitHub module calls - use an authenticated default context instead of anonymous access. + Connect-GitHubAppDefaultContext reuses the owner's default GitHub App context or connects with Connect-GitHubApp -Default. #> [CmdletBinding()] param( @@ -39,11 +38,11 @@ function Connect-GitHubAppDefaultContext { function Show-RepoList { <# .SYNOPSIS - Displays a formatted list of repositories for a GitHub organization. + Show the repositories for a GitHub organization. .DESCRIPTION - Connects to the specified GitHub organization, retrieves all repositories with their - descriptions and custom Type property, then outputs a sorted table grouped by type and name. + Show-RepoList gets repositories with their descriptions and custom Type property. + It sorts them by type and name, displays a table, and returns the repository objects. .EXAMPLE Show-RepoList @@ -101,12 +100,12 @@ function Show-RepoList { function Update-MDSection { <# .SYNOPSIS - Updates a specific section within a markdown file. + Update a named section in a Markdown file. .DESCRIPTION - This function searches for a named section within a markdown file, identified by special comment markers. - It replaces the content between the markers with the provided new content. If the markers are not found, - an error is thrown. The function supports `-WhatIf` and `-Confirm` parameters for safety. + Update-MDSection replaces the content between the named comment markers. + If a marker is missing, the function throws an error. + It supports the `-WhatIf` and `-Confirm` parameters. .EXAMPLE Update-MDSection -Path '.\profile\README.md' -Name 'MODULE_LIST' -Content 'New module list' @@ -121,15 +120,15 @@ function Update-MDSection { [outputType([void])] [CmdletBinding(SupportsShouldProcess)] param( - # Path to the markdown file where the section should be updated. + # Path to the Markdown file to update. [Parameter()] [string] $Path = 'src\docs\index.md', - # Name of the section to be updated, used in comment markers. + # Section name in the comment markers. [Parameter()] [string] $Name = 'MODULE_LIST', - # The new content to insert between the section markers. + # Content to insert between the section markers. [Parameter()] [string] $Content ) @@ -163,10 +162,10 @@ function Update-MDSection { function Get-TemplateContent { <# .SYNOPSIS - Reads a template file as raw text. + Read a template file as text. .DESCRIPTION - Loads a UTF-8 template file from disk and returns the complete content as a string. + Get-TemplateContent reads a UTF-8 template file and returns its full content as a string. #> [OutputType([string])] [CmdletBinding()] @@ -181,11 +180,12 @@ function Get-TemplateContent { function Get-PropertyValue { <# .SYNOPSIS - Gets the first non-empty property value from an object. + Get the first property value that is not empty. .DESCRIPTION - Evaluates the provided property names in order and returns the first property - value that exists and is not null/whitespace. Returns the default value otherwise. + Get-PropertyValue reads the named properties in order. + It returns the first value that is not null or whitespace. + If no value qualifies, it returns the default value. #> [OutputType([object])] [CmdletBinding()] @@ -221,12 +221,12 @@ function Get-PropertyValue { function Invoke-GitHubApi { <# .SYNOPSIS - Invokes a GitHub REST API GET request. + Send a GET request to the GitHub REST API. .DESCRIPTION - Calls the GitHub module API wrapper, ensures a default GitHub App context - for authenticated requests (unless -Anonymous is used), normalizes wrapped - responses, and treats HTTP 404 as missing data. + Invoke-GitHubApi calls the GitHub module API wrapper and unwraps its response. + HTTP 404 returns no data. + With -Anonymous, the request uses anonymous access. #> [OutputType([object])] [CmdletBinding()] @@ -308,11 +308,10 @@ function Invoke-GitHubApi { function Get-RepositoryReadmeContent { <# .SYNOPSIS - Gets a repository README as plain text. + Get a repository README as text. .DESCRIPTION - Downloads the repository README from GitHub and decodes the returned - Base64 content to UTF-8 text. + Get-RepositoryReadmeContent downloads the repository README from GitHub and decodes the Base64 content to UTF-8 text. #> [OutputType([string])] [CmdletBinding()] @@ -341,11 +340,10 @@ function Get-RepositoryReadmeContent { function Get-MarkdownSummary { <# .SYNOPSIS - Extracts a short summary from markdown content. + Get a short summary from Markdown content. .DESCRIPTION - Removes common markdown formatting and returns the first non-empty paragraph, - suitable for compact previews. + Get-MarkdownSummary removes common Markdown formatting and returns the first paragraph that is not empty. #> [OutputType([string])] [CmdletBinding()] @@ -380,11 +378,11 @@ function Get-MarkdownSummary { function ConvertTo-HtmlAttributeValue { <# .SYNOPSIS - Converts text to a safe HTML attribute preview value. + Convert text to an HTML attribute value. .DESCRIPTION - Normalizes whitespace, truncates to a max length, and escapes special HTML - characters for use in attributes such as title. + ConvertTo-HtmlAttributeValue normalizes whitespace and limits the text length. + It escapes special HTML characters for attributes such as title. #> [OutputType([string])] [CmdletBinding()] @@ -414,11 +412,11 @@ function ConvertTo-HtmlAttributeValue { function Get-OpenItemCount { <# .SYNOPSIS - Gets the open issue or pull request count for a repository. + Get the number of open issues or pull requests in a repository. .DESCRIPTION - Uses GitHub search API with a repository/type/state query and returns - the total count. + Get-OpenItemCount queries the GitHub search API by repository, type, and state. + It returns the total count. #> [OutputType([int])] [CmdletBinding()] @@ -445,11 +443,11 @@ function Get-OpenItemCount { function Get-RepositoryVersion { <# .SYNOPSIS - Gets a repository's latest version identifier. + Get a repository's latest version identifier. .DESCRIPTION - Returns the latest release tag/name when available, otherwise falls back - to the most recent tag, or N/A. + Get-RepositoryVersion returns the latest release tag or name. + If no release is available, it returns the first repository tag, or N/A if no tag exists. #> [OutputType([string])] [CmdletBinding()] @@ -481,11 +479,11 @@ function Get-RepositoryVersion { function Get-WorkflowReference { <# .SYNOPSIS - Gets the Process-PSModule workflow reference used by a repository. + Get a repository's Process-PSModule workflow reference. .DESCRIPTION - Scans common workflow entry files on the default branch and extracts the - `@ref` from `uses: PSModule/Process-PSModule/...@ref` if present. + Get-WorkflowReference reads workflow files on the default branch. + It extracts `@ref` from `uses: PSModule/Process-PSModule/...@ref` when present. #> [OutputType([string])] [CmdletBinding()] @@ -649,11 +647,10 @@ function Get-WorkflowReference { function Get-ProcessReferenceStatus { <# .SYNOPSIS - Computes status of a Process-PSModule workflow reference. + Determine the status of a Process-PSModule workflow reference. .DESCRIPTION - Classifies a workflow reference value relative to the latest available - Process-PSModule version. + Get-ProcessReferenceStatus compares the reference with the latest available Process-PSModule version. #> [OutputType([string])] [CmdletBinding()] @@ -699,11 +696,10 @@ function Get-ProcessReferenceStatus { function New-ModuleCatalogPage { <# .SYNOPSIS - Creates or updates a generated module catalog page. + Create or update a generated module catalog page. .DESCRIPTION - Builds markdown content from module metadata and writes it to the - target page path. + New-ModuleCatalogPage builds Markdown content from module metadata and writes it to the target page. #> [CmdletBinding(SupportsShouldProcess)] param( @@ -743,11 +739,11 @@ $($ModuleData.About) function Update-ActionList { <# .SYNOPSIS - Updates the GitHub Actions list section in the documentation. + Update the GitHub Actions list in the documentation. .DESCRIPTION - Generates an HTML table of all GitHub Actions repositories from the module's repo list - and updates the ACTION_LIST section in the GitHub Actions index markdown file. + Update-ActionList builds an HTML table from GitHub Actions repositories in the repository list. + It updates the ACTION_LIST section in the GitHub Actions index Markdown file. .EXAMPLE Update-ActionList @@ -802,11 +798,11 @@ $actionTableRows function Update-ModuleList { <# .SYNOPSIS - Updates the PowerShell modules list section in the documentation. + Update the PowerShell module catalog in the documentation. .DESCRIPTION - Generates an enriched HTML table for PSModule module repositories and writes - repository-specific catalog pages that summarize README and module metadata. + Update-ModuleList builds an HTML table for PSModule module repositories. + It writes a catalog page for each repository with a README summary and module metadata. #> [CmdletBinding(SupportsShouldProcess)] param( @@ -929,11 +925,11 @@ function Update-ModuleList { function Update-FunctionAppList { <# .SYNOPSIS - Updates the Azure Function Apps list section in the documentation. + Update the Azure Function Apps list in the documentation. .DESCRIPTION - Generates an HTML table of all Azure Function App repositories from the module's repo list - and updates the FUNCTIONAPP_LIST section in the PowerShell FunctionApps index markdown file. + Update-FunctionAppList builds an HTML table from Azure Function App repositories in the repository list. + It updates the FUNCTIONAPP_LIST section in the PowerShell FunctionApps index Markdown file. .EXAMPLE Update-FunctionAppList From d25f9eb105290fc4f80e8fc51d08158988d50c26 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:36:52 +0100 Subject: [PATCH 4/6] Clarify site and test-report help descriptions --- .github/actions/Build-ZensicalSite/action.yml | 2 +- .../actions/Build-ZensicalSite/src/main.ps1 | 6 +++--- .github/actions/Document-PSModule/action.yml | 4 ++-- .github/actions/Expose-TestData/action.yml | 6 +++--- .../actions/Get-PesterCodeCoverage/action.yml | 10 +++++----- .../src/Get-PesterCodeCoverage.Helpers.psm1 | 20 +++++++++---------- .../Get-PesterCodeCoverage/src/main.ps1 | 12 +++++------ .../actions/Get-PesterTestResults/action.yml | 12 +++++------ .../Get-PesterTestResults/src/main.ps1 | 6 +++--- .github/actions/Inject-SiteScripts/action.yml | 2 +- .../actions/Inject-SiteScripts/src/main.ps1 | 10 +++++----- .github/actions/Install-PSModule/action.yml | 2 +- .github/actions/Install-Zensical/action.yml | 2 +- .github/actions/Install-Zensical/src/main.ps1 | 4 ++-- .github/actions/Structure-Site/action.yml | 2 +- .github/actions/Structure-Site/src/main.ps1 | 6 +++--- 16 files changed, 53 insertions(+), 53 deletions(-) diff --git a/.github/actions/Build-ZensicalSite/action.yml b/.github/actions/Build-ZensicalSite/action.yml index 5031f0a9..80251ab5 100644 --- a/.github/actions/Build-ZensicalSite/action.yml +++ b/.github/actions/Build-ZensicalSite/action.yml @@ -1,5 +1,5 @@ name: Build-ZensicalSite -description: Build Zensical site output and normalize output folder. +description: Build a Zensical site in the framework artifact directory. inputs: WorkingDirectory: diff --git a/.github/actions/Build-ZensicalSite/src/main.ps1 b/.github/actions/Build-ZensicalSite/src/main.ps1 index 365482df..41ca09bf 100644 --- a/.github/actions/Build-ZensicalSite/src/main.ps1 +++ b/.github/actions/Build-ZensicalSite/src/main.ps1 @@ -2,11 +2,11 @@ <# .SYNOPSIS - Builds the Zensical site under the framework artifact directory. + Build the Zensical site in the framework artifact directory. .DESCRIPTION - Runs zensical build from .PSModule/site. The generated site remains at - /.PSModule/site/_site for downstream workflow steps. + The script runs zensical build from .PSModule/site. + The site remains at /.PSModule/site/_site for later workflow steps. .EXAMPLE ./main.ps1 -WorkingDirectory '.' diff --git a/.github/actions/Document-PSModule/action.yml b/.github/actions/Document-PSModule/action.yml index d82f83ab..1f185a25 100644 --- a/.github/actions/Document-PSModule/action.yml +++ b/.github/actions/Document-PSModule/action.yml @@ -7,11 +7,11 @@ inputs: description: Name of the module to process. required: false ShowSummaryOnSuccess: - description: Show GitHub Step Summary even when all commands succeed. + description: Show the GitHub step summary even when all commands succeed. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' diff --git a/.github/actions/Expose-TestData/action.yml b/.github/actions/Expose-TestData/action.yml index 38acc14d..81bd4c62 100644 --- a/.github/actions/Expose-TestData/action.yml +++ b/.github/actions/Expose-TestData/action.yml @@ -1,5 +1,5 @@ name: Expose-TestData -description: Exposes caller-provided Process-PSModule TestData as environment variables. +description: Expose caller-provided Process-PSModule TestData as environment variables. author: PSModule branding: icon: unlock @@ -8,8 +8,8 @@ branding: inputs: TestData: description: | - Optional single-line JSON object with 'secrets' and 'variables' maps. Entries are validated by - Import-TestData and exported to GITHUB_ENV for later steps in the same job. + Optional single-line JSON object with 'secrets' and 'variables' maps. + Import-TestData validates the entries and writes them to GITHUB_ENV for later steps in the same job. required: false default: '' diff --git a/.github/actions/Get-PesterCodeCoverage/action.yml b/.github/actions/Get-PesterCodeCoverage/action.yml index 29bc7496..75668c51 100644 --- a/.github/actions/Get-PesterCodeCoverage/action.yml +++ b/.github/actions/Get-PesterCodeCoverage/action.yml @@ -1,5 +1,5 @@ name: Get-PesterCodeCoverage -description: A GitHub Action that is used to gather Code Coverage for the PSModule process. +description: Collect code coverage results for the PSModule process. author: PSModule branding: icon: upload-cloud @@ -15,24 +15,24 @@ inputs: required: false default: 'false' Version: - description: Specifies the version of the GitHub module to be installed. Accepts an exact version or a NuGet version range (for example '[1.2.0, 2.0.0)'). + description: GitHub module version to install. Use an exact version or a NuGet version range (for example '[1.2.0, 2.0.0)'). required: false Prerelease: description: Allow prerelease versions if available. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' StepSummary_Mode: description: | - Controls which sections to show in the GitHub step summary. + Select the sections to show in the GitHub step summary. Use 'Full' for all sections, 'None' to disable, or a comma-separated list of 'Missed, Executed, Files'. required: false default: Missed, Files CodeCoveragePercentTarget: - description: The target for code coverage. + description: Target code coverage percentage. required: false outputs: diff --git a/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 b/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 index 045f4b2c..32eef129 100644 --- a/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 +++ b/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 @@ -1,18 +1,18 @@ function Normalize-IndentationExceptFirst { <# .SYNOPSIS - Normalizes the indentation of a multi-line string, except for the first line. + Normalize multiline string indentation except on the first line. .DESCRIPTION - This function takes a multi-line string and normalizes the indentation of all lines except the first one. - It removes the minimum leading whitespace from all subsequent lines. + Normalize-IndentationExceptFirst leaves the first line unchanged. + It removes the minimum leading whitespace from each remaining line. .PARAMETER Code - The multi-line string to normalize. + The multiline string to normalize. .OUTPUTS - Returns the normalized multi-line string. - s#> + The multiline string with adjusted indentation. + #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseApprovedVerbs', '', Scope = 'Function', Justification = 'Function isn''t exported.')] [OutputType([string])] [CmdletBinding()] @@ -24,12 +24,12 @@ # Split the code into lines $lines = $Code -split "`r?`n" - # If there's 0 or 1 line, there's nothing special to do + # A single-line string needs no indentation adjustment. if ($lines.Count -le 1) { return $Code } - # The first line stays as-is; we skip it for indentation measurement + # Exclude the first line from the indentation measurement. $firstLine = $lines[0] $subsequentLines = $lines[1..($lines.Count - 1)] @@ -47,13 +47,13 @@ for ($i = 0; $i -lt $subsequentLines.Count; $i++) { $line = $subsequentLines[$i] - # Only attempt to remove indentation if we actually have some whitespace + # Remove indentation only when the line starts with whitespace. if ($line -match '^(\s+)(.*)$') { # $matches[1] = leading whitespace; $matches[2] = the rest $leading = $matches[1] $rest = $matches[2] - # If we have enough whitespace to remove $minIndent worth, do it + # Remove the minimum indentation when the prefix is long enough. if ($leading.Length -ge $minIndent) { $leading = $leading.Substring($minIndent) } diff --git a/.github/actions/Get-PesterCodeCoverage/src/main.ps1 b/.github/actions/Get-PesterCodeCoverage/src/main.ps1 index 995a5825..233096bf 100644 --- a/.github/actions/Get-PesterCodeCoverage/src/main.ps1 +++ b/.github/actions/Get-PesterCodeCoverage/src/main.ps1 @@ -38,7 +38,7 @@ LogGroup 'List files' { $files.Name | Out-String } -# Accumulators for coverage items across all files +# Coverage items from all report files. $allMissed = @() $allExecuted = @() $allFiles = @() @@ -84,7 +84,7 @@ foreach ($file in $files) { } $jsonContent.FilesAnalyzed = $normalizedFiles - # Now accumulate coverage items + # Collect coverage items from this report. $allMissed += $jsonContent.CommandsMissed $allExecuted += $jsonContent.CommandsExecuted $allFiles += $jsonContent.FilesAnalyzed @@ -98,7 +98,7 @@ $finalExecuted = $allExecuted | $finalFiles = $allFiles | Sort-Object -Unique -# -- Remove from missed any command that shows up in executed -- +# Exclude missed commands that an execution report includes. $executedKeys = $finalExecuted | ForEach-Object { '{0}|{1}|{2}|{3}|{4}|{5}|{6}' -f $_.File, $_.Line, $_.Command, $_.StartColumn, $_.EndColumn, $_.Class, $_.Function } @@ -109,7 +109,7 @@ $finalMissed = $allMissed | $executedKeys -notcontains $key } -# -- Compute the new coverage percentages -- +# Calculate combined code coverage. $missedCount = $finalMissed.Count $executedCount = $finalExecuted.Count $totalAnalyzed = $missedCount + $executedCount @@ -313,7 +313,7 @@ LogGroup 'Step Summary - Set step summary' { Write-Verbose "Step Summary Mode: $stepSummaryMode" - # If mode is 'None', skip step summary generation completely + # If the mode is 'None', omit the step summary. if ($stepSummaryMode -eq 'None') { Write-Verbose 'Step summary is disabled' return @@ -386,7 +386,7 @@ LogGroup 'Step Summary - Set step summary' { } -# Throw an error if coverage is below target +# Fail the action if coverage is below the target. if ($coveragePercent -lt $coveragePercentTarget) { Write-GitHubError "Coverage is below target! Found $coveragePercent%, target is $coveragePercentTarget%." exit 1 diff --git a/.github/actions/Get-PesterTestResults/action.yml b/.github/actions/Get-PesterTestResults/action.yml index b9d9b706..7f7b41ef 100644 --- a/.github/actions/Get-PesterTestResults/action.yml +++ b/.github/actions/Get-PesterTestResults/action.yml @@ -1,5 +1,5 @@ name: Get-PesterTestResults -description: A GitHub Action that is used to gather test results for the PSModule process. +description: Collect test results for the PSModule process. author: PSModule branding: icon: upload-cloud @@ -7,13 +7,13 @@ branding: inputs: SourceCodeTestSuites: - description: The test suites to run for the source code. + description: Source code test suites whose results the action expects. required: true PSModuleTestSuites: - description: The test suites to run for the PSModule. + description: PSModule framework test suites whose results the action expects. required: true ModuleTestSuites: - description: The test suites to run for the module. + description: Module-local test suites whose results the action expects. required: true BeforeAllModuleLocalResult: description: The workflow result for the BeforeAll-ModuleLocal job. @@ -28,14 +28,14 @@ inputs: required: false default: 'false' Version: - description: Specifies the version of the GitHub module to be installed. The value must be an exact version. + description: GitHub module version to install. The value must be an exact version. required: false Prerelease: description: Allow prerelease versions if available. required: false default: 'false' WorkingDirectory: - description: The working directory where the script will run from. + description: Working directory for the script. required: false default: '.' diff --git a/.github/actions/Get-PesterTestResults/src/main.ps1 b/.github/actions/Get-PesterTestResults/src/main.ps1 index 8fad1a96..6c8478b8 100644 --- a/.github/actions/Get-PesterTestResults/src/main.ps1 +++ b/.github/actions/Get-PesterTestResults/src/main.ps1 @@ -37,7 +37,7 @@ LogGroup 'Expected test suites' { # Build an array of expected test suite objects $expectedTestSuites = @() - # SourceCodeTestSuites: expected file names start with "SourceCode-" + # SourceCodeTestSuites: expect PSModuleTest-SourceCode and PSModuleLint-SourceCode reports. foreach ($suite in $sourceCodeTestSuites) { $expectedTestSuites += [pscustomobject]@{ Name = "PSModuleTest-SourceCode-$($suite.OSName)-TestResult-Report" @@ -53,7 +53,7 @@ LogGroup 'Expected test suites' { } } - # PSModuleTestSuites: expected file names start with "Module-" + # PSModuleTestSuites: expect PSModuleTest-Module and PSModuleLint-Module reports. foreach ($suite in $psModuleTestSuites) { $expectedTestSuites += [pscustomobject]@{ Name = "PSModuleTest-Module-$($suite.OSName)-TestResult-Report" @@ -119,7 +119,7 @@ foreach ($expected in $expectedTestSuites) { } } - # Determine if there’s any failure for this single test file + # Detect a failure in this test result file. $hasTestsValue = $null -ne $result.Tests $hasPassedValue = $null -ne $result.Passed $hasFailedValue = $null -ne $result.Failed diff --git a/.github/actions/Inject-SiteScripts/action.yml b/.github/actions/Inject-SiteScripts/action.yml index 0a280e76..253298aa 100644 --- a/.github/actions/Inject-SiteScripts/action.yml +++ b/.github/actions/Inject-SiteScripts/action.yml @@ -6,7 +6,7 @@ inputs: description: Path to the generated site output directory. required: true WorkflowPath: - description: Path to the checked out workflow repository root. + description: Path to the checked-out workflow repository root. required: false default: _wf diff --git a/.github/actions/Inject-SiteScripts/src/main.ps1 b/.github/actions/Inject-SiteScripts/src/main.ps1 index 8bc4fbe8..92655b80 100644 --- a/.github/actions/Inject-SiteScripts/src/main.ps1 +++ b/.github/actions/Inject-SiteScripts/src/main.ps1 @@ -2,11 +2,11 @@ <# .SYNOPSIS - Injects shared JavaScript snippets into generated site HTML files. + Inject shared JavaScript snippets into generated site HTML files. .DESCRIPTION - Reads scripts from .github/scripts/site-injectors in the checked out workflow - repository and injects each script into every HTML file under SitePath, once per file. + The script reads .github/scripts/site-injectors in the checked-out workflow repository. + It injects each script into every HTML file under SitePath, once per file. .EXAMPLE ./main.ps1 -SitePath './.PSModule/site/_site' -WorkflowPath '_wf' @@ -19,11 +19,11 @@ #> [CmdletBinding()] param( - # Path to generated site output directory containing HTML files. + # Path to the generated site output directory with HTML files. [Parameter(Mandatory)] [string]$SitePath, - # Relative path to the checked out workflow repository root. + # Relative path to the checked-out workflow repository root. [Parameter(Mandatory)] [string]$WorkflowPath ) diff --git a/.github/actions/Install-PSModule/action.yml b/.github/actions/Install-PSModule/action.yml index 0b3f3440..1a881e8f 100644 --- a/.github/actions/Install-PSModule/action.yml +++ b/.github/actions/Install-PSModule/action.yml @@ -1,5 +1,5 @@ name: Install-PSModule -description: Installs PSModule. +description: Install the framework's bundled PSModule helper module. runs: using: composite diff --git a/.github/actions/Install-Zensical/action.yml b/.github/actions/Install-Zensical/action.yml index 18a16b4b..7b7df155 100644 --- a/.github/actions/Install-Zensical/action.yml +++ b/.github/actions/Install-Zensical/action.yml @@ -1,5 +1,5 @@ name: Install-Zensical -description: Install Zensical CLI used for documentation site generation. +description: Install the Zensical CLI for documentation site builds. runs: using: composite diff --git a/.github/actions/Install-Zensical/src/main.ps1 b/.github/actions/Install-Zensical/src/main.ps1 index 936e4886..4a01b601 100644 --- a/.github/actions/Install-Zensical/src/main.ps1 +++ b/.github/actions/Install-Zensical/src/main.ps1 @@ -2,10 +2,10 @@ <# .SYNOPSIS - Installs the Zensical CLI used by site build workflows. + Install the Zensical CLI for site build workflows. .DESCRIPTION - Installs the zensical Python package in the current runner environment. + The script installs the zensical Python package in the runner environment. .EXAMPLE ./main.ps1 diff --git a/.github/actions/Structure-Site/action.yml b/.github/actions/Structure-Site/action.yml index cb6d5cd2..7cf80e8a 100644 --- a/.github/actions/Structure-Site/action.yml +++ b/.github/actions/Structure-Site/action.yml @@ -1,5 +1,5 @@ name: Structure-Site -description: Structure generated docs and create site config for Zensical. +description: Structure generated documentation and create the Zensical site configuration. inputs: WorkingDirectory: diff --git a/.github/actions/Structure-Site/src/main.ps1 b/.github/actions/Structure-Site/src/main.ps1 index 1a227da8..998b9c21 100644 --- a/.github/actions/Structure-Site/src/main.ps1 +++ b/.github/actions/Structure-Site/src/main.ps1 @@ -2,11 +2,11 @@ <# .SYNOPSIS - Structures generated documentation content and writes a resolved site config. + Structure the generated documentation and write the resolved site configuration. .DESCRIPTION - Copies generated docs, README, and assets into .PSModule/site and resolves zensical.toml - placeholders and site_dir for build execution. + The script copies generated documentation, README, and assets into .PSModule/site. + It resolves zensical.toml placeholders and sets site_dir for the build. .EXAMPLE ./main.ps1 -WorkingDirectory '.' -Name 'MyModule' From a2bde6694cf238a77e21b3441066a61813a10567 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:43:18 +0100 Subject: [PATCH 5/6] State test action options in direct prose --- .github/actions/Build-PSModule/action.yml | 2 +- .../actions/Get-PesterTestResults/action.yml | 2 +- .github/actions/Structure-Site/action.yml | 2 +- .github/actions/Test-PSModule/action.yml | 119 ++++++++++-------- 4 files changed, 71 insertions(+), 54 deletions(-) diff --git a/.github/actions/Build-PSModule/action.yml b/.github/actions/Build-PSModule/action.yml index 7e5bb5df..c7ac417d 100644 --- a/.github/actions/Build-PSModule/action.yml +++ b/.github/actions/Build-PSModule/action.yml @@ -1,5 +1,5 @@ name: Build-PSModule -description: Build a PowerShell module for publication to the PowerShell Gallery. +description: Build a PowerShell module for the PowerShell Gallery. author: PSModule inputs: diff --git a/.github/actions/Get-PesterTestResults/action.yml b/.github/actions/Get-PesterTestResults/action.yml index 7f7b41ef..e8345be3 100644 --- a/.github/actions/Get-PesterTestResults/action.yml +++ b/.github/actions/Get-PesterTestResults/action.yml @@ -10,7 +10,7 @@ inputs: description: Source code test suites whose results the action expects. required: true PSModuleTestSuites: - description: PSModule framework test suites whose results the action expects. + description: PSModule test suites whose results the action expects. required: true ModuleTestSuites: description: Module-local test suites whose results the action expects. diff --git a/.github/actions/Structure-Site/action.yml b/.github/actions/Structure-Site/action.yml index 7cf80e8a..14d8f06c 100644 --- a/.github/actions/Structure-Site/action.yml +++ b/.github/actions/Structure-Site/action.yml @@ -1,5 +1,5 @@ name: Structure-Site -description: Structure generated documentation and create the Zensical site configuration. +description: Prepare documentation and site configuration for Zensical. inputs: WorkingDirectory: diff --git a/.github/actions/Test-PSModule/action.yml b/.github/actions/Test-PSModule/action.yml index aa7d51c4..ef4fdd58 100644 --- a/.github/actions/Test-PSModule/action.yml +++ b/.github/actions/Test-PSModule/action.yml @@ -1,95 +1,104 @@ name: Test-PSModule -description: Test a PowerShell module before publishing the module to the PowerShell Gallery. +description: Test a PowerShell module before PowerShell Gallery publication. author: PSModule inputs: Name: - description: The name of the module to test. The name of the repository is used if not specified. + description: Module name. If omitted, the action uses the repository name. required: false Settings: - description: The type of tests to run. Can be either 'Module' or 'SourceCode'. + description: Test type. Use 'Module' or 'SourceCode'. required: true StepSummary_Mode: description: | - Controls which tests to show in the GitHub step summary. Allows "Full" (show all tests), "Failed" (only failed tests), or "None" (disable step summary). + Select the tests to show in the GitHub step summary. + Use "Full" for all tests, "Failed" for failed tests, + or "None" to omit the summary. required: false StepSummary_ShowTestOverview: description: | - Controls whether to show the test overview table in the GitHub step summary. + Show the test overview table in the GitHub step summary. required: false StepSummary_ShowConfiguration: description: | - Controls whether to show the configuration details in the GitHub step summary. + Show configuration details in the GitHub step summary. required: false Run_Path: description: | - Directories to be searched for tests, paths directly to test files, or combination of both. + Directories to search for tests, paths to test files, or both. required: false Run_ExcludePath: description: | - Directories or files to be excluded from the run. + Directories or files to exclude from the run. required: false Run_ScriptBlock: description: | - ScriptBlocks containing tests to be executed. + ScriptBlocks with tests to run. required: false Run_Container: description: | - ContainerInfo objects containing tests to be executed. + ContainerInfo objects with tests to run. required: false Run_TestExtension: description: | - Filter used to identify test files. + Filter that identifies test files. required: false Run_Exit: description: | - Exit with non-zero exit code when the test run fails. Exit code is always set to `$LASTEXITCODE` even when this option is `$false`. - When used together with Throw, throwing an exception is preferred. + If the test run fails, exit with a nonzero code. + The run sets `$LASTEXITCODE` even when this option is `$false`. + If Throw is also enabled, prefer an exception. required: false Run_Throw: description: | - Throw an exception when test run fails. When used together with Exit, throwing an exception is preferred. + If the test run fails, throw an exception. + If Exit is also enabled, prefer an exception. required: false Run_SkipRun: description: | - Runs the discovery phase but skips run. Use it with PassThru to get object populated with all tests. + Run test discovery without test execution. + Use PassThru to return an object with all tests. required: false Run_SkipRemainingOnFailure: description: | - Skips remaining tests after failure for selected scope, options are None, Run, Container and Block. + Skip the remaining tests after a failure in the selected scope. + Options: None, Run, Container, and Block. required: false Filter_Tag: description: | - Tags of Describe, Context or It to be run. + Tags on Describe, Context, or It blocks to run. required: false Filter_ExcludeTag: description: | - Tags of Describe, Context or It to be excluded from the run. + Tags on Describe, Context, or It blocks to exclude from the run. required: false Filter_Line: description: | - Filter by file and scriptblock start line, useful to run parsed tests programmatically to avoid problems with expanded names. + Filter parsed tests by file and scriptblock start line + to avoid errors from expanded names. Example: 'C:\tests\file1.Tests.ps1:37' required: false Filter_ExcludeLine: description: | - Exclude by file and scriptblock start line, takes precedence over Line. + Exclude tests by file and scriptblock start line. + This filter takes precedence over Line. required: false Filter_FullName: description: | - Full name of test with -like wildcards, joined by dot. Example: '*.describe Get-Item.test1' + Full test name with -like wildcards and dot-separated parts. + Example: '*.describe Get-Item.test1' required: false CodeCoverage_Enabled: description: | - Enable CodeCoverage. + Enable code coverage. required: false CodeCoverage_OutputFormat: description: | - Format to use for code coverage report. Possible values in Pester 6.1: JaCoCo or Cobertura. + Code coverage report format. Pester 6.1 supports JaCoCo or Cobertura. required: false CodeCoverage_OutputPath: description: | - Path relative to the current directory where code coverage report is saved. + Code coverage report path, relative to the current directory. required: false CodeCoverage_OutputEncoding: description: | @@ -97,19 +106,21 @@ inputs: required: false CodeCoverage_Path: description: | - Directories or files to be used for code coverage, by default the Path(s) from general settings are used, unless overridden here. + Directories or files for code coverage. + Without an override, the action uses Path(s) from the general settings. required: false CodeCoverage_ExcludeTests: description: | - Exclude tests from code coverage. This uses the TestFilter from general configuration. + Exclude tests from code coverage. + This option uses TestFilter from the general configuration. required: false CodeCoverage_RecursePaths: description: | - Will recurse through directories in the Path option. + Search subdirectories of the directories in the Path option. required: false CodeCoverage_CoveragePercentTarget: description: | - Target percent of code coverage that you want to achieve. + Target percentage for code coverage. required: false CodeCoverage_UseBreakpoints: description: | @@ -117,19 +128,19 @@ inputs: required: false CodeCoverage_SingleHitBreakpoints: description: | - Remove breakpoint when it is hit. + Remove each breakpoint after its first hit. required: false TestResult_Enabled: description: | - Enable TestResult. + Enable test result reports. required: false TestResult_OutputFormat: description: | - Format to use for test result report. Possible values: NUnitXml, NUnit2.5, NUnit3 or JUnitXml + Test result report format: NUnitXml, NUnit2.5, NUnit3, or JUnitXml. required: false TestResult_OutputPath: description: | - Path relative to the current directory where test result report is saved. + Test result report path, relative to the current directory. required: false TestResult_OutputEncoding: description: | @@ -137,53 +148,59 @@ inputs: required: false TestResult_TestSuiteName: description: | - Set the name assigned to the root 'test-suite' element. + Set the name of the root 'test-suite' element. required: false Should_ErrorAction: description: | - Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test. + Select the error behavior for Should. + Use 'Stop' to throw on error, + or 'Continue' to fail at the end of the test. required: false Debug_ShowFullErrors: description: | - Show full errors including Pester internal stack. This property is deprecated, and if set to true it will override Output.StackTraceVerbosity to 'Full'. + Show full errors with the internal Pester stack. + When true, this deprecated property overrides + Output.StackTraceVerbosity with 'Full'. required: false Debug_WriteDebugMessages: description: | - Write Debug messages to screen. + Write debug messages to the screen. required: false Debug_WriteDebugMessagesFrom: description: | - Write Debug messages from a given source, WriteDebugMessages must be set to true for this to work. - You can use like wildcards to get messages from multiple sources, as well as * to get everything. + Write debug messages from the selected source. + Set WriteDebugMessages to true to enable these messages. + Use like wildcards for multiple sources, or * for all sources. required: false Debug_ShowNavigationMarkers: description: | - Write paths after every block and test, for easy navigation in VSCode. + Write paths after each block and test for navigation in VSCode. required: false Debug_ReturnRawResultObject: description: | - Returns unfiltered result object, this is for development only. Do not rely on this object for additional properties, - non-public properties will be renamed without previous notice. + Return the unfiltered result object for development only. + Do not depend on additional properties. + Non-public property names change without prior notice. required: false Output_Verbosity: description: | - The verbosity of output, options are None, Normal, Detailed and Diagnostic. + Output verbosity: None, Normal, Detailed, or Diagnostic. required: false Output_StackTraceVerbosity: description: | - The verbosity of stacktrace output, options are None, FirstLine, Filtered and Full. + Stack trace verbosity: None, FirstLine, Filtered, or Full. required: false Output_CIFormat: description: | - The CI format of error output in build logs, options are None, Auto, AzureDevops and GithubActions. + CI error format in build logs: None, Auto, AzureDevops, or GithubActions. required: false Output_CILogLevel: description: | - The CI log level in build logs, options are Error and Warning. + CI log level in build logs: Error or Warning. required: false Output_RenderMode: description: | - The mode used to render console output, options are Auto, Ansi, ConsoleColor and Plaintext. + Console output mode: Auto, Ansi, ConsoleColor, or Plaintext. required: false TestDrive_Enabled: description: | @@ -202,14 +219,14 @@ inputs: required: false default: 'false' Version: - description: Specifies the version of the GitHub module to be installed. The value must be an exact version. + description: GitHub module version to install. The value must be an exact version. required: false Prerelease: description: Allow prerelease versions if available. required: false default: 'false' WorkingDirectory: - description: The working directory to use for the action. This is the root folder where tests and outputs are expected. + description: Working directory for the action. Tests and outputs use this root folder. required: false default: '.' @@ -224,11 +241,11 @@ outputs: value: ${{ steps.test.conclusion }} Executed: description: | - Whether tests were executed. + Whether the run executed tests. value: ${{ steps.test.outputs.Executed }} Result: description: | - Overall result of the Pester test run (e.g., Passed, Failed). + Overall Pester result (for example, Passed, Failed). value: ${{ steps.test.outputs.Result }} FailedCount: description: | @@ -256,7 +273,7 @@ outputs: value: ${{ steps.test.outputs.InconclusiveCount }} NotRunCount: description: | - Number of tests not run. + Number of tests that did not run. value: ${{ steps.test.outputs.NotRunCount }} TotalCount: description: | From aa992660e3eefe8d9a3881d95fe32bab491d9f52 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 14:00:29 +0100 Subject: [PATCH 6/6] State exception precedence and native output type --- .../src/Get-PesterCodeCoverage.Helpers.psm1 | 2 ++ .github/actions/Test-PSModule/action.yml | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 b/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 index 32eef129..a0b0c498 100644 --- a/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 +++ b/.github/actions/Get-PesterCodeCoverage/src/Get-PesterCodeCoverage.Helpers.psm1 @@ -11,6 +11,8 @@ The multiline string to normalize. .OUTPUTS + System.String + The multiline string with adjusted indentation. #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseApprovedVerbs', '', Scope = 'Function', Justification = 'Function isn''t exported.')] diff --git a/.github/actions/Test-PSModule/action.yml b/.github/actions/Test-PSModule/action.yml index ef4fdd58..753fe7b5 100644 --- a/.github/actions/Test-PSModule/action.yml +++ b/.github/actions/Test-PSModule/action.yml @@ -47,12 +47,12 @@ inputs: description: | If the test run fails, exit with a nonzero code. The run sets `$LASTEXITCODE` even when this option is `$false`. - If Throw is also enabled, prefer an exception. + Run_Throw takes precedence over Run_Exit when both are enabled. required: false Run_Throw: description: | If the test run fails, throw an exception. - If Exit is also enabled, prefer an exception. + Run_Throw takes precedence over Run_Exit when both are enabled. required: false Run_SkipRun: description: |