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

Prep work for upcoming PR oss-review-toolkit#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,12 @@ data class FileList(
             }
         }
     }
+
+    operator fun plus(other: FileList): FileList {
+        require(provenance == other.provenance) {
+            "Cannot merge FileLists with different provenance: $provenance != ${other.provenance}."
+        }
+
+        return copy(files = files + other.files)
+    }
 }

model/src/main/kotlin/ScanResult.kt

@@ -73,4 +73,19 @@ data class ScanResult(
      */
     fun filterByIgnorePatterns(ignorePatterns: Collection<String>): ScanResult =
         copy(summary = summary.filterByIgnorePatterns(ignorePatterns))
+
+    operator fun plus(other: ScanResult): ScanResult {
+        require(provenance == other.provenance) {
+            "Cannot merge ScanResults with different provenance: $provenance != ${other.provenance}."
+        }
+
+        require(scanner == other.scanner) {
+            "Cannot merge ScanResults with different scanners: $scanner != ${other.scanner}."
+        }
+
+        return copy(
+            summary = summary + other.summary,
+            additionalData = additionalData + other.additionalData
+        )
+    }
 }

model/src/main/kotlin/ScanSummary.kt

@@ -146,6 +146,17 @@ data class ScanSummary(
             issues = issues.filter { it.affectedPath == null || !matcher.matches(it.affectedPath) }
         )
     }
+
+    operator fun plus(other: ScanSummary): ScanSummary {
+        return copy(
+            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,50 @@ data class ScannerRun(
         scanResultsById.mapValues { (_, scanResults) ->
             scanResults.flatMapTo(mutableSetOf()) { it.summary.issues }
         }.zipWithSets(issues)
+
+    operator fun plus(other: ScannerRun): ScannerRun {
+        require(environment == other.environment) {
+            "Cannot merge ScannerRuns with different environments: $environment != ${other.environment}."
+        }
+
+        require(config == other.config) {
+            "Cannot merge ScannerRuns with different configurations: $config != ${other.config}."
+        }
+
+        val mergedFiles = (files.toList() + other.files.toList())
+            .groupBy { it.provenance }
+            .values
+            .map { fileLists ->
+                fileLists.reduce { acc, next -> acc + next }
+            }
+            .toSet()
+
+        val mergedScanResults = (scanResults + other.scanResults)
+            .groupBy { it.provenance to it.scanner }
+            .values
+            .map { scanResults ->
+                scanResults.reduce { acc, next -> acc + next }
+            }
+            .toSet()
+
+        val mergedIssues = (issues.keys union other.issues.keys).associateWith { key ->
+            issues[key].orEmpty() union other.issues[key].orEmpty()
+        }
+
+        val mergedScanners = (scanners.keys union other.scanners.keys).associateWith { key ->
+            scanners[key].orEmpty() union other.scanners[key].orEmpty()
+        }
+
+        return copy(
+            startTime = minOf(startTime, other.startTime),
+            endTime = maxOf(endTime, other.endTime),
+            provenances = provenances + other.provenances,
+            scanResults = mergedScanResults,
+            issues = mergedIssues,
+            scanners = mergedScanners,
+            files = mergedFiles
+        )
+    }
 }
 
 private fun scanResultForProvenanceResolutionIssues(packageProvenance: KnownProvenance?, issues: List<Issue>) =