Modules/businessdev.ALbuild.Containers/Private/Select-BcArtifactVersion.ps1

function Select-BcArtifactVersion {
    <#
    .SYNOPSIS
        Applies a selection strategy to a set of candidate artifact version strings.
    .DESCRIPTION
        Internal, pure helper (no I/O) so the selection logic is fully unit-testable. Candidates
        are version strings (optionally suffixed with "/country"); the function sorts them by
        their numeric version and returns the subset matching the requested strategy.
 
        Strategies:
          All - all candidates, ascending by version
          Latest - the highest version
          First - the lowest version
          Closest - the lowest version >= ClosestToVersion, else the highest
    #>

    [CmdletBinding()]
    [OutputType([string[]])]
    param(
        [Parameter(Mandatory)]
        [AllowEmptyCollection()]
        [string[]] $Candidates,

        [Parameter(Mandatory)]
        [ValidateSet('All', 'Latest', 'First', 'Closest')]
        [string] $Select,

        [string] $ClosestToVersion
    )

    $getVersion = { param($c) [version](($c -split '/', 2)[0]) }

    $sorted = @($Candidates | Sort-Object -Property @{ Expression = { & $getVersion $_ } })

    if ($sorted.Count -eq 0) { return @() }

    switch ($Select) {
        'All'    { return $sorted }
        'First'  { return @($sorted[0]) }
        'Latest' { return @($sorted[$sorted.Count - 1]) }
        'Closest' {
            if ([string]::IsNullOrWhiteSpace($ClosestToVersion)) {
                throw "ClosestToVersion is required when Select is 'Closest'."
            }
            $target = [version]$ClosestToVersion
            $closest = $sorted | Where-Object { (& $getVersion $_) -ge $target } | Select-Object -First 1
            if (-not $closest) { $closest = $sorted[$sorted.Count - 1] }
            return @($closest)
        }
    }
}