MetaNull.ModuleMaker

0.0.29.0

MetaNull.ModuleMaker.psm1

#Requires -Module Microsoft.PowerShell.PSResourceGet
# Module Constants

Set-Variable INSIDE_MODULEMAKER_MODULE -option Constant -value $true
Function Get-ResourceDirectory {
<#
    .SYNOPSIS
        Get the location of the Module's ResourceDirectory
 
    .EXAMPLE
        $Item = Get-ResourceDirectory
#>
[CmdletBinding()]
[OutputType([PSCustomObject])]
param()
Process {
    if((Get-Variable INSIDE_MODULEMAKER_MODULE -ErrorAction SilentlyContinue)) {
        #INSIDE_MODULEMAKER_MODULE is a constant defined in the module
        #If it is set, then the script is run from a loaded module, PSScriptRoot = Directory of the psm1
        Get-Item (Join-Path $PSScriptRoot resource)
    } else {
        #Otherwise, the script was probably called from the command line, PSScriptRoot = Directory /source/private
        Get-Item (Join-Path (Split-Path (Split-Path $PSScriptRoot)) resource)
    }
}
}
Function Test-JoinPath {
<#
    .SYNOPSIS
        Test if the output of Join-Path exists
 
    .EXAMPLE
        Test-JoinPath -Path $env:TEMP -Name toto
 
    .EXAMPLE
        JoinPath -Path $env:TEMP -Name toto | Test-JoinPath
#>
[CmdletBinding(DefaultParameterSetName = 'LiteralPathAny')]
[OutputType([PSCustomObject])]
param(
    [Parameter(Mandatory,Position=0,ValueFromPipeline,ParameterSetName = 'LiteralPathAny')]
    [Parameter(Mandatory,Position=0,ValueFromPipeline,ParameterSetName = 'LiteralPathDirectory')]
    [Parameter(Mandatory,Position=0,ValueFromPipeline,ParameterSetName = 'LiteralPathFile')]
    [string]
    $LiteralPath,

    [Parameter(Mandatory,Position=0,ParameterSetName = 'PathAny')]
    [Parameter(Mandatory,Position=0,ParameterSetName = 'PathDirectory')]
    [Parameter(Mandatory,Position=0,ParameterSetName = 'PathFile')]
    [string]
    $Path,
    [Parameter(Mandatory,Position=0,ParameterSetName = 'PathAny')]
    [Parameter(Mandatory,Position=0,ParameterSetName = 'PathDirectory')]
    [Parameter(Mandatory,Position=0,ParameterSetName = 'PathFile')]
    [string]
    $Name,

    [Parameter(Mandatory,Position=1,ParameterSetName = 'PathDirectory')]
    [Parameter(Mandatory,Position=1,ParameterSetName = 'LiteralPathDirectory')]
    [switch]
    $Directory,

    [Parameter(Mandatory,Position=1,ParameterSetName = 'PathFile')]
    [Parameter(Mandatory,Position=1,ParameterSetName = 'LiteralPathFile')]
    [switch]
    $File

)
Process {
    if($Directory.IsPresent -and $Directory) {
        $PathType = 'Container'
    } elseif($File.IsPresent -and $File) {
        $PathType = 'Container'
    } else {
        $PathType = 'Any'
    }

    if($PsCmdlet.ParameterSetName -in 'LiteralPathAny','LiteralPathDirectory','LiteralPathFile') {
        return Test-Path -LiteralPath $LiteralPath -PathType $PathType
    } else {
        return Test-Path -LiteralPath (Join-Path -Path $Path -ChildPath $Name) -PathType $PathType
    }
}
}
Function Test-ModuleDefinition {
[CmdletBinding()]
param(
    [Parameter(Mandatory = $false)]
    [AllowEmptyString()]
    [AllowNull()]
    [Alias('Path','DataFile')]
    [string] $ModuleDefinitionPath
)
End {
    $EAB = $ErrorActionPreference
    try {
        $ErrorActionPreference = 'Stop'
        if(-not $ModuleDefinitionPath) {
            Write-Debug "Module definition path is null, empty or not provided"
            return $false
        }
        if(-not (Test-Path -Path $ModuleDefinitionPath -PathType Leaf)) {
            Write-Debug "Module definition file does not exist or is not a file, for path: $ModuleDefinitionPath"
            return $false
        }

        Write-Debug "Importing Module definition from: $ModuleDefinitionPath"
        $ModuleDefinition = Import-PowerShellDataFile -Path $ModuleDefinitionPath

        if($null -eq $ModuleDefinition.Name -or $null -eq $ModuleDefinition.ModuleSettings -or $null -eq $ModuleDefinition.ModuleSettings.GUID) {
            Write-Debug "Module definition is invalid: `$_.Name or `$_.GUID are missing"
            return $false
        }
        if($ModuleDefinition.Name -eq '%%MODULE_NAME%%' -or $ModuleDefinition.ModuleSettings.GUID -eq '%%MODULE_GUID%%') {
            Write-Debug "Module definition is invalid: `$_.Name or `$_.GUID are not initialized"
            return $false
        }
        if($ModuleDefinition.Name -eq [string]::empty -or $ModuleDefinition.ModuleSettings.GUID -eq [string]::empty) {
            Write-Debug "Module definition is invalid: `$_.Name or `$_.GUID are empty"
            return $false
        }
        
        Write-Debug "Module definition is valid. Module: $($ModuleDefinition.Name)"
        
        $ModulePath = $ModuleDefinitionPath | Split-Path -Parent
        Write-Debug "Testing Module structure from: $ModulePath"
        if(-not (Test-Path -Path (Join-Path $ModulePath source) -PathType Container)) {
            Write-Debug "Module source directory does not exist"
            return $false
        }
        if(-not (Test-Path -Path (Join-Path $ModulePath test) -PathType Container)) {
            Write-Debug "Module test directory does not exist"
            return $false
        }
        if(-not (Test-Path -Path (Join-Path $ModulePath Build.ps1) -PathType Leaf)) {
            Write-Debug "Module's Build script does not exist"
            return $false
        }
        if(-not (Test-Path -Path (Join-Path $ModulePath Publish.ps1) -PathType Leaf)) {
            Write-Debug "Module's Publish script does not exist"
            return $false
        }

        Write-Debug "Module structure is valid. Path: $($ModulePath)"

        return $true
    } catch {
        Write-Verbose "$($_.Exception.Message)"
        # Swallow exception, to permit returninbg $false instead of throwing
    } finally {
        $ErrorActionPreference = $EAB
    }
    return $false
}
}
Function Invoke-BuildModule {
[CmdletBinding(DefaultParameterSetName = 'IncrementBuild')]
param(
    [Parameter(Mandatory,ValueFromPipeline)]
    [ValidateScript({
        Test-ModuleDefinition -ModuleDefinitionPath $_
    })]
    [Alias('Path','DataFile')]
    [string] $ModuleDefinitionPath,

    [switch] $IncrementMajor,

    [switch] $IncrementMinor,

    [switch] $IncrementRevision
)
Process {
    $BackupErrorActionPreference = $ErrorActionPreference
    $ErrorActionPreference = 'Stop'
    try {
        $ModulePath = $ModuleDefinitionPath | Split-Path -Parent
        $ScriptPath = Join-Path $ModulePath Build.ps1 -Resolve
        Push-Location (Split-Path $ScriptPath -Parent)
        
        $ScriptArguments = $args | Where-Object { $_ -ne $ModuleDefinitionPath }
        if($ScriptArguments -eq $null) {
            $ScriptArguments = @()
        }
        . $ScriptPath @ScriptArguments

        $ModuleDefinitionPath  | Write-Output
    } finally {
        Pop-Location
        $ErrorActionPreference = $BackupErrorActionPreference
    }
}
}
Function Invoke-PublishModule {
[CmdletBinding(DefaultParameterSetName = 'psgallery')]
param(
    [Parameter(Mandatory,ValueFromPipeline)]
    [ValidateScript({
        Test-ModuleDefinition -ModuleDefinitionPath $_
    })]
    [Alias('Path','DataFile')]
    [string] $ModuleDefinitionPath,

    [Parameter(Mandatory = $true, ParameterSetName = 'custom')]
    [string] $RepositoryUri,

    [Parameter(Mandatory = $true, ParameterSetName = 'custom')]
    [string] $RepositoryName,

    [Parameter(Mandatory = $false)]
    [string] $VaultName = 'MySecretVault',

    [Parameter(Mandatory = $false)]
    [string] $SecretName = 'PSGalleryCredential',

    [Parameter(Mandatory = $false)]
    [Switch] $PromptSecret,

    [Parameter(Mandatory = $false)]
    [Switch] $PersonalAccessTokenAsString
)
Process {
    $BackupErrorActionPreference = $ErrorActionPreference
    $ErrorActionPreference = 'Stop'
    try {
        $ModulePath = $ModuleDefinitionPath | Split-Path -Parent
        $ScriptPath = Join-Path $ModulePath Publish.ps1 -Resolve
        Push-Location (Split-Path $ScriptPath -Parent)
        
        $ScriptArguments = $args | Where-Object { $_ -ne $ModuleDefinitionPath }
        if($ScriptArguments -eq $null) {
            $ScriptArguments = @()
        }
        . $ScriptPath @ScriptArguments

        $ModuleDefinitionPath  | Write-Output
    } finally {
        Pop-Location
        $ErrorActionPreference = $BackupErrorActionPreference
    }
}
}
Function Invoke-TestModule {
[CmdletBinding()]
param(
    [Parameter(Mandatory,ValueFromPipeline)]
    [ValidateScript({
        Test-ModuleDefinition -ModuleDefinitionPath $_
    })]
    [Alias('Path','DataFile')]
    [string] $ModuleDefinitionPath
)
Process {
    $BackupErrorActionPreference = $ErrorActionPreference
    $ErrorActionPreference = 'Stop'
    try {
        $ModulePath = $ModuleDefinitionPath | Split-Path -Parent
        $ScriptPath = Join-Path $ModulePath Build.ps1 -Resolve
        Push-Location (Split-Path $ScriptPath -Parent)
        
        Invoke-Pester -Path . -OutputFile .\testresults.xml -OutputFormat NUnitXml -CodeCoverageOutputFile .\coverage.xml -PassThru

        $ModuleDefinitionPath  | Write-Output
    } finally {
        Pop-Location
        $ErrorActionPreference = $BackupErrorActionPreference
    }
}
}
Function New-Module {
<#
    .SYNOPSIS
        Create an empty Powershell Module
 
    .DESCRIPTION
        Create an empty Powershell Module with the following structure:
        - ModuleName
            - Build.psd1 # Contains the module's configuration (automatically generated by New-Module)
            - Version.psd1 # Contains the module's version (automatically generated during Build)
            - Build.ps1 # A script that builds the module
            - Publish.ps1 # A script that publishes the built module to a repository such as PSGallery
            - source # Contains the module's source code
                - public # Contains public/exposed functions
                    - Verb-Name.ps1 # Defines the public function "Verb-Name" (e.g.: "Get-Something")
                - private # Contains private functions (accessible only from within the module)
                    - Verb-Name.ps1 # Defines the private function "Verb-Name" (e.g.: "Invoke-Something")
                - init # Contains module initialization code
                    - Init.ps1 # Contains module initialization code, such as definition of Constants, etc.
                - class # Contains .net classes exposed by the module
                    - ClassName.cs # Defines the class "ClassName"
            - test # Contains the module's tests
                - public # Contains tests for public/exposed functions
                    - Verb-Name.Tests.ps1 # Contains tests for the public function "Verb-Name" (e.g.: "Get-Something")
                - private # Contains tests for private functions
                    - Verb-Name.Tests.ps1 # Contains tests for the private function "Verb-Name" (e.g.: "Invoke-Something")
            - resource # Contains resources contained in the module (e.g. data files that are accessible to the module)
     
    .PARAMETER LiteralPath
        The path to the directory where the module will be created. E.g: $env:TEMP
 
    .PARAMETER Name
        The name of the module. E.g.: MyModule
 
    .PARAMETER Description
        The description of the module. E.g.: "A module that does something"
 
    .PARAMETER Uri
        The URI of the module's documentation or repository. E.g.: "https://www.test.com/mymodule"
 
    .PARAMETER Author
        The author of the module. E.g.: "Pascal Havelange"
 
    .PARAMETER Vendor
        The vendor/company of the authors. E.g.: "MetaNull"
 
    .PARAMETER Copyright
        The copyright statement of the module. E.g.: "(c) 2025"
 
    .PARAMETER ModuleDependencies
        An array of module dependencies. E.g.: @("PackageManagement", "PowerShellGet")
        The module automatically adds the dependencies to the module's configuration file.
 
    .PARAMETER AssemblyDependencies
        An array of assembly dependencies. E.g.: @("System.Net.WebUtility", "System.Management.Automation.PSCredential")
        The module automatically adds the dependencies to the module's configuration file.
 
    .PARAMETER Force
        If the module directory already exists, overwrite it.
 
    .OUTPUTS
        Returns a [System.IO.FileInfo] object representing the module's configuration file (Build.psd1)
 
    .EXAMPLE
        # Create a new 'MyModule' module in the $env:TEMP directory
        $Module = New-Module -Path $env:TEMP -Name MyModule
 
        # Create a new public function 'Get-Something' in the module, and a test for it
        $Module | New-Function -Public -Verb Get -Name Something
         
        $Module | Invoke-Build
        $Module | Invoke-Publish
 
#>
[CmdletBinding()]
[OutputType([System.IO.FileInfo])]
param(
    [Parameter(Mandatory)]
    [ValidateScript({
        Test-Path -Path $_ -PathType Container
    })]
    [Alias('Path')]
    [string] $LiteralPath,

    [Parameter(Mandatory)]
    [ValidateScript({
        $_ -match '^[a-zA-Z][a-zA-Z0-9\._-]*$'
    })]
    [string] $Name,

    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyString()]
    [string] $Description = $null,

    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyString()]
    [ValidateScript({
        try {
            if($null -eq $_ -or [string]::empty -eq $_ -or [System.Uri]::new($_)) {
                return $true
            }
        } catch {
            # Swallow exception, to permit returninbg $false instead of throwing
        }
        return $false
    })]
    [string] $Uri = 'https://www.test.com/mymodule',

    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyString()]
    [string] $Author = ([System.Security.Principal.WindowsIdentity]::GetCurrent().Name),
    
    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyString()]
    [string] $Vendor = 'Unknown',
    
    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyString()]
    [string] $Copyright = "© $((Get-Date).Year). All rights reserved",
    
    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyCollection()]
    [string[]] $ModuleDependencies,
    
    [Parameter(Mandatory = $false)]
    [AllowNull()]
    [AllowEmptyCollection()]
    [string[]] $AssemblyDependencies,

    [Parameter(Mandatory = $false)]
    [switch] $Force

)
Process {
    $BackupErrorActionPreference = $ErrorActionPreference
    $ErrorActionPreference = 'Stop'
    try {
        $NewItemForce = $false
        $DirectoryPath = Join-Path $LiteralPath $Name
        if(Test-Path $DirectoryPath -PathType Any) {
            if($Force.IsPresent -and $Force) {
                "Target directory $DirectoryPath exists, overwriting." | Write-Warning
                $NewItemForce = $true
            } else {
                throw "Target directory $DirectoryPath exists"
            }
        }
        # Create the directories
        $RootDirectory = New-Item -Path $LiteralPath -Name $Name -ItemType Directory -Force:$NewItemForce
        $SourceDirectory = New-Item (Join-Path $RootDirectory source) -ItemType Directory -Force:$NewItemForce
        $TestDirectory = New-Item (Join-Path $RootDirectory test) -ItemType Directory -Force:$NewItemForce
        $SourcePublicDirectory = New-Item (Join-Path $SourceDirectory public) -ItemType Directory -Force:$NewItemForce
        $SourcePrivateDirectory = New-Item (Join-Path $SourceDirectory private) -ItemType Directory -Force:$NewItemForce
        $SourceInitDirectory = New-Item (Join-Path $SourceDirectory init) -ItemType Directory -Force:$NewItemForce
        $TestPublicDirectory = New-Item (Join-Path $TestDirectory public) -ItemType Directory -Force:$NewItemForce
        $TestPrivateDirectory = New-Item (Join-Path $TestDirectory private) -ItemType Directory -Force:$NewItemForce

        # Create the module's configuration file, script files, and module's sample source and test files
        if((Get-Variable INSIDE_MODULEMAKER_MODULE -ErrorAction SilentlyContinue)) {
            #INSIDE_MODULEMAKER_MODULE is a constant defined in the module
            #If it is set, then the script is run from a loaded module, PSScriptRoot = Directory of the psm1
            $ResourceDirectory = Get-Item (Join-Path $PSScriptRoot resource)
        } else {
            #Otherwise, the script was probably called from the command line, PSScriptRoot = Directory /source/private
            $ResourceDirectory = Get-Item (Join-Path (Split-Path (Split-Path $PSScriptRoot)) resource)
        }
        Copy-Item $ResourceDirectory\script\*.ps1 $RootDirectory -Force:$NewItemForce
        Copy-Item $ResourceDirectory\data\*.psd1 $RootDirectory -Force:$NewItemForce
        Copy-Item -Path $ResourceDirectory\dummy\* -Destination $RootDirectory -Recurse -Force:$NewItemForce

        # Update Module's configuration
        $ManifestFile = Get-Item (Join-Path $RootDirectory Build.psd1)
        $ManifestFileContent = Get-Content -LiteralPath $ManifestFile
        $Replace = @{
            '%%MODULE_GUID%%'= (New-Guid)
            '%%MODULE_NAME%%' = "$Name"
            '%%MODULE_DESCRIPTION%%' = "$Description"
            '%%MODULE_URI%%' = "$Uri"
            '%%MODULE_AUTHOR%%' = "$Author"
            '%%MODULE_VENDOR%%'= "$Vendor"
            '%%MODULE_COPYRIGHT%%' = "$Copyright"
            "%%ASSEMBLY_DEPENDENCIES%%" = $null
            "%%MODULE_DEPENDENCIES%%" = $null
        }
        if($AssemblyDependencies) {
            $Replace.'%%ASSEMBLY_DEPENDENCIES%%' = "'$($AssemblyDependencies -join "','")'"
        }
        if($ModuleDependencies) {
            $Replace.'"%%MODULE_DEPENDENCIES%%"' = "'$($ModuleDependencies -join "','")'"
        }
        $Replace.GetEnumerator() | Foreach-Object {
            if($_.Value) {
                $ManifestFileContent = $ManifestFileContent -replace "$($_.Key)","$($_.Value)"
            } else {
                $ManifestFileContent = $ManifestFileContent -replace "$($_.Key)"
            }
        }
        $ManifestFileContent | Set-Content -LiteralPath $ManifestFile -Force:$NewItemForce

        $ManifestFile | Write-Output
    } finally {
        $ErrorActionPreference = $BackupErrorActionPreference
    }
}
}
Function New-ModuleFunction {
<#
.SYNOPSIS
    Create a new function in a module created by ModuleMaker
 
.DESCRIPTION
    This function creates a new function in a module created by ModuleMaker. It creates a new function in the source directory and a new test file in the test directory.
 
.PARAMETER ModuleDefinitionPath
    The path to the module definition file (Build.psd1). This file is created by New-Module and contains the module's metadata.
 
.PARAMETER Name
    The name of the new function. This name must be a valid Powershell function name.
 
.PARAMETER Private
    If this switch is present, the function will be created in the private directory. Otherwise, it will be created in the public directory.
 
.OUTPUTS
    The path to the module definition file (Build.psd1) is returned.
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory,ValueFromPipeline)]
    [ValidateScript({
        Test-ModuleDefinition -ModuleDefinitionPath $_
    })]
    [Alias('Path','DataFile')]
    [string] $ModuleDefinitionPath,

    [Parameter(Mandatory)]
    [ValidateScript({
        $_ -match '^[a-zA-Z][a-zA-Z0-9\._-]*$'
    })]
    [string] $Name,

    [Parameter(Mandatory=$false)]
    [switch] $Private
)
Process {
    $BackupErrorActionPreference = $ErrorActionPreference
    $ErrorActionPreference = 'Stop'
    try {
        $DummyName = "Get-Dummy"
        $ModulePath = $ModuleDefinitionPath | Split-Path -Parent
        $ResourcePath = Get-ResourceDirectory

        $Visibility = if($Private) { 'private' } else { 'public' }
        $TargetSourceDirectory = Join-Path (Join-Path $ModulePath source) $Visibility -Resolve
        $TargetTestDirectory = Join-Path (Join-Path $ModulePath test) $Visibility -Resolve

        $TemplateFunction = Join-Path $ResourcePath "dummy\source\public\$DummyName.ps1" -Resolve
        $TargetFunction = Join-Path $TargetSourceDirectory "$Name.ps1"
        Copy-Item -Path $TemplateFunction -Destination $TargetFunction | Out-Null
        $Content = Get-Content -LiteralPath $TemplateFunction -Raw
        $Content -replace $DummyName, $Name | Set-Content -LiteralPath $TargetFunction
        
        $TemplateTest = Join-Path $ResourcePath "dummy\test\public\$DummyName.Tests.ps1" -Resolve
        $TargetTest = Join-Path $TargetTestDirectory "$Name.Tests.ps1"
        Copy-Item -Path $TemplateTest -Destination $TargetTest | Out-Null
        $Content = Get-Content -LiteralPath $TemplateTest -Raw
        $Content -replace $DummyName, $Name | Set-Content -LiteralPath $TargetTest

        $ModuleDefinitionPath  | Write-Output
    } finally {
        $ErrorActionPreference = $BackupErrorActionPreference
    }
}
}