Indented.Build.psm1

function GetBuildSystem {
    [OutputType([String])]
    param ( )

    if ($env:APPVEYOR -eq $true) { return 'AppVeyor' }
    if ($env:JENKINS_URL)        { return 'Jenkins' }

    return 'Desktop'
}

function Add-PesterTemplate {
    <#
    .SYNOPSIS
        Add a pester template file for each function or class in the module.
    .DESCRIPTION
        Add a pester template file for each function or class in the module.
 
        Adds new files only.
    #>


    [CmdletBinding()]
    param (
        # BuildInfo is used to determine the source path.
        [Parameter(ValueFromPipeline)]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject]$BuildInfo = (Get-BuildInfo)
    )

    begin {
        $header = @(
            '#region:TestFileHeader'
            'param ('
            ' [Boolean]$UseExisting'
            ')'
            ''
            'if (-not $UseExisting) {'
            ' $moduleBase = $psscriptroot.Substring(0, $psscriptroot.IndexOf("\test"))'
            ' $stubBase = Resolve-Path (Join-Path $moduleBase "test*\stub\*")'
            ' if ($null -ne $stubBase) {'
            ' $stubBase | Import-Module -Force'
            ' }'
            ''
            ' Import-Module $moduleBase -Force'
            '}'
            '#endregion'
        ) -join ([Environment]::NewLine)
    }

    process {
        $testPath = Join-Path $buildInfo.Path.Source.Module 'test*'
        if (Test-Path $testPath) {
            $testPath = Resolve-Path $testPath
        } else {
            $testPath = (New-Item (Join-Path $buildInfo.Path.Source.Module 'test') -ItemType Directory).FullName
        }

        foreach ($file in $buildInfo | Get-BuildItem -Type ShouldMerge) {
            $relativePath = $file.FullName -replace ([Regex]::Escape($buildInfo.Path.Source.Module)) -replace '^\\' -replace '\.ps1$'
            $fileTestPath = Join-Path $testPath ('{0}.tests.ps1' -f $relativePath)

            $script = [System.Text.StringBuilder]::new()
            if (-not (Test-Path $fileTestPath)) {
                $null = $script.AppendLine($header).
                                AppendLine().
                                AppendFormat('InModuleScope {0} {{', $buildInfo.ModuleName).AppendLine()

                foreach ($function in $file | Get-FunctionInfo) {
                    $null = $script.AppendFormat(' Describe {0} -Tag CI {{', $function.Name).AppendLine().
                                    AppendLine(' }').
                                    AppendLine()
                }

                $null = $script.AppendLine('}')

                $parent = Split-Path $fileTestPath -Parent
                if (-not (Test-Path $parent)) {
                    $null = New-Item $parent -ItemType Directory -Force
                }
                Set-Content -Path $fileTestPath -Value $script.ToString().Trim()
            }
        }
    }
}

function BuildTask {
    <#
    .SYNOPSIS
        Create a build task object.
    .DESCRIPTION
        A build task is a predefined task used to build well-structured PowerShell projects.
    #>


    [CmdletBinding()]
    [OutputType('Indented.BuildTask')]
    param (
        # The name of the task.
        [Parameter(Mandatory)]
        [String]$Name,

        # The stage during which the task will be invoked.
        [Parameter(Mandatory)]
        [String]$Stage,

        # Where the task should appear in the build order respective to the stage.
        [Int32]$Order = 1024,

        # The task will only be invoked if the filter condition is true.
        [ScriptBlock]$If = { $true },

        # The task implementation.
        [Parameter(Mandatory)]
        [ScriptBlock]$Definition
    )

    [PSCustomObject]@{
        Name       = $Name
        Stage      = $Stage
        If         = $If
        Order      = $Order
        Definition = $Definition
        PSTypeName = 'Indented.BuildTask'
    }
}

function Convert-CodeCoverage {
    <#
    .SYNOPSIS
        Converts code coverage line and file reference from root module to file.
    .DESCRIPTION
        When tests are executed against a merged module, all lines are relative to the psm1 file.
 
        This command updates line references to match the development file set.
    #>


    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position = 1, ValueFromPipelineByPropertyName)]
        [PSObject]$CodeCoverage,

        [Parameter(Mandatory)]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject]$BuildInfo
    )

    begin {
        $module = $buildInfo.Path.Build.RootModule |
            Get-FunctionInfo |
            Group-Object Name -AsHashTable

        $functions = $BuildInfo |
            Get-BuildItem -Type ShouldMerge |
            Get-FunctionInfo |
            Group-Object Name -AsHashTable
    }

    process {
        foreach ($category in 'MissedCommands', 'HitCommands') {
            foreach ($command in $CodeCoverage.$category) {
                $command.File = $functions[$command.Function].Extent.File

                $command.StartLine = $command.Line = $command.StartLine -
                                     $module[$command.Function].Extent.StartLineNumber +
                                     $functions[$command.Function].Extent.StartLineNumber

                $command.EndLine = $command.EndLine -
                                   $module[$command.Function].Extent.StartLineNumber +
                                   $functions[$command.Function].Extent.StartLineNumber
            }
        }
    }
}

function ConvertTo-ChocoPackage {
    <#
    .SYNOPSIS
        Convert a PowerShell module into a chocolatey package.
    .DESCRIPTION
        Convert a PowerShell module into a chocolatey package.
    .EXAMPLE
        Find-Module pester | ConvertTo-ChocoPackage
 
        Find the module pester on a PS repository and convert the module to a chocolatey package.
    .EXAMPLE
        Get-Module SqlServer -ListAvailable | ConvertTo-ChocoPackage
 
        Get the installed module SqlServer and convert the module to a chocolatey package.
    .EXAMPLE
        Find-Module VMware.PowerCli | ConvertTo-ChocoPackage
 
        Find the module VMware.PowerCli on a PS repository and convert the module, and all dependencies, to chocolatey packages.
    #>


    [CmdletBinding()]
    param (
        # The module to package.
        [Parameter(Mandatory, ValueFromPipeline)]
        [ValidateScript( {
            if ($_ -is [System.Management.Automation.PSModuleInfo] -or
                $_ -is [Microsoft.PackageManagement.Packaging.SoftwareIdentity] -or
                $_.PSTypeNames[0] -eq 'Microsoft.PowerShell.Commands.PSRepositoryItemInfo') {


                $true
            } else {
                throw 'InputObject must be a PSModuleInfo, SoftwareIdentity, or PSRepositoryItemInfo object.'
            }
        } )]
        [Object]$InputObject,

        # Write the generated nupkg file to the specified folder.
        [String]$Path = '.',

        # A temporary directory used to stage the choco package content before packing.
        [String]$CacheDirectory = (Join-Path $env:TEMP (New-Guid))
    )

    begin {
        $Path = $pscmdlet.GetUnresolvedProviderPathFromPSPath($Path)

        try {
            $null = New-Item $CacheDirectory -ItemType Directory
        } catch {
            $pscmdlet.ThrowTerminatingError($_)
        }
    }

    process {
        try {
            $erroractionpreference = 'Stop'

            $packagePath = Join-Path $CacheDirectory $InputObject.Name.ToLower()
            $toolsPath = New-Item (Join-Path $packagePath 'tools') -ItemType Directory

            switch ($InputObject) {
                { $_ -is [System.Management.Automation.PSModuleInfo] } {
                    Write-Verbose ('Building {0} from PSModuleInfo' -f $InputObject.Name)

                    $dependencies = $InputObject.RequiredModules

                    $null = $psboundparameters.Remove('InputObject')
                    # Package dependencies as well
                    foreach ($dependency in $dependencies) {
                        Get-Module $dependency.Name -ListAvailable |
                            Where-Object Version -eq $dependency.Version |
                            ConvertTo-ChocoPackage @psboundparameters
                    }

                    if ((Split-Path $InputObject.ModuleBase -Leaf) -eq $InputObject.Version) {
                        $destination = New-Item (Join-Path $toolsPath $InputObject.Name) -ItemType Directory
                    } else {
                        $destination = $toolsPath
                    }

                    Copy-Item $InputObject.ModuleBase -Destination $destination -Recurse

                    break
                }
                { $_ -is [Microsoft.PackageManagement.Packaging.SoftwareIdentity] } {
                    Write-Verbose ('Building {0} from SoftwareIdentity' -f $InputObject.Name)

                    $dependencies = $InputObject.Dependencies |
                        Select-Object @{n='Name';e={ $_ -replace 'powershellget:|/.+$' }},
                                      @{n='Version';e={ $_ -replace '^.+?/|#.+$' }}

                    [Xml]$swidTagText = $InputObject.SwidTagText

                    $InputObject = [PSCustomObject]@{
                        Name        = $InputObject.Name
                        Version     = $InputObject.Version
                        Author      = $InputObject.Entities.Where{ $_.Role -eq 'author' }.Name
                        Copyright   = $swidTagText.SoftwareIdentity.Meta.copyright
                        Description = $swidTagText.SoftwareIdentity.Meta.summary
                    }

                    if ((Split-Path $swidTagText.SoftwareIdentity.Meta.InstalledLocation -Leaf) -eq $InputObject.Version) {
                        $destination = New-Item (Join-Path $toolsPath $InputObject.Name) -ItemType Directory
                    } else {
                        $destination = $toolsPath
                    }

                    Copy-Item $swidTagText.SoftwareIdentity.Meta.InstalledLocation -Destination $destination -Recurse

                    break
                }
                { $_.PSTypeNames[0] -eq 'Microsoft.PowerShell.Commands.PSRepositoryItemInfo' } {
                    Write-Verbose ('Building {0} from PSRepositoryItemInfo' -f $InputObject.Name)

                    $dependencies = $InputObject.Dependencies |
                        Select-Object @{n='Name';e={ $_['Name'] }}, @{n='Version';e={ $_['MinimumVersion'] }}

                    $null = $psboundparameters.Remove('InputObject')
                    $params = @{
                        Name            = $InputObject.Name
                        RequiredVersion = $InputObject.Version
                        Source          = $InputObject.Repository
                        ProviderName    = 'PowerShellGet'
                        Path            = New-Item (Join-Path $CacheDirectory 'savedPackages') -ItemType Directory -Force
                    }
                    Save-Package @params | ConvertTo-ChocoPackage @psboundparameters

                    # The current module will be last in the chain. Prevent packaging of this iteration.
                    $InputObject = $null

                    break
                }
            }

            if ($InputObject) {
                # Inject chocolateyInstall.ps1
                $install = @(
                    'Get-ChildItem $psscriptroot -Directory |'
                    ' Copy-Item -Destination "C:\Program Files\WindowsPowerShell\Modules" -Recurse -Force'
                ) | Out-String
                Set-Content (Join-Path $toolsPath 'chocolateyInstall.ps1') -Value $install

                # Inject chocolateyUninstall.ps1
                $uninstall = @(
                    'Get-Module {0} -ListAvailable |'
                    ' Where-Object {{ $_.Version -eq "{1}" -and $_.ModuleBase -match "Program Files\\WindowsPowerShell\\Modules" }} |'
                    ' Select-Object -ExpandProperty ModuleBase |'
                    ' Remove-Item -Recurse -Force'
                ) | Out-String
                $uninstall = $uninstall -f $InputObject.Name,
                                           $InputObject.Version
                Set-Content (Join-Path $toolsPath 'chocolateyUninstall.ps1') -Value $uninstall

                # Inject nuspec
                $nuspecPath = Join-Path $packagePath ('{0}.nuspec' -f $InputObject.Name)
                $nuspec = @(
                    '<?xml version="1.0" encoding="utf-8"?>'
                    '<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">'
                    ' <metadata>'
                    ' <version>{0}</version>'
                    ' <title>{1}</title>'
                    ' <authors>{2}</authors>'
                    ' <copyright>{3}</copyright>'
                    ' <id>{1}</id>'
                    ' <summary>{1} PowerShell module</summary>'
                    ' <description>{4}</description>'
                    ' </metadata>'
                    '</package>'
                ) | Out-String
                $nuspec = [Xml]($nuspec -f @(
                    $InputObject.Version,
                    $InputObject.Name,
                    $InputObject.Author,
                    $InputObject.Copyright,
                    $InputObject.Description
                ))
                if ($dependencies) {
                    $fragment = [System.Text.StringBuilder]::new('<dependencies>')

                    $null = foreach ($dependency in $dependencies) {
                        $fragment.AppendFormat('<dependency id="{0}"', $dependency.Name)
                        if ($dependency.Version) {
                            $fragment.AppendFormat(' version="{0}"', $dependency.Version)
                        }
                        $fragment.Append(' />').AppendLine()
                    }

                    $null = $fragment.AppendLine('</dependencies>')

                    $xmlFragment = $nuspec.CreateDocumentFragment()
                    $xmlFragment.InnerXml = $fragment.ToString()

                    $null = $nuspec.package.metadata.AppendChild($xmlFragment)
                }
                $nuspec.Save($nuspecPath)

                choco pack $nuspecPath --out=$Path
            }
        } catch {
            Write-Error -ErrorRecord $_
        } finally {
            Remove-Item $packagePath -Recurse -Force
        }
    }

    end {
        Remove-Item $CacheDirectory -Recurse -Force
    }
}

function Enable-Metadata {
    <#
    .SYNOPSIS
        Enable a metadata property which has been commented out.
    .DESCRIPTION
        This function is derived Get and Update-Metadata from PoshCode\Configuration.
 
        A boolean value is returned indicating if the property is available in the metadata file.
 
        If the property does not exist, or exists more than once within the specified file this command will return false.
    .INPUTS
        System.String
    .EXAMPLE
        Enable-Metadata .\module.psd1 -PropertyName RequiredAssemblies
 
        Enable an existing (commented) RequiredAssemblies property within the module.psd1 file.
    #>


    [CmdletBinding()]
    [OutputType([Boolean])]
    param (
        # A valid metadata file or string containing the metadata.
        [Parameter(ValueFromPipelineByPropertyName, Position = 0)]
        [ValidateScript( { Test-Path $_ -PathType Leaf } )]
        [Alias("PSPath")]
        [String]$Path,

        # The property to enable.
        [String]$PropertyName
    )

    process {
        # If the element can be found using Get-Metadata leave it alone and return true
        $shouldEnable = $false
        try {
            $null = Get-Metadata @psboundparameters -ErrorAction Stop
        } catch [System.Management.Automation.ItemNotFoundException] {
            # The function will only execute where the requested value is not present
            $shouldEnable = $true
        } catch {
            # Ignore other errors which may be raised by Get-Metadata except path not found.
            if ($_.Exception.Message -eq 'Path must point to a .psd1 file') {
                $pscmdlet.ThrowTerminatingError($_)
            }
        }
        if (-not $shouldEnable) {
            return $true
        }

        $manifestContent = Get-Content $Path -Raw

        $tokens = $parseErrors = $null
        $ast = [System.Management.Automation.Language.Parser]::ParseInput(
            $manifestContent,
            $Path,
            [Ref]$tokens,
            [Ref]$parseErrors
        )

        # Attempt to find a comment which matches the requested property
        $regex = '^ *# *({0}) *=' -f $PropertyName
        $existingValue = @($tokens | Where-Object { $_.Kind -eq 'Comment' -and $_.Text -match $regex })
        if ($existingValue.Count -eq 1) {
            $manifestContent = $ast.Extent.Text.Remove(
                $existingValue.Extent.StartOffset,
                $existingValue.Extent.EndOffset - $existingValue.Extent.StartOffset
            ).Insert(
                $existingValue.Extent.StartOffset,
                $existingValue.Extent.Text -replace '^# *'
            )

            try {
                Set-Content -Path $Path -Value $manifestContent -NoNewline -ErrorAction Stop
                $true
            } catch {
                $false
            }
        } elseif ($existingValue.Count -eq 0) {
            # Item not found
            Write-Warning "Cannot find disabled property '$PropertyName' in $Path"
            $false
        } else {
            # Ambiguous match
            Write-Warning "Found more than one '$PropertyName' in $Path"
            $false
        }
    }
}

function Export-BuildScript {
    <#
    .SYNOPSIS
        Export a build script for use with Invoke-Build.
    .DESCRIPTION
        Export a build script for use with Invoke-Build.
    .INPUTS
        BuildInfo (from Get-BuildInfo)
    #>


    [CmdletBinding()]
    [OutputType([String])]
    param (
        # The build information object is used to determine which tasks are applicable.
        [Parameter(ValueFromPipeline)]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject]$BuildInfo = (Get-BuildInfo),

        # By default the build system is automatically discovered. The BuildSystem parameter overrides any automatically discovered value. Tasks associated with the build system are added to the generated script.
        [String]$BuildSystem,

        # The build script will be written to the the specified path.
        [String]$Path = '.build.ps1'
    )

    if ($BuildSystem) {
        $BuildInfo.BuildSystem = $BuildSystem
    }

    $script = [System.Text.StringBuilder]::new()
    $null = $script.AppendLine('param (').
                    AppendLine(' [String]$ModuleName,').
                    AppendLine().
                    AppendLine(' [PSTypeName("Indented.BuildInfo")]').
                    AppendLine(' [ValidateCount(1, 1)]').
                    AppendLine(' [PSObject[]]$BuildInfo').
                    AppendLine(')').
                    AppendLine()

    $tasks = $BuildInfo | Get-BuildTask | Sort-Object {
        switch ($_.Stage) {
            'Setup'   { 1; break }
            'Build'   { 2; break }
            'Test'    { 3; break }
            'Pack'    { 4; break }
            'Publish' { 5; break }
        }
    }, Order, Name

    # Build the wrapper tasks and insert the block at the top of the script
    $taskSets = [System.Text.StringBuilder]::new()
    $taskStages = ($tasks | Group-Object Stage -NoElement).Name

    # Add a default task set
    $null = $taskSets.AppendFormat('task default {0},', $taskStages[0]).AppendLine()
    for ($i = 1; $i -lt $taskStages.Count; $i++) {
        $null = $taskSets.AppendFormat(
            ' {0}{1}',
            $taskStages[$i],
            @(',', '')[$i -eq $taskStages.Count - 1]
        ).AppendLine()
    }
    $null = $taskSets.AppendLine()

    $tasks | Group-Object Stage | ForEach-Object {
        $indentLength = 'task '.Length + $_.Name.Length
        $null = $taskSets.AppendFormat('task {0} {1}', $_.Name, $_.Group[0].Name)
        foreach ($task in $_.Group | Select-Object -Skip 1) {
            $null = $taskSets.Append(',').
                              AppendLine().
                              AppendFormat('{0} {1}', (' ' * $indentLength), $task.Name)
        }
        $null = $taskSets.AppendLine().
                          AppendLine()
    }
    $null = $script.Append($taskSets.ToString())

    # Add supporting functions to create the BuildInfo object.
    (Get-Command Get-BuildInfo).ScriptBlock.Ast.FindAll(
        {
            param ( $ast )

            $ast -is [System.Management.Automation.Language.CommandAst]
        },
        $true
    ) | ForEach-Object GetCommandName |
        Select-Object -Unique |
        Sort-Object |
        ForEach-Object {
            $commandInfo = Get-Command $_

            if ($commandInfo.Source -eq $myinvocation.MyCommand.ModuleName) {
                $null = $script.AppendFormat('function {0} {{', $commandInfo.Name).
                                Append($commandInfo.Definition).
                                AppendLine('}').
                                AppendLine()
            }
        }

    'Convert-CodeCoverage', 'ConvertTo-ChocoPackage', 'Enable-Metadata', 'Get-BuildInfo', 'Get-BuildItem', 'Get-FunctionInfo', 'Get-LevenshteinDistance' | ForEach-Object {
        $null = $script.AppendFormat('function {0} {{', $_).
                        Append((Get-Command $_).Definition).
                        AppendLine('}').
                        AppendLine()
    }

    # Add a generic task which allows BuildInfo to be retrieved
    $null = $script.AppendLine('task GetBuildInfo {').
                    AppendLine(' Get-BuildInfo').
                    AppendLine('}').
                    AppendLine()

    # Add a task that allows all all build jobs within the current project to run
    $null = $script.AppendLine('task BuildAll {').
                    AppendLine(' [String[]]$task = ${*}.Task.Name').
                    AppendLine().
                    AppendLine(' # Re-submit the build request without the BuildAll task').
                    AppendLine(' if ($task.Count -eq 1 -and $task[0] -eq "BuildAll") {').
                    AppendLine(' $task = "default"').
                    AppendLine(' } else {').
                    AppendLine(' $task = $task -ne "BuildAll"').
                    AppendLine(' }').
                    AppendLine().
                    AppendLine(' Get-BuildInfo | ForEach-Object {').
                    AppendLine(' Write-Host').
                    AppendLine(' "Building {0} ({1})" -f $_.ModuleName, $_.Version | Write-Host -ForegroundColor Green').
                    AppendLine(' Write-Host').
                    AppendLine(' Invoke-Build -BuildInfo $_ -Task $task').
                    AppendLine(' }').
                    AppendLine('}').
                    AppendLine()

    $tasks | ForEach-Object {
        $null = $script.AppendFormat('task {0}', $_.Name)
        if ($_.If -and $_.If.ToString().Trim() -ne '$true') {
            $null = $script.AppendLine(' -If (').
                            AppendLine($_.If.ToString().Trim()).
                            Append(')')
        }
        $null = $script.AppendLine(' {').
                        AppendLine($_.Definition.ToString().Trim("`r`n")).
                        AppendLine('}').
                        AppendLine()
    }

    $script.ToString() | Set-Content $Path
}

function Get-BuildInfo {
    <#
    .SYNOPSIS
        Get properties required to build the project.
    .DESCRIPTION
        Get the properties required to build the project, or elements of the project.
    .EXAMPLE
        Get-BuildInfo
 
        Get build information for the current or any child directories.
    #>


    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')]
    [CmdletBinding()]
    [OutputType('Indented.BuildInfo')]
    param (
        [String]$ModuleName = '*',

        # Generate build information for the specified path.
        [ValidateScript( { Test-Path $_ -PathType Container } )]
        [String]$ProjectRoot = $pwd.Path
    )

    $ProjectRoot = $pscmdlet.GetUnresolvedProviderPathFromPSPath($ProjectRoot)
    Get-ChildItem $ProjectRoot\*\*.psd1 | Where-Object {
        ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
        ($moduleManifest = Test-ModuleManifest $_.FullName -ErrorAction SilentlyContinue)
    } | ForEach-Object {
        $configOverridePath = Join-Path $_.Directory.FullName 'buildConfig.psd1'
        if (Test-Path $configOverridePath) {
            $config = Import-PowerShellDataFile $configOverridePath
        } else {
            $config = @{}
        }

        try {
            [PSCustomObject]@{
                ModuleName  = $moduleName = $_.BaseName
                Version     = $version = $moduleManifest.Version
                Config      = [PSCustomObject]@{
                    CodeCoverageThreshold = (0.8, $config.CodeCoverageThreshold)[$null -ne $config.CodeCoverageThreshold]
                    EndOfLineChar         = ([Environment]::NewLine, $config.EndOfLineChar)[$null -ne $config.EndOfLineChar]
                    License               = ('MIT', $config.License)[$null -ne $config.License]
                    CreateChocoPackage    = ($false, $config.CreateChocoPackage)[$null -ne $config.CreateChocoPackage]
                }
                Path        = [PSCustomObject]@{
                    ProjectRoot = $ProjectRoot
                    Source      = [PSCustomObject]@{
                        Module   = $_.Directory
                        Manifest = $_
                    }
                    Build       = [PSCustomObject]@{
                        Module     = $module = [System.IO.DirectoryInfo][System.IO.Path]::Combine($ProjectRoot, 'build', $moduleName, $version)
                        Manifest   = [System.IO.FileInfo](Join-Path $module ('{0}.psd1' -f $moduleName))
                        RootModule = [System.IO.FileInfo](Join-Path $module ('{0}.psm1' -f $moduleName))
                        Output     = [System.IO.DirectoryInfo][System.IO.Path]::Combine($ProjectRoot, 'build\output', $moduleName)
                        Package    = [System.IO.DirectoryInfo][System.IO.Path]::Combine($ProjectRoot, 'build\packages')
                    }
                }
                BuildSystem = GetBuildSystem
                PSTypeName  = 'Indented.BuildInfo'
            }
        } catch {
            Write-Error -ErrorRecord $_
        }
    } | Where-Object ModuleName -like $ModuleName
}

function Get-BuildItem {
    <#
    .SYNOPSIS
        Get source items.
    .DESCRIPTION
        Get items from the source tree which will be consumed by the build process.
 
        This function centralises the logic required to enumerate files and folders within a project.
    #>


    [CmdletBinding()]
    [OutputType([System.IO.FileInfo], [System.IO.DirectoryInfo])]
    param (
        # Gets items by type.
        #
        # ShouldMerge - *.ps1 files from enum*, class*, priv*, pub* and InitializeModule if present.
        # Static - Files which are not within a well known top-level folder. Captures help content in en-US, format files, configuration files, etc.
        [Parameter(Mandatory)]
        [ValidateSet('ShouldMerge', 'Static')]
        [String]$Type,

        # BuildInfo is used to determine the source path.
        [Parameter(Mandatory, ValueFromPipeline)]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject]$BuildInfo,

        # Exclude script files containing PowerShell classes.
        [Switch]$ExcludeClass
    )

    try {
        Push-Location $buildInfo.Path.Source.Module

        $itemTypes = [Ordered]@{
            enumeration    = 'enum*'
            class          = 'class*'
            private        = 'priv*'
            public         = 'pub*'
            initialisation = 'InitializeModule.ps1'
        }

        if ($Type -eq 'ShouldMerge') {
            foreach ($itemType in $itemTypes.Keys) {
                if ($itemType -ne 'class' -or ($itemType -eq 'class' -and -not $ExcludeClass)) {
                    Get-ChildItem $itemTypes[$itemType] -Recurse -ErrorAction SilentlyContinue |
                        Where-Object { -not $_.PSIsContainer -and $_.Extension -eq '.ps1' -and $_.Length -gt 0 } |
                        Add-Member -NotePropertyName 'BuildItemType' -NotePropertyValue $itemType -PassThru
                }
            }
        } elseif ($Type -eq 'Static') {
            [String[]]$exclude = $itemTypes.Values + '*.config', 'test*', 'doc*', 'help', '.build*.ps1', 'build.psd1'

            foreach ($item in Get-ChildItem) {
                $shouldExclude = $false

                foreach ($exclusion in $exclude) {
                    if ($item.Name -like $exclusion) {
                        $shouldExclude = $true
                    }
                }

                if (-not $shouldExclude) {
                    $item
                }
            }
        }
    } catch {
        $pscmdlet.ThrowTerminatingError($_)
    } finally {
        Pop-Location
    }
}

function Get-BuildTask {
    <#
    .SYNOPSIS
        Get build tasks.
    .DESCRIPTION
        Get the build tasks deemed to be applicable to this build.
 
        If the ListAvailable parameter is supplied, all available tasks will be returned.
    #>


    [CmdletBinding(DefaultParameterSetName = 'ForBuild')]
    [OutputType('BuildTask')]
    param (
        # A build information object used to determine which tasks will apply to the current build.
        [Parameter(Mandatory, Position = 1, ValueFromPipeline, ParameterSetName = 'ForBuild')]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject]$BuildInfo,

        # Filter tasks by task name.
        [String]$Name = '*',

        # List all available tasks, irrespective of conditions applied to the task.
        [Parameter(Mandatory, ParameterSetName = 'List')]
        [Switch]$ListAvailable
    )

    begin {
        if (-not $Name.EndsWith('.ps1') -and -not $Name.EndsWith('*')) {
            $Name += '.ps1'
        }
        $path = Join-Path $myinvocation.MyCommand.Module.ModuleBase 'task'

        if (-not $Script:buildTaskCache) {
            $Script:buildTaskCache = @{}
            Get-ChildItem $path -File -Filter *.ps1 -Recurse | ForEach-Object {
                $task = . $_.FullName
                $Script:buildTaskCache.Add($task.Name, $task)
            }
        }
    }

    process {
        if ($buildInfo) {
            Push-Location $buildInfo.Path.Source.Module
        }

        try {
            $Script:buildTaskCache.Values | Where-Object {
                Write-Verbose ('Evaluating {0}' -f $_.Name)

                $_.Name -like $Name -and ($ListAvailable -or (& $_.If))
            }
        } catch {
            Write-Error -Message ('Failed to evaluate task condition: {0}' -f $_.Exception.Message) -ErrorId 'ConditionEvaluationFailed'
        }

        if ($buildInfo) {
            Pop-Location
        }
    }
}

function Get-FunctionInfo {
    <#
    .SYNOPSIS
        Get an instance of FunctionInfo.
    .DESCRIPTION
        FunctionInfo does not present a public constructor. This function calls an internal / private constructor on FunctionInfo to create a description of a function from a script block or file containing one or more functions.
    .EXAMPLE
        Get-ChildItem -Filter *.psm1 | Get-FunctionInfo
 
        Get all functions declared within the *.psm1 file and construct FunctionInfo.
    .EXAMPLE
        Get-ChildItem C:\Scripts -Filter *.ps1 -Recurse | Get-FunctionInfo
 
        Get all functions declared in all ps1 files in C:\Scripts.
    #>


    [CmdletBinding(DefaultParameterSetName = 'FromPath')]
    [OutputType([System.Management.Automation.FunctionInfo])]
    param (
        # The path to a file containing one or more functions.
        [Parameter(Position = 1, ValueFromPipeline, ValueFromPipelineByPropertyName, ParameterSetName = 'FromPath')]
        [Alias('FullName')]
        [String]$Path,

        # A script block containing one or more functions.
        [Parameter(ParameterSetName = 'FromScriptBlock')]
        [ScriptBlock]$ScriptBlock,

        # By default functions nested inside other functions are ignored. Setting this parameter will allow nested functions to be discovered.
        [Switch]$IncludeNested
    )

    begin {
        $executionContextType = [PowerShell].Assembly.GetType('System.Management.Automation.ExecutionContext')
        $constructor = [System.Management.Automation.FunctionInfo].GetConstructor(
            [System.Reflection.BindingFlags]'NonPublic, Instance',
            $null,
            [System.Reflection.CallingConventions]'Standard, HasThis',
            ([String], [ScriptBlock], $executionContextType),
            $null
        )
    }

    process {
        if ($pscmdlet.ParameterSetName -eq 'FromPath') {
            $Path = $pscmdlet.GetUnresolvedProviderPathFromPSPath($Path)

            try {
                $tokens = $errors = @()
                $ast = [System.Management.Automation.Language.Parser]::ParseFile(
                    $Path,
                    [Ref]$tokens,
                    [Ref]$errors
                )
                if ($errors[0].ErrorId -eq 'FileReadError') {
                    throw [InvalidOperationException]::new($errors[0].Message)
                }
            } catch {
                $errorRecord = @{
                    Exception = $_.Exception.GetBaseException()
                    ErrorId   = 'AstParserFailed'
                    Category  = 'OperationStopped'
                }
                Write-Error @ErrorRecord
            }
        } else {
            $ast = $ScriptBlock.Ast
        }

        $ast.FindAll( {
                param( $childAst )

                $childAst -is [System.Management.Automation.Language.FunctionDefinitionAst]
            },
            $IncludeNested
        ) | ForEach-Object {
            try {
                $internalScriptBlock = $_.Body.GetScriptBlock()
            } catch {
                Write-Debug $_.Exception.Message
            }
            if ($internalScriptBlock) {
                $extent = $_.Extent | Select-Object File, StartLineNumber, EndLineNumber

                $constructor.Invoke(([String]$_.Name, $internalScriptBlock, $null)) |
                    Add-Member -NotePropertyName Extent -NotePropertyValue $extent -PassThru
            }
        }
    }
}

function Get-LevenshteinDistance {
    <#
    .SYNOPSIS
        Get the Levenshtein distance between two strings.
    .DESCRIPTION
        The Levenshtein distance represents the number of changes required to change one string into another. This algorithm can be used to test for typing errors.
 
        This command makes use of the Fastenshtein library.
 
        Credit for this algorithm goes to Dan Harltey. Converted to PowerShell from https://github.com/DanHarltey/Fastenshtein/blob/master/src/Fastenshtein/StaticLevenshtein.cs.
    #>


    [CmdletBinding()]
    param (
        # The reference string.
        [Parameter(Mandatory)]
        [String]$ReferenceString,

        # The different string.
        [Parameter(Mandatory, ValueFromPipeline)]
        [AllowEmptyString()]
        [String]$DifferenceString
    )

    process {
        if ($DifferenceString.Length -eq 0) {
            return [PSCustomObject]@{
                ReferenceString  = $ReferenceString
                DifferenceString = $DifferenceString
                Distance         = $ReferenceString.Length
            }
        }

        $costs = [Int[]]::new($DifferenceString.Length)

        for ($i = 0; $i -lt $costs.Count; $i++) {
            $costs[$i] = $i + 1
        }

        for ($i = 0; $i -lt $ReferenceString.Length; $i++) {
            $cost = $i
            $additionCost = $i

            $value1Char = $ReferenceString[$i]

            for ($j = 0; $j -lt $DifferenceString.Length; $j++) {
                $insertionCost = $cost
                $cost = $additionCost

                $additionCost = $costs[$j]

                if ($value1Char -ne $DifferenceString[$j]) {
                    if ($insertionCost -lt $cost) {
                        $cost = $insertionCost
                    }
                    if ($additionCost -lt $cost) {
                        $cost = $additionCost
                    }

                    ++$cost
                }

                $costs[$j] = $cost
            }
        }

        [PSCustomObject]@{
            ReferenceString  = $ReferenceString
            DifferenceString = $DifferenceString
            Distance         = $costs[$costs.Count - 1]
        }
    }
}

function New-ConfigDocument {
    <#
    .SYNOPSIS
        Create a new build configuration document
    .DESCRIPTION
        The build configuration document may be used to adjust the configurable build values for a single module.
 
        This file is optional, without it the following default values will be used:
 
          - CodeCoverageThreshold: 0.8 (80%)
          - EndOfLineChar: [Environment]::NewLine
          - License: MIT
          - CreateChocoPackage: $false
    #>


    [CmdletBinding(SupportsShouldProcess)]
    param (
        # BuildInfo is used to determine the source path.
        [Parameter(ValueFromPipeline)]
        [PSTypeName('Indented.BuildInfo')]
        $BuildInfo = (Get-BuildInfo)
    )

    process {
        $documentPath = Join-Path $BuildInfo.Path.Source.Module 'buildConfig.psd1'

        $eolChar = switch -Regex ([Environment]::NewLine) {
            '\r\n' { '`r`n'; break }
            '\n'   { '`n'; break }
            '\r'   { '`r'; break }
        }

        # Build configuration for Indented.Build
        @(
            '@{'
            ' CodeCoverageThreshold = 0.8'
            (' EndOfLineChar = "{0}"' -f $eolChar)
            " License = 'MIT'"
            ' CreateChocoPackage = $false'
            '}'
        ) | Set-Content -Path $documentPath
    }
}

function Start-Build {
    <#
    .SYNOPSIS
        Start a build.
    .DESCRIPTION
        Start a build using Invoke-Build. If a build script is not present one will be created.
 
        If a build script exists it will be used. If the build script exists this command is superfluous.
    #>


    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingCmdletAliases', '')]
    [CmdletBinding()]
    param (
        # The task categories to execute.
        [String[]]$BuildType = ('Setup', 'Build', 'Test'),

        [Parameter(ValueFromPipeline)]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject[]]$BuildInfo = (Get-BuildInfo),

        [String]$ScriptName = '.build.ps1'
    )

    foreach ($instance in $BuildInfo) {
        try {
            # If a build script exists in the project root, use it.
            $buildScript = Join-Path $instance.Path.ProjectRoot $ScriptName

            # Remove the script if it is created by this process. Export-BuildScript can be used to create a persistent script.
            $shouldClean = $false
            if (-not (Test-Path $buildScript)) {
                $instance | Export-BuildScript -Path $buildScript
                $shouldClean = $true
            }

            Import-Module InvokeBuild -Global
            Invoke-Build -Task $BuildType -File $buildScript -BuildInfo $instance
        } catch {
            throw
        } finally {
            if ($shouldClean) {
                Remove-Item $buildScript
            }
        }
    }
}

function Update-DevRootModule {
    <#
    .SYNOPSIS
        Update a dev root module which dot-sources all module content.
    .DESCRIPTION
        Create or update a root module file which loads module content using dot-sourcing.
 
        All content which should would normally be merged is added to a psm1 file. All other module content, such as required assebmlies, is ignored.
    #>


    [CmdletBinding(SupportsShouldProcess)]
    param (
        # BuildInfo is used to determine the source path.
        [Parameter(ValueFromPipeline)]
        [PSTypeName('Indented.BuildInfo')]
        [PSObject]$BuildInfo = (Get-BuildInfo)
    )

    process {
        $script = [System.Text.StringBuilder]::new()

        $groupedItems = $buildInfo |
            Get-BuildItem -Type ShouldMerge |
            Where-Object BaseName -ne 'InitializeModule' |
            Group-Object BuildItemType

        $null = foreach ($group in $groupedItems) {
            $script.AppendFormat('${0} = @(', $group.Name).AppendLine()
            foreach ($file in $group.Group) {
                $relativePath = $file.FullName -replace ([Regex]::Escape($buildInfo.Path.Source.Module)) -replace '^\\' -replace '\.ps1$'
                $groupTypePath, $relativePath = $relativePath -split '\\', 2

                $script.AppendFormat(" '{0}'", $relativePath).AppendLine()
            }
            $script.AppendLine(')').AppendLine()

            $script.AppendFormat('foreach ($file in ${0}) {{', $group.Name).AppendLine().
                    AppendFormat(' . ("{{0}}\{0}\{{1}}.ps1" -f $psscriptroot, $file)', $groupTypePath).AppendLine().
                    AppendLine('}').
                    AppendLine()


            if ($group.Name -eq 'public') {
                $script.AppendLine('$functionsToExport = @(')

                foreach ($function in $group.Group | Get-FunctionInfo) {
                    $script.AppendFormat(" '{0}'", $function.Name).AppendLine()
                }

                $script.AppendLine(')')
                $script.AppendLine('Export-ModuleMember -Function $functionsToExport').AppendLine()
            }
        }

        $initializeScriptPath = Join-Path $buildInfo.Path.Source.Module.FullName 'InitializeModule.ps1'
        if (Test-Path $initializeScriptPath) {
            $null = $script.AppendLine('. ("{0}\InitializeModule.ps1" -f $psscriptroot)').
                            AppendLine('InitializeModule')
        }

        $rootModulePath = Join-Path $buildInfo.Path.Source.Module ('{0}.psm1' -f $buildInfo.ModuleName)
        Set-Content -Path $rootModulePath -Value $script.ToString()
    }
}

function InitializeModule {
    # Fill the build task cache. This makes the module immune to source file deletion once the cache is filled (when building itself).
    $null = Get-BuildTask -ListAvailable
}

InitializeModule