Resource/Resource.ps1

#region Copyright & License

# Copyright © 2012 - 2022 François Chabot
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

#endregion

Set-StrictMode -Version Latest

function Get-ResourceItem {
   [CmdletBinding()]
   [OutputType([System.IO.FileInfo[]])]
   param (
      [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
      [ValidateNotNullOrEmpty()]
      [string[]]
      $Name,

      [Parameter(Mandatory = $false)]
      [ValidateNotNullOrEmpty()]
      [string]
      $FolderPath = $MyInvocation.PSScriptRoot,

      [Parameter(Mandatory = $false)]
      [ValidateNotNullOrEmpty()]
      [string[]]
      $Extension = @('.dll', '.exe')
   )
   Process {
      $Name | ForEach-Object -Process { $_ } -PipelineVariable currentName | ForEach-Object -Process {
         $items = Get-ChildItem -Path $FolderPath -File -Recurse | Where-Object -FilterScript { $_.BaseName -eq $currentName -and $_.Extension -in $Extension } | Get-Item
         if ($items | Test-None) {
            throw "Resource item not found [Path: '$FolderPath', Name: '$currentName', Extension = '$($Extension -join ', ')']."
         }
         $duplicateItems = $items | Group-Object Name | Where-Object Count -GT 1
         if ($duplicateItems | Test-Any) {
            throw "Ambiguous resource items found ['$($duplicateItems.Name -join "', '")'] matching criteria [Path: '$FolderPath', Name: '$currentName', Extensions = '$($Extension -join ', ')']."
         }
         $items
      }
   }
}

function New-ResourceItem {
   [CmdletBinding(DefaultParameterSetName = 'named-resource')]
   [OutputType([PSCustomObject[]])]
   param (
      [Alias('Resource')]
      [Parameter(Mandatory = $true, ParameterSetName = 'named-resource')]
      [Parameter(Mandatory = $true, ParameterSetName = 'file-resource')]
      [ValidateNotNullOrEmpty()]
      [string]
      $ResourceGroup,

      [Parameter(Mandatory = $true, ParameterSetName = 'named-resource')]
      [Parameter(Mandatory = $false, ParameterSetName = 'file-resource')]
      [ValidateNotNullOrEmpty()]
      [string[]]
      $Name,

      [Parameter(Mandatory = $true, ParameterSetName = 'file-resource')]
      [ValidateScript( { $_ | ForEach-Object { (Test-Path -Path $_ -PathType Leaf) -or (Test-Path -Path $_ -IsValid) } } )]
      [PSObject[]]
      $Path,

      [Parameter(Mandatory = $false, ParameterSetName = 'file-resource')]
      [switch]
      $SkipPathResolution,

      [Parameter(Mandatory = $false, ParameterSetName = 'named-resource')]
      [Parameter(Mandatory = $false, ParameterSetName = 'file-resource')]
      [ValidateScript( { $_ -is [bool] -or $_ -is [ScriptBlock] } )]
      [ValidateNotNullOrEmpty()]
      [PSObject]
      $Condition = $true,

      [Parameter(Mandatory = $false, ParameterSetName = 'named-resource')]
      [Parameter(Mandatory = $false, ParameterSetName = 'file-resource')]
      [switch]
      $PassThru,

      [Parameter(DontShow, Mandatory = $false, ParameterSetName = 'named-resource', ValueFromRemainingArguments = $true)]
      [Parameter(DontShow, Mandatory = $false, ParameterSetName = 'file-resource', ValueFromRemainingArguments = $true)]
      [AllowNull()]
      [AllowEmptyCollection()]
      [object[]]
      $UnboundArguments = @()
   )
   Resolve-ActionPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState

   $splattedArguments = ConvertTo-SplattedArguments -UnboundArguments $UnboundArguments
   # any item is assumed to be included by default unless specified otherwise: when its Condition is either $false or deferred (a ScriptBlock)
   if ($Condition -is [ScriptBlock] -or -not($Condition)) { $splattedArguments.Add('Condition', $Condition) }

   $items = $(if ($PSCmdlet.ParameterSetName -eq 'named-resource') {
         $Name
      } elseif ($SkipPathResolution) {
         $Path
      } else {
         # -ErrorAction, see https://stackoverflow.com/a/49493910/1789441
         $Path | Resolve-Path -ErrorAction Stop | Select-Object -ExpandProperty ProviderPath
      }
   )
   $items | ForEach-Object -Process {
      $item = New-Object -TypeName PSCustomObject
      if ($PSCmdlet.ParameterSetName -eq 'named-resource') {
         Add-Member -InputObject $item -MemberType NoteProperty -Name Name -Value $_
      } else {
         Add-Member -InputObject $item -MemberType NoteProperty -Name Name -Value $(if ($Name | Test-Any) { $Name } else { Split-Path -Path $_ -Leaf })
         Add-Member -InputObject $item -MemberType NoteProperty -Name Path -Value $_
      }
      Add-ResourceItemMembers -Item $item -Members $splattedArguments
      if ($PassThru) {
         $item
      } else {
         # only add items whose condition is either $true or deferred (ScriptBlock)
         if ($Condition -is [ScriptBlock] -or $Condition) {
            if ($Manifest.ContainsKey($ResourceGroup)) {
               $Manifest.$ResourceGroup = @($Manifest.$ResourceGroup) + $item
            } else {
               $Manifest.Add($ResourceGroup, $item)
            }
         }
      }
   }
}

function New-ResourceManifest {
   [CmdletBinding()]
   [OutputType([HashTable])]
   param (
      [Parameter(Mandatory = $true)]
      [ValidateNotNullOrEmpty()]
      [string]
      $Type,

      [Parameter(Mandatory = $true)]
      [ValidateNotNullOrEmpty()]
      [string]
      $Name,

      [Parameter(Mandatory = $false)]
      [AllowNull()]
      [string]
      $Description,

      [Parameter(Mandatory = $false)]
      [ValidateSet('Manifest', 'Resource', 'None')]
      [string]
      $ItemUnicityScope = 'Manifest',

      [Parameter(Mandatory = $true)]
      [ValidateNotNullOrEmpty()]
      [scriptblock]
      $Build,

      [Parameter(DontShow, Mandatory = $false, ValueFromRemainingArguments = $true)]
      [AllowNull()]
      [AllowEmptyCollection()]
      [object[]]
      $UnboundArguments = @()
   )
   Resolve-ActionPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
   $item = New-Object -TypeName PSCustomObject
   Add-Member -InputObject $item -MemberType NoteProperty -Name Type -Value $Type
   Add-Member -InputObject $item -MemberType NoteProperty -Name Name -Value $Name
   Add-Member -InputObject $item -MemberType NoteProperty -Name Description -Value $Description
   Add-ResourceItemMembers -Item $item -Members (ConvertTo-SplattedArguments -UnboundArguments $UnboundArguments)

   $manifestBuildScript = [scriptblock] {
      [CmdletBinding()]
      [OutputType([void])]
      param (
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [HashTable]
         $Manifest
      )
      . $Build
   }

   $manifest = @{ }
   $manifest.Add('Properties', $item)
   & $manifestBuildScript -Manifest $manifest
   $manifest
}

#region helpers

function Add-ResourceItemMembers {
   [CmdletBinding()]
   [OutputType([void])]
   param (
      [Parameter(Mandatory = $true)]
      [ValidateNotNullOrEmpty()]
      [PSCustomObject]
      $Item,

      [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
      [AllowEmptyCollection()]
      [HashTable]
      $Members
   )
   Process {
      $Members.Keys | ForEach-Object -Process {
         if ($Members.$_ -is [ScriptBlock]) {
            # ScriptMethod instead of ScriptProperty to avoid any error to be silenced; see https://stackoverflow.com/a/19777735/1789441
            Add-Member -InputObject $item -MemberType ScriptMethod -Name $_ -Value $Members.$_
         } else {
            Add-Member -InputObject $item -MemberType NoteProperty -Name $_ -Value $Members.$_
         }
      }
   }
}

function Compare-ResourceItem {
   [CmdletBinding()]
   [OutputType([PSCustomObject[]])]
   param (
      [Parameter(Mandatory = $true)]
      [ValidateNotNull()]
      [ValidateScript( { $_.GetType().Name -eq 'PSCustomObject' } )]
      [PSCustomObject]
      $ReferenceItem,

      [Parameter(Mandatory = $true)]
      [ValidateNotNull()]
      [PSCustomObject]
      $DifferenceItem
   )
   Resolve-ActionPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
   $referenceProperties = @(Get-Member -InputObject $ReferenceItem -MemberType NoteProperty, ScriptProperty | Select-Object -ExpandProperty Name)
   $differenceProperties = @(Get-Member -InputObject $DifferenceItem -MemberType NoteProperty, ScriptProperty | Select-Object -ExpandProperty Name)
   $referenceProperties + $differenceProperties | Select-Object -Unique -PipelineVariable key | ForEach-Object -Process {
      if ($referenceProperties.Contains($key) -and !$differenceProperties.Contains($key)) {
         [PSCustomObject]@{Property = $key ; ReferenceValue = $ReferenceItem.$key ; SideIndicator = '<' ; DifferenceValue = $null } | Tee-Object -Variable difference
         Write-Verbose -Message $difference
      } elseif (!$referenceProperties.Contains($key) -and $differenceProperties.Contains($key)) {
         [PSCustomObject]@{Property = $key ; ReferenceValue = $null ; SideIndicator = '>' ; DifferenceValue = $DifferenceItem.$key } | Tee-Object -Variable difference
         Write-Verbose -Message $difference
      } else {
         $referenceValue, $differenceValue = $ReferenceItem.$key, $DifferenceItem.$key
         if ($referenceValue -is [array] -and $differenceValue -is [array]) {
            $arrayDifferences = Compare-Object -ReferenceObject $referenceValue -DifferenceObject $differenceValue
            if ($arrayDifferences | Test-Any) {
               $uniqueReferenceValues = @($arrayDifferences | Where-Object -FilterScript { $_.SideIndicator -eq '<=' } | ForEach-Object -Process { $_.InputObject }) -join ', '
               $uniqueDifferenceValues = @($arrayDifferences | Where-Object -FilterScript { $_.SideIndicator -eq '=>' } | ForEach-Object -Process { $_.InputObject }) -join ', '
               [PSCustomObject]@{Property = $key ; ReferenceValue = "($uniqueReferenceValues)" ; SideIndicator = '<>' ; DifferenceValue = "($uniqueDifferenceValues)" } | Tee-Object -Variable difference
               Write-Verbose -Message $difference
            }
         } elseif ($referenceValue -is [HashTable] -and $differenceValue -is [HashTable]) {
            Compare-HashTable -ReferenceHashTable $referenceValue -DifferenceHashTable $differenceValue -Prefix "$Key"
         } elseif ($referenceValue -ne $differenceValue) {
            [PSCustomObject]@{Property = $key ; ReferenceValue = $referenceValue ; SideIndicator = '<>' ; DifferenceValue = $differenceValue } | Tee-Object -Variable difference
            Write-Verbose -Message $difference
         }
      }
   }
}

function ConvertTo-SplattedArguments {
   [CmdletBinding()]
   [OutputType([HashTable])]
   param (
      [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
      [AllowEmptyCollection()]
      [PSObject[]]
      $UnboundArguments
   )
   $splattedArguments = @{ }
   $UnboundArguments | ForEach-Object -Process {
      if ($_ -is [array]) {
         $splattedArguments.$lastParameterName = $_
      } else {
         switch -regex ($_) {
            # parse parameter name
            '^-(\w+):?$' {
               $splattedArguments.Add(($lastParameterName = $matches[1]), $null)
               break
            }
            # parse values of last parsed parameter
            default {
               $splattedArguments.$lastParameterName = $_
               break
            }
         }
      }
   }
   $splattedArguments
}

#endregion
# SIG # Begin signature block
# MIII0QYJKoZIhvcNAQcCoIIIwjCCCL4CAQExCzAJBgUrDgMCGgUAMGkGCisGAQQB
# gjcCAQSgWzBZMDQGCisGAQQBgjcCAR4wJgIDAQAABBAfzDtgWUsITrck0sYpfvNR
# AgEAAgEAAgEAAgEAAgEAMCEwCQYFKw4DAhoFAAQUr4BsU//GPY7/m6c1ixGDag2S
# AaugggVMMIIFSDCCAzCgAwIBAgIJAJkr3mJdTBkUMA0GCSqGSIb3DQEBCwUAMEEx
# PzA9BgNVBAMeNgBpAGMAcgBhAGYAdABzAG8AZgB0AHcAYQByAGUAQABzAHQAYQB0
# AGUAbABlAHMAcwAuAGIAZTAeFw0yMTA2MjUxNDEyMjNaFw00MTA2MjAxNDEyMjNa
# MEExPzA9BgNVBAMeNgBpAGMAcgBhAGYAdABzAG8AZgB0AHcAYQByAGUAQABzAHQA
# YQB0AGUAbABlAHMAcwAuAGIAZTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC
# ggIBAOeqdUHBv7sxSeX3aj6yPKj7PAvs8izpVXjyEBl5aR8mQneVcXuF53AH7EW1
# 6E5p4+Az5pJPGUD5c3tXhiGMF7vgLhQjO6hlaVBRIqiIYHikNLwMNy6YBMc/QQYM
# rPhqHEFsZ53dkBIIj3M8e3kFcTFA09n25yDtTPDab4nd9yUhc9Qc8+nfpIzfYsoP
# 1pZ3nCzhw6hN2/44v1dkQrG3dRYwt+px65p6NPNZWEJpt4VCJjIFh+lBYJdxm9d4
# X/rAnlHIkbv7liOavWDzgHVabS3hdAWtcDmynm+7+FcZDFqPWNCl3e4SS7xe4s/R
# CKFKA0IsfKkSk9YJlLgeSQIEXUOOWXJAGaLqnRD8xWLZsc4Oi9GZg7XV1mv/S88c
# oztXnwtAN3OOlRKBh2QbomMgxeMO0GvsLE/cq5Q/YKAoz+KGr/7LcZq9jzQ8IPus
# ZvWLeDXmxPiwJjpZc1koLgfGIEX2NStQTT3QmacWr9thrWcKvI+4uBmI4exS9B4a
# R3nV91w5EY+2RoYsHqej9LWwNamO96+jMX9pxprTX+EkLUuMAikw/po8sBC9MUUn
# 5pMWmUv7DCtQOLGGBDDMMMkn4ZcjpCEEdPGHRKfqNnD27ssGtDjiNzfQrsm67toU
# bBwUF+gyJq/YckWquYJhA9ZOFWEADuIwGnsOzsoRvuQyY+p9AgMBAAGjQzBBMA4G
# A1UdDwEB/wQEAwIHgDAWBgNVHSUBAf8EDDAKBggrBgEFBQcDAzAXBgNVHREEEDAO
# ggxzdGF0ZWxlc3MuYmUwDQYJKoZIhvcNAQELBQADggIBACithYM3qckZRc9+Xbfu
# a6gWr3HwjrW+FHKgjfrcOm8ZnLVapb9xFqsqrRQqd3RXWQDINEGrtI2rSfrzyfoK
# UiTgldIfQNP1ZcGY229d++90t3hdo2mlt05hjYlbMENloJHpsEP0vQZmwOcEimCT
# ex1pymYM+P9pj3j8UD1PT1eIZot6or8fBRl63UybyDSrM7L4UOkkAOniKxWy5pW6
# 6duS8SR+SZpr3Bv44NyXPj0Nv+MIpLmsLrd7XPBFmnGxzY01ZO9vzi9KEhM2wT5i
# jPqHDNOvfPiADtAa+EyUBzdJiqy9heCz/TMZQgMWGwtfqJNxWZmsHcha2anW4Qt+
# mzrLO4GojWoVog9uVSAq+l0a+YQsd1u1kUmm4vgZCFyUA+lEp4LkI7ca2VBHkLPD
# w+u2DoDMRiqFPZjO7BCKjGc0jj9B/qGR3JVt+tqDdB621xXf2YGF2oFvxZQ/keGt
# 0ujfJ+JwN3nCulDAA4773q6KUnfykyrvAgITNbRJL6TngeRKtw9VIJBPxzqMzLpV
# 5ggXNituwLaD1CCBJ1oo9DZHpL9gplXp1wGrelJOTiJhh+pdNsPtRH7CrranWa5h
# LFLuigqin0eewQ5giJ1VaiBVEseOmiZog+27UpFIv40aDzgGL3YxB/Mu0ojwrQtp
# WLmqJCmWnR5qxOm0yK+zNWe0MYIC7zCCAusCAQEwTjBBMT8wPQYDVQQDHjYAaQBj
# AHIAYQBmAHQAcwBvAGYAdAB3AGEAcgBlAEAAcwB0AGEAdABlAGwAZQBzAHMALgBi
# AGUCCQCZK95iXUwZFDAJBgUrDgMCGgUAoHgwGAYKKwYBBAGCNwIBDDEKMAigAoAA
# oQKAADAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNwIBBDAcBgorBgEEAYI3AgELMQ4w
# DAYKKwYBBAGCNwIBFTAjBgkqhkiG9w0BCQQxFgQU3ShIPSXyasYmljEaCPEMNdm3
# ICUwDQYJKoZIhvcNAQEBBQAEggIAUBbrmkFbHKB/ybvy4gyqTuzMTx/bkJA0Cn+R
# DoFxhnBA1oBlCCggKEgb39WSWz0ls+UBYI4SnqGx3C9SbDPdenEd4H44t/+HzBCu
# gLxyWHY1Zpav+syVYHWgAFheNRuofVaCQ1wWpFXEdx3NuGhtScshgXAGX6TTvPCI
# VYjT8robc9s2w/ic3cBhkoMTybmSOUYJbb4IdjJs782tsrQa2Q3zlO/m86nFtWsc
# /6Hib59lN2QZHMmo5gRVCNhK+7oPuNNj/tvJVO02lbpW6kLb0+8G17a+D7MIuElQ
# xRcdTSgRHtkh+sYtfP3Fl9Y84f6YbE/l5kBkWdeqrvWYQJ7wihq/q/VzjvmmqPss
# 686Ef1IoLg978AUQTP4Sielon412QMbkRSJTSME95rcpWhCSfacllK8xULS/Lfd7
# ZuewrLNhIcpr/Y5xUmW7EZeIs1glGqURErAGyZ7vy4JQ/cNAi8hT1btLKZ8P5rIL
# bw5vnge78n1foeIHGFt8Es1ZnH8SsRBT9cGuBfVnZCQ7KJRmKGqoFb2s1glslUH3
# JRKSjGNq0NjGDE3NCOivA3XJErI2H+Lz44ji9vyF/u5cisfix5f4mG9qahCSgRYe
# Cwjuwiu5y02oslTPXLxfLhwIe8w/dFX6oa4xZZTgIWYkK7wiZOKaJ9EKuObb5LLq
# Ox7fNDA=
# SIG # End signature block