Snippet Choice

integrations/schemas/repository-configuration-schema.json

@@ -142,6 +142,84 @@
           }
         }
       }
+    },
+    "snippet_choices": {
+      "type": "array",
+      "description": "A configuration to select a snippet from a package with multiple snippet findings.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "provenance": {
+            "type": "object",
+            "properties": {
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "url"
+            ]
+          },
+          "choices": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "given": {
+                  "type": "object",
+                  "properties": {
+                    "sourceLocation": {
+                      "type": "object",
+                      "properties": {
+                        "path": {
+                          "type": "string"
+                        },
+                        "lineStart": {
+                          "type": "integer"
+                        },
+                        "lineEnd": {
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "path",
+                        "lineStart",
+                        "lineEnd"
+                      ]
+                    }
+                  }
+                },
+                "choice": {
+                  "type": "object",
+                  "properties": {
+                    "purl": {
+                      "type": "string"
+                    },
+                    "reason": {
+                      "$ref": "#/definitions/snippetChoiceReason"
+                    },
+                    "comment": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "reason",
+                    "reasoning"
+                  ]
+                }
+              },
+              "required": [
+                "given",
+                "choice"
+              ]
+            }
+          }
+        },
+        "required": [
+          "provenance",
+          "choices"
+        ]
+      }
     }
   },
   "definitions": {
@@ -210,6 +288,13 @@
         "NOT_DETECTED",
         "REFERENCE"
       ]
+    },
+    "snippetChoiceReason": {
+      "enum": [
+        "NO_RELEVANT_FINDING",
+        "ORIGINAL_FINDING",
+        "OTHER"
+      ]
     }
   }
 }

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

@@ -68,5 +68,11 @@ data class RepositoryConfiguration(
      * Defines license choices within this repository.
      */
     @JsonInclude(value = JsonInclude.Include.CUSTOM, valueFilter = LicenseChoicesFilter::class)
-    val licenseChoices: LicenseChoices = LicenseChoices()
+    val licenseChoices: LicenseChoices = LicenseChoices(),
+
+    /**
+     * Defines snippet choices for projects in this repository.
+     */
+    @JsonInclude(value = JsonInclude.Include.NON_EMPTY)
+    val snippetChoices: List<SnippetChoices> = emptyList()
 )

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

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2024 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * 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
+ *
+ *     https://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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config
+
+import org.ossreviewtoolkit.model.config.snippet.Provenance
+import org.ossreviewtoolkit.model.config.snippet.SnippetChoice
+
+/**
+ * A collection of snippet choices for a given provenance.
+ */
+data class SnippetChoices(
+    /**
+     * The provenance this snippet choice applies to.
+     */
+    val provenance: Provenance,
+
+    /**
+     * The snippet choices for this package.
+     */
+    val choices: List<SnippetChoice>
+)

model/src/main/kotlin/config/snippet/Provenance.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2024 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * 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
+ *
+ *     https://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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config.snippet
+
+import org.ossreviewtoolkit.model.RepositoryProvenance
+
+/**
+ * The URL of the [RepositoryProvenance] the snippet choice applies to.
+ */
+data class Provenance(val url: String)

model/src/main/kotlin/config/snippet/SnippetChoice.kt

@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2024 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * 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
+ *
+ *     https://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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config.snippet
+
+import org.ossreviewtoolkit.model.TextLocation
+
+/**
+ * A snippet choice for a given source file.
+ */
+data class SnippetChoice(
+    /**
+     * The source file criteria for which the snippet choice is made.
+     */
+    val given: Given,
+
+    /**
+     * The snippet criteria to make the snippet choice.
+     */
+    val choice: Choice
+)
+
+/**
+ * A source file criteria for which the snippet choice is made.
+ */
+data class Given(
+    /**
+     * The source file for which the snippet choice is made.
+     */
+    val sourceLocation: TextLocation
+)
+
+/**
+ * A snippet criteria to make the snippet choice.
+ */
+data class Choice(
+    /**
+     * The purl of the snippet chosen by this snippet choice. If [reason] is [SnippetChoiceReason.NO_RELEVANT_FINDING],
+     * it is null.
+     */
+    val purl: String? = null,
+
+    /**
+     * The reason why this snippet choice was made.
+     */
+    val reason: SnippetChoiceReason,
+
+    /**
+     * An optional comment describing the snippet choice.
+     */
+    val comment: String? = null
+)

model/src/main/kotlin/config/snippet/SnippetChoiceReason.kt

@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2024 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * 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
+ *
+ *     https://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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config.snippet
+
+/**
+ * The reason for which the snippet choice has been made.
+ */
+enum class SnippetChoiceReason {
+    /**
+     * No relevant finding has been found for the corresponding source file. All snippets will be ignored.
+     */
+    NO_RELEVANT_FINDING,
+
+    /**
+     * One snippet finding is relevant for the corresponding source file. All other snippets will be ignored.
+     */
+    ORIGINAL_FINDING,
+
+    /**
+     * Other reason.
+     */
+    OTHER
+}

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

@@ -24,12 +24,15 @@ import com.fasterxml.jackson.databind.exc.ValueInstantiationException
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.core.spec.style.WordSpec
 import io.kotest.matchers.collections.haveSize
+import io.kotest.matchers.nulls.beNull
 import io.kotest.matchers.should
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.string.shouldContain
 import io.kotest.matchers.string.shouldNotContain
 
 import org.ossreviewtoolkit.model.Identifier
+import org.ossreviewtoolkit.model.TextLocation
+import org.ossreviewtoolkit.model.config.snippet.SnippetChoiceReason
 import org.ossreviewtoolkit.model.fromYaml
 import org.ossreviewtoolkit.utils.spdx.toSpdx
 import org.ossreviewtoolkit.utils.test.shouldNotBeNull
@@ -121,6 +124,18 @@ class RepositoryConfigurationTest : WordSpec({
                     - given: MPL-2.0 or EPL-1.0
                       choice: MPL-2.0
                     - choice: MPL-2.0 AND MIT
+                snippet_choices:
+                   - provenance:
+                        url: "https://github.com/vdurmont/semver4j.git"
+                     choices:
+                        - given:
+                             source_location:
+                                path: "CHANGELOG.md"
+                                start_line: 2
+                                end_line: 5
+                          choice:
+                             reason: "NO_RELEVANT_FINDING"
+                             comment: "Explain why this location has only false positive snippets"
             """.trimIndent()
 
             val repositoryConfiguration = configuration.fromYaml<RepositoryConfiguration>()
@@ -197,6 +212,20 @@ class RepositoryConfigurationTest : WordSpec({
                     choice shouldBe "MPL-2.0 AND MIT".toSpdx()
                 }
             }
+
+            val snippetChoices = repositoryConfiguration.snippetChoices
+            snippetChoices should haveSize(1)
+
+            with(snippetChoices.first()) {
+                provenance.url shouldBe "https://github.com/vdurmont/semver4j.git"
+                with(choices.first()) {
+                    given.sourceLocation shouldBe TextLocation("CHANGELOG.md", 2, 5)
+
+                    choice.purl should beNull()
+                    choice.reason shouldBe SnippetChoiceReason.NO_RELEVANT_FINDING
+                    choice.comment shouldBe "Explain why this location has only false positive snippets"
+                }
+            }
         }
     }
 })

scanner/src/main/kotlin/ScanContext.kt

@@ -25,6 +25,7 @@ import org.ossreviewtoolkit.model.Package
 import org.ossreviewtoolkit.model.PackageType
 import org.ossreviewtoolkit.model.config.Excludes
 import org.ossreviewtoolkit.model.config.ScannerConfiguration
+import org.ossreviewtoolkit.model.config.SnippetChoices
 import org.ossreviewtoolkit.utils.spdx.SpdxExpression
 
 /**
@@ -60,5 +61,10 @@ data class ScanContext(
      * The packages known to be covered in the context of this scan. For package scanners, this is the list of packages
      * that have the same provenance as the reference package.
      */
-    val coveredPackages: List<Package> = emptyList()
+    val coveredPackages: List<Package> = emptyList(),
+
+    /**
+     * The [SnippetChoices] of the project to scan.
+     */
+    val snippetChoices: List<SnippetChoices> = emptyList()
 )

scanner/src/main/kotlin/Scanner.kt

@@ -115,7 +115,8 @@ class Scanner(
                 ortResult.labels + labels,
                 PackageType.PROJECT,
                 ortResult.repository.config.excludes,
-                scannerConfig.detectedLicenseMapping
+                scannerConfig.detectedLicenseMapping,
+                snippetChoices = ortResult.repository.config.snippetChoices
             )
         )
 
@@ -127,7 +128,8 @@ class Scanner(
                 ortResult.labels,
                 PackageType.PACKAGE,
                 ortResult.repository.config.excludes,
-                scannerConfig.detectedLicenseMapping
+                scannerConfig.detectedLicenseMapping,
+                snippetChoices = ortResult.repository.config.snippetChoices
             )
         )