Engines/Bicep/Invoke-AvmBicepDocs.ps1

function Invoke-AvmBicepDocs {
    <#
    .SYNOPSIS
        Render Bicep module READMEs through the pinned Bicep docs CLI.

    .DESCRIPTION
        Uses the packaged template or a validated nearest-config template.
        Renders all source-backed modules before changing any README;
        source-less READMEs are preserved and reported as not rendered.
        CheckDrift uses packaged Pester 5.5+ requirements to compare LF-normalized
        content without writing module files.
        A private provenance render identifies generated JSON-example comments
        before accepting omitted complete pairs.
        Authored Notes come only from README.notes.md; missing sidecars stop
        generation. IncludeRenderedContent returns generated strings for
        independent, in-memory byte comparisons and requires CheckDrift.
    #>

    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '',
        Justification = 'Noun mirrors the avm CLI verb (avm docs).')]
    [OutputType([pscustomobject])]
    param(
        [Parameter(Mandatory)]
        $Context,

        [switch] $AllowPathFallback,

        [string] $OutputFile = 'README.md',

        [switch] $CheckDrift,

        [switch] $IncludeRenderedContent,

        [switch] $PreparationOnly,

        [AllowEmptyCollection()]
        [object[]] $SelectedScope
    )

    Set-StrictMode -Version 3.0
    $ErrorActionPreference = 'Stop'

    if ($Context.Ecosystem -ne 'bicep') {
        throw [System.ArgumentException]::new(
            "Invoke-AvmBicepDocs requires a bicep context (got Ecosystem='$($Context.Ecosystem)').")
    }
    if ($OutputFile -cne 'README.md') {
        throw [System.ArgumentException]::new(
            'Bicep documentation generates README.md in each module; -OutputFile must be README.md.')
    }
    if ($IncludeRenderedContent -and -not $CheckDrift) {
        throw [System.ArgumentException]::new(
            '-IncludeRenderedContent requires -CheckDrift to prevent accidental README writes.')
    }
    if ($PreparationOnly -and -not $CheckDrift) {
        throw [System.ArgumentException]::new('README validation preparation requires -CheckDrift.')
    }

    $tool = Resolve-AvmTool -Name 'bicep' -ModuleRoot $Context.Root -AllowPathFallback:$AllowPathFallback
    $repositoryRoot = Get-AvmBicepMonorepoRoot -Path $Context.Root
    if (-not $repositoryRoot) {
        $repositoryRoot = $Context.Root
    }
    $scopes = @(if ($PSBoundParameters.ContainsKey('SelectedScope')) { $SelectedScope } else {
            Get-AvmMetadataScope -Context $Context -IncludeModuleDirectories -IncludeReadmeOnly
        })
    $plan = [System.Collections.Generic.List[object]]::new()
    $issues = [System.Collections.Generic.List[object]]::new()
    $changed = [System.Collections.Generic.List[string]]::new()
    $notRendered = [System.Collections.Generic.List[string]]::new()
    $renderedReadmes = [System.Collections.Generic.List[object]]::new()
    $readmeInputs = [System.Collections.Generic.List[object]]::new()
    $validationSummary = $null
    $filesProcessed = 0
    $filesSelected = 0
    $utf8 = [System.Text.UTF8Encoding]::new($false, $true)
    $pathComparer = if ($IsWindows) {
        [System.StringComparer]::OrdinalIgnoreCase
    }
    else { [System.StringComparer]::Ordinal }
    $compiledTemplates = [System.Collections.Generic.Dictionary[string, object]]::new(
        $pathComparer)
    $renderStages = [System.Collections.Generic.Dictionary[string, string]]::new($pathComparer)

    try {
        foreach ($scope in $scopes) {
            $files = @(Get-ChildItem -LiteralPath $scope.Path -Force |
                    Where-Object { $_.Name -ieq 'main.bicep' })
            if ($files.Count -gt 0 -and
                ($files.Count -ne 1 -or $files[0].PSIsContainer -or
                $files[0].Name -cne 'main.bicep' -or
                ($files[0].Attributes -band [System.IO.FileAttributes]::ReparsePoint))) {
                throw [AvmConfigurationException]::new(
                    "Bicep documentation needs a regular main.bicep with exact casing in '$($scope.Path)'.")
            }
            if ($files.Count -eq 0) {
                if (Test-Path -LiteralPath (Join-Path $scope.Path 'README.md')) {
                    $relative = [System.IO.Path]::GetRelativePath(
                        $Context.Root, (Join-Path $scope.Path 'README.md')).Replace('\', '/')
                    $notRendered.Add($relative)
                    $issues.Add([pscustomobject][ordered]@{
                            File     = $relative
                            Line     = 0
                            Column   = 0
                            Severity = 'warning'
                            Code     = 'avm.bicep.docs-no-source'
                            Message  = "'$relative' has no main.bicep; it is preserved but not rendered or compared by Bicep docs."
                        })
                }
                continue
            }

            $docsConfiguration = Get-AvmBicepDocsConfiguration -ModulePath $scope.Path
            $sourcePath = $files[0].FullName
            $target = Join-Path -Path $scope.Path -ChildPath 'README.md'
            $relative = [System.IO.Path]::GetRelativePath($Context.Root, $target).Replace('\', '/')
            $filesSelected++
            try {
                $values = Get-AvmBicepDocsCustomValue -ModulePath $scope.Path `
                    -RepositoryRoot $repositoryRoot -ToolPath $tool.Path `
                    -CompiledTemplateCache $compiledTemplates
            }
            catch [AvmProcessException], [AvmConfigurationException] {
                if (-not $CheckDrift) {
                    throw
                }
                $issues.Add([pscustomobject][ordered]@{
                        File     = $relative
                        Line     = 0
                        Column   = 0
                        Severity = 'error'
                        Code     = 'avm.bicep.docs-render-failed'
                        Message  = "Bicep docs could not prepare '$relative': $($_.Exception.Message)"
                    })
                continue
            }
            try {
                $renderInput = Get-AvmBicepDocsRenderInput -SourcePath $sourcePath -Root $repositoryRoot `
                    -Configuration $docsConfiguration -Stages $renderStages -Confirm:$false -WhatIf:$false
                $result = Invoke-AvmBicepDocsRender -Values $values -SourcePath $renderInput.SourcePath `
                    -ToolPath $tool.Path -WorkingDirectory $renderInput.WorkingDirectory
            }
            catch [AvmProcessException], [AvmConfigurationException] {
                if (-not $CheckDrift) {
                    throw
                }
                $issues.Add([pscustomobject][ordered]@{
                        File     = $relative
                        Line     = 0
                        Column   = 0
                        Severity = 'error'
                        Code     = 'avm.bicep.docs-render-failed'
                        Message  = "Bicep docs could not start for '$relative': $($_.Exception.Message)"
                    })
                continue
            }
            $unmappedExample = $null -ne $result.StdOut -and
            $result.StdOut.Contains('__AVM_DOCS_MISSING_EXAMPLE__:')
            $ambiguousRoles = $null -ne $result.StdOut -and
            $result.StdOut.Contains('__AVM_DOCS_AMBIGUOUS_ROLES__:')
            $missingVariant = $null -ne $result.StdOut -and
            $result.StdOut.Contains('__AVM_DOCS_MISSING_VARIANT__:')
            $invalidExample = [regex]::Match(
                [string]$result.StdOut, '(?m)^__AVM_DOCS_INVALID_EXAMPLE__:(.*)$')
            if ($result.ExitCode -ne 0 -or [string]::IsNullOrWhiteSpace($result.StdOut) -or
                $unmappedExample -or $ambiguousRoles -or $missingVariant -or
                $invalidExample.Success) {
                $message = if ($invalidExample.Success) {
                    "Bicep docs could not render '$relative': $($invalidExample.Groups[1].Value.Trim())"
                }
                elseif ($unmappedExample) {
                    "Bicep docs included an example without a matching source for '$relative'. Check tests/e2e and bicepconfig.json scope reassignments."
                }
                elseif ($ambiguousRoles) {
                    "Bicep docs found conflicting compiled role names for a documented roleAssignments parameter in '$relative'."
                }
                elseif ($missingVariant) {
                    "Bicep docs discriminator variants differ from the compiled Bicep mapping in '$relative'."
                }
                else {
                    Add-AvmProcessFailureDetail `
                        -Message "Bicep docs did not render a README for '$sourcePath' (exit $($result.ExitCode))." `
                        -StdOut $result.StdOut -StdErr $result.StdErr
                }
                if ($CheckDrift) {
                    $issues.Add([pscustomobject][ordered]@{
                            File     = $relative
                            Line     = 0
                            Column   = 0
                            Severity = 'error'
                            Code     = 'avm.bicep.docs-render-failed'
                            Message  = $message
                        })
                    continue
                }
                throw [AvmConfigurationException]::new($message)
            }

            $renderedContent = ([string]$result.StdOut).ReplaceLineEndings("`n")
            $filesProcessed++
            if ($IncludeRenderedContent) {
                $renderedReadmes.Add([pscustomobject]@{
                        Path    = $relative
                        Content = $renderedContent
                    })
            }
            $expected = $utf8.GetBytes($renderedContent)
            $current = if ([System.IO.File]::Exists($target)) {
                , [System.IO.File]::ReadAllBytes($target)
            }
            else {
                $null
            }
            $currentForComparison = $current
            if ($null -ne $current) {
                try {
                    $currentForComparison = $utf8.GetBytes(
                        $utf8.GetString($current).ReplaceLineEndings("`n"))
                }
                catch [System.Text.DecoderFallbackException] {
                    $currentForComparison = $current
                }
            }
            $readmeCase = $null
            if ($CheckDrift) {
                $readmeCase = @{
                    Current                = $currentForComparison
                    Expected               = $expected
                    MissingExampleComments = 0
                }
                $readmeInputs.Add(@{ Case = $readmeCase; IssuePath = $target })
            }
            if ($null -ne $currentForComparison -and
                [System.Linq.Enumerable]::SequenceEqual(
                    [byte[]]$currentForComparison, [byte[]]$expected)) {
                continue
            }
            $missingExampleComments = 0
            if ($CheckDrift -and $null -ne $current) {
                $probe = Get-AvmBicepDocsExampleCommentProbe `
                    -Values $values -GeneratedContent $result.StdOut
                if ($null -ne $probe) {
                    try {
                        $probeResult = Invoke-AvmBicepDocsRender -Values $probe.Values `
                            -SourcePath $renderInput.SourcePath -ToolPath $tool.Path `
                            -WorkingDirectory $renderInput.WorkingDirectory
                    }
                    catch [AvmProcessException] {
                        $issues.Add([pscustomobject][ordered]@{
                                File     = $relative
                                Line     = 0
                                Column   = 0
                                Severity = 'error'
                                Code     = 'avm.bicep.docs-provenance-failed'
                                Message  = "Bicep docs could not verify generated comments in '$relative': $($_.Exception.Message)"
                            })
                        continue
                    }
                    if ($probeResult.ExitCode -ne 0 -or
                        [string]::IsNullOrWhiteSpace($probeResult.StdOut)) {
                        $message = Add-AvmProcessFailureDetail `
                            -Message "Bicep docs provenance render failed for '$relative' (exit $($probeResult.ExitCode))." `
                            -StdOut $probeResult.StdOut -StdErr $probeResult.StdErr
                        $issues.Add([pscustomobject][ordered]@{
                                File     = $relative
                                Line     = 0
                                Column   = 0
                                Severity = 'error'
                                Code     = 'avm.bicep.docs-provenance-failed'
                                Message  = $message
                            })
                        continue
                    }
                    $missingExampleComments = Get-AvmBicepDocsExampleCommentDifferenceCount `
                        -CurrentBytes $currentForComparison -GeneratedContent $renderedContent `
                        -ProbeContent ([string]$probeResult.StdOut).ReplaceLineEndings("`n") `
                        -Markers $probe.Markers
                }
            }
            if ($missingExampleComments -gt 0) {
                $readmeCase.MissingExampleComments = $missingExampleComments
                continue
            }

            if ($CheckDrift) {
                continue
            }

            $original = $null
            if ($null -ne $current) {
                try {
                    $original = $utf8.GetString($current)
                }
                catch [System.Text.DecoderFallbackException] {
                    throw [AvmConfigurationException]::new(
                        "Bicep README must contain valid UTF-8: $target")
                }
            }
            $plan.Add([pscustomobject]@{
                    Path     = $target
                    Original = $original
                    Content  = $renderedContent
                })
            $changed.Add($relative)
        }
    }
    finally {
        foreach ($stage in $renderStages.Values) {
            if ([System.IO.Directory]::Exists($stage)) {
                [System.IO.Directory]::Delete($stage, $true)
            }
        }
    }

    if ($PreparationOnly) {
        return [pscustomobject]@{ ReadmeInputs = $readmeInputs.ToArray(); Issues = $issues.ToArray() }
    }
    if ($CheckDrift -and $readmeInputs.Count -gt 0) {
        $convention = @{
            Root                 = $Context.Root
            ReadmeInputs         = $readmeInputs.ToArray()
            NativeReadmeExpected = -1
        }
        $suite = Join-Path -Path $PSScriptRoot -ChildPath '..' `
            -AdditionalChildPath '..', 'Resources', 'bicep', 'conventions', 'Readme.Tests.ps1'
        $validationSummary = Invoke-AvmBicepPesterSuite -Files @($suite) -WorkingDirectory $Context.Root `
            -Mode Convention -ConventionData $convention -EnvVars @{} -InProcess
        foreach ($issue in @($validationSummary.Issues)) {
            $issuePath = if ([string]::IsNullOrWhiteSpace($issue.File)) { $Context.Root } else { $issue.File }
            $issues.Add((New-AvmBicepConventionIssue -Root $Context.Root -Path $issuePath `
                        -Code $issue.Code -Message $issue.Message -Severity $issue.Severity -Line $issue.Line))
        }
        if ($convention.NativeReadmeExpected -lt $readmeInputs.Count -or
            $validationSummary.Total -ne $convention.NativeReadmeExpected -or
            $validationSummary.Failed -gt @($validationSummary.Issues | Where-Object {
                    $_ -is [System.Collections.IDictionary] -and $_.Contains('NativeConvention') -and $_.NativeConvention
                }).Count -or
            $validationSummary.Passed + $validationSummary.Failed -ne $convention.NativeReadmeExpected) {
            $issues.Add((New-AvmBicepConventionIssue -Root $Context.Root -Path $Context.Root `
                        -Code 'avm.bicep.docs-suite-incomplete' -Message 'The packaged README suite did not execute all intended requirements.'))
        }
    }
    $status = 'pass'
    if (@($issues | Where-Object { $_.Severity -eq 'error' }).Count -gt 0) {
        $status = 'fail'
        $changed.Clear()
    }
    elseif ($plan.Count -gt 0) {
        Test-AvmModuleInitializationPlan -Root $Context.Root -Plan $plan.ToArray()
        if ($PSCmdlet.ShouldProcess(($changed -join ', '), 'Write generated Bicep READMEs')) {
            $null = Write-AvmModuleInitializationPlan -Root $Context.Root -Plan $plan.ToArray() -Confirm:$false
        }
        else {
            $status = 'skipped'
            $changed.Clear()
        }
    }

    return [pscustomobject][ordered]@{
        Engine            = 'bicep'
        Tool              = ('{0}/{1}' -f $tool.Name, $tool.Version)
        ToolPath          = $tool.Path
        ToolSource        = $tool.Source
        Status            = $status
        FilesSelected     = $filesSelected
        FilesProcessed    = $filesProcessed
        NotRendered       = $notRendered.ToArray()
        Changed           = $changed.ToArray()
        Issues            = $issues.ToArray()
        GeneratedReadmes  = $renderedReadmes.ToArray()
        ValidationSummary = $validationSummary
    }
}

# SIG # Begin signature block
# MIInOQYJKoZIhvcNAQcCoIInKjCCJyYCAQExDzANBglghkgBZQMEAgEFADB5Bgor
# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG
# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCD4abgXVIsVHOvp
# 2uB5X0em1izrKTWV602Y/RIYDIdcKaCCDMkwggYEMIID7KADAgECAhMzAAACHPrN
# xZvoL37EAAAAAAIcMA0GCSqGSIb3DQEBCwUAMFcxCzAJBgNVBAYTAlVTMR4wHAYD
# VQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBD
# b2RlIFNpZ25pbmcgUENBIDIwMjQwHhcNMjYwNDE2MTg1OTQxWhcNMjcwNDE1MTg1
# OTQxWjB0MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UE
# BxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYD
# VQQDExVNaWNyb3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IB
# DwAwggEKAoIBAQDVsZfgOKmM31HPfoWOoNEiw0SlCiIxUMC0I9NMWbucKOw/e9lP
# oAoehQVu6SG65V4EPzrYsnBnFPNoi4/HoOdjhz1qkrEt4I6tEcxXU6oOeY9zGveC
# /3iBeuhLYxM3M/PkcUoebF+Nednm8OkdSPoDu8imViHPQq/8CQUu0WRR4rE+dMRf
# rpVqfmNi2qWCX94T4MsepijGVkwE//tJg0ryAiYdHT34LSnlG/RSBZmQRGWZ5g8j
# qnKjRParSqMft1gvjuUTVgtWNZfgcLFSK5Wa0myrq8OPcgTGGsRgun+tnSS+IxDT
# xVsAPH1OzvPjwomguByhUe/OcvUN0D5Wmp7xAgMBAAGjggGqMIIBpjAOBgNVHQ8B
# Af8EBAMCB4AwHwYDVR0lBBgwFgYKKwYBBAGCN0wIAQYIKwYBBQUHAwMwHQYDVR0O
# BBYEFNoH7a2YDjOSwpkp6DHcmUS7J+0yMFQGA1UdEQRNMEukSTBHMS0wKwYDVQQL
# EyRNaWNyb3NvZnQgSXJlbGFuZCBPcGVyYXRpb25zIExpbWl0ZWQxFjAUBgNVBAUT
# DTIzMDAxMis1MDc1NjkwHwYDVR0jBBgwFoAUf1k/VCHarU/vBeXmo9ctBpQSCDEw
# YAYDVR0fBFkwVzBVoFOgUYZPaHR0cDovL3d3dy5taWNyb3NvZnQuY29tL3BraW9w
# cy9jcmwvTWljcm9zb2Z0JTIwQ29kZSUyMFNpZ25pbmclMjBQQ0ElMjAyMDI0LmNy
# bDBtBggrBgEFBQcBAQRhMF8wXQYIKwYBBQUHMAKGUWh0dHA6Ly93d3cubWljcm9z
# b2Z0LmNvbS9wa2lvcHMvY2VydHMvTWljcm9zb2Z0JTIwQ29kZSUyMFNpZ25pbmcl
# MjBQQ0ElMjAyMDI0LmNydDAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEBCwUAA4IC
# AQAUnEqhaRXe0T3hIJjvdQErEkrA/7bByjn6t5IArODkkRjzkYwtKMc2yYj2quaN
# rLutWw2YZcngKPy1b71YyDJQTy4NDRwaSh9Tw5thrk3NmcPrAHia5vtcBJ1CgtKK
# 7mQbIcQ22d/N3813ayCDDFewu1+jsZmX+r/aTEqaOM4TVxVtRSkuCy8nAXKuChOK
# Li/zA4XuH8iEYqIsj2YoNaeSxVmeGiERXpKdo3dDmYi0kO5w2D8VS4c3+9h6gElY
# BaAAg/dYErBg27qT3vv0zRDJhJufvCNylA8S7/+8H5E/PV5cng6na9VV/w9OV3qu
# uND6zdGa2EX38Glp50F9AIQk3p2xXmcvorDeM4XJ7UlWYBi6g80J1SSOQnInCYFE
# msfUNn3+1AaTJKSJL83quKArTac2pKhu0Yzzzrzo6HrsRiQKzpnRBb1/dMa6P3hz
# 75XbMRBctNsFhZC07WCmjExdLg2eHW5uV0TY8D5+6wozJf7vF3+WHkYPO85Z+BC6
# U4FkNbYNycZ9cE4j1tXRdyDCfml6c0HWPHjNVDObrv9lKt3qUqFpX38VCqVCyNOO
# 1UcXfQiVjJw32U2WUKZjt/neJKHEBsm9kFsLuWzkQ53+qcaSaytmsCnk2gOglrlD
# 5d3kKyvvAw+rzm0lT8K38P6PLxfZQHhu4W8dV7Av8N2ZmDCCBr0wggSloAMCAQIC
# EzMAAAA5O7Y3Gb8GHWcAAAAAADkwDQYJKoZIhvcNAQEMBQAwgYgxCzAJBgNVBAYT
# AlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYD
# VQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xMjAwBgNVBAMTKU1pY3Jvc29mdCBS
# b290IENlcnRpZmljYXRlIEF1dGhvcml0eSAyMDExMB4XDTI0MDgwODIwNTQxOFoX
# DTM2MDMyMjIyMTMwNFowVzELMAkGA1UEBhMCVVMxHjAcBgNVBAoTFU1pY3Jvc29m
# dCBDb3Jwb3JhdGlvbjEoMCYGA1UEAxMfTWljcm9zb2Z0IENvZGUgU2lnbmluZyBQ
# Q0EgMjAyNDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANgBnB7jOMeq
# lRYHNa265v4IY9fH8TKhemHfPINe1gpLaV3dhg324WwH06LcHbpnsBukCDNitryo
# 0dtS/EW6I/yEL/bLSY8hKpbfQuWusBPr9qazYcDxCW/qnjb5JsI1s8bNOg3bVATv
# QVL4tcf03aTycsz8QeCdM0l/yHRObJ9QqazM1r6VPEOJ7LL+uEEb73w6QCuhs89a
# 1uv1zerOYMnsneRRwCbpyW11IcggU0cRKDDq1pjVJzIbIF6+oiXXbReOsgeI8zu1
# FyQfK0fVkaya8SmVHQ/tOf23mZ4W9k0Ri22QW9p3UgSC5OUDktKxxcCmGL6tXLfO
# GSWHIIV4YrTJTT6PNty5REojHJuZHArkF9VnHTERWoTjAzfI3kP+5b4alUdhgAZ7
# ttOu1bVnXfHaqPYl2rPs20ji03LOVWsh/radgE17es5hL+t6lV0eVHrVhsssROWJ
# uz2MXMCt7iw7lFPG9LXKGjsmonn2gotGdHIuEg5JnJMJVmixd5LRlkmgYRZKzhxS
# CwyoGIq0PhaA7Y+VPct5pCHkijcIIDm0nlkK+0KyepolcqGm0T/GYQRMhHJlGOOm
# VQop36wUVUYklUy++vDWeEgEo4s7hxN6mIbf2MSIQ/iIfMZgJxC69oukMUXCrOC3
# SkE/xIkgpfl22MM1itkZ35nNXkMolU1lAgMBAAGjggFOMIIBSjAOBgNVHQ8BAf8E
# BAMCAYYwEAYJKwYBBAGCNxUBBAMCAQAwHQYDVR0OBBYEFH9ZP1Qh2q1P7wXl5qPX
# LQaUEggxMBkGCSsGAQQBgjcUAgQMHgoAUwB1AGIAQwBBMA8GA1UdEwEB/wQFMAMB
# Af8wHwYDVR0jBBgwFoAUci06AjGQQ7kUBU7h6qfHMdEjiTQwWgYDVR0fBFMwUTBP
# oE2gS4ZJaHR0cDovL2NybC5taWNyb3NvZnQuY29tL3BraS9jcmwvcHJvZHVjdHMv
# TWljUm9vQ2VyQXV0MjAxMV8yMDExXzAzXzIyLmNybDBeBggrBgEFBQcBAQRSMFAw
# TgYIKwYBBQUHMAKGQmh0dHA6Ly93d3cubWljcm9zb2Z0LmNvbS9wa2kvY2VydHMv
# TWljUm9vQ2VyQXV0MjAxMV8yMDExXzAzXzIyLmNydDANBgkqhkiG9w0BAQwFAAOC
# AgEAFJQfOChP7onn6fLIMKrSlN1WYKwDFgAddymOUO3FrM8d7B/W/iQ6DxXsDn7D
# 5W4wMwYeLystcEqfkjz4NURRgazyMu5yRzQh4LqjA4tStTcJh1opExo7nn5PuPBY
# nbu0+THSuVHTe0VTTPVhily/piFrDo3axQ9P4C+Ol5yet+2gTfekICS5xS+cYfSI
# vgn0JksVBVMYVI5QFu/qhnLhsEFEUzG8fvv0hjgkO+lkpV9ty6GkN4vdnd7ya6Q6
# aR9y34aiM1qmxaxBi6OUnyNl6fkuun/diTFnYDLTppOkr/mg5WSfCiDVMNCxtj4w
# PKC5OmHm1DQIt/MNokbbH3UGsFP1QbzsLocuSqLCvH09Io3fDPTmscR9Y75G4qX7
# RTX8AdBPo0I6OEojf39zuFZt0qOHm65YWQE69cZM2ueE1MB05dNNgHK9gTE7zKvK
# /fg8B2qjW88MT/WF5V5uvZGtqa9FSL2RazArA+rDPuf6JGYz4HpgMZHB4S6szWSK
# YBv0VisCzfxgeU+dquXW9bd0auYlOB58DPcOYKdc3Se94g+xL4pcEhbB54JOgAkw
# YTu/9dLeH2pDqeJZAABVDWRQCaXfO5LgyKwKCLYXpigrZYCjUSBcr+Ve8PFWMhVT
# Ql0v4q8J/AUmQN5W4n101cY2L4A7GTQG1h32HHAvfQESWP0xghnGMIIZwgIBATBu
# MFcxCzAJBgNVBAYTAlVTMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24x
# KDAmBgNVBAMTH01pY3Jvc29mdCBDb2RlIFNpZ25pbmcgUENBIDIwMjQCEzMAAAIc
# +s3Fm+gvfsQAAAAAAhwwDQYJYIZIAWUDBAIBBQCggZAwGQYJKoZIhvcNAQkDMQwG
# CisGAQQBgjcCAQQwLwYJKoZIhvcNAQkEMSIEIOryZFZpUzPSyseaShPmsRF16x6i
# RiO7sZrPuWY+A4UfMEIGCisGAQQBgjcCAQwxNDAyoBSAEgBNAGkAYwByAG8AcwBv
# AGYAdKEagBhodHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20wDQYJKoZIhvcNAQEBBQAE
# ggEAuNB8iicF2mj2iqIrPgqlRtq1Kr7fSrVjiX+YWdOdrSagn1r2/O3sUtKwyGLl
# rP/trd1AbrsyS9hZpMQOjFikAXF/60PmfrTS9sT59HC3RfwRSjjgQCb77R5r/ka8
# l54njJ+J+qGxLOtlU5xPEqMvPReBcx/6z8KTVUfjVg+gFTvSBpW9CRDkJYMMzHHu
# Blp5u8uxQa4gXW9Jb1Y8Sh1C5+18iKF07zKaCMMpeQgF2kxuE5viE+3PzoFcDydJ
# B05dzAYgB0tTwgDz6X96VmdBaveOWEjy6FkDu/S0o18jVSezXv2qIIQufUbwlFqg
# H+MQo1MBUnzSHL0jYK2QAA7h4aGCF5YwgheSBgorBgEEAYI3AwMBMYIXgjCCF34G
# CSqGSIb3DQEHAqCCF28wghdrAgEDMQ8wDQYJYIZIAWUDBAIBBQAwggFSBgsqhkiG
# 9w0BCRABBKCCAUEEggE9MIIBOQIBAQYKKwYBBAGEWQoDATAxMA0GCWCGSAFlAwQC
# AQUABCDo7dd+yinddGky+xOvQseyjKZ0+w8TXyiSEMvMCpuyeAIGavyAI3y4GBMy
# MDI2MTExNzE2NDgzMy44OTlaMASAAgH0oIHRpIHOMIHLMQswCQYDVQQGEwJVUzET
# MBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMV
# TWljcm9zb2Z0IENvcnBvcmF0aW9uMSUwIwYDVQQLExxNaWNyb3NvZnQgQW1lcmlj
# YSBPcGVyYXRpb25zMScwJQYDVQQLEx5uU2hpZWxkIFRTUyBFU046QTkzNS0wM0Uw
# LUQ5NDcxJTAjBgNVBAMTHE1pY3Jvc29mdCBUaW1lLVN0YW1wIFNlcnZpY2WgghHs
# MIIHIDCCBQigAwIBAgITMwAAAifVwIPDsS5XLQABAAACJzANBgkqhkiG9w0BAQsF
# ADB8MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMH
# UmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSYwJAYDVQQD
# Ex1NaWNyb3NvZnQgVGltZS1TdGFtcCBQQ0EgMjAxMDAeFw0yNjAyMTkxOTQwMDRa
# Fw0yNzA1MTcxOTQwMDRaMIHLMQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGlu
# Z3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBv
# cmF0aW9uMSUwIwYDVQQLExxNaWNyb3NvZnQgQW1lcmljYSBPcGVyYXRpb25zMScw
# JQYDVQQLEx5uU2hpZWxkIFRTUyBFU046QTkzNS0wM0UwLUQ5NDcxJTAjBgNVBAMT
# HE1pY3Jvc29mdCBUaW1lLVN0YW1wIFNlcnZpY2UwggIiMA0GCSqGSIb3DQEBAQUA
# A4ICDwAwggIKAoICAQDixWy1fDOSL4qj3A1pady+elIDLwnF3UuLzJIOWwGHcEgr
# xxwtnyviUIDmmxylTUl1u+2rBPp2zT4BwwQhvGaJpExqvPLlDFlbfmSflKI86eFq
# ofiZ7j8NTRO4l7wGg9Njm+muNauTcFW2qdfIjKE950Okrm9MnMOGYy+fibNYdxTP
# RPq1T4MLZK3s3vdMyMEOldcOQkSKpxD6/1Gk6gOmCu2KgI8f0ex6vYxnKDl9W0OL
# SEa/6y82oIbsm+1QBifOQ47xWKTG1CmvtGr85LzA75/MAcUmRw5/of/qET0UFV1W
# ulMcJrI6DASAsNCNB+6WLrotuBZAj+VMlqbn5RMZ6Q4IY7JwaAiIXh7VjxrnwUOY
# ZG8WEGhfrA98di+7LEn9AqvvEOyG+UQcjVhCCbMGXigJXSApeyeWupCsD0jgQMNC
# xfB5BLBDWxgdY3dJBEPgxfkgTDQLBggtVv2d5CYxHKgIItB4bI5eSb5jkIG2Wotn
# FetT0legpw/Eozwf39ao6tENY21eVWIzRw/GsmvwjYQF6vVrxOD0pGVsfqGF8s3V
# PeY7hI2TxHFMqNA0IB/a2NLY7JTxYAKAP/11EJZt7xbqDLMgD1YDdGEzGpQijm3n
# APCL2CebP/jmu90abJ2W425yglGHTI/nCBrwSpfRCgwzrfFelJaCKM6+35aFfwID
# AQABo4IBSTCCAUUwHQYDVR0OBBYEFNLW58N4MGSG6ud7jWqgT92orfReMB8GA1Ud
# IwQYMBaAFJ+nFV0AXmJdg/Tl0mWnG1M1GelyMF8GA1UdHwRYMFYwVKBSoFCGTmh0
# dHA6Ly93d3cubWljcm9zb2Z0LmNvbS9wa2lvcHMvY3JsL01pY3Jvc29mdCUyMFRp
# bWUtU3RhbXAlMjBQQ0ElMjAyMDEwKDEpLmNybDBsBggrBgEFBQcBAQRgMF4wXAYI
# KwYBBQUHMAKGUGh0dHA6Ly93d3cubWljcm9zb2Z0LmNvbS9wa2lvcHMvY2VydHMv
# TWljcm9zb2Z0JTIwVGltZS1TdGFtcCUyMFBDQSUyMDIwMTAoMSkuY3J0MAwGA1Ud
# EwEB/wQCMAAwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwgwDgYDVR0PAQH/BAQDAgeA
# MA0GCSqGSIb3DQEBCwUAA4ICAQAqncud4PSC1teb2H6nRuy7sDiKK13FXJirVB4T
# fwjdo2Mb+QL4j7wZ/k4G9P0CANHZFrDQcK0VFDTysrYu8Z0Aha14acDZPsyIoPvA
# GRRhaHEuf7NckRjkfa/ylo1KyII8jbL9N9sJAqBPL8V4FNBjljv+1GHDOw127rZz
# 5ZSTPoAPb2SA0v5yDgcpUMfxglPyp6cnPPoQpTtD9OGx8Dwm2P+o1TPxBIy6I0T9
# RauulogVCvKwflfeLTcKAvnSG1rCjerSXmU1DNXOsAD/bsrSjgbX5mAbD7XTRMF/
# vawAWESFcn/BjjizxeWZb00aYSlkJA2rVtFlMM481aVWXdAbXPP5RzUiWTlgyHf/
# G7lCxHYWGIZuB13T3aI6Y8mEgn/ou40aiFJo8r0+i0P5GdNneWtxiR0CMKUfko+5
# s/73cwe1Wfp8BKXa270cicVQasFf5sRV7pFm+V7fNRXwCu7anTOmga76zO7/2t+z
# OlibvphT+Q6Zd+B2qYsSn4xBaY+YzHpnycLW5cvJyhPxBCcb1oRYfhRzCADb2utI
# 2EtGCjc2P2ii4LyR4QMb/n8cOweL9IqVTKKzzVk+zZJxV3vrp4LyuQXw0O30la6B
# cHdNAAAB9UC83zs3G9d+AlIfZLM97tMUNKWjbBpIirFx6LTDFXVtZQd7hqzLYByj
# bjH0ujCCB3EwggVZoAMCAQICEzMAAAAVxedrngKbSZkAAAAAABUwDQYJKoZIhvcN
# AQELBQAwgYgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYD
# VQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xMjAw
# BgNVBAMTKU1pY3Jvc29mdCBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eSAyMDEw
# MB4XDTIxMDkzMDE4MjIyNVoXDTMwMDkzMDE4MzIyNVowfDELMAkGA1UEBhMCVVMx
# EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoT
# FU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUt
# U3RhbXAgUENBIDIwMTAwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDk
# 4aZM57RyIQt5osvXJHm9DtWC0/3unAcH0qlsTnXIyjVX9gF/bErg4r25PhdgM/9c
# T8dm95VTcVrifkpa/rg2Z4VGIwy1jRPPdzLAEBjoYH1qUoNEt6aORmsHFPPFdvWG
# UNzBRMhxXFExN6AKOG6N7dcP2CZTfDlhAnrEqv1yaa8dq6z2Nr41JmTamDu6Gnsz
# rYBbfowQHJ1S/rboYiXcag/PXfT+jlPP1uyFVk3v3byNpOORj7I5LFGc6XBpDco2
# LXCOMcg1KL3jtIckw+DJj361VI/c+gVVmG1oO5pGve2krnopN6zL64NF50ZuyjLV
# wIYwXE8s4mKyzbnijYjklqwBSru+cakXW2dg3viSkR4dPf0gz3N9QZpGdc3EXzTd
# EonW/aUgfX782Z5F37ZyL9t9X4C626p+Nuw2TPYrbqgSUei/BQOj0XOmTTd0lBw0
# gg/wEPK3Rxjtp+iZfD9M269ewvPV2HM9Q07BMzlMjgK8QmguEOqEUUbi0b1qGFph
# AXPKZ6Je1yh2AuIzGHLXpyDwwvoSCtdjbwzJNmSLW6CmgyFdXzB0kZSU2LlQ+QuJ
# YfM2BjUYhEfb3BvR/bLUHMVr9lxSUV0S2yW6r1AFemzFER1y7435UsSFF5PAPBXb
# GjfHCBUYP3irRbb1Hode2o+eFnJpxq57t7c+auIurQIDAQABo4IB3TCCAdkwEgYJ
# KwYBBAGCNxUBBAUCAwEAATAjBgkrBgEEAYI3FQIEFgQUKqdS/mTEmr6CkTxGNSnP
# EP8vBO4wHQYDVR0OBBYEFJ+nFV0AXmJdg/Tl0mWnG1M1GelyMFwGA1UdIARVMFMw
# UQYMKwYBBAGCN0yDfQEBMEEwPwYIKwYBBQUHAgEWM2h0dHA6Ly93d3cubWljcm9z
# b2Z0LmNvbS9wa2lvcHMvRG9jcy9SZXBvc2l0b3J5Lmh0bTATBgNVHSUEDDAKBggr
# BgEFBQcDCDAZBgkrBgEEAYI3FAIEDB4KAFMAdQBiAEMAQTALBgNVHQ8EBAMCAYYw
# DwYDVR0TAQH/BAUwAwEB/zAfBgNVHSMEGDAWgBTV9lbLj+iiXGJo0T2UkFvXzpoY
# xDBWBgNVHR8ETzBNMEugSaBHhkVodHRwOi8vY3JsLm1pY3Jvc29mdC5jb20vcGtp
# L2NybC9wcm9kdWN0cy9NaWNSb29DZXJBdXRfMjAxMC0wNi0yMy5jcmwwWgYIKwYB
# BQUHAQEETjBMMEoGCCsGAQUFBzAChj5odHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20v
# cGtpL2NlcnRzL01pY1Jvb0NlckF1dF8yMDEwLTA2LTIzLmNydDANBgkqhkiG9w0B
# AQsFAAOCAgEAnVV9/Cqt4SwfZwExJFvhnnJL/Klv6lwUtj5OR2R4sQaTlz0xM7U5
# 18JxNj/aZGx80HU5bbsPMeTCj/ts0aGUGCLu6WZnOlNN3Zi6th542DYunKmCVgAD
# sAW+iehp4LoJ7nvfam++Kctu2D9IdQHZGN5tggz1bSNU5HhTdSRXud2f8449xvNo
# 32X2pFaq95W2KFUn0CS9QKC/GbYSEhFdPSfgQJY4rPf5KYnDvBewVIVCs/wMnosZ
# iefwC2qBwoEZQhlSdYo2wh3DYXMuLGt7bj8sCXgU6ZGyqVvfSaN0DLzskYDSPeZK
# PmY7T7uG+jIa2Zb0j/aRAfbOxnT99kxybxCrdTDFNLB62FD+CljdQDzHVG2dY3RI
# LLFORy3BFARxv2T5JL5zbcqOCb2zAVdJVGTZc9d/HltEAY5aGZFrDZ+kKNxnGSgk
# ujhLmm77IVRrakURR6nxt67I6IleT53S0Ex2tVdUCbFpAUR+fKFhbHP+CrvsQWY9
# af3LwUFJfn6Tvsv4O+S3Fb+0zj6lMVGEvL8CwYKiexcdFYmNcP7ntdAoGokLjzba
# ukz5m/8K6TT4JDVnK+ANuOaMmdbhIurwJ0I9JZTmdHRbatGePu1+oDEzfbzL6Xu/
# OHBE0ZDxyKs6ijoIYn/ZcGNTTY3ugm2lBRDBcQZqELQdVTNYs6FwZvKhggNPMIIC
# NwIBATCB+aGB0aSBzjCByzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0
# b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3Jh
# dGlvbjElMCMGA1UECxMcTWljcm9zb2Z0IEFtZXJpY2EgT3BlcmF0aW9uczEnMCUG
# A1UECxMeblNoaWVsZCBUU1MgRVNOOkE5MzUtMDNFMC1EOTQ3MSUwIwYDVQQDExxN
# aWNyb3NvZnQgVGltZS1TdGFtcCBTZXJ2aWNloiMKAQEwBwYFKw4DAhoDFQAjHzqt
# hPwO0GDckDMA6x54lIiMKqCBgzCBgKR+MHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
# EwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3Nv
# ZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBD
# QSAyMDEwMA0GCSqGSIb3DQEBCwUAAgUA7qb+pjAiGA8yMDI2MTExNzE2MjYxNFoY
# DzIwMjYxMTE4MTYyNjE0WjB2MDwGCisGAQQBhFkKBAExLjAsMAoCBQDupv6mAgEA
# MAkCAQACAUgCAf8wBwIBAAICEewwCgIFAO6oUCYCAQAwNgYKKwYBBAGEWQoEAjEo
# MCYwDAYKKwYBBAGEWQoDAqAKMAgCAQACAwehIKEKMAgCAQACAwGGoDANBgkqhkiG
# 9w0BAQsFAAOCAQEAi8rSVxbHPwRciyuWdYKfUoN8YhjkPRzGLIbB//xHjobQMkRl
# 5egXZaobDd4uX/vmn1i9czDKQ0wOQIVfenBd+mlRC94G13uI4lpgHTFDDc3LvzKo
# Mfpd1OxpT7APWNfUDK4eKgXKy7xo2VGRMgZ8SBKJOZdPMmRGpssC84aUFv13vcks
# QAQVvPaZ7z65BxX5uALTmhGYdI7wcQHUnFagPmxqFiVZTd1lEQnAKygmrypN0Xzo
# +WrqzAvC52ea2PRqgtWBbUjAO69s3msN4qjTCfI1fS0A+bSDDY08wEDVHWtoMBV5
# f2aa66UqZ4iNZHd5OGTQZFMH7WVloelqDCkELjGCBA0wggQJAgEBMIGTMHwxCzAJ
# BgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25k
# MR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jv
# c29mdCBUaW1lLVN0YW1wIFBDQSAyMDEwAhMzAAACJ9XAg8OxLlctAAEAAAInMA0G
# CWCGSAFlAwQCAQUAoIIBSjAaBgkqhkiG9w0BCQMxDQYLKoZIhvcNAQkQAQQwLwYJ
# KoZIhvcNAQkEMSIEIK2mqwCCA+X59xvAjClGAPu3b8v6mLHrMO4fs+vb6biZMIH6
# BgsqhkiG9w0BCRACLzGB6jCB5zCB5DCBvQQg5ecBGjWhUhw4skoOqUTRp2r+Nn1N
# d2WddZFxcZOEEXIwgZgwgYCkfjB8MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2Fz
# aGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENv
# cnBvcmF0aW9uMSYwJAYDVQQDEx1NaWNyb3NvZnQgVGltZS1TdGFtcCBQQ0EgMjAx
# MAITMwAAAifVwIPDsS5XLQABAAACJzAiBCDasJO+Q8k9nxgqFBL1nWSDggX4YBk6
# KFD55OrP9+fYGTANBgkqhkiG9w0BAQsFAASCAgCS/uhj9WFpuQFGqXlSD5nZBUE/
# Bp1OWG4fXKov5okaedXxOyEOaHQ5J7NMEMjDk/oG+BY6hvaK3M87HVCXMVapdi44
# 5LAtZVEDrgmti4CG+bo4lcYh5xm5msCayLrMZLlnjsq1Hp8dR1dJpjSuYYy6b0TX
# Vx/B2SSi1XaaUHjI5dHRJgr16F1TWQvVfNsqt7F8DqvIRdGQzFmgJN3kudMvxn2z
# rQ60iZ3ttQ1ONNuIMkPx7FaS7IAIzl3a8o/00o02TeOE6VoLgQhiAXZCd+qFeYkd
# hV5J2t72x9BKcTV49dwqV0nInran3xRQTR0pjIajc60c8hIjcsMMcC+Hv+mFozYC
# KxK/ExkUcSStgu/AT55MwgZ9/sCpNU2T/KDMoJy9feCvTvbptmckSnXi8rPS3nUd
# WecOmib42EULtLw/Y9vRHKr6bsw3rDKPqPB+sU7AqAYoHT/lBctPICfyNevF6b0x
# /IXbqSlLGdc7oZWMvLOOfJLugK/f0e/9kYxPFeAdKBlz8tGMl71FdOpmK7qRjS5a
# qbK7Fgox6VhnpAJoZJFVijAMGnB0KwUoFQCSnglH4d0cZIIf2ejbuID76qxACzw9
# ++aiiXH/nnX7N6Y23CrrnznYZ91X4mTSqaYgIJ5SlnmzLshaxfqsIm/2Y67TYPDn
# tXTmEinqaRbh7XCKTA==
# SIG # End signature block