feat(utils): Allow version range for package configuration

The version ranges are only taken in account if the package configuration
contains the `id` and the `sourceCodeOrigin`, or just the `id`.
The `revision` part of the `vcs` property is still optional to prevent a
breaking change, see [2]. See [1] for the specification.

Fixes #9918.

[1]: #9918 (comment)
[2]: #9918 (comment)

Signed-off-by: Nicolas Nobelis <[email protected]>

Author: nnobelis

model/src/main/kotlin/config/PackageConfiguration.kt

@@ -30,6 +30,8 @@ import org.ossreviewtoolkit.model.RepositoryProvenance
 import org.ossreviewtoolkit.model.SourceCodeOrigin
 import org.ossreviewtoolkit.model.VcsInfo
 import org.ossreviewtoolkit.model.VcsType
+import org.ossreviewtoolkit.model.utils.isApplicableIvyVersion
+import org.ossreviewtoolkit.model.utils.isVersionRange
 import org.ossreviewtoolkit.utils.common.replaceCredentialsInUri
 
 /**
@@ -80,14 +82,20 @@ data class PackageConfiguration(
         ) {
             "A package configuration must contain at most one of 'sourceArtifactUrl', 'vcs' or 'sourceCodeOrigin'."
         }
+
+        if (id.isVersionRange()) {
+            require(vcs == null && sourceArtifactUrl == null) {
+                "A package configuration cannot have a version range and a 'vcs' or 'sourceArtifactUrl'."
+            }
+        }
     }
 
     fun matches(otherId: Identifier, provenance: Provenance): Boolean {
         @Suppress("ComplexCondition")
         if (!id.type.equals(otherId.type, ignoreCase = true) ||
             id.namespace != otherId.namespace ||
             id.name != otherId.name ||
-            id.version != otherId.version
+            !id.isApplicableIvyVersion(otherId)
         ) {
             return false
         }

model/src/main/kotlin/utils/VersionUtils.kt

@@ -63,4 +63,4 @@ internal fun Identifier.isApplicableIvyVersion(pkgId: Identifier) =
         it.showStackTrace()
     }.getOrDefault(false)
 
-private fun Identifier.isVersionRange() = versionRangeIndicators.any { version.contains(it, ignoreCase = true) }
+internal fun Identifier.isVersionRange() = versionRangeIndicators.any { version.contains(it, ignoreCase = true) }

model/src/test/kotlin/config/PackageConfigurationTest.kt

@@ -19,6 +19,7 @@
 
 package org.ossreviewtoolkit.model.config
 
+import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.WordSpec
 import io.kotest.matchers.shouldBe
 
@@ -159,6 +160,19 @@ class PackageConfigurationTest : WordSpec({
             ) shouldBe true
         }
 
+        "return true if source code origin is equal and identifier matches with version is in range" {
+            val config =
+                PackageConfiguration(
+                    id = Identifier.EMPTY.copy(name = "some-name", version = "[51.0.0,60.0.0]"),
+                    sourceCodeOrigin = SourceCodeOrigin.ARTIFACT
+                )
+
+            config.matches(
+                config.id.copy(version = "55"),
+                ARTIFACT_PROVENANCE
+            ) shouldBe true
+        }
+
         "return false if only source code origin is not equal" {
             val config =
                 PackageConfiguration(
@@ -193,5 +207,53 @@ class PackageConfigurationTest : WordSpec({
                 ARTIFACT_PROVENANCE
             ) shouldBe false
         }
+
+        "return true if only matched by id with a matching version range" {
+            val config =
+                PackageConfiguration(
+                    id = Identifier.EMPTY.copy(name = "some-name", version = "[51.0.0,60.0.0]")
+                )
+
+            config.matches(
+                config.id.copy(version = "55"),
+                ARTIFACT_PROVENANCE
+            ) shouldBe true
+        }
+
+        "return false if only matched by id with a non-matching version range" {
+            val config =
+                PackageConfiguration(
+                    id = Identifier.EMPTY.copy(name = "some-name", version = "[51.0.0,60.0.0]")
+                )
+
+            config.matches(
+                config.id.copy(version = "6"),
+                ARTIFACT_PROVENANCE
+            ) shouldBe false
+        }
+    }
+
+    "init()" should {
+        "throw an exception if a version range is given while having a vcs" {
+            val baseConfig = vcsPackageConfig(
+                name = "some-name",
+                revision = "12345678",
+                url = "ssh://git@host/repo.git"
+            )
+            shouldThrow<IllegalArgumentException> {
+                baseConfig.copy(
+                    id = baseConfig.id.copy(version = "[51.0.0,60.0.0]")
+                )
+            }
+        }
+
+        "throw an exception if a version range is given while having a source artifact URL" {
+            val baseConfig = sourceArtifactConfig(name = "some-name", url = "https://host/path/file.zip")
+            shouldThrow<IllegalArgumentException> {
+                baseConfig.copy(
+                    id = baseConfig.id.copy(version = "[51.0.0,60.0.0]")
+                )
+            }
+        }
     }
 })

website/docs/configuration/package-configurations.md

@@ -13,24 +13,38 @@ Use a package configuration file to:
 
 ## Package Configuration File Basics
 
-Each package configuration applies exactly to one *package id* and *provenance* which must be specified.
-The *provenance* can be specified as either a *source artifact* or a *VCS location* with an optional revision.
+A package configuration applies to the packages it matches with.
+It contains the mandatory `id` matcher, for matching package IDs, which allows for using [Ivy-style version matchers](https://ant.apache.org/ivy/history/2.5.0/settings/version-matchers.html).
+In addition to the `id`, at most one of the matchers `vcs`, `sourceArtifactUrl` or `sourceCodeOrigin` may additionally
+be specified, which targets the repository provenance, the source artifact provenance or just the source code origin of
+the package's scan result(s).
 
-Here is an example of a package configuration for `ansi-styles 4.2.1`, when the source artifact is (to be) scanned:
+The following example illustrates a package configuration for `ansi-styles 4.2.1`, utilizing the available options:
 
 ```yaml
+# Apply only specified source artifact by its URL.
 id: "NPM::ansi-styles:4.2.1"
 source_artifact_url: "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.2.1.tgz"
-```
-
-If the source repository is (to be) scanned, then use the package configuration below:
 
-```yaml
+# Apply only to specific code repository URL with optionally a hash.
 id: "NPM::ansi-styles:4.2.1"
 vcs:
   type: "Git"
   url: "https://github.com/chalk/ansi-styles.git"
   revision: "74d421cf32342ac6ec7b507bd903a9e1105f74d7"
+
+# Apply to all versions lower than 4.2.1 where a code repository was scanned.
+id: "NPM::ansi-styles:(,4.2.1]"
+source_code_origin: VCS
+
+# Apply to versions all versions greater or equal to 4.0 
+# and lower or equal to 4.2.1 where a source artifact was scanned.
+id: "NPM::ansi-styles:[4.0,4.2.1]"
+source_code_origin: SOURCE_ARTIFACT
+
+# Apply only to version 4.2.1, regardless whether
+# code repository or source artifact was scanned.
+id: "NPM::ansi-styles:4.2.1"
 ```
 
 ## Defining Path Excludes and License Finding Curations