codaamok.build

3.0.2

codaamok.build.psm1

#region Private functions
function GetPSGalleryNextAvailableVersionNumber {
    param (
        [Parameter(Mandatory)]
        [String]$ModuleName,

        [Parameter(Mandatory)]
        [Version]$VersionToBuild
    )

    Write-Verbose "Qualifying the version number to build with is available in the PowerShell Gallery" -Verbose

    for ($i = $VersionToBuild.Build; $i -le 100; $i++) {
        if ($i -eq 100) {
            throw "You have 100 unlisted packages under the same build number? Sort your life out."
        }

        try {
            $PSGalleryModuleInfo = Find-Module -Name $ModuleName -RequiredVersion $VersionToBuild -ErrorAction "Stop"
            if ($PSGalleryModuleInfo) {
                Write-Verbose "Found module in the gallery with the same verison number, adding one to the Build number and will query the gallery again"

                $VersionToBuild = [System.Version]::New(
                    $VersionToBuild.Major,
                    $VersionToBuild.Minor,
                    $VersionToBuild.Build + $i
                )
            }
            else {
                throw "Unusually, there was no object returned or excpetion throw from Find-Module while sussing out unlisted packages"
            }
        }
        catch {
            if ($_.Exception.Message -match "No match was found for the specified search criteria") {
                Write-Verbose "Found the next available version number to build with" -Verbose
                break
            }
            else {
                throw $_
            }
        }
    }

    return $VersionToBuild
}
#endregion

#region Public functions
function Get-BuildCommands {
    <#
    .SYNOPSIS
        Auxiliary
        Short description
    .DESCRIPTION
        Long description
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    .INPUTS
        Inputs (if any)
    .OUTPUTS
        Output (if any)
    .NOTES
        General notes
    #>
    param (
    )

    $Commands = @{}

    Get-Command -Module "codaamok.build" | ForEach-Object {
        $Help = Get-Help -Name $_.Name
        $Synopsis = $Help.Synopsis

        if ([String]::IsNullOrWhiteSpace($Synopsis[0])) { 
            $Commands["N/A"] += @($_.Name)
        } 
        else {
            $Commands[($Synopsis -split '\n')[0]] += @($_.Name)
        }
    }

    foreach ($Key in $Commands.Keys) {
        Write-Host $Key -ForegroundColor Blue
        foreach ($Value in $Commands[$Key]) {
            Write-Host ("- {0}" -f $Value) -ForegroundColor Green
        }
        Write-Host ""
    }
}

function New-ModuleDirStructure {
    <#
    .SYNOPSIS
        Setup
        Short description
    .DESCRIPTION
        Long description
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    .INPUTS
        Inputs (if any)
    .OUTPUTS
        Output (if any)
    .NOTES
        General notes
    #>
    param (
        [Parameter(Mandatory)]
        [String]$Path,
        [Parameter(Mandatory)]
        [String]$ModuleName,
        [Parameter()]
        [String]$Author = "Adam Cook (@codaamok)",
        [Parameter(Mandatory)]
        [String]$Description,
        [Parameter()]
        [String[]]$Tags,
        [Parameter()]
        [String]$ProjectUri,
        [Parameter()]
        [Switch]$CreateFormatFile,
        [Parameter()]
        [Version]$PowerShellVersion = 5.1
    )

    # Create the module and private function directories
    @(
        "$Path\.github\workflows",
        "$Path\src",
        "$Path\src\ScriptsToProcess",
        "$Path\src\Files",
        "$Path\src\Private",
        "$Path\src\Public",
        "$Path\src\Types",
        "$Path\src\en-US",
        "$Path\tests",
        "$Path\build",
        "$Path\release",
        "$Path\docs"
    ) | ForEach-Object {
        New-Item -Path $_ -ItemType Directory -Force
        New-Item -Path $_\.gitkeep -ItemType File -Force
    }

    #Create the module and related files
    $GitIgnorePath = Join-Path -Path $Path -ChildPath ".gitignore"
    $ModuleScript = "{0}.psm1" -f $ModuleName
    $ModuleScriptPath = Join-Path -Path $Path -ChildPath $ModuleScript
    $ModuleManifest = "{0}.psd1" -f $ModuleName
    $ModuleManifestPath = Join-Path -Path $Path -ChildPath $ModuleManifest
    New-Item $ModuleManifestPath -ItemType File -Force
    @(
        '$Public = @( Get-ChildItem -Path $PSScriptRoot\Public -Recurse -Filter "*.ps1" )'
        '$Private = @( Get-ChildItem -Path $PSScriptRoot\Private -Recurse -Filter "*.ps1" )'
        'foreach ($import in @($Public + $Private)) {'
        ' try {'
        ' . $import.fullname'
        ' }'
        ' catch {'
        ' Write-Error -Message "Failed to import function $($import.fullname): $_"'
        ' }'
        '}'
        'Export-ModuleMember -Function $Public.Basename'
    ) | Set-Content -Path $ModuleManifestPath -Force
    @(
        'build/*'
        'release/*'
        '!*.gitkeep'
    ) | Set-Content -Path $GitIgnorePath

    $ModuleHelp = "about_{0}.help.txt" -f $ModuleName
    $ModuleHelpPath - "{0}\src\en-US\{2}" -f $Path, $ModuleName, $ModuleHelp
    New-Item $ModuleHelpPath -ItemType File -Force

    $NewModuleManifestSplat = @{
        Path                = Join-Path -Path $Path -ChildPath 'src' | Join-Path -ChildPath $ModuleManifest
        RootModule          = $ModuleScript
        Description         = $Description
        PowerShellVersion   = $PowerShellVersion
        Author              = $Author
        FunctionsToExport   = '*'
    }

    if ($CreateFormatFile) { 
        $ModuleFormat = "{0}.Format.ps1xml" -f $ModuleName
        $ModuleFormatPath = "{0}\src\{1}" -f $Path, $ModuleFormat
        New-Item $ModuleFormatPath -ItemType File -Force
        $NewModuleManifestSplat["FormatsToProcess"] = $ModuleFormat
    }

    if ($ProjectUri) {
        $NewModuleManifestSplat["ProjectUri"] = $ProjectUri
    }

    New-ModuleManifest @NewModuleManifestSplat

    # Copy the public/exported functions into the public folder, private functions into private folder

}

function New-ProjectDirStructure {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String]$Path,

        [Parameter(Mandatory)]
        [String]$Name,

        [Parameter()]
        [String]$Platform
    )

    # TODO create CHANGELOG.md, copy github action workflow and build script, create module dir structure
}

function New-VSCodeTaskFile {
    <#
    .SYNOPSIS
        Setup
        Short description
    .DESCRIPTION
        Long description
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    .INPUTS
        Inputs (if any)
    .OUTPUTS
        Output (if any)
    .NOTES
        General notes
    #>
}

function Update-BuildFiles {
    <#
    .SYNOPSIS
        Setup
        Copy the build files (script + GitHub Actiosn workflow) from the module's install directory to the specified directory
    .DESCRIPTION
        Copy the build files (script + GitHub Actiosn workflow) from the module's install directory to the specified directory
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String]$DestinationPath
    )

    $Module = Get-Module "codaamok.build"

    # FileList property could be empty if imported the non-released module manifest during development
    if ([String]::IsNullOrWhiteSpace($Module.FileList)) {
        $Module = [PSCustomObject]@{
            FileList = Get-ChildItem -Path "$($Module.ModuleBase)\Files" -Force | Select-Object -ExpandProperty FullName
        }
    }

    $oldbuildyml = "{0}\.github\workflows\build.yml" -f $DestinationPath
    if (Test-Path $oldbuildyml) { 
        Remove-Item -Path $oldbuildyml -Confirm
    }

    switch -Regex ($Module.FileList) {
        "pipeline\.yml$" {
            $Destination = "{0}\.github\workflows" -f $DestinationPath
            if (-not (Test-Path $Destination)) {
                $null = New-Item -Path $Destination -ItemType "Directory" -Force
            }
            Copy-Item -Path $_ -Destination $Destination -Confirm
        }
        "gitignore$" {
            $Destination = "{0}\.gitignore" -f $DestinationPath
            Copy-Item -Path $_ -Destination $Destination -Confirm
        }
        default {
            Copy-Item -Path $_ -Destination $DestinationPath -Confirm
        }
    }
}

function Export-RootModule {
    <#
    .SYNOPSIS
        Build
        Get all of the function definition content for the module and create a single .psm1 with said content
    .DESCRIPTION
        Get all of the function definition content for the module and create a single .psm1 with said content
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String[]]$DevModulePath,

        [Parameter(Mandatory)]
        [String[]]$RootModule
    )

    $null = New-Item -Path $RootModule -ItemType "File" -Force

    foreach ($FunctionType in "Private","Public","Types") {
        '#region {0} functions' -f $FunctionType | Add-Content -Path $RootModule

        $Files = @(Get-ChildItem $DevModulePath\$FunctionType -Filter *.ps1 -Recurse)

        foreach ($File in $Files) {
            Get-Content -Path $File.FullName | Add-Content -Path $RootModule

            # Add new line only if the current file isn't the last one (minus 1 because array indexes from 0)
            if ($Files.IndexOf($File) -ne ($Files.Count - 1)) {
                Write-Output "" | Add-Content -Path $RootModule
            }
        }

        '#endregion' -f $FunctionType | Add-Content -Path $RootModule
        Write-Output "" | Add-Content -Path $RootModule
    }
}

function Export-ScriptsToProcess {
    <#
    .SYNOPSIS
        Build
        Create a single Process.ps1 script file for all script files under ScriptsToProcess\*
    .DESCRIPTION
        Create a single Process.ps1 script file for all script files under ScriptsToProcess\*
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String[]]$Path
    ) 

    $ProcessScript = New-Item -Path $BuildRoot\build\$Script:ModuleName\Process.ps1 -ItemType "File" -Force
    $Files = @(Get-ChildItem $Path -Filter *.ps1)

    foreach ($File in $Files) {
        Get-Content -Path $File.FullName | Add-Content -Path $ProcessScript

        # Add new line only if the current file isn't the last one (minus 1 because array indexes from 0)
        if ($Files.IndexOf($File) -ne ($Files.Count - 1)) {
            Write-Output "" | Add-Content -Path $ProcessScript
        }
    }
}

function Export-UnreleasedNotes {
    <#
    .SYNOPSIS
        Short description
    .DESCRIPTION
        Long description
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    .INPUTS
        Inputs (if any)
    .OUTPUTS
        Output (if any)
    .NOTES
        General notes
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String]$Path,

        [Parameter(Mandatory)]
        [PSCustomObject]$ChangeLogData,

        [Parameter()]
        [Bool]$NewRelease
    )

    $EmptyChangeLog = $true

    $ReleaseNotes = foreach ($Property in $ChangeLogData.Unreleased[0].Data.PSObject.Properties.Name) {
        $Data = $ChangeLogData.Unreleased[0].Data.$Property

        if ($Data) {
            $EmptyChangeLog = $false

            Write-Output ("# {0}" -f $Property)

            foreach ($item in $Data) {
                Write-Output ("- {0}" -f $item)
            }
        }
    }

    if ($EmptyChangeLog -eq $true -Or $ReleaseNotes.Count -eq 0) {
        if ($NewRelease.IsPresent) {
            throw "Can not build with empty Unreleased section in the change log"
        }
        else {
            $ReleaseNotes = "None"
        }
    }

    Write-Verbose "Release notes:" -Verbose
    $ReleaseNotes | Write-Verbose -Verbose

    Set-Content -Value $ReleaseNotes -Path $Path -Force
}

function Get-BuildVersionNumber {
    <#
    .SYNOPSIS
        Build
        Qualify the next version number to build with
    .DESCRIPTION
        Qualify the next version number to build with
    .EXAMPLE
        PS C:\> Get-BuildVersionNumber -ModuleName "PSShlink" -ManifestData $ManifestData -ChangeLogData $ChangeLogData
    #>
    param (
        [Parameter(Mandatory)]
        [String]$ModuleName,

        [Parameter(Mandatory, ParameterSetName='DetermineNextVersion')]
        [Hashtable]$ManifestData,

        [Parameter(Mandatory, ParameterSetName='DetermineNextVersion')]
        [PSCustomObject]$ChangeLogData,

        [Parameter(Mandatory, ParameterSetName='HardCodeNextVersion')]
        [Version]$VersionToBuild,

        [Parameter(ParameterSetName='DetermineNextVersion')]
        [Switch]$NewRelease
    )

    # Get PowerShell Gallery current verison number (if published)
    try {
        $PSGalleryModuleInfo = Find-Module -Name $ModuleName -ErrorAction "Stop"
    }
    catch {
        if ($_.Exception.Message -notmatch "No match was found for the specified search criteria") {
            throw $_
        }
        else {
            $PSGalleryModuleInfo = [PSCustomObject]@{
                "Name"    = $ModuleName
                "Version" = "0.0"
            }
        }
    }

    Write-Verbose ("PowerShell Gallery verison: {0}" -f $PSGalleryModuleInfo.Version) -Verbose
    Write-Verbose ("Changelog version: {0}" -f $ChangeLogData.Released[0].Version) -Verbose
    Write-Verbose ("Manifest version: {0}" -f $ManifestData.ModuleVersion) -Verbose

    if (-not $VersionToBuild) {
        if ($NewRelease.IsPresent) {
            # Try and piece together an understanding from the module manifest, PowerShell Gallery, and the change log, as to what the next version number should be

            # If the last released version in the change log and latest version available in the PowerShell gallery do not match, throw an exception - get them level!
            if ($null -ne $ChangeLogData.Released[0].Version -And $ChangeLogData.Released[0].Version -ne $PSGalleryModuleInfo.Version) {
                throw "The latest released version in the changelog does not match the latest released version in the PowerShell gallery"
            }
            # If module isn't yet published in the PowerShell gallery, and there's no Released section in the change log, set initial version as per the manifest
            elseif ($PSGalleryModuleInfo.Version -eq "0.0" -And $ChangeLogData.Released.Count -eq 0) {
                Write-Verbose "Module is not published to the PowerShell Gallery and there is not a Released section in the change log. Will use version from the module manifest." -Verbose
                $VersionToBuild = [System.Version]$ManifestData.ModuleVersion
            }
            # If module isn't yet published in the PowerShell gallery, and there is a Released section in the change log, update version
            elseif ($PSGalleryModuleInfo.Version -eq "0.0" -And $ChangeLogData.Released.Count -ge 1) {
                Write-Verbose "Module is not published to the PowerShell Gallery and there is a Released secton in the change log. Will +1 on the minor build from the changelog version." -Verbose
                $CurrentVersion = [System.Version]$ChangeLogData.Released[0].Version
                $VersionToBuild = [System.Version]::New(
                    $CurrentVersion.Major,
                    $CurrentVersion.Minor + 1,
                    $CurrentVersion.Build
                )
            }
            # If the module's PowerShell Gallery version and the last Released verison in the change log are in harmony, update version
            elseif ($ChangeLogData.Released[0].Version -eq $PSGalleryModuleInfo.Version) {
                Write-Verbose "Module is published to the PowerShell Gallery and its version matches the last Releases section in the changelog. Will +1 on the mintor build from the PowerShell Gallery version." -Verbose
                $CurrentVersion = [System.Version]$PSGalleryModuleInfo.Version
                $VersionToBuild = [System.Version]::New(
                    $CurrentVersion.Major,
                    $CurrentVersion.Minor + 1,
                    $CurrentVersion.Build
                )
            }
            else {
                Write-Output ("Latest release version from change log: {0}" -f $ChangeLogData.Released[0].Version)
                Write-Output ("Latest release version from PowerShell gallery: {0}" -f $PSGalleryModuleInfo.Version)
                throw "Can not determine next version number"
            }

            # Loop through and suss out any unlisted packages for the module in the PowerShell Gallery using the same version number
            # Keep looping and bumping the build version number by 1 until an available version number is found
            # Try this process up to 100 times and fail if can't find one
            # This can execute even if the module is not yet in the gallery because unlisted packages can still be present
            $VersionToBuild = GetPSGalleryNextAvailableVersionNumber -ModuleName $ModuleName -VersionToBuild $VersionToBuild
        }
        else {
            $VersionToBuild = [System.Version]::New(
                ([System.Version]$ManifestData.ModuleVersion).Major, 
                ([System.Version]$ManifestData.ModuleVersion).Minor, 
                ([System.Version]$ManifestData.ModuleVersion).Build + 1
            )
        }
    }
    else {
        Write-Verbose "Version to build with is hard coded" -Verbose
        if ($PSGalleryModuleInfo.Version -ne "0.0") {
            Write-Verbose "Module is published to the PowerShell Gallery" -Verbose
            $VersionToBuild = GetPSGalleryNextAvailableVersionNumber -ModuleName $ModuleName -VersionToBuild $VersionToBuild
        }
        else {
            Write-Verbose "Module not published to the PowerShell Gallery, will build with the given version number" -Verbose
        }
    }

    Write-Verbose ("Version to build: '{0}'" -f $VersionToBuild) -Verbose

    return $VersionToBuild
}

function Get-PublicFunctions {
    <#
    .SYNOPSIS
        Build
        Get a list of functions - as functions to export - defined in script files within the Public directory
    .DESCRIPTION
        Get a list of functions - as functions to export - defined in script files within the Public directory
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String[]]$Path
    )

    $Files = @(Get-ChildItem $Path -Filter *.ps1 -Recurse)

    foreach ($File in $Files) {
        $tokens = $errors = @()
        $Ast = [System.Management.Automation.Language.Parser]::ParseFile(
            $File.FullName,
            [ref]$tokens,
            [ref]$errors
        )

        if ($errors[0].ErrorId -eq 'FileReadError') {
            throw [InvalidOperationException]::new($errors[0].Message)
        }

        Write-Output $Ast.EndBlock.Statements.Name
    }
}

function Invoke-BuildClean {
    <#
    .SYNOPSIS
        Build
        Empty the contents of the build and release directories. If not exist, create them.
    .DESCRIPTION
        Empty the contents of the build and release directories. If not exist, create them.
    .EXAMPLE
        PS C:\> <example usage>
        Explanation of what the example does
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [String[]]$Path
    )

    foreach ($item in $Path) {
        if (Test-Path $item) {
            Remove-Item -Path $item\* -Exclude ".gitkeep" -Recurse -Force
        }
        else {
            $null = New-Item -Path $item -ItemType "Directory" -Force
        }
    }
}

function New-BuildEnvironmentVariable {
    <#
    .SYNOPSIS
        Build
        Set build and platform specific environment variables.
    .DESCRIPTION
        Set build and platform specific environment variables.
    .EXAMPLE
        PS C:\> New-BuildEnvironmentVariable -Variables @{ VersionToBuild = "1.2.3" } -Platform "GitHubActions"
        
        Writes to GitHub Action's environment variable file to create environment variable "VersionToBuild" with value of "1.2.3".
    #>
    param (
        [Parameter(Mandatory)]
        [Hashtable]$Variable,

        [Parameter(Mandatory)]
        [ValidateSet("GitHubActions")]
        [String[]]$Platform
    )

    switch ($Platform) {
        "GitHubActions" {
            foreach ($var in $Variable.GetEnumerator()) {
                Write-Output ("{0}={1}" -f $var.Key, $var.Value) | Add-Content -Path $env:GITHUB_ENV 
            }
        }
    }
}
#endregion

#region Types functions
#endregion