refactor(license-fact-provider): Ensure that license texts are not blank

Ensure in all license fact providers that returned license texts are not
blank. Use a `LicenseText` value class to model this in the API of
`getLicenseText()`. This way all consumers can rely on the text not being
blank, and that if a provider violates that constraint, it will fail
immediately instead of leading to follow-up errors.

Signed-off-by: Martin Nonnenmacher <[email protected]>
Signed-off-by: Sebastian Schuberth <[email protected]>

Author: sschuberth

plugins/license-fact-providers/api/src/main/kotlin/CompositeLicenseFactProvider.kt

@@ -30,7 +30,7 @@ class CompositeLicenseFactProvider(
      *  providers: the first provider in the list that has a fact for a given license ID will be used.
      */
     private val providers: List<LicenseFactProvider>
-) : LicenseFactProvider {
+) : LicenseFactProvider() {
     override val descriptor = PluginDescriptor(
         id = "Composite",
         displayName = "Composite License Fact Provider",

plugins/license-fact-providers/api/src/main/kotlin/LicenseFactProvider.kt

@@ -22,10 +22,15 @@ package org.ossreviewtoolkit.plugins.licensefactproviders.api
 import org.ossreviewtoolkit.plugins.api.Plugin
 
 /** A provider for license facts. */
-interface LicenseFactProvider : Plugin {
-    /** Return the license text for the given [licenseId], or `null` if the license text is not available. */
-    fun getLicenseText(licenseId: String): String?
+abstract class LicenseFactProvider : Plugin {
+    /** Return the [LicenseText] for the given [licenseId], or `null` if no valid text is available. */
+    abstract fun getLicenseText(licenseId: String): LicenseText?
+
+    /** Return a non-blank license text for the given [licenseId], or `null` if no valid text is available. */
+    @Deprecated("Java-only API", level = DeprecationLevel.HIDDEN)
+    @JvmName("getLicenseText")
+    fun getNonBlankLicenseText(licenseId: String): String? = getLicenseText(licenseId)?.text
 
     /** Return `true´ if this provider has a license text for the given [licenseId]. */
-    fun hasLicenseText(licenseId: String): Boolean
+    abstract fun hasLicenseText(licenseId: String): Boolean
 }

plugins/license-fact-providers/api/src/main/kotlin/LicenseText.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright (C) 2025 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.plugins.licensefactproviders.api
+
+/** A value class to represent a valid license text. It guarantees that the text is not blank. */
+@JvmInline
+value class LicenseText(val text: String) {
+    init {
+        require(text.isNotBlank()) { "The license text must not be blank." }
+    }
+}

plugins/license-fact-providers/dir/src/main/kotlin/DirLicenseFactProvider.kt

@@ -27,6 +27,7 @@ import org.ossreviewtoolkit.plugins.api.OrtPlugin
 import org.ossreviewtoolkit.plugins.api.PluginDescriptor
 import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProvider
 import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProviderFactory
+import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseText
 import org.ossreviewtoolkit.utils.ort.ORT_CUSTOM_LICENSE_TEXTS_DIRNAME
 import org.ossreviewtoolkit.utils.ort.ortConfigDirectory
 
@@ -59,16 +60,20 @@ class DefaultDirLicenseFactProvider(descriptor: PluginDescriptor = DefaultDirLic
 open class DirLicenseFactProvider(
     override val descriptor: PluginDescriptor = DirLicenseFactProviderFactory.descriptor,
     config: DirLicenseFactProviderConfig
-) : LicenseFactProvider {
+) : LicenseFactProvider() {
     private val licenseTextDir = File(config.licenseTextDir).also {
         if (!it.isDirectory) {
             logger.warn { "The license text directory '${it.absolutePath}' does not exist or is not a directory." }
         }
     }
 
-    override fun getLicenseText(licenseId: String) = getLicenseTextFile(licenseId)?.readText()
+    override fun getLicenseText(licenseId: String) = getLicenseTextFile(licenseId)?.readText()?.let { LicenseText(it) }
 
     override fun hasLicenseText(licenseId: String) = getLicenseTextFile(licenseId) != null
 
-    private fun getLicenseTextFile(licenseId: String) = licenseTextDir.resolve(licenseId).takeIf { it.isFile }
+    private fun getLicenseTextFile(licenseId: String) =
+        licenseTextDir.resolve(licenseId).takeIf { it.isFile && it.isNotBlank }
 }
+
+private val File.isNotBlank: Boolean
+    get() = useLines { lines -> lines.any { line -> line.any { !it.isWhitespace() } } }

plugins/license-fact-providers/dir/src/test/kotlin/DirLicenseFactProviderTest.kt

@@ -33,14 +33,23 @@ class DirLicenseFactProviderTest : WordSpec({
 
             val provider = DirLicenseFactProviderFactory.create(licenseTextDir = licenseDir.absolutePath)
 
-            provider.getLicenseText("LicenseRef-custom-license") shouldBe "custom license text"
+            provider.getLicenseText("LicenseRef-custom-license")?.text shouldBe "custom license text"
         }
 
         "return null if no license text is found" {
             val provider = DirLicenseFactProviderFactory.create(licenseTextDir = tempdir().absolutePath)
 
             provider.getLicenseText("LicenseRef-non-existing-license") should beNull()
         }
+
+        "return null if the license text file is blank" {
+            val licenseDir = tempdir()
+            licenseDir.resolve("LicenseRef-blank-license").writeText("   \n   ")
+
+            val provider = DirLicenseFactProviderFactory.create(licenseTextDir = licenseDir.absolutePath)
+
+            provider.getLicenseText("LicenseRef-blank-license") should beNull()
+        }
     }
 
     "hasLicenseText()" should {
@@ -58,5 +67,14 @@ class DirLicenseFactProviderTest : WordSpec({
 
             provider.hasLicenseText("LicenseRef-non-existing-license") shouldBe false
         }
+
+        "return false if the license text file is blank" {
+            val licenseDir = tempdir()
+            licenseDir.resolve("LicenseRef-blank-license").writeText("   \n   ")
+
+            val provider = DirLicenseFactProviderFactory.create(licenseTextDir = licenseDir.absolutePath)
+
+            provider.hasLicenseText("LicenseRef-blank-license") shouldBe false
+        }
     }
 })

plugins/license-fact-providers/scancode/src/funTest/kotlin/ScanCodeLicenseFactProviderFunTest.kt

@@ -37,7 +37,7 @@ class ScanCodeLicenseFactProviderFunTest : WordSpec({
 
             val provider = ScanCodeLicenseFactProviderFactory.create(scanCodeLicenseTextDir = licenseDir.absolutePath)
 
-            provider.getLicenseText("test") shouldBe "custom license text"
+            provider.getLicenseText("test")?.text shouldBe "custom license text"
         }
 
         "remove YAML front matter from the license text" {
@@ -54,14 +54,14 @@ class ScanCodeLicenseFactProviderFunTest : WordSpec({
 
             val provider = ScanCodeLicenseFactProviderFactory.create(scanCodeLicenseTextDir = licenseDir.absolutePath)
 
-            provider.getLicenseText("test") shouldBe "custom license text"
+            provider.getLicenseText("test")?.text shouldBe "custom license text"
         }
 
         "read license texts from the detected ScanCode license directory" {
             val provider = ScanCodeLicenseFactProviderFactory.create()
 
             provider.getLicenseText("MIT") shouldNotBeNull {
-                this should startWith("Permission is hereby granted, free of charge, to any person obtaining")
+                text should startWith("Permission is hereby granted, free of charge, to any person obtaining")
             }
         }
 
@@ -70,6 +70,22 @@ class ScanCodeLicenseFactProviderFunTest : WordSpec({
 
             provider.getLicenseText("UnknownLicense") should beNull()
         }
+
+        "return null if the license file contains only YAML front matter" {
+            val licenseDir = tempdir()
+            (licenseDir / "test.LICENSE").writeText(
+                """
+                |---
+                |key: value
+                |---
+                |
+                """.trimMargin()
+            )
+
+            val provider = ScanCodeLicenseFactProviderFactory.create(scanCodeLicenseTextDir = licenseDir.absolutePath)
+
+            provider.getLicenseText("test") should beNull()
+        }
     }
 
     "hasLicenseText()" should {
@@ -84,5 +100,21 @@ class ScanCodeLicenseFactProviderFunTest : WordSpec({
 
             provider.hasLicenseText("UnknownLicense") shouldBe false
         }
+
+        "return false if the license file contains only YAML front matter" {
+            val licenseDir = tempdir()
+            (licenseDir / "test.LICENSE").writeText(
+                """
+                |---
+                |key: value
+                |---
+                |
+                """.trimMargin()
+            )
+
+            val provider = ScanCodeLicenseFactProviderFactory.create(scanCodeLicenseTextDir = licenseDir.absolutePath)
+
+            provider.hasLicenseText("test") shouldBe false
+        }
     }
 })

plugins/license-fact-providers/scancode/src/main/kotlin/ScanCodeLicenseFactProvider.kt

@@ -27,6 +27,7 @@ import org.ossreviewtoolkit.plugins.api.OrtPlugin
 import org.ossreviewtoolkit.plugins.api.PluginDescriptor
 import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProvider
 import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProviderFactory
+import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseText
 import org.ossreviewtoolkit.utils.common.Os
 import org.ossreviewtoolkit.utils.common.realFile
 
@@ -50,7 +51,7 @@ data class ScanCodeLicenseFactProviderConfig(
 class ScanCodeLicenseFactProvider(
     override val descriptor: PluginDescriptor = ScanCodeLicenseFactProviderFactory.descriptor,
     private val config: ScanCodeLicenseFactProviderConfig
-) : LicenseFactProvider {
+) : LicenseFactProvider() {
     /**
      * The directory that contains the ScanCode license texts. This is located using a heuristic based on the path of
      * the ScanCode binary.
@@ -118,21 +119,36 @@ class ScanCodeLicenseFactProvider(
             "${licenseId.removePrefix("LicenseRef-scancode-").lowercase()}.LICENSE"
         }
 
-        return scanCodeLicenseTextDir?.resolve(filename)?.takeIf { it.isFile }
+        return scanCodeLicenseTextDir?.resolve(filename)?.takeIf { it.isFile && it.isNotBlank }
     }
 
-    override fun getLicenseText(licenseId: String): String? =
-        getLicenseTextFile(licenseId)?.readText()?.removeYamlFrontMatter()
+    override fun getLicenseText(licenseId: String) =
+        getLicenseTextFile(licenseId)?.useLines { lines ->
+            lines.skipYamlFrontMatter().joinToString("\n").trimEnd()
+        }?.let {
+            LicenseText(it)
+        }
 
     override fun hasLicenseText(licenseId: String): Boolean = getLicenseTextFile(licenseId) != null
 }
 
-internal fun String.removeYamlFrontMatter(): String {
-    val lines = lines()
-
-    // Remove any YAML front matter enclosed by "---" from ScanCode license files.
-    val licenseLines = lines.takeUnless { it.first() == "---" }
-        ?: lines.drop(1).dropWhile { it != "---" }.drop(1)
+internal fun Sequence<String>.skipYamlFrontMatter(): Sequence<String> {
+    var inFrontMatter = false
 
-    return licenseLines.dropWhile { it.isEmpty() }.joinToString("\n").trimEnd()
+    return filterIndexed { index, line ->
+        if (index == 0 && line == "---") {
+            inFrontMatter = true
+            false
+        } else if (inFrontMatter) {
+            if (line == "---") inFrontMatter = false
+            false
+        } else {
+            true
+        }
+    }.dropWhile {
+        it.isBlank()
+    }
 }
+
+private val File.isNotBlank: Boolean
+    get() = useLines { lines -> lines.skipYamlFrontMatter().any { line -> line.any { !it.isWhitespace() } } }

plugins/license-fact-providers/scancode/src/test/kotlin/ScanCodeLicenseFactProviderTest.kt

@@ -23,8 +23,8 @@ import io.kotest.core.spec.style.WordSpec
 import io.kotest.matchers.shouldBe
 
 class ScanCodeLicenseFactProviderTest : WordSpec({
-    "removeYamlFrontMatter" should {
-        "remove a YAML front matter" {
+    "skipYamlFrontMatter()" should {
+        "skip a YAML front matter" {
             val text = """
                 ---
                 key: alasir
@@ -62,10 +62,6 @@ class ScanCodeLicenseFactProviderTest : WordSpec({
             """.trimIndent()
         }
 
-        "remove trailing whitespace" {
-            "last sentence\n".removeYamlFrontMatter() shouldBe "last sentence"
-        }
-
         "remove leading empty lines" {
             "\nfirst sentence".removeYamlFrontMatter() shouldBe "first sentence"
         }
@@ -75,3 +71,5 @@ class ScanCodeLicenseFactProviderTest : WordSpec({
         }
     }
 })
+
+private fun String.removeYamlFrontMatter() = lineSequence().skipYamlFrontMatter().joinToString("\n")

plugins/license-fact-providers/spdx/src/main/kotlin/SpdxLicenseFactProvider.kt

@@ -25,6 +25,7 @@ import org.ossreviewtoolkit.plugins.api.OrtPlugin
 import org.ossreviewtoolkit.plugins.api.PluginDescriptor
 import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProvider
 import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProviderFactory
+import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseText
 
 @OrtPlugin(
     id = "SPDX",
@@ -34,8 +35,12 @@ import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseFactProvider
 )
 class SpdxLicenseFactProvider(
     override val descriptor: PluginDescriptor = SpdxLicenseFactProviderFactory.descriptor
-) : LicenseFactProvider {
-    override fun getLicenseText(licenseId: String) = getLicenseTextResource(licenseId)?.readText()
+) : LicenseFactProvider() {
+    override fun getLicenseText(licenseId: String) =
+        getLicenseTextResource(licenseId)?.readText()?.let {
+            // It can be safely assumed that the license text is not blank as all SPDX license texts are non-blank.
+            LicenseText(it)
+        }
 
     override fun hasLicenseText(licenseId: String) = getLicenseTextResource(licenseId) != null
 

plugins/license-fact-providers/spdx/src/test/kotlin/SpdxLicenseFactProviderTest.kt

@@ -37,20 +37,20 @@ class SpdxLicenseFactProviderTest : WordSpec({
 
     "getLicenseText()" should {
         "return the license text for Apache-2.0" {
-            val text = provider.getLicenseText(SpdxLicense.APACHE_2_0.id)
-            text should contain("Apache License")
-            text should haveLength(11357)
+            val license = provider.getLicenseText(SpdxLicense.APACHE_2_0.id)
+            license?.text should contain("Apache License")
+            license?.text should haveLength(11357)
         }
 
         "return the license text for all SPDX licenses" {
             enumValues<SpdxLicense>().forAll {
-                provider.getLicenseText(it.id) shouldNot beEmpty()
+                provider.getLicenseText(it.id)?.text shouldNot beEmpty()
             }
         }
 
         "return the license text for all SPDX exceptions" {
             enumValues<SpdxLicenseException>().forAll {
-                provider.getLicenseText(it.id) shouldNot beEmpty()
+                provider.getLicenseText(it.id)?.text shouldNot beEmpty()
             }
         }