PSModule.build.ps1

#requires -version 5
#requires -module BuildHelpers
#Build Script for Powershell Modules
#Uses Invoke-Build (https://github.com/nightroman/Invoke-Build)
#Run by changing to the project root directory and run ./Invoke-Build.ps1
#Uses a master-always-deploys strategy and semantic versioning - http://nvie.com/posts/a-successful-git-branching-model/

param (
    #Skip publishing to various destinations (Appveyor,Github,PowershellGallery,etc.)
    [Switch]$SkipPublish,
    #Force publish step even if we are not in master. If you are following GitFlow or GitHubFlow you should never need to do this.
    [Switch]$ForcePublish,
    #Show detailed environment variables. WARNING: Running this in a CI like appveyor may expose your secrets to the log! Be careful!
    [Switch]$ShowEnvironmentVariables,
    #Powershell modules required for the build process
    [String[]]$BuildHelperModules = @("BuildHelpers","Pester","powershell-yaml","Microsoft.Powershell.Archive","PSScriptAnalyzer"),
    #Which build files/folders should be excluded from packaging
    [String[]]$BuildFilesToExclude = @("Build","Release","Tests",".git*","appveyor.yml","gitversion.yml","*.build.ps1",".vscode",".placeholder"),
    #Where to perform the building of the module. Defaults to "Release" under the project directory. You can specify either a path relative to the project directory, or a literal alternate path.
    [String]$BuildOutputPath,
    #NuGet API Key for Powershell Gallery Publishing. Defaults to environment variable of the same name
    [String]$NuGetAPIKey = $env:NuGetAPIKey,
    #GitHub User for Github Releases. Defaults to environment variable of the same name
    [String]$GitHubUserName = $env:GitHubUserName,
    #GitHub API Key for Github Releases. Defaults to environment variable of the same name
    [String]$GitHubAPIKey = $env:GitHubAPIKey,
    #Setting this option will only publish to Github as "draft" (hidden) releases for both GA and prerelease, that you then must approve to show to the world.
    [Switch]$GitHubPublishAsDraft
)

#Initialize Build Environment
Enter-Build {
    #TODO: Make bootstrap module loading more flexible and dynamic
    <#
    if (-not (Get-Command "Set-BuildEnvironment" -module BuildHelpers)) {
        $HelpersPath = "$Buildroot\Build\Helpers"
        import-module -force -name "$HelpersPath\BuildHelpers"
    }
    #>


    #Move to the Project Directory if we aren't there already. This should never be necessary, just a sanity check
    Set-Location $buildRoot

    #Set the buildOutputPath to "Release" by default if not otherwise specified
    if (-not $BuildOutputPath) {
        $BuildOutputPath = "Release"
    }

    #Configure some easy to use build environment variables
    Set-BuildEnvironment -BuildOutput $BuildOutputPath -Force
    $BuildProjectPath = join-path $env:BHBuildOutput $env:BHProjectName

    #If this is a meta-build of PowerCD, include certain additional files that are normally excluded.
    #This is so we can use the same build file for both PowerCD and templates deployed from PowerCD.
    $PowerCDIncludeFiles = @("Build","Tests",".git*","appveyor.yml","gitversion.yml","*.build.ps1",".vscode",".placeholder")
    if ($env:BHProjectName -match 'PowerCD') {
        $BuildFilesToExclude = $BuildFilesToExclude | Where-Object {$PowerCDIncludeFiles -notcontains $PSItem}
    }
    #Define the Project Build Path
    Write-Build Green "Build Initialization - Project Build Path: $BuildProjectPath"

    #If the branch name is master-test, run the build like we are in "master"
    if ($env:BHBranchName -eq 'master-test') {
        write-build Magenta "Build Initialization - Detected master-test branch, running as if we were master"
        $SCRIPT:BranchName = "master"
    } else {
        $SCRIPT:BranchName = $env:BHBranchName
    }
    write-build Green "Build Initialization - Current Branch Name: $BranchName"
    $PassThruParams = @{}
    if ( ($VerbosePreference -ne 'SilentlyContinue') -or ($CI -and ($BranchName -ne 'master')) ) {
        write-build Green "Build Initialization - Verbose Build Logging Enabled"
        $SCRIPT:VerbosePreference = "Continue"
        $PassThruParams.Verbose = $true
    }


    $lines = '----------------------------------------------------------------'
    function Write-VerboseHeader ([String]$Message) {
        #Simple function to add lines around a header
        write-verbose ""
        write-verbose $lines
        write-verbose $Message
        write-verbose $lines
    }

    #Detect if we are in a continuous integration environment (Appveyor, etc.) or otherwise running noninteractively
    if ($ENV:CI -or $CI -or ([Environment]::GetCommandLineArgs() -like '-noni*')) {
        write-build Green 'Build Initialization - Detected a Noninteractive or CI environment, disabling prompt confirmations'
        $SCRIPT:CI = $true
        $ConfirmPreference = 'None'
        $ProgressPreference = "SilentlyContinue"
    }

    #Register Nuget
    if (!(get-packageprovider "Nuget" -ForceBootstrap -ErrorAction silentlycontinue)) {
        write-verbose "Nuget Provider Not found. Fetching..."
        Install-PackageProvider Nuget -forcebootstrap -scope currentuser @PassThruParams | out-string | write-verbose
        write-verboseheader "Installed Nuget Provider Info"
        Get-PackageProvider Nuget @PassThruParams | format-list | out-string | write-verbose
    }

    #Fix a bug with the Appveyor 2017 image having a broken nuget (points to v3 URL but installed packagemanagement doesn't query v3 correctly)
    if ($ENV:APPVEYOR -and ($ENV:APPVEYOR_BUILD_WORKER_IMAGE -eq 'Visual Studio 2017')) {
        write-verbose "Detected Appveyor VS2017 Image, using v2 Nuget API"
        #Next command will detect this was removed and add this back
        UnRegister-PackageSource -Name nuget.org


        #Add the nuget repository so we can download things like GitVersion
        # TODO: Make this optional code when running interactively
        if (!(Get-PackageSource "nuget.org" -erroraction silentlycontinue)) {
            write-verbose "Registering nuget.org as package source"
            Register-PackageSource -provider NuGet -name nuget.org -location http://www.nuget.org/api/v2 -Trusted @PassThruParams  | out-string | write-verbose
        }
        else {
            $nugetOrgPackageSource = Set-PackageSource -name 'nuget.org' -Trusted @PassThruParams
            if ($PassThruParams.Verbose) {
                write-verboseheader "Nuget.Org Package Source Info"
                $nugetOrgPackageSource | format-table | out-string | write-verbose
            }
        }
    }


    #Move to the Project Directory if we aren't there already. This should never be necessary, just a sanity check
    Set-Location $buildRoot

    #Force TLS 1.2 for all HTTPS transactions
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

    write-verboseheader "Build Environment Prepared! Environment Information:"
    Get-BuildEnvironment | format-list | out-string | write-verbose
    if ($ShowEnvironmentVariables) {
        write-verboseheader "Current Environment Variables"
        get-childitem env: | out-string | write-verbose

        write-verboseheader "Powershell Variables"
        Get-Variable | select-object name, value, visibility | format-table -autosize | out-string | write-verbose
    }
}

task Clean {
    #Reset the BuildOutput Directory
    if (test-path $buildProjectPath) {
        Write-Verbose "Removing and resetting Build Output Path: $buildProjectPath"
        remove-item $buildProjectPath -Recurse @PassThruParams
        remove-item $buildOutputPath\PowerCD-TestResults*.xml
    }
    New-Item -Type Directory $BuildProjectPath @PassThruParams | out-null
    #Unmount any modules named the same as our module
    Remove-Module $env:BHProjectName -erroraction silentlycontinue
}

task Version {
    #Fetch GitVersion if required
    $GitVersionEXE = (Get-Item "$BuildRoot\Build\Helpers\GitVersion\*\GitVersion.exe" -erroraction continue | Select-Object -last 1).fullname
    if (-not (Test-Path -PathType Leaf $GitVersionEXE)) {
        throw "Path to Gitversion ($GitVersionEXE) is not valid or points to a folder"
        <# This is temporarily disabled as we need to use the beta gitversion for Mainline Deployment. Will be re-enabled when latest v4 is available on nuget.
            #TODO: Re-enable once Gitversion v4 stable is available
            $GitVersionCMDPackageName = "gitversion.commandline"
            $GitVersionCMDPackage = Get-Package $GitVersionCMDPackageName -erroraction SilentlyContinue
            if (!($GitVersionCMDPackage)) {
                write-verbose "Package $GitVersionCMDPackageName Not Found Locally, Installing..."
                write-verboseheader "Nuget.Org Package Source Info for fetching GitVersion"
                Get-PackageSource | Format-Table | out-string | write-verbose

                #Fetch GitVersion
                $GitVersionCMDPackage = Install-Package $GitVersionCMDPackageName -scope currentuser -source 'nuget.org' -force @PassThruParams
            }
        $GitVersionEXE = ((Get-Package $GitVersionCMDPackageName).source | split-path -Parent) + "\tools\GitVersion.exe"
        #>

    }

    #Calculate the GitVersion
    write-verbose "Executing GitVersion to determine version info"
    $GitVersionOutput = &$GitVersionEXE $BuildRoot

    #Since GitVersion doesn't return error exit codes, we look for error text in the output in the output
    if ($GitVersionOutput -match '^[ERROR|INFO] \[') {throw "An error occured when running GitVersion.exe in $buildRoot"}
    try {
        $SCRIPT:GitVersionInfo = $GitVersionOutput | ConvertFrom-JSON -ErrorAction stop
    } catch {
        throw "There was an error when running GitVersion.exe $buildRoot. The output of the command (if any) follows:"
        $GitVersionOutput
    }

    write-verboseheader "GitVersion Results"
    $GitVersionInfo | format-list | out-string | write-verbose

    $SCRIPT:ProjectBuildVersion = [Version]$GitVersionInfo.MajorMinorPatch
    $SCRIPT:ProjectSemVersion = $GitVersionInfo.fullsemver

    #GA release detection
    if ($BranchName -eq 'master') {
        $Script:IsGARelease = $true
        $Script:ProjectVersion = $ProjectBuildVersion
    } else {
        $SCRIPT:ProjectPreReleaseVersion = $GitVersionInfo.nugetversion
        $SCRIPT:ProjectPreReleaseTag = $ProjectPreReleaseVersion.split('-') | Select-Object -last 1
        $Script:ProjectVersion = $ProjectPreReleaseVersion
    }

    write-build Green "Task $($task.name)` - Calculated Project Version: $ProjectVersion"

    #Tag the release if this is a GA build
    if ($BranchName -match '^(master|releases?[/-])') {
        write-build Green "Task $($task.name)` - In Master/Release branch, adding release tag v$ProjectVersion to this build"
        $SCRIPT:isTagRelease = $true
        if ($BranchName -eq 'master') {
            write-build Green "Task $($task.name)` - In Master branch, marking for General Availability publish"
            [Switch]$SCRIPT:IsGARelease = $true
        }
    }

    #Reset the build dir to the versioned release directory. TODO: This should probably be its own task.
    $SCRIPT:BuildReleasePath = Join-Path $BuildProjectPath $ProjectBuildVersion
    if (-not (Test-Path -pathtype Container $BuildReleasePath)) {New-Item -type Directory $BuildReleasePath | out-null}
    $SCRIPT:BuildReleaseManifest = Join-Path $BuildReleasePath (split-path $env:BHPSModuleManifest -leaf)
    write-build Green "Task $($task.name)` - Using Release Path: $BuildReleasePath"
}

#Copy all powershell module "artifacts" to Build Directory
task CopyFilesToBuildDir {

    #Make sure we are in the project location in case something changed
    Set-Location $buildRoot

    #The file or file paths to copy, excluding the powershell psm1 and psd1 module and manifest files which will be autodetected
    copy-item -Recurse -Path $buildRoot\* -Exclude $BuildFilesToExclude -Destination $BuildReleasePath @PassThruParams
}

#Update the Metadata of the module with the latest version information.
task UpdateMetadata Version,CopyFilesToBuildDir,{
    # Update-ModuleManifest butchers PrivateData, using update-metadata from BuildHelpers instead.
    # Set the Module Version to the calculated Project Build version. Cannot use update-modulemanifest for this because it will complain the version isn't correct (ironic)
    Update-Metadata -Path $buildReleaseManifest -PropertyName ModuleVersion -Value $ProjectBuildVersion

    # This is needed for proper discovery by get-command and Powershell Gallery
    $moduleFunctionsToExport = (Get-ChildItem "$BuildReleasePath\Public" -Filter *.ps1).basename
    if (-not $moduleFunctionsToExport) {
        write-warning "No functions found in the powershell module. Did you define any yet? Create a new one called something like New-MyFunction.ps1 in the Public folder"
    } else {
        Update-Metadata -Path $BuildReleaseManifest -PropertyName FunctionsToExport -Value $moduleFunctionsToExport
    }

    if (-not $IsGARelease) {
        $Script:ProjectVersion = $ProjectPreReleaseVersion

        #Create an empty file in the root directory of the module for easy identification that its not a valid release.
        "This is a prerelease build and not meant for deployment!" > (Join-Path $BuildReleasePath "PRERELEASE-$ProjectVersion")

        #Set the prerelease version in the Manifest File
        Update-Metadata -Path $BuildReleaseManifest -PropertyName PreRelease -value $ProjectPreReleaseTag
    }

    if ($isTagRelease) {
        #Set an email address for the tag commit to work if it isn't already present
        if (-not (git config user.email)) {
            git config user.email "buildtag@$env:ComputerName"
        }

        #Tag the release. This keeps Gitversion performant, as well as provides a master audit trail
        if (-not (git tag -l "v$ProjectVersion")) {
            git tag "v$ProjectVersion" -a -m "Automatic GitVersion Release Tag Generated by Invoke-Build"
        } else {
            write-warning "Tag $ProjectVersion already exists. This is normal if you are running multiple builds on the same commit, otherwise this should not happen."
        }
    }

    # Add Release Notes from current version
    # TODO: Generate Release Notes from GitHub
    #Update-Metadata -Path $env:BHPSModuleManifest -PropertyName ReleaseNotes -Value ("$($env:APPVEYOR_REPO_COMMIT_MESSAGE): $($env:APPVEYOR_REPO_COMMIT_MESSAGE_EXTENDED)")
}

#Pester Testing
task Pester {
    #Find the latest module
    try {
        $moduleManifestCandidatePath = join-path (join-path $BuildProjectPath '*') '*.psd1'
        $moduleManifestCandidates = Get-Item $moduleManifestCandidatePath -ErrorAction stop
        $moduleManifestPath = ($moduleManifestCandidates | Select-Object -last 1).fullname
        $moduleDirectory = Split-Path $moduleManifestPath
    } catch {
        throw "Did not detect any module manifests in $BuildProjectPath. Did you run 'Invoke-Build Build' first?"
    }

    write-verboseheader "Starting Pester Tests..."
    write-build Green "Task $($task.name)` - Testing $moduleDirectory"

    $PesterResultFile = "$env:BHBuildOutput\$env:BHProjectName-TestResults_PS$PSVersion`_$TimeStamp.xml"

    $PesterParams = @{
        Script = @{Path = "Tests"; Parameters = @{ModulePath = (split-path $moduleManifestPath)}}
        OutputFile = $PesterResultFile
        OutputFormat = "NunitXML"
        PassThru = $true
        OutVariable = 'TestResults'
    }

    #If we are in vscode, add the VSCodeMarkers
    if ($host.name -match 'Visual Studio Code') {
        write-verbose "Detected Visual Studio Code, adding test markers"
        $PesterParams.PesterOption = (new-pesteroption -IncludeVSCodeMarker)
    }

    Invoke-Pester @PesterParams | Out-Null

    # In Appveyor? Upload our test results!
    If ($ENV:APPVEYOR) {
        $UploadURL = "https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)"
        write-verbose "Detected we are running in AppVeyor! Uploading Pester Results to $UploadURL"
        (New-Object 'System.Net.WebClient').UploadFile(
            "https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)",
            $PesterResultFile )
    }

    # Failed tests?
    # Need to error out or it will proceed to the deployment. Danger!
    if ($TestResults.failedcount -isnot [int] -or $TestResults.FailedCount -gt 0) {
        Write-Error "Failed '$($TestResults.FailedCount)' tests, build failed"
        $SCRIPT:SkipPublish = $true
    }
    "`n"
}

task Package Version,PreDeploymentChecks,{
    $ZipArchivePath = (join-path $env:BHBuildOutput "$env:BHProjectName-$ProjectVersion.zip")
    write-build Green "Task $($task.name)` - Writing Finished Module to $ZipArchivePath"
    #Package the Powershell Module
    Compress-Archive -Path $BuildProjectPath -DestinationPath $ZipArchivePath -Force @PassThruParams

    $SCRIPT:ArtifactPaths += $ZipArchivePath
    #If we are in Appveyor, push completed zip to Appveyor Artifact
    if ($env:APPVEYOR) {
        write-build Green "Task $($task.name)` - Detected Appveyor, pushing Powershell Module archive to Artifacts"
        Push-AppveyorArtifact $ZipArchivePath
    }
}

task PreDeploymentChecks Test,{
    #Do not proceed if the most recent Pester test is not passing.
    $CurrentErrorActionPreference = $ErrorActionPreference
    try {
        $ErrorActionPreference = "Stop"
        $MostRecentPesterTestResult = [xml]((Get-Content -raw (get-item "$env:BHBuildOutput/*-TestResults*.xml" | Sort-Object lastwritetime | Select-Object -last 1)))
        $MostRecentPesterTestResult = $MostRecentPesterTestResult."test-results"
        if (
            $MostRecentPesterTestResult -isnot [System.XML.XMLElement] -or
            $MostRecentPesterTestResult.errors -gt 0 -or
            $MostRecentPesterTestResult.failures -gt 0
        ) {throw "Fail!"}
    } catch {
        throw "Pester tests failed, or unable to detect a clean passing Pester Test nunit xml file in the $BuildOutput directory. Refusing to publish/deploy until all tests pass."
    }
    finally {
        $ErrorActionPreference = $CurrentErrorActionPreference
    }

    if (($BranchName -match '^(master$|releases?[-/])') -or $ForcePublish) {
        if (-not (Get-Item $BuildReleasePath/*.psd1 -erroraction silentlycontinue)) {throw "No Powershell Module Found in $BuildReleasePath. Skipping deployment. Did you remember to build it first with {Invoke-Build Build}?"}
    } else {
        write-build Magenta "Task $($task.name)` - We are not in master or release branch, skipping publish. If you wish to publish anyways such as for testing, run {InvokeBuild Publish -ForcePublish:$true}"
        $script:SkipPublish=$true
    }
}

task PublishGitHubRelease -if (-not $SkipPublish) Package,{
    if ($SkipPublish) {$SkipGitHubRelease = $true}
    if ($AppVeyor -and -not $GitHubAPIKey) {
        write-build DarkYellow "Task $($task.name)` - Couldn't find GitHubAPIKey in the Appveyor secure environment variables. Did you save your Github API key as an Appveyor Secure Variable? https://docs.microsoft.com/en-us/powershell/gallery/psgallery/creating-and-publishing-an-item and https://github.com/settings/tokens"
        $SkipGitHubRelease = $true
    }
    if (-not $env:GitHubAPIKey) {
        #TODO: Add Windows Credential Store support and some kind of Linux secure storage or caching option
        write-build DarkYellow "Task $($task.name)` - `$env:GitHubAPIKey was not found as an environment variable. Please specify it or use {Invoke-Build publish -GitHubUser `"MyGitHubUser`" -GitHubAPIKey `"MyAPIKeyString`"}. Have you created a GitHub API key with minimum public_repo scope permissions yet? https://github.com/settings/tokens"
        $SkipGitHubRelease = $true
    }
    if (-not $env:GitHubUserName) {
        write-build DarkYellow "Task $($task.name)` - `$env:GitHubUserName was not found as an environment variable. Please specify it or use {Invoke-Build publish -GitHubUser `"MyGitHubUser`" -GitHubAPIKey `"MyAPIKeyString`"}. Have you created a GitHub API key with minimum public_repo scope permissions yet? https://github.com/settings/tokens"
        $SkipGitHubRelease = $true
    }
    if ($SkipGitHubRelease) {
        write-build Magenta "Task $($task.name): Skipping Publish to GitHub Releases"
        continue
    } else {
        #Inspiration from https://www.herebedragons.io/powershell-create-github-release-with-artifact

        #Create the release
        #Currently all releases are draft on publish and must be manually made public on the website or via the API
        $releaseData = @{
            tag_name = [string]::Format("v{0}", $ProjectVersion);
            target_commitish = "master";
            name = [string]::Format("v{0}", $ProjectVersion);
            body = $env:BHCommitMessage;
            draft = $false;
            prerelease = $true;
        }

        #Only master builds are considered GA
        if ($BranchName -eq 'master') {
            $releasedata.prerelease = $false
        }

        if ($GitHubPublishDraft) {$releasedata.draft = $true}

        $auth = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($GitHubApiKey + ":x-oauth-basic"))
        $releaseParams = @{
            Uri = "https://api.github.com/repos/$env:gitHubUserName/$env:BHProjectName/releases"
            Method = 'POST'
            Headers = @{
                Authorization = $auth
            }
            ContentType = 'application/json'
            Body = (ConvertTo-Json $releaseData -Compress)
        }

        $result = Invoke-RestMethod @releaseParams -ErrorAction stop

        $uploadUriBase = $result.upload_url -creplace '\{\?name,label\}'  # Strip the , "?name=$artifact" part

        $uploadParams = @{
            Method = 'POST';
                Headers = @{
                    Authorization = $auth;
                }
            ContentType = 'application/zip';
        }
        foreach ($artifactItem in $artifactPaths) {
            $uploadparams.URI = $uploadUriBase + "?name=$(split-path $artifactItem -leaf)"
            $uploadparams.Infile = $artifactItem
            $result = Invoke-RestMethod @uploadParams -erroraction stop
        }
    }
}

task PublishPSGallery -if (-not $SkipPublish) {
    if ($SkipPublish) {[switch]$SkipPSGallery = $true}
    if ($AppVeyor -and -not $NuGetAPIKey) {
        write-build DarkYellow "Couldn't find NuGetAPIKey in the Appveyor secure environment variables. Did you save your NuGet/Powershell Gallery API key as an Appveyor Secure Variable? https://docs.microsoft.com/en-us/powershell/gallery/psgallery/creating-and-publishing-an-item and https://www.appveyor.com/docs/build-configuration/"
        $SkipPSGallery = $true
    }
    if (-not $NuGetAPIKey) {
        #TODO: Add Windows Credential Store support and some kind of Linux secure storage or caching option
        write-build DarkYellow '$env:NuGetAPIKey was not found as an environment variable. Please specify it or use {Invoke-Build publish -NuGetAPIKey "MyAPIKeyString"}. Have you registered for a Powershell Gallery API key yet? https://docs.microsoft.com/en-us/powershell/gallery/psgallery/creating-and-publishing-an-item'
        $SkipPSGallery = $true
    }

    if ($SkipPSGallery) {
        Write-Build Magenta "Task $($task.name)` - Skipping Powershell Gallery Publish"
        continue
    } else {
        $publishParams = @{
                Path = $BuildReleasePath
                NuGetApiKey = $NuGetAPIKey
                Repository = 'PSGallery'
                Force = $true
                ErrorAction = 'Stop'
                Confirm = $false
        }
        Publish-Module @publishParams @PassThruParams
    }
}

### SuperTasks
# These are the only supported items to run directly from Invoke-Build
task Build Clean,Version,CopyFilesToBuildDir,UpdateMetadata
task Test Pester
task Publish Version,PreDeploymentChecks,Package,PublishGitHubRelease,PublishPSGallery

#Default Task - Build and Test
task . Clean,Build,Test,Package