feat(api): Implement api endpoint and service for handling Issues

Add an endpoint to retrieve issues, their source and affected packages
for an ORT run.

Resolves #405.

Signed-off-by: Marcel Bochtler <marcel.bochtler@bosch.com>
Signed-off-by: Wolfgang Klenk <wolfgang.klenk2@bosch.com>

api/v1/mapping/src/commonMain/kotlin/Mappings.kt

@@ -36,6 +36,7 @@ import org.eclipse.apoapsis.ortserver.api.v1.model.ExtendedRepositoryType as Api
 import org.eclipse.apoapsis.ortserver.api.v1.model.Identifier as ApiIdentifier
 import org.eclipse.apoapsis.ortserver.api.v1.model.InfrastructureService as ApiInfrastructureService
 import org.eclipse.apoapsis.ortserver.api.v1.model.Issue as ApiIssue
+import org.eclipse.apoapsis.ortserver.api.v1.model.IssueWithIdentifier as ApiIssueWithIdentifier
 import org.eclipse.apoapsis.ortserver.api.v1.model.JiraNotificationConfiguration as ApiJiraNotificationConfiguration
 import org.eclipse.apoapsis.ortserver.api.v1.model.JiraRestClientConfiguration as ApiJiraRestClientConfiguration
 import org.eclipse.apoapsis.ortserver.api.v1.model.JobConfigurations as ApiJobConfigurations
@@ -88,6 +89,7 @@ import org.eclipse.apoapsis.ortserver.model.EvaluatorJob
 import org.eclipse.apoapsis.ortserver.model.EvaluatorJobConfiguration
 import org.eclipse.apoapsis.ortserver.model.InfrastructureService
 import org.eclipse.apoapsis.ortserver.model.InfrastructureServiceDeclaration
+import org.eclipse.apoapsis.ortserver.model.IssueWithIdentifier
 import org.eclipse.apoapsis.ortserver.model.JiraNotificationConfiguration
 import org.eclipse.apoapsis.ortserver.model.JiraRestClientConfiguration
 import org.eclipse.apoapsis.ortserver.model.JobConfigurations
@@ -472,6 +474,8 @@ fun ApiScannerJobConfiguration.mapToModel() = ScannerJobConfiguration(
 
 fun Secret.mapToApi() = ApiSecret(name, description)
 
+fun IssueWithIdentifier.mapToApi() = ApiIssueWithIdentifier(issue.mapToApi(), identifier?.mapToApi())
+
 fun VulnerabilityWithIdentifier.mapToApi() =
     ApiVulnerabilityWithIdentifier(vulnerability.mapToApi(), identifier.mapToApi())
 

api/v1/model/src/commonMain/kotlin/IssueWithIdentifier.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2024 The ORT Server Authors (See <https://github.com/eclipse-apoapsis/ort-server/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.eclipse.apoapsis.ortserver.api.v1.model
+
+import kotlinx.serialization.Serializable
+
+/**
+ * A union data class to associate a [Issue] with an [Identifier].
+ */
+@Serializable
+data class IssueWithIdentifier(
+    val issue: Issue,
+    val identifier: Identifier?
+)

core/src/main/kotlin/api/RunsRoute.kt

@@ -39,6 +39,7 @@ import org.eclipse.apoapsis.ortserver.api.v1.mapping.mapToApi
 import org.eclipse.apoapsis.ortserver.api.v1.mapping.mapToModel
 import org.eclipse.apoapsis.ortserver.api.v1.model.SortDirection
 import org.eclipse.apoapsis.ortserver.api.v1.model.SortProperty
+import org.eclipse.apoapsis.ortserver.core.apiDocs.getIssuesByRunId
 import org.eclipse.apoapsis.ortserver.core.apiDocs.getLogsByRunId
 import org.eclipse.apoapsis.ortserver.core.apiDocs.getOrtRunById
 import org.eclipse.apoapsis.ortserver.core.apiDocs.getPackagesByRunId
@@ -52,11 +53,13 @@ import org.eclipse.apoapsis.ortserver.dao.QueryParametersException
 import org.eclipse.apoapsis.ortserver.logaccess.LogFileService
 import org.eclipse.apoapsis.ortserver.logaccess.LogLevel
 import org.eclipse.apoapsis.ortserver.logaccess.LogSource
+import org.eclipse.apoapsis.ortserver.model.IssueWithIdentifier
 import org.eclipse.apoapsis.ortserver.model.OrtRun
 import org.eclipse.apoapsis.ortserver.model.VulnerabilityWithIdentifier
 import org.eclipse.apoapsis.ortserver.model.authorization.RepositoryPermission
 import org.eclipse.apoapsis.ortserver.model.repositories.OrtRunRepository
 import org.eclipse.apoapsis.ortserver.model.runs.Package
+import org.eclipse.apoapsis.ortserver.services.IssueService
 import org.eclipse.apoapsis.ortserver.services.PackageService
 import org.eclipse.apoapsis.ortserver.services.ReportStorageService
 import org.eclipse.apoapsis.ortserver.services.RepositoryService
@@ -68,6 +71,7 @@ import org.koin.ktor.ext.inject
  * API for the run's endpoint. This endpoint provides information related to ORT runs and their results.
  */
 fun Route.runs() = route("runs/{runId}") {
+    val issueService by inject<IssueService>()
     val ortRunRepository by inject<OrtRunRepository>()
     val repositoryService by inject<RepositoryService>()
     val vulnerabilityService by inject<VulnerabilityService>()
@@ -115,6 +119,22 @@ fun Route.runs() = route("runs/{runId}") {
         }
     }
 
+    route("issues") {
+        get(getIssuesByRunId) {
+            call.forRun(ortRunRepository) { ortRun ->
+                requirePermission(RepositoryPermission.READ_ORT_RUNS.roleName(ortRun.repositoryId))
+
+                val pagingOptions = call.pagingOptions(SortProperty("timestamp", SortDirection.DESCENDING))
+
+                val issueForOrtRun = issueService.listForOrtRunId(ortRun.id, pagingOptions.mapToModel())
+
+                val pagedResponse = issueForOrtRun.mapToApi(IssueWithIdentifier::mapToApi)
+
+                call.respond(HttpStatusCode.OK, pagedResponse)
+            }
+        }
+    }
+
     route("vulnerabilities") {
         get(getVulnerabilitiesByRunId) {
             call.forRun(ortRunRepository) { ortRun ->

core/src/main/kotlin/apiDocs/RunsDocs.kt

@@ -27,13 +27,16 @@ import kotlinx.datetime.Clock
 
 import org.eclipse.apoapsis.ortserver.api.v1.model.ExtendedRepositoryType
 import org.eclipse.apoapsis.ortserver.api.v1.model.Identifier
+import org.eclipse.apoapsis.ortserver.api.v1.model.Issue
+import org.eclipse.apoapsis.ortserver.api.v1.model.IssueWithIdentifier
 import org.eclipse.apoapsis.ortserver.api.v1.model.OrtRun
 import org.eclipse.apoapsis.ortserver.api.v1.model.OrtRunStatus
 import org.eclipse.apoapsis.ortserver.api.v1.model.Package
 import org.eclipse.apoapsis.ortserver.api.v1.model.PagedResponse
 import org.eclipse.apoapsis.ortserver.api.v1.model.PagingData
 import org.eclipse.apoapsis.ortserver.api.v1.model.ProcessedDeclaredLicense
 import org.eclipse.apoapsis.ortserver.api.v1.model.RemoteArtifact
+import org.eclipse.apoapsis.ortserver.api.v1.model.Severity
 import org.eclipse.apoapsis.ortserver.api.v1.model.SortDirection
 import org.eclipse.apoapsis.ortserver.api.v1.model.SortProperty
 import org.eclipse.apoapsis.ortserver.api.v1.model.VcsInfo
@@ -150,6 +153,50 @@ val getLogsByRunId: OpenApiRoute.() -> Unit = {
     }
 }
 
+val getIssuesByRunId: OpenApiRoute.() -> Unit = {
+    operationId = "GetIssuesByRunId"
+    summary = "Get the issues of an ORT run."
+    tags = listOf("Issues")
+
+    request {
+        pathParameter<Long>("runId") {
+            description = "The ID of the ORT run."
+        }
+
+        standardListQueryParameters()
+    }
+
+    response {
+        HttpStatusCode.OK to {
+            description = "Success."
+            jsonBody<PagedResponse<IssueWithIdentifier>> {
+                example("Get issues for an ORT run") {
+                    value = PagedResponse(
+                        listOf(
+                            Issue(
+                                message = "An issue",
+                                severity = Severity.ERROR,
+                                source = "source",
+                                timestamp = Clock.System.now()
+                            )
+                        ),
+                        PagingData(
+                            limit = 20,
+                            offset = 0,
+                            totalCount = 1,
+                            sortProperties = listOf(SortProperty("timestamp", SortDirection.DESCENDING))
+                        )
+                    )
+                }
+            }
+        }
+
+        HttpStatusCode.NotFound to {
+            description = "The ORT run does not exist."
+        }
+    }
+}
+
 val getVulnerabilitiesByRunId: OpenApiRoute.() -> Unit = {
     operationId = "GetVulnerabilitiesByRunId"
     summary = "Get the vulnerabilities found in an ORT run."

core/src/main/kotlin/di/Module.kt

@@ -65,6 +65,7 @@ import org.eclipse.apoapsis.ortserver.secrets.SecretStorage
 import org.eclipse.apoapsis.ortserver.services.AuthorizationService
 import org.eclipse.apoapsis.ortserver.services.DefaultAuthorizationService
 import org.eclipse.apoapsis.ortserver.services.InfrastructureServiceService
+import org.eclipse.apoapsis.ortserver.services.IssueService
 import org.eclipse.apoapsis.ortserver.services.OrganizationService
 import org.eclipse.apoapsis.ortserver.services.PackageService
 import org.eclipse.apoapsis.ortserver.services.ProductService
@@ -124,6 +125,7 @@ fun ortServerModule(config: ApplicationConfig) = module {
     single { RepositoryService(get(), get(), get(), get(), get(), get(), get(), get(), get(), get()) }
     single { SecretService(get(), get(), get(), get()) }
     single { VulnerabilityService(get()) }
+    single { IssueService(get()) }
     single { PackageService(get()) }
     singleOf(::ReportStorageService)
     singleOf(::InfrastructureServiceService)