fix(yarn2): Handle dependencies with multiple versions

Handle the case that a package appears multiple times with different
versions in the dependency graph. In this case, try to select the
correct version based on semantic version ranges.

Signed-off-by: Oliver Heger <oliver.heger@bosch.com>

Author: oheger-bosch

plugins/package-managers/node/src/main/kotlin/yarn2/Yarn2DependencyHandler.kt

@@ -33,6 +33,9 @@ import org.ossreviewtoolkit.plugins.packagemanagers.node.NodePackageManagerType
 import org.ossreviewtoolkit.plugins.packagemanagers.node.PackageJson
 import org.ossreviewtoolkit.plugins.packagemanagers.node.parsePackage
 
+import org.semver4j.Semver
+import org.semver4j.range.RangeListFactory
+
 internal class Yarn2DependencyHandler(
     private val moduleInfoResolver: ModuleInfoResolver
 ) : DependencyHandler<PackageInfo> {
@@ -86,13 +89,15 @@ internal class Yarn2DependencyHandler(
      * locator from the virtual package's actual resolved version (handles virtual packages whose `children.version`
      * was overridden by Yarn's `resolutions` feature).
      *
-     * If both targeted lookups fail, fall back to searching the map for all installed versions of the same module
-     * by name. This handles the case where Yarn's `resolutions` feature (or similar mechanisms) cause a non-virtual
-     * dependency locator to reference a version that is not present in the map, while a different version of the
-     * same module was actually installed. If exactly one candidate is found, it is used. If multiple candidates are
-     * found, the resolution is ambiguous and an exception is thrown.
+     * If both targeted lookups fail, fall back to searching the map for all installed non-virtual, non-project
+     * versions of the same module by name. This handles the case where Yarn's `resolutions` feature (or similar
+     * mechanisms) cause a non-virtual dependency locator to reference a version that is not present in the map,
+     * while a different version of the same module was actually installed. If exactly one candidate is found, it
+     * is used. If multiple candidates are found, the semver range from the [dependency]'s descriptor is used to
+     * narrow down the candidates. If after all fallbacks the result is still not unique, an exception is thrown.
      */
     internal fun packageInfoFor(dependency: PackageInfo.Dependency): PackageInfo {
+        // Direct lookup by the real locator.
         packageInfoForLocator[dependency.realLocator]?.let { return it }
 
         // Fallback for virtual packages: derive the real locator from the virtual package's resolved version.
@@ -101,30 +106,34 @@ internal class Yarn2DependencyHandler(
             packageInfoForLocator["$moduleName@npm:${virtualInfo.children.version}"]?.let { return it }
         }
 
-        // Fallback for version mismatches caused by Yarn's `resolutions` feature: find the single installed version
-        // of the same module by name, ignoring the exact version in the locator.
+        // Fallback for version mismatches caused by Yarn's `resolutions` feature: find installed versions of the
+        // same module by name, ignoring the exact version in the locator.
         val moduleName = Locator.parse(dependency.realLocator).moduleName
         val candidates = packageInfoForLocator.values.filter {
             it.moduleName == moduleName && !it.isProject && !it.isVirtual
         }
 
-        return when (candidates.size) {
-            1 -> candidates.single().also {
+        if (candidates.size == 1) {
+            return candidates.single().also {
                 logger.debug {
                     "Resolved locator '${dependency.realLocator}' to '${it.value}' via module name lookup."
                 }
             }
+        }
 
-            0 -> error(
-                "Could not find a PackageInfo for locator '${dependency.realLocator}'. No entry for module " +
-                    "'$moduleName' exists in ${packageInfoForLocator.keys}."
-            )
+        if (candidates.size > 1) {
+            candidates.matchVersionRange(dependency)?.let { return it }
 
-            else -> error(
+            error(
                 "Could not unambiguously resolve locator '${dependency.realLocator}'. Found ${candidates.size} " +
                     "installed versions of module '$moduleName': ${candidates.map { it.value }}."
             )
         }
+
+        error(
+            "Could not find a PackageInfo for locator '${dependency.realLocator}'. No entry for module " +
+                "'$moduleName' exists in ${packageInfoForLocator.keys}."
+        )
     }
 }
 
@@ -169,3 +178,31 @@ internal data class Locator(
 
     val isVirtual: Boolean = remainder.startsWith("virtual:") && !isProject
 }
+
+/**
+ * Try to find a single [PackageInfo] from this collection that matches the given [dependency] taking semantic
+ * version ranges into account.
+ */
+private fun Collection<PackageInfo>.matchVersionRange(dependency: PackageInfo.Dependency): PackageInfo? {
+    val descriptorRemainder = Locator.parse(dependency.descriptor).remainder
+    if (descriptorRemainder.startsWith("npm:")) {
+        val rangeSpec = descriptorRemainder.removePrefix("npm:")
+        val range = runCatching { RangeListFactory.create(rangeSpec) }.getOrNull()
+        if (range != null) {
+            val matchingCandidates = filter { candidate ->
+                Semver.coerce(candidate.children.version)?.let { range.isSatisfiedBy(it) } == true
+            }
+
+            if (matchingCandidates.size == 1) {
+                return matchingCandidates.single().also {
+                    logger.debug {
+                        "Resolved locator '${dependency.realLocator}' to '${it.value}' via semver range " +
+                            "matching on descriptor '${dependency.descriptor}'."
+                    }
+                }
+            }
+        }
+    }
+
+    return null
+}

plugins/package-managers/node/src/test/kotlin/yarn2/Yarn2DependencyHandlerTest.kt

@@ -177,6 +177,33 @@ class Yarn2DependencyHandlerTest : WordSpec({
             exception.message shouldContain "2"
             exception.message shouldContain "cookie"
         }
+
+        "use the semver range from the descriptor to disambiguate multiple candidates" {
+            // Two real versions are installed. The descriptor's range matches only one of them.
+            val info100 = packageInfo("cookie@npm:1.0.0", "1.0.0")
+            val info200 = packageInfo("cookie@npm:2.0.0", "2.0.0")
+            // Descriptor "cookie@npm:^1.0.0" matches 1.0.0 but not 2.0.0.
+            val dependency = PackageInfo.Dependency(descriptor = "cookie@npm:^1.0.0", locator = "cookie@npm:1.0.2")
+            val handler = handlerWith(mapOf("cookie@npm:1.0.0" to info100, "cookie@npm:2.0.0" to info200))
+
+            handler.packageInfoFor(dependency) shouldBe info100
+        }
+
+        "throw when the semver range from the descriptor still matches multiple candidates" {
+            // Both installed versions satisfy the descriptor range.
+            val info440 = packageInfo("debug@npm:4.4.0", "4.4.0")
+            val info443 = packageInfo("debug@npm:4.4.3", "4.4.3")
+            // Descriptor "debug@npm:^4.3.0" matches both 4.4.0 and 4.4.3.
+            val dependency = PackageInfo.Dependency(descriptor = "debug@npm:^4.3.0", locator = "debug@npm:4.3.6")
+            val handler = handlerWith(mapOf("debug@npm:4.4.0" to info440, "debug@npm:4.4.3" to info443))
+
+            val exception = shouldThrow<IllegalStateException> {
+                handler.packageInfoFor(dependency)
+            }
+
+            exception.message shouldContain "2"
+            exception.message shouldContain "debug"
+        }
     }
 })
 
@@ -194,7 +221,7 @@ private fun packageInfo(locator: String, version: String, deps: List<PackageInfo
 /**
  * Create a [PackageInfo.Dependency] with the given [locator]. The descriptor is set to a dummy value.
  */
-private fun dep(locator: String) = PackageInfo.Dependency(descriptor = "dummy", locator = locator)
+private fun dep(locator: String) = PackageInfo.Dependency(descriptor = "dummy@npm:^1.2.3", locator = locator)
 
 /**
  * Create a [Yarn2DependencyHandler] with the given [packageInfoForLocator] map set via