Add More test for Private Functions

.vscode/settings.json

@@ -4,10 +4,11 @@
     "files.trimTrailingWhitespace": true,
     "files.insertFinalNewline": true,
     "editor.insertSpaces": true,
+    "editor.tabSize": 4,
     // -------- Search configuration --------
     // Exclude the Output folder from search results.
     "search.exclude": {
-        "Output/**": true,
+        "Output": true,
     },
     //-------- PowerShell Configuration --------
     // Use a custom PowerShell Script Analyzer settings file for this workspace.
@@ -17,4 +18,4 @@
     "powershell.codeFormatting.preset": "OTBS",
     "editor.formatOnSave": true,
     "powershell.scriptAnalysis.enable": true
-}
+}

Plaster/Public/Get-ModuleExtension.ps1 → Plaster/Private/Get-ModuleExtension.ps1

@@ -1,4 +1,29 @@
 function Get-ModuleExtension {
+    <#
+    .SYNOPSIS
+    Retrieves module extensions based on specified criteria.
+
+    .DESCRIPTION
+    This function retrieves module extensions that match the specified module
+    name and version criteria.
+
+    .PARAMETER ModuleName
+    The name of the module to retrieve extensions for.
+
+    .PARAMETER ModuleVersion
+    The version of the module to retrieve extensions for.
+
+    .PARAMETER ListAvailable
+    Indicates whether to list all available modules or only the the latest
+    version of each module.
+
+    .EXAMPLE
+    Get-ModuleExtension -ModuleName "MyModule" -ModuleVersion "1.0.0"
+
+    Retrieves extensions for the module "MyModule" with version "1.0.0".
+    .NOTES
+
+    #>
     [CmdletBinding()]
     param(
         [string]
@@ -11,9 +36,9 @@ function Get-ModuleExtension {
         $ListAvailable
     )
 
-    #Only get the latest version of each module
+    # Only get the latest version of each module
     $modules = Get-Module -ListAvailable
-    if (!$ListAvailable) {
+    if (!$ListAvailable.IsPresent) {
         $modules = $modules |
             Group-Object Name |
             ForEach-Object {
@@ -25,28 +50,6 @@ function Get-ModuleExtension {
 
     Write-Verbose "Found $($modules.Length) installed modules to scan for extensions."
 
-    function ParseVersion($versionString) {
-        $parsedVersion = $null
-
-        if ($versionString) {
-            # We're targeting Semantic Versioning 2.0 so make sure the version has
-            # at least 3 components (X.X.X).  This logic ensures that the "patch"
-            # (third) component has been specified.
-            $versionParts = $versionString.Split('.')
-            if ($versionParts.Length -lt 3) {
-                $versionString = "$versionString.0"
-            }
-
-            if ($PSVersionTable.PSEdition -eq "Core") {
-                $parsedVersion = New-Object -TypeName "System.Management.Automation.SemanticVersion" -ArgumentList $versionString
-            } else {
-                $parsedVersion = New-Object -TypeName "System.Version" -ArgumentList $versionString
-            }
-        }
-
-        return $parsedVersion
-    }
-
     foreach ($module in $modules) {
         if ($module.PrivateData -and
             $module.PrivateData.PSData -and
@@ -58,8 +61,18 @@ function Get-ModuleExtension {
 
                 Write-Verbose "Comparing against module extension: $($extension.Module)"
 
-                $minimumVersion = ParseVersion $extension.MinimumVersion
-                $maximumVersion = ParseVersion $extension.MaximumVersion
+                if ([String]::IsNullOrEmpty($extension.MinimumVersion)) {
+                    # Fill with a default value if not specified
+                    $minimumVersion = $null
+                } else {
+                    $minimumVersion = Resolve-ModuleVersionString $extension.MinimumVersion
+                }
+                if ([String]::IsNullOrEmpty($extension.MaximumVersion)) {
+                    # Fill with a default value if not specified
+                    $maximumVersion = $null
+                } else {
+                    $maximumVersion = Resolve-ModuleVersionString $extension.MaximumVersion
+                }
 
                 if (($extension.Module -eq $ModuleName) -and
                     (!$minimumVersion -or $ModuleVersion -ge $minimumVersion) -and

Plaster/Private/Get-PlasterManifestPathForCulture.ps1

@@ -0,0 +1,69 @@
+function Get-PlasterManifestPathForCulture {
+    <#
+    .SYNOPSIS
+    Returns the path to the Plaster manifest file for a specific culture.
+
+    .DESCRIPTION
+    This function checks for the existence of a Plaster manifest file that
+    matches the specified culture. It first looks for a culture-specific
+    manifest, then checks for a parent culture manifest, and finally falls back
+    to an invariant culture manifest if no specific match is found. The function
+    returns the path to the manifest file if found, or $null if no matching
+    manifest is found.
+
+    .PARAMETER TemplatePath
+    The path to the template directory.
+    This should be a fully qualified path to the directory containing the
+    Plaster manifest files.
+
+    .PARAMETER Culture
+    The culture information for which to retrieve the Plaster manifest file.
+
+    .EXAMPLE
+    GetPlasterManifestPathForCulture -TemplatePath "C:\Templates" -Culture (Get-Culture)
+
+    This example retrieves the path to the Plaster manifest file for the current culture.
+    .NOTES
+    This is a private function used by Plaster to locate the appropriate
+    manifest file based on the specified culture.
+    #>
+    [CmdletBinding()]
+    [OutputType([String])]
+    param (
+        [string]
+        $TemplatePath,
+        [ValidateNotNull()]
+        [CultureInfo]
+        $Culture
+    )
+    if (![System.IO.Path]::IsPathRooted($TemplatePath)) {
+        $TemplatePath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($TemplatePath)
+    }
+
+    # Check for culture-locale first.
+    $plasterManifestBasename = "plasterManifest"
+    $plasterManifestFilename = "${plasterManifestBasename}_$($culture.Name).xml"
+    $plasterManifestPath = Join-Path $TemplatePath $plasterManifestFilename
+    if (Test-Path $plasterManifestPath) {
+        return $plasterManifestPath
+    }
+
+    # Check for culture next.
+    if ($culture.Parent.Name) {
+        $plasterManifestFilename = "${plasterManifestBasename}_$($culture.Parent.Name).xml"
+        $plasterManifestPath = Join-Path $TemplatePath $plasterManifestFilename
+        if (Test-Path $plasterManifestPath) {
+            return $plasterManifestPath
+        }
+    }
+
+    # Fallback to invariant culture manifest.
+    $plasterManifestPath = Join-Path $TemplatePath "${plasterManifestBasename}.xml"
+    if (Test-Path $plasterManifestPath) {
+        return $plasterManifestPath
+    }
+
+    # If no manifest is found, return $null.
+    # TODO: Should we throw an error instead?
+    return $null
+}

Plaster/Private/InitializePredefinedVariables.ps1 → Plaster/Private/Initialize-PredefinedVariables.ps1

@@ -1,11 +1,37 @@
-function InitializePredefinedVariables {
+function Initialize-PredefinedVariables {
+    <#
+    .SYNOPSIS
+    Initializes predefined variables used by Plaster.
+
+    .DESCRIPTION
+    This function sets up several predefined variables that are used throughout
+    the Plaster template processing. It includes variables for the template
+    path, destination path, and other relevant information.
+
+    .PARAMETER TemplatePath
+    The file system path to the Plaster template directory.
+
+    .PARAMETER DestPath
+    The file system path to the destination directory.
+
+    .EXAMPLE
+    Initialize-PredefinedVariables -TemplatePath "C:\Templates\MyTemplate" -DestPath "C:\Projects\MyProject"
+
+    This example initializes the predefined variables with the specified
+    template and destination paths.
+    .NOTES
+    This function is typically called at the beginning of the Plaster template
+    processing to ensure that all necessary variables are set up before any
+    template processing occurs.
+    #>
     [CmdletBinding()]
     param(
         [string]
         $TemplatePath,
         [string]
         $DestPath
     )
+
     # Always set these variables, even if the command has been run with -WhatIf
     $WhatIfPreference = $false
 
@@ -28,4 +54,4 @@ function InitializePredefinedVariables {
     Set-Variable -Name PLASTER_Date -Value ($now.ToShortDateString()) -Scope Script
     Set-Variable -Name PLASTER_Time -Value ($now.ToShortTimeString()) -Scope Script
     Set-Variable -Name PLASTER_Year -Value ($now.Year) -Scope Script
-}
+}

Plaster/Private/Invoke-PlasterOperation.ps1

@@ -1,26 +1,59 @@
 # Enhanced error handling wrapper
 function Invoke-PlasterOperation {
+    <#
+    .SYNOPSIS
+    Wraps the execution of a script block with enhanced error handling and
+    logging capabilities.
+
+    .DESCRIPTION
+    This function wraps the execution of a script block with enhanced error
+    handling and logging capabilities.
+
+    .PARAMETER ScriptBlock
+    The script block to execute.
+
+    .PARAMETER OperationName
+    The name of the operation being performed.
+
+    .PARAMETER PassThru
+    If specified, the output of the script block output will be returned.
+
+    .EXAMPLE
+    Invoke-PlasterOperation -ScriptBlock { Get-Process } -OperationName 'GetProcesses' -PassThru
+
+    This example executes the `Get-Process` cmdlet within the context of the
+    `Invoke-PlasterOperation` function, logging the operation and returning the
+    output.
+
+    .NOTES
+    This function is designed to be used within the Plaster module to ensure
+    consistent logging and error handling across various operations.
+    It is not intended for direct use outside of the Plaster context.
+    #>
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
-        [scriptblock]$ScriptBlock,
+        [scriptblock]
+        $ScriptBlock,
 
-        [string]$OperationName = 'PlasterOperation',
+        [string]
+        $OperationName = 'PlasterOperation',
 
-        [switch]$PassThru
+        [switch]
+        $PassThru
     )
 
     try {
         Write-PlasterLog -Level Debug -Message "Starting operation: $OperationName"
         $result = & $ScriptBlock
         Write-PlasterLog -Level Debug -Message "Completed operation: $OperationName"
 
-        if ($PassThru) {
+        if ($PassThru.IsPresent) {
             return $result
         }
     } catch {
         $errorMessage = "Operation '$OperationName' failed: $($_.Exception.Message)"
         Write-PlasterLog -Level Error -Message $errorMessage
         throw $_
     }
-}
+}

Plaster/Private/Resolve-ModuleVersionString.ps1

@@ -0,0 +1,52 @@
+function Resolve-ModuleVersionString {
+    <#
+    .SYNOPSIS
+    Resolve a module version string to a System.Version or
+    System.Management.Automation.SemanticVersion object.
+
+    .DESCRIPTION
+    This function takes a version string and returns a parsed version object.
+    It ensures that the version string is in a valid format, particularly for
+    Semantic Versioning 2.0, which requires at least three components
+    (major.minor.patch). If the patch component is missing, the function will
+    append ".0" to the version string.
+
+    .PARAMETER versionString
+    The version string to resolve.
+
+    .EXAMPLE
+    Resolve-ModuleVersionString -versionString "1.2"
+
+    This example resolves the version string "1.2" to a valid version object.
+    .NOTES
+    This function is designed to be used within the Plaster module to ensure consistent version handling.
+    It is not intended for direct use outside of the Plaster context.
+    #>
+    param(
+        [Parameter(Mandatory, Position = 0)]
+        [ValidateNotNullOrEmpty()]
+        $VersionString
+    )
+
+    # We're targeting Semantic Versioning 2.0 so make sure the version has
+    # at least 3 components (X.X.X).  This logic ensures that the "patch"
+    # (third) component has been specified.
+    $versionParts = $VersionString.Split('.')
+    if ($versionParts.Length -lt 3) {
+        $VersionString = "$VersionString.0"
+    }
+
+    if ($PSVersionTable.PSEdition -eq "Core") {
+        $newObjectSplat = @{
+            TypeName = "System.Management.Automation.SemanticVersion"
+            ArgumentList = $VersionString
+        }
+        return New-Object @newObjectSplat
+    } else {
+        $newObjectSplat = @{
+            TypeName = "System.Version"
+            ArgumentList = $VersionString
+        }
+        return New-Object @newObjectSplat
+    }
+}