👷‍♂️ Improves Usage Ergonomics

.github/workflows/release.yml

@@ -15,15 +15,15 @@ jobs:
     steps:
       - run: echo "Beginning release."
       - name: "Transfer 'version-json' artifact from triggering workflow"
-        uses: pwshrc/actions-transfer-artifact@v0.3.7
+        uses: pwshrc/actions-transfer-artifact@v0.3.9
         with:
           name: 'version-json'
       - name: "Transfer 'PSGallery-package' artifact from triggering workflow"
-        uses: pwshrc/actions-transfer-artifact@v0.3.7
+        uses: pwshrc/actions-transfer-artifact@v0.3.9
         with:
           name: 'PSGallery-package'
       - name: "Transfer 'release-notes' artifact from triggering workflow"
-        uses: pwshrc/actions-transfer-artifact@v0.3.7
+        uses: pwshrc/actions-transfer-artifact@v0.3.9
         with:
           name: 'release-notes'
 
@@ -33,10 +33,10 @@ jobs:
     needs: [begin-release]
     steps:
     - name: Check out repository code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Populate GitVersion variables
       id: gitversion_vars
-      uses: pwshrc/actions-determine-version@v0.8.5
+      uses: pwshrc/actions-determine-version@v0.8.6
       with:
         mode: 'download'
     - name: "Get artifact: PSGallery-package"
@@ -46,12 +46,12 @@ jobs:
         path: ./out/
     - name: Publish Prerelease to PSGallery (WhatIf)
       if: steps.gitversion_vars.outputs.PreReleaseTag != ''
-      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
       with:
         run: ./build/publish.ps1 -NUGET_KEY "abc" -Prerelease -WhatIf
     - name: Publish Release to PSGallery (WhatIf)
       if: steps.gitversion_vars.outputs.PreReleaseTag == ''
-      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
       with:
         run: ./build/publish.ps1 -NUGET_KEY "abc" -WhatIf
 
@@ -61,10 +61,10 @@ jobs:
     needs: [test-publish-psgallery-package]
     steps:
     - name: Check out repository code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Populate GitVersion variables
       id: gitversion_vars
-      uses: pwshrc/actions-determine-version@v0.8.5
+      uses: pwshrc/actions-determine-version@v0.8.6
       with:
         mode: 'download'
     - name: "Get artifact: PSGallery-package"
@@ -74,14 +74,14 @@ jobs:
         path: ./out/
     - name: Publish Prerelease to PSGallery
       if: steps.gitversion_vars.outputs.PreReleaseTag != ''
-      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
       env:
         NUGET_KEY: ${{ secrets.NUGET_KEY }}
       with:
         run: ./build/publish.ps1 -NUGET_KEY "$env:NUGET_KEY" -Prerelease
     - name: Publish Release to PSGallery
       if: steps.gitversion_vars.outputs.PreReleaseTag == ''
-      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
       env:
         NUGET_KEY: ${{ secrets.NUGET_KEY }}
       with:
@@ -93,15 +93,15 @@ jobs:
     needs: [publish-psgallery-package]
     steps:
     - name: Check out repository code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Get GitVersion
       id: gitversion_vars
-      uses: pwshrc/actions-determine-version@v0.8.5
+      uses: pwshrc/actions-determine-version@v0.8.6
       with:
         mode: 'download'
     - name: Get release notes
       id: get-releasenotes
-      uses: pwshrc/actions-create-release-notes@v0.8.6
+      uses: pwshrc/actions-create-release-notes@v0.8.8
       with:
         mode: 'download'
         github_token: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/review-dependabot.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Review Dependabot PR
-        uses: pwshrc/actions-review-dependabot@v0.6.0
+        uses: pwshrc/actions-review-dependabot@v0.6.2
         with:
           github_token: "${{ secrets.GITHUB_TOKEN }}"
           required-pr-user-login: 'dependabot[bot]'

.github/workflows/validate.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Lint with PSScriptAnalyzer
-        uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+        uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
         with:
           run: ./build/lint.ps1 -CI -NoFail:([bool]"${{ secrets.MANDATE_LINT_SUCCESS != 'true' }}")
 
@@ -24,7 +24,7 @@ jobs:
     steps:
     - name: Populate GitVersion variables
       id: gitversion_vars
-      uses: pwshrc/actions-determine-version@v0.8.5
+      uses: pwshrc/actions-determine-version@v0.8.6
       with:
         mode: 'upload'
 
@@ -34,7 +34,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Create release notes
-      uses: pwshrc/actions-create-release-notes@v0.8.6
+      uses: pwshrc/actions-create-release-notes@v0.8.8
       with:
         mode: 'upload'
         github_token: "${{ secrets.GITHUB_TOKEN }}"
@@ -45,30 +45,33 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Check out repository code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: Populate GitVersion
       id: gitversion_vars
-      uses: pwshrc/actions-determine-version@v0.8.5
+      uses: pwshrc/actions-determine-version@v0.8.6
       with:
         mode: 'download'
     - name: Populate release notes
       id: get-releasenotes
-      uses: pwshrc/actions-create-release-notes@v0.8.6
+      uses: pwshrc/actions-create-release-notes@v0.8.8
       with:
         mode: 'download'
         github_token: "${{ secrets.GITHUB_TOKEN }}"
     - name: Build PSGallery package
-      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
       env:
-        PackageVersionNuGet: ${{ steps.gitversion_vars.outputs.NuGetVersionV2 }}
-        PackageVersionMajorMinorPatchBuild: ${{ steps.gitversion_vars.outputs.AssemblySemVer }}
+        PackageVersion: ${{ steps.gitversion_vars.outputs.NuGetVersionV2 }}
+        ModuleVersionMajor: ${{ steps.gitversion_vars.outputs.Major }}
+        ModuleVersionMinor: ${{ steps.gitversion_vars.outputs.Minor }}
+        ModuleVersionPatch: ${{ steps.gitversion_vars.outputs.Patch }}
         PackageVersionPrereleaseTag: ${{ steps.gitversion_vars.outputs.PreReleaseTag }}
         CommitSha: ${{ steps.gitversion_vars.outputs.Sha }}
         ReleaseNotesFilepath: ${{ steps.get-releasenotes.outputs.filepath }}
       with:
         run: |
           [string] $releaseNotes = (Get-Content -Raw -Path ./out/release-notes.md -Encoding UTF8).Trim()
-          ./build/package.ps1 -PackageVersionNuGet $Env:PackageVersionNuGet -PackageVersionMajorMinorPatchBuild $Env:PackageVersionMajorMinorPatchBuild -PackageVersionPrereleaseTag $Env:PackageVersionPrereleaseTag -ReleaseNotes $releaseNotes -CommitSha $Env:CommitSha
+          [Version] $moduleVersion = [Version]::new($Env:ModuleVersionMajor, $Env:ModuleVersionMinor, $Env:ModuleVersionPatch)
+          ./build/package.ps1 -PackageVersion $Env:PackageVersion -ModuleVersion $moduleVersion -PackageVersionPrereleaseTag $Env:PackageVersionPrereleaseTag -ReleaseNotes $releaseNotes -CommitSha $Env:CommitSha
     - name: "Create artifact: PSGallery-package"
       uses: actions/upload-artifact@v3
       with:
@@ -102,14 +105,14 @@ jobs:
     needs: build-release-package
     steps:
     - name: Check out repository code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
     - name: "Get artifact: PSGallery-package"
       uses: actions/download-artifact@v3
       with:
         name: PSGallery-package
         path: ./out/
     - name: Test with Pester
-      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.7
+      uses: pwshrc/actions-invoke-lib-dependent-pwsh@v0.2.9
       with:
         run: ./build/test.ps1 -UsePackageExport -CI -OutputFilesPrefix "${{ matrix.os }}-" -NoFail:([bool]"${{ matrix.experimental }}")
     - name: "Create artifact: tests-${{ matrix.os }}"

build/funcs/New-ModuleManifestCustomized.ps1

@@ -62,8 +62,8 @@ function New-ModuleManifestCustomized {
         [string] $PackageVersion,
 
         [Parameter(Mandatory = $true)]
-        [ValidateNotNullOrEmpty()]
-        [string] $PackageVersionMajorMinorPatchBuild,
+        [ValidateNotNull()]
+        [Version] $ModuleVersion,
 
         [Parameter(Mandatory = $false)]
         [string] $PackageVersionPrereleaseTag,
@@ -159,7 +159,7 @@ function New-ModuleManifestCustomized {
         -CompanyName $CompanyName `
         -Description $packageSynopsis `
         -Copyright $PackageCopyright `
-        -ModuleVersion $PackageVersion `
+        -ModuleVersion $ModuleVersion `
         -Guid $PackageGuid `
         -Tags $PackageTags `
         -LicenseUri "${ProjectUrlAtVersion}/${LicenseFileName}" `

build/package-dev.ps1

@@ -20,30 +20,36 @@ elseif (Get-Command gitversion -ErrorAction SilentlyContinue) {
 if ($gitversion_bin) {
     [PSObject] $versionInfo = & $gitversion_bin | ConvertFrom-Json
 
-    [string] $PackageVersionNuGet = $versionInfo | Select-Object -ExpandProperty NuGetVersionV2
+    [string] $PackageVersion = $versionInfo | Select-Object -ExpandProperty NuGetVersionV2
     [string] $PackageVersionPrereleaseTag = $versionInfo | Select-Object -ExpandProperty PreReleaseTag
-    [string] $PackageVersionMajorMinorPatchBuild = $versionInfo | Select-Object -ExpandProperty AssemblySemVer
+    [string] $assemblySemVer = $versionInfo | Select-Object -ExpandProperty AssemblySemVer
     [string] $CommitSha = $versionInfo | Select-Object -ExpandProperty Sha
 } else {
-    [string] $PackageVersionNuGet = "0.0.1"
+    [string] $PackageVersion = "0.0.1"
     [string] $PackageVersionPrereleaseTag = $null
-    [string] $PackageVersionMajorMinorPatchBuild = "0.0.1.0"
+    [string] $assemblySemVer = "0.0.1"
     [string] $CommitSha = (git rev-parse HEAD)
 }
 [string] $ReleaseNotes = "Fake Release Notes"
 
 if (-not $PackageVersionPrereleaseTag) {
-    $PackageVersionNuGet += "-dev"
+    $PackageVersion += "-dev"
     $PackageVersionPrereleaseTag = "dev"
 } else {
-    $PackageVersionNuGet = $PackageVersionNuGet.Replace("-" + $PackageVersionPrereleaseTag, "-dev-" + $PackageVersionPrereleaseTag)
+    $PackageVersion = $PackageVersion.Replace("-" + $PackageVersionPrereleaseTag, "-dev-" + $PackageVersionPrereleaseTag)
     $PackageVersionPrereleaseTag = "dev-" + $PackageVersionPrereleaseTag
 }
 
+if (-not $PackageVersionPrereleaseTag) {
+    [Version] $moduleVersion = [Version] $assemblySemVer
+} else {
+    [Version] $moduleVersion = [Version] ($assemblySemVer -replace "-$PackageVersionPrereleaseTag", "")
+}
+
 [string] $ds = [System.IO.Path]::DirectorySeparatorChar
 & "${PSScriptRoot}${ds}package.ps1" `
-    -PackageVersionNuGet $PackageVersionNuGet `
-    -PackageVersionMajorMinorPatchBuild $PackageVersionMajorMinorPatchBuild `
+    -PackageVersion $PackageVersion `
+    -ModuleVersion $moduleVersion `
     -PackageVersionPrereleaseTag $PackageVersionPrereleaseTag `
     -ReleaseNotes $ReleaseNotes `
     -CommitSha $CommitSha

build/package.ps1

@@ -6,11 +6,11 @@
 param(
     [Parameter(Mandatory = $true)]
     [ValidateNotNullOrEmpty()]
-    [string] $PackageVersionNuGet,
+    [string] $PackageVersion,
 
     [Parameter(Mandatory = $true)]
-    [ValidateNotNullOrEmpty()]
-    [string] $PackageVersionMajorMinorPatchBuild,
+    [ValidateNotNull()]
+    [Version] $ModuleVersion,
 
     [Parameter(Mandatory = $false)]
     [string] $PackageVersionPrereleaseTag,
@@ -61,7 +61,6 @@ Set-StrictMode -Version Latest
 
 . "${PSScriptRoot}${ds}funcs${ds}Get-PSGalleryModuleNested.ps1"
 [object[]] $nestedRuntimePSGalleryModules = @(Get-PSGalleryModuleNested -RuntimeDependencies)
-[string] $packageVersion = $PackageVersionNuGet
 
 . "${PSScriptRoot}${ds}funcs${ds}New-ModuleManifestCustomized.ps1"
 [System.IO.FileInfo] $moduleManifest = New-ModuleManifestCustomized `
@@ -78,8 +77,8 @@ Set-StrictMode -Version Latest
     -PackageCopyright $packageCopyright `
     -PackageTags $packageTagsForNuSpec `
     -ReleaseNotes $ReleaseNotes `
-    -PackageVersion $packageVersion `
-    -PackageVersionMajorMinorPatchBuild $PackageVersionMajorMinorPatchBuild `
+    -PackageVersion $PackageVersion `
+    -ModuleVersion $ModuleVersion `
     -PackageVersionPrereleaseTag $PackageVersionPrereleaseTag `
     -PackageGuid $packageGuid `
     -PSEdition_Desktop:$PSEdition_Desktop `
@@ -90,7 +89,7 @@ Set-StrictMode -Version Latest
 . "${PSScriptRoot}${ds}funcs${ds}New-TemporaryProjectFile.ps1"
 [System.IO.FileInfo] $projectFile = New-TemporaryProjectFile `
     -PackageId $PackageId `
-    -PackageVersion $packageVersion `
+    -PackageVersion $PackageVersion `
     -CompanyName $companyName `
     -Authors $authors `
     -GitRepositoryUrl $repositoryGitUrl `

src/Search-CommandPath.ps1

@@ -3,6 +3,22 @@ $ErrorActionPreference = "Stop"
 Set-StrictMode -Version Latest
 
 
+<#
+.SYNOPSIS
+    Searches for the specified command in the current session's command path.
+.PARAMETER Name
+    The name of the command to search for.
+.PARAMETER All
+    If specified, returns all commands with the specified name in the current session's command path.
+.NOTES
+    Similar to *nix `which` or `where` commands.
+.OUTPUTS
+    System.String
+.EXAMPLE
+    Search-CommandPath -Name "notepad"
+.EXAMPLE
+    Search-CommandPath -Name "notepad" -All
+#>
 function Search-CommandPath {
     [CmdletBinding()]
     param(

src/Test-Command.ps1

@@ -3,6 +3,18 @@ $ErrorActionPreference = "Stop"
 Set-StrictMode -Version Latest
 
 
+<#
+.SYNOPSIS
+    Tests whether or not the specified command exists in the current session.
+.PARAMETER Name
+    The name of the command to test for.
+.PARAMETER ExecutableOnly
+    If specified, only indicates success if the command is an executable.
+.OUTPUTS
+    System.Boolean
+.NOTES
+    Similar to using *nix `type` or `typeset` commands with the `-t` option.
+#>
 function Test-Command() {
     param(
         [Parameter(Mandatory = $true)]

src/Test-Elevation.ps1

@@ -3,6 +3,12 @@ $ErrorActionPreference = "Stop"
 Set-StrictMode -Version Latest
 
 
+<#
+.SYNOPSIS
+    Tests whether or not the current session is elevated.
+.OUTPUTS
+    System.Boolean
+#>
 function Test-Elevation() {
     return [bool](([System.Security.Principal.WindowsIdentity]::GetCurrent()).groups -match "S-1-5-32-544")
 }

src/Test-LinkCapability.ps1

@@ -6,6 +6,13 @@ Set-StrictMode -Version Latest
 <#
 .SYNOPSIS
     Tests which filesystem link capabilities are supported by the current session.
+.OUTPUTS
+    System.Management.Automation.PSCustomObject
+    If the current session supports filesystem links, returns an object with the following properties:
+        HardLinks: An array of strings indicating which types of hard links are supported.
+        Junctions: An array of strings indicating which types of junctions are supported.
+        SymbolicLinks: An array of strings indicating which types of symbolic links are supported.
+    If the current session does not support filesystem links, returns $false.
 .NOTES
     See: https://docs.microsoft.com/en-us/windows/win32/fileio/hard-links-and-junctions
 #>

src/Test-ReparsePoint.ps1

@@ -3,6 +3,12 @@ $ErrorActionPreference = "Stop"
 Set-StrictMode -Version Latest
 
 
+<#
+.SYNOPSIS
+    Tests whether or not the specified path is a reparse point.
+.OUTPUTS
+    System.Boolean
+#>
 function Test-ReparsePoint([string]$path) {
     $file = Get-Item $path -Force -ea SilentlyContinue
     return [bool]($file.Attributes -band [IO.FileAttributes]::ReparsePoint)

src/Test-SessionInteractivity.ps1

@@ -4,6 +4,12 @@ $ErrorActionPreference = "Stop"
 Set-StrictMode -Version Latest
 
 
+<#
+.SYNOPSIS
+    Tests whether or not the current session is interactive.
+.OUTPUTS
+    System.Boolean
+#>
 function Test-SessionInteractivity {
     [CmdletBinding()]
     param()