fix: check all local versions before remote when explicit version requested

PSDepend/PSDependScripts/Nuget.ps1

@@ -149,14 +149,17 @@ if(Test-Path $PackagePath)
     $GetGalleryVersion = { (Find-NugetPackage -Name $DependencyName -PackageSourceUrl $Source -Credential $Credential -IsLatest).Version }
 
     # Version string, and equal to current
-    if( $Version -and $Version -ne 'latest' -and $Version -eq $ExistingVersion)
+    if($Version -and $Version -ne 'latest')
     {
-        Write-Verbose "You have the requested version [$Version] of [$DependencyName]"
-        if($PSDependAction -contains 'Test')
+        if(Test-VersionEquality $Version $ExistingVersion)
         {
-            return $True
+            Write-Verbose "You have the requested version [$Version] of [$DependencyName]"
+            if($PSDependAction -contains 'Test')
+            {
+                return $True
+            }
+            return $null
         }
-        return $null
     }
 
     # latest, and we have latest

PSDepend/PSDependScripts/PSGalleryModule.ps1

@@ -225,6 +225,17 @@ $Existing = Get-Module -ListAvailable -Name $ModuleName -ErrorAction SilentlyCon
 
 if($Existing) {
     Write-Verbose "Found existing module [$Name]"
+
+    if($Version -and $Version -ne 'latest') {
+        $matchedInstall = $Existing | Where-Object { Test-VersionEquality $Version $_.Version.ToString() } | Select-Object -First 1
+        if ($matchedInstall) {
+            Write-Verbose "You have the requested version [$Version] of [$Name]"
+            Import-PSDependModule -Name $ModuleName -Action $PSDependAction -Version $matchedInstall.Version
+            if($PSDependAction -contains 'Test') { return $true }
+            return $null
+        }
+    }
+
     # Thanks to Brandon Padgett!
     $ExistingVersion = $Existing | Measure-Object -Property Version -Maximum | Select-Object -ExpandProperty Maximum
     $FindModuleParams = @{Name = $Name }
@@ -238,18 +249,6 @@ if($Existing) {
         $FindModuleParams.Add('AllowPrerelease', $AllowPrerelease)
     }
 
-    # Version string, and equal to current
-    if($Version -and $Version -ne 'latest' -and $Version -eq $ExistingVersion) {
-        Write-Verbose "You have the requested version [$Version] of [$Name]"
-        # Conditional import
-        Import-PSDependModule -Name $ModuleName -Action $PSDependAction -Version $ExistingVersion
-
-        if($PSDependAction -contains 'Test') {
-            return $true
-        }
-        return $null
-    }
-
     $GalleryVersion = Find-Module @FindModuleParams | Measure-Object -Property Version -Maximum | Select-Object -ExpandProperty Maximum
     [System.Version]$parsedExistingVersion = $null
     [System.Version]$parsedGalleryVersion = $null

PSDepend/PSDependScripts/PSGalleryNuget.ps1

@@ -133,16 +133,19 @@ if(Test-Path $ModulePath)
     $GetGalleryVersion = { (Find-NugetPackage -Name $Name -PackageSourceUrl $Source -Credential $Credential -IsLatest).Version }
 
     # Version string, and equal to current
-    if( $Version -and $Version -ne 'latest' -and $Version -eq $ExistingVersion)
+    if($Version -and $Version -ne 'latest')
     {
-        Write-Verbose "You have the requested version [$Version] of [$Name]"
-        # Conditional import
-        Import-PSDependModule -Name $ModulePath -Action $PSDependAction -Version $ExistingVersion
-        if($PSDependAction -contains 'Test')
+        if(Test-VersionEquality $Version $ExistingVersion)
         {
-            return $True
+            Write-Verbose "You have the requested version [$Version] of [$Name]"
+            # Conditional import
+            Import-PSDependModule -Name $ModulePath -Action $PSDependAction -Version $ExistingVersion
+            if($PSDependAction -contains 'Test')
+            {
+                return $True
+            }
+            return $null
         }
-        return $null
     }
 
     # latest, and we have latest

PSDepend/PSDependScripts/Package.ps1

@@ -169,21 +169,25 @@ $Existing = Get-Package @GetParam
 if($Existing)
 {
     Write-Verbose "Found existing package [$Name]"
-    # Thanks to Brandon Padgett!
-    $ExistingVersion = $Existing | Measure-Object -Property Version -Maximum | Select-Object -ExpandProperty Maximum
-    $GetSourceVersion = { Find-Package -Name $Name -Source $Source | Measure-Object -Property Version -Maximum | Select-Object -ExpandProperty Maximum }
-
-    # Version string, and equal to current
-    if( $Version -and $Version -ne 'latest' -and $Version -eq $ExistingVersion)
+
+    if($Version -and $Version -ne 'latest')
     {
-        Write-Verbose "You have the requested version [$Version] of [$Name]"
-        if($PSDependAction -contains 'Test')
+        $matchedInstall = $Existing | Where-Object { Test-VersionEquality $Version $_.Version } | Select-Object -First 1
+        if ($matchedInstall)
         {
-            return $True
+            Write-Verbose "You have the requested version [$Version] of [$Name]"
+            if($PSDependAction -contains 'Test')
+            {
+                return $True
+            }
+            return $null
         }
-        return $null
     }
-
+
+    # Thanks to Brandon Padgett!
+    $ExistingVersion = $Existing | Measure-Object -Property Version -Maximum | Select-Object -ExpandProperty Maximum
+    $GetSourceVersion = { Find-Package -Name $Name -Source $Source | Measure-Object -Property Version -Maximum | Select-Object -ExpandProperty Maximum }
+
     $SourceVersion = (& $GetSourceVersion)
     [System.Version]$parsedExistingVersion = $null
     [System.Version]$parsedSourceVersion = $null

PSDepend/Private/Test-VersionEquality.ps1

@@ -0,0 +1,87 @@
+function Test-VersionEquality {
+    <#
+    .SYNOPSIS
+    Compare two versions by casting and comparing individual components.
+
+    .DESCRIPTION
+    Compare two version strings by attempting to parse them as System.Version
+    and System.Management.Automation.SemanticVersion, and comparing their
+    components. If parsing fails, fall back to string comparison.
+
+    .PARAMETER ReferenceVersion
+    The reference version string to compare against.
+
+    .PARAMETER DifferenceVersion
+    The version string to compare with the reference version.
+
+    .EXAMPLE
+    Test-VersionEquality -ReferenceVersion '1.2.3' -DifferenceVersion '1.2.3'
+
+    Returns true for identical three-part versions.
+
+    .EXAMPLE
+    Test-VersionEquality -ReferenceVersion '1.2.0' -DifferenceVersion '1.2'
+
+    Returns true when both omit build (treated as 0).
+
+    .EXAMPLE
+    Test-VersionEquality -ReferenceVersion '1.2.3' -DifferenceVersion '1.2.4'
+
+    Returns false when build differs.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [string]$ReferenceVersion,
+        [string]$DifferenceVersion
+    )
+
+    # First, check if either version string is null or empty. If so, they can't
+    # be equal.
+    if (
+        [string]::IsNullOrEmpty($ReferenceVersion) -or
+        [string]::IsNullOrEmpty($DifferenceVersion)
+    ) {
+        return $false
+    }
+
+    # Parsing requires existing references to exist, so we create them.
+    [System.Version]$parsedRef = $null
+    [System.Version]$parsedDiff = $null
+
+    # Check if we can parse both versions as System.Version. If we can, we
+    # compare them using individual components.
+    # Because System.Version treats missing components as -1, we use Math.Max to
+    # treat them as 0 for comparison purposes (e.g. 1.2 is treated as 1.2.0.0).
+    if ([System.Version]::TryParse($ReferenceVersion, [ref]$parsedRef) -and
+        [System.Version]::TryParse($DifferenceVersion, [ref]$parsedDiff)
+    ) {
+        return (
+            $parsedRef.Major -eq $parsedDiff.Major -and
+            $parsedRef.Minor -eq $parsedDiff.Minor -and
+            [Math]::Max($parsedRef.Build, 0) -eq [Math]::Max($parsedDiff.Build, 0) -and
+            [Math]::Max($parsedRef.Revision, 0) -eq [Math]::Max($parsedDiff.Revision, 0)
+        )
+    }
+
+    # If they can't be parsed as System.Version, we attempt to parse them as
+    # SemanticVersion, which can handle prerelease and build metadata.
+    [System.Management.Automation.SemanticVersion]$parsedRefSemVer = $null
+    [System.Management.Automation.SemanticVersion]$parsedDiffSemVer = $null
+
+    if (
+        [System.Management.Automation.SemanticVersion]::TryParse(
+            $ReferenceVersion, [ref]$parsedRefSemVer
+        ) -and
+        [System.Management.Automation.SemanticVersion]::TryParse(
+            $DifferenceVersion, [ref]$parsedDiffSemVer
+        )
+    ) {
+        return $parsedRefSemVer -eq $parsedDiffSemVer
+    }
+
+    # TODO: Investigate if we want to add additional parsing logic here for
+    # other version formats (e.g. date or commit based versions)
+
+    return $ReferenceVersion -eq $DifferenceVersion
+}