feat(model): Add + merge operators for scan-domain objects

Prep work for upcoming PR #10502.

* `FileList`, `ScanSummary`, `ScanResult` and `ScannerRun` now
  implement `operator fun plus(...)`, enabling declarative, type-safe
  merging of scan data.
    * Each operator validates invariants (e.g. identical provenance,
      identical scanner / environment / config) and throws an
      `IllegalArgumentException` on mismatch.
    * For compatible objects, collections are union-merged; time ranges
      are widened (`startTime = min`, `endTime = max`).

* `ScannerRun.plus()`
    * Merges file lists and scan results by `provenance to scanner`
      using the new operators.
    * Combines issues / scanners maps by key union.
    * Carries forward earliest start and latest end timestamps.

* **Unit tests**
    * Extensive coverage in `ScannerRunTest` for all merge scenarios,
      including negative cases (different config / environment) and
      positive cases for times, provenances, issues, scanners, file
      lists and scan results.

Signed-off-by: Jonatan Männchen <jonatan@maennchen.ch>

Author: maennchen

model/src/main/kotlin/FileList.kt

@@ -64,4 +64,19 @@ data class FileList(
             }
         }
     }
+
+    /**
+     * Merge this [FileList] with the given [other] [FileList].
+     *
+     * Both [FileList]s must have the same [provenance], otherwise an [IllegalArgumentException] is thrown.
+     */
+    operator fun plus(other: FileList) =
+        FileList(
+            provenance = provenance.also {
+                require(it == other.provenance) {
+                    "Cannot merge FileLists with different provenance: $it != ${other.provenance}."
+                }
+            },
+            files = files + other.files
+        )
 }

model/src/main/kotlin/ScanResult.kt

@@ -73,4 +73,26 @@ data class ScanResult(
      */
     fun filterByIgnorePatterns(ignorePatterns: Collection<String>): ScanResult =
         copy(summary = summary.filterByIgnorePatterns(ignorePatterns))
+
+    /**
+     * Merge this [ScanResult] with the given [other] [ScanResult].
+     *
+     * Both [ScanResult]s must have the same [provenance] and [scanner], otherwise an [IllegalArgumentException] is
+     * thrown.
+     */
+    operator fun plus(other: ScanResult) =
+        ScanResult(
+            provenance = provenance.also {
+                require(it == other.provenance) {
+                    "Cannot merge ScanResults with different provenance: $it != ${other.provenance}."
+                }
+            },
+            scanner = scanner.also {
+                require(it == other.scanner) {
+                    "Cannot merge ScanResults with different scanners: $it != ${other.scanner}."
+                }
+            },
+            summary = summary + other.summary,
+            additionalData = additionalData + other.additionalData
+        )
 }

model/src/main/kotlin/ScanSummary.kt

@@ -146,6 +146,23 @@ data class ScanSummary(
             issues = issues.filter { it.affectedPath == null || !matcher.matches(it.affectedPath) }
         )
     }
+
+    /**
+     * Merge this [ScanSummary] with the given [other] [ScanSummary].
+     *
+     * The [startTime] and [endTime] are widened to the earliest and latest time of both summaries.
+     *
+     * The [licenseFindings], [copyrightFindings], [snippetFindings] and [issues] are merged by concatenation.
+     */
+    operator fun plus(other: ScanSummary) =
+        ScanSummary(
+            startTime = minOf(startTime, other.startTime),
+            endTime = maxOf(endTime, other.endTime),
+            licenseFindings = licenseFindings + other.licenseFindings,
+            copyrightFindings = copyrightFindings + other.copyrightFindings,
+            snippetFindings = snippetFindings + other.snippetFindings,
+            issues = issues + other.issues
+        )
 }
 
 /**

model/src/main/kotlin/ScannerRun.kt

@@ -273,6 +273,53 @@ data class ScannerRun(
         scanResultsById.mapValues { (_, scanResults) ->
             scanResults.flatMapTo(mutableSetOf()) { it.summary.issues }
         }.zipWithSets(issues)
+
+    /**
+     * Merge this [ScannerRun] with the given [other] [ScannerRun].
+     *
+     * Both [ScannerRun]s must have the same [environment] and [config], otherwise an [IllegalArgumentException] is
+     * thrown.
+     *
+     * files and scanResults are merged by their [KnownProvenance]s, while issues and scanners are merged by their
+     * names.
+     *
+     * The [startTime] and [endTime] are widened to the earliest and latest values of both [ScannerRun]s.
+     */
+    operator fun plus(other: ScannerRun): ScannerRun {
+        val mergedFiles = (files + other.files)
+            .groupBy { it.provenance }
+            .values
+            .mapTo(mutableSetOf()) { fileLists ->
+                fileLists.reduce { acc, next -> acc + next }
+            }
+
+        val mergedScanResults = (scanResults + other.scanResults)
+            .groupBy { it.provenance to it.scanner }
+            .values
+            .mapTo(mutableSetOf()) { scanResults ->
+                scanResults.reduce { acc, next -> acc + next }
+            }
+
+        return ScannerRun(
+            startTime = minOf(startTime, other.startTime),
+            endTime = maxOf(endTime, other.endTime),
+            environment = environment.also {
+                require(it == other.environment) {
+                    "Cannot merge ScannerRuns with different environments: $it != ${other.environment}."
+                }
+            },
+            config = config.also {
+                require(it == other.config) {
+                    "Cannot merge ScannerRuns with different configurations: $it != ${other.config}."
+                }
+            },
+            provenances = provenances + other.provenances,
+            scanResults = mergedScanResults,
+            issues = issues.zipWithSets(other.issues),
+            scanners = scanners.zipWithSets(other.scanners),
+            files = mergedFiles
+        )
+    }
 }
 
 private fun scanResultForProvenanceResolutionIssues(packageProvenance: KnownProvenance?, issues: List<Issue>) =