Status code docs improvements

cli/src/funTest/kotlin/OrtMainFunTest.kt

@@ -39,11 +39,11 @@ import org.ossreviewtoolkit.model.OrtResult
 import org.ossreviewtoolkit.model.config.OrtConfiguration
 import org.ossreviewtoolkit.model.config.OrtConfigurationWrapper
 import org.ossreviewtoolkit.model.config.ProviderPluginConfiguration
-import org.ossreviewtoolkit.model.config.REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.model.readValue
 import org.ossreviewtoolkit.model.toYaml
 import org.ossreviewtoolkit.model.writeValue
 import org.ossreviewtoolkit.utils.common.EnvironmentVariableFilter
+import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.test.getAssetFile
 import org.ossreviewtoolkit.utils.test.matchExpectedResult
 import org.ossreviewtoolkit.utils.test.patchActualResult
@@ -228,7 +228,7 @@ class OrtMainFunTest : StringSpec() {
         }
 
         "EnvironmentVariableFilter is correctly initialized" {
-            val referenceConfigFile = File("../model/src/main/resources/$REFERENCE_CONFIG_FILENAME").absolutePath
+            val referenceConfigFile = File("../model/src/main/resources/$ORT_REFERENCE_CONFIG_FILENAME").absolutePath
 
             OrtMain().test(
                 "-c", referenceConfigFile,

integrations/jenkins/Jenkinsfile

@@ -28,7 +28,8 @@ final DOCKER_BUILD_ARGS = '--build-arg http_proxy=$http_proxy --build-arg https_
 // Disable the entry point to work around https://issues.jenkins-ci.org/browse/JENKINS-51307.
 final DOCKER_RUN_ARGS = '-e http_proxy -e https_proxy --entrypoint=""'
 
-// The status code ORT commands return for failures (like rule violations), not errors (like existing output files).
+// The minimum status code ORT CLI commands return on exit for failures (like rule violations), not errors (like
+// existing output files).
 final ORT_FAILURE_STATUS_CODE = 2
 
 @NonCPS

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

@@ -30,6 +30,7 @@ import org.apache.logging.log4j.kotlin.logger
 
 import org.ossreviewtoolkit.model.Severity
 import org.ossreviewtoolkit.utils.common.EnvironmentVariableFilter
+import org.ossreviewtoolkit.utils.ort.ORT_FAILURE_STATUS_CODE
 import org.ossreviewtoolkit.utils.ort.ORT_PACKAGE_CONFIGURATIONS_DIRNAME
 import org.ossreviewtoolkit.utils.ort.ORT_PACKAGE_CURATIONS_DIRNAME
 import org.ossreviewtoolkit.utils.ort.ORT_PACKAGE_CURATIONS_FILENAME
@@ -100,12 +101,14 @@ data class OrtConfiguration(
     ),
 
     /**
-     * The threshold from which on issues count as severe.
+     * The threshold from which on issues count as severe. Severe issues cause the status code on exit of the CLI
+     * commands to be at least [ORT_FAILURE_STATUS_CODE].
      */
     val severeIssueThreshold: Severity = Severity.WARNING,
 
     /**
-     * The threshold from which on rule violations count as severe.
+     * The threshold from which on rule violations count as severe. Severe rule violations cause the status code on exit
+     * of the CLI commands to be at least [ORT_FAILURE_STATUS_CODE].
      */
     val severeRuleViolationThreshold: Severity = Severity.WARNING,
 
@@ -192,8 +195,3 @@ data class OrtConfiguration(
 data class OrtConfigurationWrapper(
     val ort: OrtConfiguration
 )
-
-/**
- * The filename of the reference configuration file.
- */
-const val REFERENCE_CONFIG_FILENAME = "reference.yml"

model/src/test/kotlin/JsonSchemaTest.kt

@@ -29,10 +29,10 @@ import io.kotest.matchers.should
 
 import java.io.File
 
-import org.ossreviewtoolkit.model.config.REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.ort.ORT_LICENSE_CLASSIFICATIONS_FILENAME
 import org.ossreviewtoolkit.utils.ort.ORT_PACKAGE_CONFIGURATION_FILENAME
 import org.ossreviewtoolkit.utils.ort.ORT_PACKAGE_CURATIONS_FILENAME
+import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.ort.ORT_REPO_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.ort.ORT_RESOLUTIONS_FILENAME
 
@@ -88,7 +88,7 @@ class JsonSchemaTest : StringSpec({
 
     "The embedded reference configuration validates successfully" {
         val ortConfigurationSchema = File("../integrations/schemas/ort-configuration-schema.json").toURI()
-        val referenceConfigFile = File("src/main/resources/$REFERENCE_CONFIG_FILENAME").toJsonNode()
+        val referenceConfigFile = File("src/main/resources/$ORT_REFERENCE_CONFIG_FILENAME").toJsonNode()
 
         val errors = schemaV7.getSchema(ortConfigurationSchema).validate(referenceConfigFile)
 

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

@@ -41,12 +41,13 @@ import java.lang.IllegalArgumentException
 import org.ossreviewtoolkit.model.Severity
 import org.ossreviewtoolkit.model.SourceCodeOrigin
 import org.ossreviewtoolkit.utils.common.EnvironmentVariableFilter
+import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.test.shouldNotBeNull
 
 class OrtConfigurationTest : WordSpec({
     "OrtConfiguration" should {
         "be deserializable from YAML" {
-            val refConfig = File("src/main/resources/$REFERENCE_CONFIG_FILENAME")
+            val refConfig = File("src/main/resources/$ORT_REFERENCE_CONFIG_FILENAME")
             val ortConfig = OrtConfiguration.load(file = refConfig)
 
             ortConfig.allowedProcessEnvironmentVariableNames should containExactlyInAnyOrder("PASSPORT", "USER_HOME")

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

@@ -26,6 +26,7 @@ import java.io.File
 
 import org.ossreviewtoolkit.model.fromYaml
 import org.ossreviewtoolkit.model.toYaml
+import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.test.shouldNotBeNull
 
 class ReporterConfigurationTest : WordSpec({
@@ -42,7 +43,7 @@ class ReporterConfigurationTest : WordSpec({
  * Load the ORT reference configuration and extract the reporter configuration.
  */
 private fun loadReporterConfig(): ReporterConfiguration =
-    OrtConfiguration.load(file = File("src/main/resources/$REFERENCE_CONFIG_FILENAME")).reporter
+    OrtConfiguration.load(file = File("src/main/resources/$ORT_REFERENCE_CONFIG_FILENAME")).reporter
 
 /**
  * Perform a serialization round-trip of the given reporter [config] and return the result. This is used to check

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

@@ -31,11 +31,12 @@ import java.io.File
 
 import org.ossreviewtoolkit.model.readValue
 import org.ossreviewtoolkit.model.writeValue
+import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME
 
 class ScannerConfigurationTest : WordSpec({
     "ScannerConfiguration" should {
         "support a serialization round-trip via an ObjectMapper" {
-            val ortConfig = OrtConfiguration.load(file = File("src/main/resources/$REFERENCE_CONFIG_FILENAME"))
+            val ortConfig = OrtConfiguration.load(file = File("src/main/resources/$ORT_REFERENCE_CONFIG_FILENAME"))
             val rereadOrtConfig = tempfile(null, ".yml").run {
                 writeValue(ortConfig)
                 readValue<OrtConfiguration>()

plugins/commands/advisor/src/main/kotlin/AdvisorCommand.kt

@@ -52,6 +52,7 @@ import org.ossreviewtoolkit.plugins.commands.api.utils.readOrtResult
 import org.ossreviewtoolkit.plugins.commands.api.utils.writeOrtResult
 import org.ossreviewtoolkit.utils.common.expandTilde
 import org.ossreviewtoolkit.utils.common.safeMkdirs
+import org.ossreviewtoolkit.utils.ort.ORT_FAILURE_STATUS_CODE
 import org.ossreviewtoolkit.utils.ort.ORT_RESOLUTIONS_FILENAME
 import org.ossreviewtoolkit.utils.ort.ortConfigDirectory
 
@@ -156,6 +157,6 @@ class AdvisorCommand : OrtCommand(
         val resolutionProvider = DefaultResolutionProvider.create(ortResultOutput, resolutionsFile)
         val issues = advisorRun.results.getIssues().flatMap { it.value }
         SeverityStatsPrinter(terminal, resolutionProvider).stats(issues)
-            .print().conclude(ortConfig.severeIssueThreshold, 2)
+            .print().conclude(ortConfig.severeIssueThreshold, ORT_FAILURE_STATUS_CODE)
     }
 }

plugins/commands/analyzer/src/main/kotlin/AnalyzerCommand.kt

@@ -56,6 +56,7 @@ import org.ossreviewtoolkit.plugins.packagecurationproviders.api.PackageCuration
 import org.ossreviewtoolkit.plugins.packagecurationproviders.api.SimplePackageCurationProvider
 import org.ossreviewtoolkit.utils.common.expandTilde
 import org.ossreviewtoolkit.utils.common.safeMkdirs
+import org.ossreviewtoolkit.utils.ort.ORT_FAILURE_STATUS_CODE
 import org.ossreviewtoolkit.utils.ort.ORT_REPO_CONFIG_FILENAME
 import org.ossreviewtoolkit.utils.ort.ORT_RESOLUTIONS_FILENAME
 import org.ossreviewtoolkit.utils.ort.ortConfigDirectory
@@ -227,6 +228,6 @@ class AnalyzerCommand : OrtCommand(
         val resolutionProvider = DefaultResolutionProvider.create(ortResult, resolutionsFile)
         val issues = analyzerRun.result.getAllIssues().flatMap { it.value }
         SeverityStatsPrinter(terminal, resolutionProvider).stats(issues)
-            .print().conclude(ortConfig.severeIssueThreshold, 2)
+            .print().conclude(ortConfig.severeIssueThreshold, ORT_FAILURE_STATUS_CODE)
     }
 }

plugins/commands/config/src/main/kotlin/ConfigCommand.kt

@@ -30,10 +30,10 @@ import com.github.ajalt.clikt.parameters.types.file
 
 import org.ossreviewtoolkit.model.config.OrtConfiguration
 import org.ossreviewtoolkit.model.config.OrtConfigurationWrapper
-import org.ossreviewtoolkit.model.config.REFERENCE_CONFIG_FILENAME
 import org.ossreviewtoolkit.plugins.commands.api.OrtCommand
 import org.ossreviewtoolkit.utils.common.collectMessages
 import org.ossreviewtoolkit.utils.common.expandTilde
+import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME
 
 class ConfigCommand : OrtCommand(
     name = "config",
@@ -84,7 +84,7 @@ class ConfigCommand : OrtCommand(
         if (showReference) {
             echo("The reference configuration is:")
             echo()
-            echo(javaClass.getResource("/$REFERENCE_CONFIG_FILENAME").readText())
+            echo(javaClass.getResource("/$ORT_REFERENCE_CONFIG_FILENAME").readText())
         }
 
         checkSyntax?.run {

plugins/commands/scanner/src/main/kotlin/ScannerCommand.kt

@@ -63,6 +63,7 @@ import org.ossreviewtoolkit.scanner.provenance.DefaultProvenanceDownloader
 import org.ossreviewtoolkit.scanner.utils.DefaultWorkingTreeCache
 import org.ossreviewtoolkit.utils.common.expandTilde
 import org.ossreviewtoolkit.utils.common.safeMkdirs
+import org.ossreviewtoolkit.utils.ort.ORT_FAILURE_STATUS_CODE
 import org.ossreviewtoolkit.utils.ort.ORT_RESOLUTIONS_FILENAME
 import org.ossreviewtoolkit.utils.ort.ortConfigDirectory
 
@@ -154,7 +155,7 @@ class ScannerCommand : OrtCommand(
         val resolutionProvider = DefaultResolutionProvider.create(ortResult, resolutionsFile)
         val issues = scannerRun.getIssues().flatMap { it.value }
         SeverityStatsPrinter(terminal, resolutionProvider).stats(issues)
-            .print().conclude(ortConfig.severeIssueThreshold, 2)
+            .print().conclude(ortConfig.severeIssueThreshold, ORT_FAILURE_STATUS_CODE)
     }
 
     private fun runScanners(

utils/ort/src/main/kotlin/Constants.kt

@@ -49,6 +49,11 @@ const val ORT_DATA_DIR_ENV_NAME = "ORT_DATA_DIR"
  */
 const val ORT_CONFIG_FILENAME = "config.yml"
 
+/**
+ * The filename of the reference configuration file.
+ */
+const val ORT_REFERENCE_CONFIG_FILENAME = "reference.yml"
+
 /**
  * The name of the ORT copyright garbage configuration file.
  */
@@ -108,3 +113,9 @@ const val ORT_EVALUATOR_RULES_FILENAME = "evaluator.rules.kts"
  * The name of the ORT notifier script.
  */
 const val ORT_NOTIFIER_SCRIPT_FILENAME = "notifier.notifications.kts"
+
+/**
+ * The minimum status code ORT CLI commands return on exit for failures (like rule violations), not errors (like
+ * existing output files).
+ */
+const val ORT_FAILURE_STATUS_CODE = 2