Engines/Terraform/Invoke-AvmTerraformDocs.ps1

function Get-AvmTerraformDocsConfig {
    <#
    .SYNOPSIS
        Return the terraform-docs config file in a directory, or '' if none.

    .DESCRIPTION
        Looks for the conventional AVM terraform-docs config (`.terraform-docs.yml`
        then `.terraform-docs.yaml`) directly inside the given directory. Returns
        the absolute path to the first match, or an empty string when the directory
        is missing or carries no config. Co-located private helper for
        Invoke-AvmTerraformDocs.
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory)]
        [AllowEmptyString()]
        [string] $Directory
    )

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

    if (-not $Directory -or -not (Test-Path -LiteralPath $Directory -PathType Container)) {
        return ''
    }

    foreach ($name in @('.terraform-docs.yml', '.terraform-docs.yaml')) {
        $candidate = Join-Path $Directory $name
        if (Test-Path -LiteralPath $candidate -PathType Leaf) {
            return (Resolve-Path -LiteralPath $candidate).Path
        }
    }

    return ''
}

function Get-AvmTerraformDocsChildModule {
    <#
    .SYNOPSIS
        Return immediate subdirectories that contain at least one .tf file.

    .DESCRIPTION
        Used to enumerate the per-example (`examples/<name>`) and per-submodule
        (`modules/<name>`) directories that terraform-docs should document, the
        same way the upstream pre-commit porch config runs terraform-docs across
        root + each example + each submodule. Subdirectories with no Terraform
        source are skipped (e.g. a bare `examples/` holding only a shared
        `.terraform-docs.yml`). Results are sorted by name for deterministic
        ordering. Co-located private helper for Invoke-AvmTerraformDocs.
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory)]
        [string] $Parent
    )

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

    if (-not (Test-Path -LiteralPath $Parent -PathType Container)) {
        return
    }

    Get-ChildItem -LiteralPath $Parent -Directory -Force |
        Sort-Object -Property Name |
        ForEach-Object {
            $hasTf = @(Get-ChildItem -LiteralPath $_.FullName -Filter '*.tf' -File -Force).Count -gt 0
            if ($hasTf) { $_.FullName }
        }
}

function Invoke-AvmTerraformDocs {
    <#
    .SYNOPSIS
        Generate or inject README documentation via terraform-docs.

    .DESCRIPTION
        Engine implementation called by Invoke-AvmDocs when the module
        context is Ecosystem='terraform'. Resolves the 'terraform-docs'
        binary via Resolve-AvmTool, then runs terraform-docs against the
        module root and - mirroring the upstream pre-commit porch config -
        each `examples/<name>` and `modules/<name>` subdirectory.

        When a directory carries the conventional AVM terraform-docs config
        (`.terraform-docs.yml` / `.terraform-docs.yaml`) the engine honours it:

            terraform-docs --config <config> <module-path>

        The config drives the AVM 'markdown document' formatter, the
        header/footer injection (`_header.md` / `_footer.md`) and the
        `output.file` / `output.mode` (replace) behaviour. terraform-docs
        resolves `output.file`, `header-from`, `footer-from` and any
        `{{ include }}` paths relative to the positional module path, so a
        single shared `examples/.terraform-docs.yml` documents every example
        subdirectory. The examples config lives one level up from each example,
        so it is applied with the example directory as the positional argument.

        When a directory has no config the engine falls back to the previous
        behaviour:

            terraform-docs markdown table --output-file README.md --output-mode inject .

        The module's README.md must contain the marker block
        (BEGIN_TF_DOCS / END_TF_DOCS) for inject/replace mode to work.

        terraform-docs exit codes:
          0 - success
          others - tool error, surfaced as AvmProcessException.

        Drift mode (-CheckDrift, used by pr-check): terraform-docs has no
        dry-run for inject/replace mode, so generation still runs and any
        README it rewrote becomes a Status='fail' Issue. The generated content
        is then rolled back, so drift mode leaves the working copy
        byte-identical. The contract is "a module that already ran pre-commit
        has an up-to-date README"; a non-empty change set in CI therefore means
        the author did not regenerate the docs.

    .PARAMETER Context
        Module context produced by Get-AvmModuleContext. Must have
        Ecosystem='terraform'.

    .PARAMETER AllowPathFallback
        Pass through to Resolve-AvmTool.

    .PARAMETER OutputFile
        README path (relative to each module root) to generate. Defaults
        to 'README.md'.

    .PARAMETER CheckDrift
        When set, treat any README terraform-docs rewrote as a failure
        (Status='fail' with one Issue per file) instead of a silent
        regeneration. Used by the pr-check chain.

    .OUTPUTS
        pscustomobject with Engine, Tool, ToolPath, ToolSource, Status,
        FilesProcessed, Changed, Issues.
    #>

    [CmdletBinding()]
    [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
    )

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

    if ($Context.Ecosystem -ne 'terraform') {
        throw [System.ArgumentException]::new(
            "Invoke-AvmTerraformDocs requires a terraform context (got Ecosystem='$($Context.Ecosystem)').")
    }

    $tool = Resolve-AvmTool -Name 'terraform-docs' -ModuleRoot $Context.Root -AllowPathFallback:$AllowPathFallback
    $root = $Context.Root

    # Build the ordered list of documentation targets: the module root first,
    # then every example and submodule that carries Terraform source. Each
    # target records the directory to hash for drift, the config to honour (or
    # '' for the legacy table fallback) and the positional path passed to
    # terraform-docs (relative to $root so the invocation matches upstream).
    $targets = [System.Collections.Generic.List[pscustomobject]]::new()

    $targets.Add([pscustomobject]@{
            Dir    = $root
            Config = (Get-AvmTerraformDocsConfig -Directory $root)
        })

    foreach ($group in @('examples', 'modules')) {
        $parent = Join-Path $root $group
        $groupConfig = Get-AvmTerraformDocsConfig -Directory $parent
        if (-not $groupConfig) { continue }

        foreach ($childDir in @(Get-AvmTerraformDocsChildModule -Parent $parent)) {
            $targets.Add([pscustomobject]@{
                    Dir    = $childDir
                    Config = $groupConfig
                })
        }
    }
    Write-AvmLog ("docs: discovered {0} documentation target(s)" -f $targets.Count) -Level Verbose | Out-Null

    $changed = [System.Collections.Generic.List[string]]::new()

    # Drift mode must not mutate the caller's working copy, but terraform-docs
    # has no dry-run for inject/replace mode. Snapshot every README up front and
    # restore it in the finally, so generation still runs (and still reports
    # drift) while the tree is left byte-identical even if the tool throws.
    $snapshot = $null
    if ($CheckDrift) {
        Write-AvmLog ("docs: check-drift mode; snapshotting {0} output file(s)" -f $targets.Count) -Level Verbose | Out-Null
        $snapshot = Get-AvmFileSnapshot -Path @($targets | ForEach-Object { Join-Path $_.Dir $OutputFile })
    }

    try {
        foreach ($target in $targets) {
            $readmePath = Join-Path $target.Dir $OutputFile
            $beforeHash = if (Test-Path -LiteralPath $readmePath) {
                (Get-FileHash -LiteralPath $readmePath -Algorithm SHA256).Hash
            }
            else {
                ''
            }

            $positional = [System.IO.Path]::GetRelativePath($root, $target.Dir)

            if ($target.Config) {
                $configArg = [System.IO.Path]::GetRelativePath($root, $target.Config)
                $argumentList = @('--config', $configArg, $positional)
                Write-AvmLog ("docs: target {0} uses config {1}" -f $positional, $configArg) -Level Verbose | Out-Null
            }
            else {
                $argumentList = @('markdown', 'table', '--output-file', $OutputFile, '--output-mode', 'inject', $positional)
                Write-AvmLog ("docs: target {0} uses legacy table fallback" -f $positional) -Level Verbose | Out-Null
            }

            $result = Invoke-AvmProcess `
                -FilePath $tool.Path `
                -ArgumentList $argumentList `
                -WorkingDirectory $root `
                -IgnoreExitCode

            if ($result.ExitCode -ne 0) {
                $message = Add-AvmProcessFailureDetail `
                    -Message ('terraform-docs exited with code {0} for {1}.' -f $result.ExitCode, $positional) `
                    -StdOut $result.StdOut `
                    -StdErr $result.StdErr
                throw [AvmProcessException]::new(
                    $message)
            }

            $afterHash = if (Test-Path -LiteralPath $readmePath) {
                (Get-FileHash -LiteralPath $readmePath -Algorithm SHA256).Hash
            }
            else {
                ''
            }

            if ($beforeHash -ne $afterHash) {
                $relative = [System.IO.Path]::GetRelativePath($root, $readmePath).Replace('\', '/')
                $changed.Add($relative)
                Write-AvmLog ("docs: changed {0}" -f $relative) -Level Verbose | Out-Null
            }
            else {
                Write-AvmLog ("docs: unchanged {0}" -f ([System.IO.Path]::GetRelativePath($root, $readmePath).Replace('\', '/'))) -Level Verbose | Out-Null
            }
        }
    }
    finally {
        if ($null -ne $snapshot) {
            Write-AvmLog 'docs: restoring output snapshot after drift check' -Level Verbose | Out-Null
            Restore-AvmFileSnapshot -Snapshot $snapshot
        }
    }

    $status = 'pass'
    $issues = New-Object System.Collections.Generic.List[object]
    if ($CheckDrift -and $changed.Count -gt 0) {
        $status = 'fail'
        foreach ($rel in $changed) {
            $issues.Add([pscustomobject][ordered]@{
                    File     = $rel
                    Line     = 0
                    Column   = 0
                    Severity = 'error'
                    Code     = 'avm.tf.docs-drift'
                    Message  = ("'{0}' is out of date; run 'avm docs' and commit the result." -f $rel)
                })
        }
        Write-AvmLog ("docs: completed; targets={0}; changed={1}; status={2}" -f $targets.Count, $changed.Count, $status) -Level Verbose | Out-Null
    }

    return [pscustomobject][ordered]@{
        Engine         = 'terraform'
        Tool           = ('{0}/{1}' -f $tool.Name, $tool.Version)
        ToolPath       = $tool.Path
        ToolSource     = $tool.Source
        Status         = $status
        FilesProcessed = $targets.Count
        Changed        = [string[]]$changed.ToArray()
        Issues         = $issues.ToArray()
    }
}

# SIG # Begin signature block
# MIInJgYJKoZIhvcNAQcCoIInFzCCJxMCAQExDzANBglghkgBZQMEAgEFADB5Bgor
# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG
# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCB6R9RGlzbz05EH
# 7HoqCV7sH3qUVU6T0p1598HznJgnkKCCDLowggX1MIID3aADAgECAhMzAAACHU0Z
# yE7XD1dIAAAAAAIdMA0GCSqGSIb3DQEBCwUAMFcxCzAJBgNVBAYTAlVTMR4wHAYD
# VQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBD
# b2RlIFNpZ25pbmcgUENBIDIwMjQwHhcNMjYwNDE2MTg1OTQzWhcNMjcwNDE1MTg1
# OTQzWjB0MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UE
# BxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYD
# VQQDExVNaWNyb3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IB
# DwAwggEKAoIBAQDQvewXxx9gZZFC6Ys1WBay8BJ8kGA4JQnH5CMafqOASlTpK9H8
# o5ZXTXt0caVQTNMUPt445wXYD+dFtaKWTwDn1I52oUSrC9vJin1Gsqt+zyKJL5Dg
# 3eQXbQNR61DmMy20GLTIO3SFed9Rfi/ophgCLGFLDR3r0KvHjwMb/jYWS0celV/4
# Lz27LfAekm8v9E5IXaeiXbAUYZKK090n4CVl3JBtbN+9DtI9SNu/yjvozW52/u7R
# X/Ttpa/KDlpuokZ+Zcbvmtd9ur9gFLvZzh41o9MsE/clQtdaFWGvuo6Jua/ntpgk
# ey3E5/vBFe+MJPG6phdnuo6r57ZudCudiI1bAgMBAAGjggGbMIIBlzAOBgNVHQ8B
# Af8EBAMCB4AwHwYDVR0lBBgwFgYKKwYBBAGCN0wIAQYIKwYBBQUHAwMwHQYDVR0O
# BBYEFH6QuMwqcPG0hQlQ6c5jCtTTLrVeMEUGA1UdEQQ+MDykOjA4MR4wHAYDVQQL
# ExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xFjAUBgNVBAUTDTIzMDAxMis1MDc1NTkw
# HwYDVR0jBBgwFoAUf1k/VCHarU/vBeXmo9ctBpQSCDEwYAYDVR0fBFkwVzBVoFOg
# UYZPaHR0cDovL3d3dy5taWNyb3NvZnQuY29tL3BraW9wcy9jcmwvTWljcm9zb2Z0
# JTIwQ29kZSUyMFNpZ25pbmclMjBQQ0ElMjAyMDI0LmNybDBtBggrBgEFBQcBAQRh
# MF8wXQYIKwYBBQUHMAKGUWh0dHA6Ly93d3cubWljcm9zb2Z0LmNvbS9wa2lvcHMv
# Y2VydHMvTWljcm9zb2Z0JTIwQ29kZSUyMFNpZ25pbmclMjBQQ0ElMjAyMDI0LmNy
# dDAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEBCwUAA4ICAQBKTbYOjzwTG/DXGaz9
# s6+fQeaTtDcFmMY+5UyVFCyj7Pv+5i37qfX8lSL/tBIfYQfWsMuBQlfZurJD6r4H
# VJ2CeH+1fgiq8dcHdVKoZ3Sa2qXoX3cq9iS8cVb06B7+5/XJ7I0OxHH9fDsvJ3T3
# w5V/ZtAIFmLrl+P0CtG+92uzRsn0nTbdFjOkLMLWPLAU3THohKRlSEMgFJpPkm5n
# 5UAZ35xX6FWCrDLsSKb555bTifwa8mJBwdlof0bmfYidH+dxZ1FdDxvLnNl9zeKs
# A4kejaaIqqIPguhwAti5Ql7BlTNoJNwxCvBmqW2MQLnCkYN/VVUsR3V2x/rcTNzo
# Bf/Z/SpROvdaA2ZOOd1uioXJt3tdLQ7vHpqpib0KfWr/FWXW10q38VxfCnRQBqzb
# SuztR7nEMuzX7Ck+B/XaPDXd1qh72+QYyB0Z2VzWmO9zsnb9Uq/dwu8LGeQqnyu6
# 7SDGACvnXii2fb9+US492VTnXSnFKyqwgzUyFMtZK1/sHYTv6bG4TtQUygQxTN+Z
# V+aJIlKO2MqZ7bKrAnOzS9m6NgoTdWOq11bTOZwKlIEV/EhV9SWkDmdpR/hPPT2v
# 6TEj4F8PT/zHjRezIU5c/DGlt/VhY/pK0XkJtEyMmmS1BMtjU/rqBZVMIm3dnxQs
# /TBByr+Cf8Z1r7aifQVQ+WSqzjCCBr0wggSloAMCAQICEzMAAAA5O7Y3Gb8GHWcA
# AAAAADkwDQYJKoZIhvcNAQEMBQAwgYgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpX
# YXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQg
# Q29ycG9yYXRpb24xMjAwBgNVBAMTKU1pY3Jvc29mdCBSb290IENlcnRpZmljYXRl
# IEF1dGhvcml0eSAyMDExMB4XDTI0MDgwODIwNTQxOFoXDTM2MDMyMjIyMTMwNFow
# VzELMAkGA1UEBhMCVVMxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEo
# MCYGA1UEAxMfTWljcm9zb2Z0IENvZGUgU2lnbmluZyBQQ0EgMjAyNDCCAiIwDQYJ
# KoZIhvcNAQEBBQADggIPADCCAgoCggIBANgBnB7jOMeqlRYHNa265v4IY9fH8TKh
# emHfPINe1gpLaV3dhg324WwH06LcHbpnsBukCDNitryo0dtS/EW6I/yEL/bLSY8h
# KpbfQuWusBPr9qazYcDxCW/qnjb5JsI1s8bNOg3bVATvQVL4tcf03aTycsz8QeCd
# M0l/yHRObJ9QqazM1r6VPEOJ7LL+uEEb73w6QCuhs89a1uv1zerOYMnsneRRwCbp
# yW11IcggU0cRKDDq1pjVJzIbIF6+oiXXbReOsgeI8zu1FyQfK0fVkaya8SmVHQ/t
# Of23mZ4W9k0Ri22QW9p3UgSC5OUDktKxxcCmGL6tXLfOGSWHIIV4YrTJTT6PNty5
# REojHJuZHArkF9VnHTERWoTjAzfI3kP+5b4alUdhgAZ7ttOu1bVnXfHaqPYl2rPs
# 20ji03LOVWsh/radgE17es5hL+t6lV0eVHrVhsssROWJuz2MXMCt7iw7lFPG9LXK
# Gjsmonn2gotGdHIuEg5JnJMJVmixd5LRlkmgYRZKzhxSCwyoGIq0PhaA7Y+VPct5
# pCHkijcIIDm0nlkK+0KyepolcqGm0T/GYQRMhHJlGOOmVQop36wUVUYklUy++vDW
# eEgEo4s7hxN6mIbf2MSIQ/iIfMZgJxC69oukMUXCrOC3SkE/xIkgpfl22MM1itkZ
# 35nNXkMolU1lAgMBAAGjggFOMIIBSjAOBgNVHQ8BAf8EBAMCAYYwEAYJKwYBBAGC
# NxUBBAMCAQAwHQYDVR0OBBYEFH9ZP1Qh2q1P7wXl5qPXLQaUEggxMBkGCSsGAQQB
# gjcUAgQMHgoAUwB1AGIAQwBBMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAU
# ci06AjGQQ7kUBU7h6qfHMdEjiTQwWgYDVR0fBFMwUTBPoE2gS4ZJaHR0cDovL2Ny
# bC5taWNyb3NvZnQuY29tL3BraS9jcmwvcHJvZHVjdHMvTWljUm9vQ2VyQXV0MjAx
# MV8yMDExXzAzXzIyLmNybDBeBggrBgEFBQcBAQRSMFAwTgYIKwYBBQUHMAKGQmh0
# dHA6Ly93d3cubWljcm9zb2Z0LmNvbS9wa2kvY2VydHMvTWljUm9vQ2VyQXV0MjAx
# MV8yMDExXzAzXzIyLmNydDANBgkqhkiG9w0BAQwFAAOCAgEAFJQfOChP7onn6fLI
# MKrSlN1WYKwDFgAddymOUO3FrM8d7B/W/iQ6DxXsDn7D5W4wMwYeLystcEqfkjz4
# NURRgazyMu5yRzQh4LqjA4tStTcJh1opExo7nn5PuPBYnbu0+THSuVHTe0VTTPVh
# ily/piFrDo3axQ9P4C+Ol5yet+2gTfekICS5xS+cYfSIvgn0JksVBVMYVI5QFu/q
# hnLhsEFEUzG8fvv0hjgkO+lkpV9ty6GkN4vdnd7ya6Q6aR9y34aiM1qmxaxBi6OU
# nyNl6fkuun/diTFnYDLTppOkr/mg5WSfCiDVMNCxtj4wPKC5OmHm1DQIt/MNokbb
# H3UGsFP1QbzsLocuSqLCvH09Io3fDPTmscR9Y75G4qX7RTX8AdBPo0I6OEojf39z
# uFZt0qOHm65YWQE69cZM2ueE1MB05dNNgHK9gTE7zKvK/fg8B2qjW88MT/WF5V5u
# vZGtqa9FSL2RazArA+rDPuf6JGYz4HpgMZHB4S6szWSKYBv0VisCzfxgeU+dquXW
# 9bd0auYlOB58DPcOYKdc3Se94g+xL4pcEhbB54JOgAkwYTu/9dLeH2pDqeJZAABV
# DWRQCaXfO5LgyKwKCLYXpigrZYCjUSBcr+Ve8PFWMhVTQl0v4q8J/AUmQN5W4n10
# 1cY2L4A7GTQG1h32HHAvfQESWP0xghnCMIIZvgIBATBuMFcxCzAJBgNVBAYTAlVT
# MR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jv
# c29mdCBDb2RlIFNpZ25pbmcgUENBIDIwMjQCEzMAAAIdTRnITtcPV0gAAAAAAh0w
# DQYJYIZIAWUDBAIBBQCggZAwGQYJKoZIhvcNAQkDMQwGCisGAQQBgjcCAQQwLwYJ
# KoZIhvcNAQkEMSIEIKaNNQmQ6YPTVuflAmmCDj6E9glzmLf5NPg53QZa+JvvMEIG
# CisGAQQBgjcCAQwxNDAyoBSAEgBNAGkAYwByAG8AcwBvAGYAdKEagBhodHRwOi8v
# d3d3Lm1pY3Jvc29mdC5jb20wDQYJKoZIhvcNAQEBBQAEggEAVn36UvDMe2qK+pjC
# ++sZhzJD+4gJk+PJfqSKOnbi7/Auzlzh+Kpa4guQsODiWGcdVXXiqYf20IkmjmSG
# YYFcgk7+6CvWgN93YssaiafB8Sz3nNbGTkLQvno+xXbawJsXiXEMHiBiQ8NS9MGl
# CG+F0j2BGW5sLS7DEo1qz0SX84qSaOJjJ3X27BQhNI1DZnhvZQT4SpepoMSb78sB
# 9yoHKOxi/rCjX07A8jOswp+nPaFLX8sUxTgFeXDlhp0zaTdLYt3kyVHu1GmJlnGo
# xpHAgp0CoM85QE0fww9UFzfsu0jhZCIK7sqftpVIb3nlgNEXHDOYFi/guu/gu76C
# 8mi/76GCF5IwgheOBgorBgEEAYI3AwMBMYIXfjCCF3oGCSqGSIb3DQEHAqCCF2sw
# ghdnAgEDMQ8wDQYJYIZIAWUDBAIBBQAwggFQBgsqhkiG9w0BCRABBKCCAT8EggE7
# MIIBNwIBAQYKKwYBBAGEWQoDATAxMA0GCWCGSAFlAwQCAQUABCCkjZQns8AexzUp
# wadukqMfY1DCwzLQ5zNFRQa7koz62wIGavyAXK0zGBEyMDI2MTExODE0MDQ0NC4y
# WjAEgAIB9KCB0aSBzjCByzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0
# b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3Jh
# dGlvbjElMCMGA1UECxMcTWljcm9zb2Z0IEFtZXJpY2EgT3BlcmF0aW9uczEnMCUG
# A1UECxMeblNoaWVsZCBUU1MgRVNOOkE5MzUtMDNFMC1EOTQ3MSUwIwYDVQQDExxN
# aWNyb3NvZnQgVGltZS1TdGFtcCBTZXJ2aWNloIIR6jCCByAwggUIoAMCAQICEzMA
# AAIn1cCDw7EuVy0AAQAAAicwDQYJKoZIhvcNAQELBQAwfDELMAkGA1UEBhMCVVMx
# EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoT
# FU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUt
# U3RhbXAgUENBIDIwMTAwHhcNMjYwMjE5MTk0MDA0WhcNMjcwNTE3MTk0MDA0WjCB
# yzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1Jl
# ZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjElMCMGA1UECxMc
# TWljcm9zb2Z0IEFtZXJpY2EgT3BlcmF0aW9uczEnMCUGA1UECxMeblNoaWVsZCBU
# U1MgRVNOOkE5MzUtMDNFMC1EOTQ3MSUwIwYDVQQDExxNaWNyb3NvZnQgVGltZS1T
# dGFtcCBTZXJ2aWNlMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA4sVs
# tXwzki+Ko9wNaWncvnpSAy8Jxd1Li8ySDlsBh3BIK8ccLZ8r4lCA5pscpU1Jdbvt
# qwT6ds0+AcMEIbxmiaRMarzy5QxZW35kn5SiPOnhaqH4me4/DU0TuJe8BoPTY5vp
# rjWrk3BVtqnXyIyhPedDpK5vTJzDhmMvn4mzWHcUz0T6tU+DC2St7N73TMjBDpXX
# DkJEiqcQ+v9RpOoDpgrtioCPH9Hser2MZyg5fVtDi0hGv+svNqCG7JvtUAYnzkOO
# 8VikxtQpr7Rq/OS8wO+fzAHFJkcOf6H/6hE9FBVdVrpTHCayOgwEgLDQjQfuli66
# LbgWQI/lTJam5+UTGekOCGOycGgIiF4e1Y8a58FDmGRvFhBoX6wPfHYvuyxJ/QKr
# 7xDshvlEHI1YQgmzBl4oCV0gKXsnlrqQrA9I4EDDQsXweQSwQ1sYHWN3SQRD4MX5
# IEw0CwYILVb9neQmMRyoCCLQeGyOXkm+Y5CBtlqLZxXrU9JXoKcPxKM8H9/WqOrR
# DWNtXlViM0cPxrJr8I2EBer1a8Tg9KRlbH6hhfLN1T3mO4SNk8RxTKjQNCAf2tjS
# 2OyU8WACgD/9dRCWbe8W6gyzIA9WA3RhMxqUIo5t5wDwi9gnmz/45rvdGmydluNu
# coJRh0yP5wga8EqX0QoMM63xXpSWgijOvt+WhX8CAwEAAaOCAUkwggFFMB0GA1Ud
# DgQWBBTS1ufDeDBkhurne41qoE/dqK30XjAfBgNVHSMEGDAWgBSfpxVdAF5iXYP0
# 5dJlpxtTNRnpcjBfBgNVHR8EWDBWMFSgUqBQhk5odHRwOi8vd3d3Lm1pY3Jvc29m
# dC5jb20vcGtpb3BzL2NybC9NaWNyb3NvZnQlMjBUaW1lLVN0YW1wJTIwUENBJTIw
# MjAxMCgxKS5jcmwwbAYIKwYBBQUHAQEEYDBeMFwGCCsGAQUFBzAChlBodHRwOi8v
# d3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2NlcnRzL01pY3Jvc29mdCUyMFRpbWUt
# U3RhbXAlMjBQQ0ElMjAyMDEwKDEpLmNydDAMBgNVHRMBAf8EAjAAMBYGA1UdJQEB
# /wQMMAoGCCsGAQUFBwMIMA4GA1UdDwEB/wQEAwIHgDANBgkqhkiG9w0BAQsFAAOC
# AgEAKp3LneD0gtbXm9h+p0bsu7A4iitdxVyYq1QeE38I3aNjG/kC+I+8Gf5OBvT9
# AgDR2Raw0HCtFRQ08rK2LvGdAIWteGnA2T7MiKD7wBkUYWhxLn+zXJEY5H2v8paN
# SsiCPI2y/TfbCQKgTy/FeBTQY5Y7/tRhwzsNdu62c+WUkz6AD29kgNL+cg4HKVDH
# 8YJT8qenJzz6EKU7Q/ThsfA8Jtj/qNUz8QSMuiNE/UWrrpaIFQrysH5X3i03CgL5
# 0htawo3q0l5lNQzVzrAA/27K0o4G1+ZgGw+100TBf72sAFhEhXJ/wY44s8XlmW9N
# GmEpZCQNq1bRZTDOPNWlVl3QG1zz+Uc1Ilk5YMh3/xu5QsR2FhiGbgdd092iOmPJ
# hIJ/6LuNGohSaPK9PotD+RnTZ3lrcYkdAjClH5KPubP+93MHtVn6fASl2tu9HInF
# UGrBX+bEVe6RZvle3zUV8Aru2p0zpoGu+szu/9rfszpYm76YU/kOmXfgdqmLEp+M
# QWmPmMx6Z8nC1uXLycoT8QQnG9aEWH4UcwgA29rrSNhLRgo3Nj9oouC8keEDG/5/
# HDsHi/SKlUyis81ZPs2ScVd766eC8rkF8NDt9JWugXB3TQAAAfVAvN87NxvXfgJS
# H2SzPe7TFDSlo2waSIqxcei0wxV1bWUHe4asy2Aco24x9LowggdxMIIFWaADAgEC
# AhMzAAAAFcXna54Cm0mZAAAAAAAVMA0GCSqGSIb3DQEBCwUAMIGIMQswCQYDVQQG
# EwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwG
# A1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMTIwMAYDVQQDEylNaWNyb3NvZnQg
# Um9vdCBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkgMjAxMDAeFw0yMTA5MzAxODIyMjVa
# Fw0zMDA5MzAxODMyMjVaMHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5n
# dG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9y
# YXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEwMIIC
# IjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5OGmTOe0ciELeaLL1yR5vQ7V
# gtP97pwHB9KpbE51yMo1V/YBf2xK4OK9uT4XYDP/XE/HZveVU3Fa4n5KWv64NmeF
# RiMMtY0Tz3cywBAY6GB9alKDRLemjkZrBxTzxXb1hlDcwUTIcVxRMTegCjhuje3X
# D9gmU3w5YQJ6xKr9cmmvHaus9ja+NSZk2pg7uhp7M62AW36MEBydUv626GIl3GoP
# z130/o5Tz9bshVZN7928jaTjkY+yOSxRnOlwaQ3KNi1wjjHINSi947SHJMPgyY9+
# tVSP3PoFVZhtaDuaRr3tpK56KTesy+uDRedGbsoy1cCGMFxPLOJiss254o2I5Jas
# AUq7vnGpF1tnYN74kpEeHT39IM9zfUGaRnXNxF803RKJ1v2lIH1+/NmeRd+2ci/b
# fV+AutuqfjbsNkz2K26oElHovwUDo9Fzpk03dJQcNIIP8BDyt0cY7afomXw/TNuv
# XsLz1dhzPUNOwTM5TI4CvEJoLhDqhFFG4tG9ahhaYQFzymeiXtcodgLiMxhy16cg
# 8ML6EgrXY28MyTZki1ugpoMhXV8wdJGUlNi5UPkLiWHzNgY1GIRH29wb0f2y1BzF
# a/ZcUlFdEtsluq9QBXpsxREdcu+N+VLEhReTwDwV2xo3xwgVGD94q0W29R6HXtqP
# nhZyacaue7e3PmriLq0CAwEAAaOCAd0wggHZMBIGCSsGAQQBgjcVAQQFAgMBAAEw
# IwYJKwYBBAGCNxUCBBYEFCqnUv5kxJq+gpE8RjUpzxD/LwTuMB0GA1UdDgQWBBSf
# pxVdAF5iXYP05dJlpxtTNRnpcjBcBgNVHSAEVTBTMFEGDCsGAQQBgjdMg30BATBB
# MD8GCCsGAQUFBwIBFjNodHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL0Rv
# Y3MvUmVwb3NpdG9yeS5odG0wEwYDVR0lBAwwCgYIKwYBBQUHAwgwGQYJKwYBBAGC
# NxQCBAweCgBTAHUAYgBDAEEwCwYDVR0PBAQDAgGGMA8GA1UdEwEB/wQFMAMBAf8w
# HwYDVR0jBBgwFoAU1fZWy4/oolxiaNE9lJBb186aGMQwVgYDVR0fBE8wTTBLoEmg
# R4ZFaHR0cDovL2NybC5taWNyb3NvZnQuY29tL3BraS9jcmwvcHJvZHVjdHMvTWlj
# Um9vQ2VyQXV0XzIwMTAtMDYtMjMuY3JsMFoGCCsGAQUFBwEBBE4wTDBKBggrBgEF
# BQcwAoY+aHR0cDovL3d3dy5taWNyb3NvZnQuY29tL3BraS9jZXJ0cy9NaWNSb29D
# ZXJBdXRfMjAxMC0wNi0yMy5jcnQwDQYJKoZIhvcNAQELBQADggIBAJ1VffwqreEs
# H2cBMSRb4Z5yS/ypb+pcFLY+TkdkeLEGk5c9MTO1OdfCcTY/2mRsfNB1OW27DzHk
# wo/7bNGhlBgi7ulmZzpTTd2YurYeeNg2LpypglYAA7AFvonoaeC6Ce5732pvvinL
# btg/SHUB2RjebYIM9W0jVOR4U3UkV7ndn/OOPcbzaN9l9qRWqveVtihVJ9AkvUCg
# vxm2EhIRXT0n4ECWOKz3+SmJw7wXsFSFQrP8DJ6LGYnn8AtqgcKBGUIZUnWKNsId
# w2FzLixre24/LAl4FOmRsqlb30mjdAy87JGA0j3mSj5mO0+7hvoyGtmW9I/2kQH2
# zsZ0/fZMcm8Qq3UwxTSwethQ/gpY3UA8x1RtnWN0SCyxTkctwRQEcb9k+SS+c23K
# jgm9swFXSVRk2XPXfx5bRAGOWhmRaw2fpCjcZxkoJLo4S5pu+yFUa2pFEUep8beu
# yOiJXk+d0tBMdrVXVAmxaQFEfnyhYWxz/gq77EFmPWn9y8FBSX5+k77L+DvktxW/
# tM4+pTFRhLy/AsGConsXHRWJjXD+57XQKBqJC4822rpM+Zv/Cuk0+CQ1ZyvgDbjm
# jJnW4SLq8CdCPSWU5nR0W2rRnj7tfqAxM328y+l7vzhwRNGQ8cirOoo6CGJ/2XBj
# U02N7oJtpQUQwXEGahC0HVUzWLOhcGbyoYIDTTCCAjUCAQEwgfmhgdGkgc4wgcsx
# CzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRt
# b25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJTAjBgNVBAsTHE1p
# Y3Jvc29mdCBBbWVyaWNhIE9wZXJhdGlvbnMxJzAlBgNVBAsTHm5TaGllbGQgVFNT
# IEVTTjpBOTM1LTAzRTAtRDk0NzElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUtU3Rh
# bXAgU2VydmljZaIjCgEBMAcGBSsOAwIaAxUAIx86rYT8DtBg3JAzAOseeJSIjCqg
# gYMwgYCkfjB8MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4G
# A1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSYw
# JAYDVQQDEx1NaWNyb3NvZnQgVGltZS1TdGFtcCBQQ0EgMjAxMDANBgkqhkiG9w0B
# AQsFAAIFAO6np2kwIhgPMjAyNjExMTgwNDI2MTdaGA8yMDI2MTExOTA0MjYxN1ow
# dDA6BgorBgEEAYRZCgQBMSwwKjAKAgUA7qenaQIBADAHAgEAAgIfDDAHAgEAAgIT
# yTAKAgUA7qj46QIBADA2BgorBgEEAYRZCgQCMSgwJjAMBgorBgEEAYRZCgMCoAow
# CAIBAAIDB6EgoQowCAIBAAIDAYagMA0GCSqGSIb3DQEBCwUAA4IBAQCKDYzLpRmp
# +tJG8aADABROLk+Qav3VJHquTyEzFK3tIYmNrvxPsZKQWXNvLjAXtu330E970/9t
# uBRnoEwvPIP92fQye15inM6htfchwdp1iABm6obLKjfZj92A0F5yKNWu8qBvkYu0
# vk6GHBI/2toIbDbJa4Kw5eaXS/DCUaA7Ph6ZSiJjqjSfMMbjqImKK4kuz0Rr85Zo
# PBlTVJIo69nYD69b/YhV/nY+nO0PM4w/6fzUDuhLwvQXSmtR24wsCfoUCnRgVCl1
# LiwKcmR70ejN+WBu8UOoKOrEz28P8bww7Q54C+MbYo+opslnUfNvNeoYQFZ1x2bW
# WINZRUdWUfWDMYIEDTCCBAkCAQEwgZMwfDELMAkGA1UEBhMCVVMxEzARBgNVBAgT
# Cldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29m
# dCBDb3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENB
# IDIwMTACEzMAAAIn1cCDw7EuVy0AAQAAAicwDQYJYIZIAWUDBAIBBQCgggFKMBoG
# CSqGSIb3DQEJAzENBgsqhkiG9w0BCRABBDAvBgkqhkiG9w0BCQQxIgQgI5Vcw/XT
# 3aCya/ewjT8pTz7xhcbVN3KTYnW+ekz/m0AwgfoGCyqGSIb3DQEJEAIvMYHqMIHn
# MIHkMIG9BCDl5wEaNaFSHDiySg6pRNGnav42fU13ZZ11kXFxk4QRcjCBmDCBgKR+
# MHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdS
# ZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMT
# HU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEwAhMzAAACJ9XAg8OxLlctAAEA
# AAInMCIEILKp6tBQkKYCHw6QIBHYMJ/f1Pbp9y093qTd7cVdFElGMA0GCSqGSIb3
# DQEBCwUABIICADSFYpESXyjDppAb8Wt+pl76Cb/oFCmocTU1RcrzwYPQdGGFY3z/
# 93jeGeFk8La9TrQae0O/OcshXQjyGvhBlfvKy2LSCBZWpiUJlWmWFOw4OM7v/bLU
# OVONYEgiV1nrGC0QPSVvimfb/+Ju4EAZ9qJ3UH0ZtjjPGIQ/RjMKuIpThDdsbUZJ
# jmtOVAcsjs2CPaUQ1I1pxmNdWgV9XXO1TUi3bz8oPKhQOXJqw1woPmRwIDJFyAWc
# QCp5I6oIpwQLd51GwoirXUW78QszSUT/LzE7EzFcNZn5God8nLvSv86XjM0Tw8g7
# ydMptK0dQ8xkhj7zRLRI8hEzWHFW2/6LYJihYnJsI/GN0BJjp9ZfTgal9EK/Lb4k
# zMLa7gYYw/u8fBHmzYKf8odUeOfpNy+bjSySmfdUHJespFLjPBKfGe8ue3iuHsK4
# ZVRT0/3V4whi34h58+k2ltOwP74T01L2vinlzwWHPFOOuwQ/kFcfv0eAf40Xbs0u
# 53dflACg0tQdfvSOvCJ94PcxdTJPEm2enZpattjqYnCnShgKnXO7kQWzp+v1Z6Xr
# 0oMcKa8eO4g975Q8Wr4BaP963xKRb1x4rLOAcfdUjG1XysZq/s5rYLb9dc+L60NO
# 8B2QIw3OE5Zp9A09tKqLzOXR3+X+hMmAfYLsXnhauQh+y2S7E1Ra554t
# SIG # End signature block