feature: generate change protocol during migration (RDFA-624)

backend/src/main/java/org/rdfarchitect/api/controller/datasets/graphs/migration/MigrationScriptRESTController.java → backend/src/main/java/org/rdfarchitect/api/controller/datasets/graphs/migration/MigrationArtifactsRESTController.java

@@ -26,7 +26,8 @@
 
 import org.apache.jena.riot.RDFFormat;
 import org.rdfarchitect.context.MigrationSessionStore;
-import org.rdfarchitect.services.schemamigration.scriptgeneration.GenerateMigrationScriptUseCase;
+import org.rdfarchitect.services.schemamigration.artifacts.GenerateMigrationReportUseCase;
+import org.rdfarchitect.services.schemamigration.artifacts.GenerateMigrationScriptUseCase;
 import org.rdfarchitect.services.shacl.SHACLExportUseCase;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -35,6 +36,7 @@
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import java.io.ByteArrayOutputStream;
@@ -46,14 +48,15 @@
 
 @RestController
 @RequiredArgsConstructor
-public class MigrationScriptRESTController {
+public class MigrationArtifactsRESTController {
 
     private static final Logger logger =
-            LoggerFactory.getLogger(MigrationScriptRESTController.class);
+            LoggerFactory.getLogger(MigrationArtifactsRESTController.class);
 
     private final GenerateMigrationScriptUseCase generateMigrationScriptUseCase;
     private final SHACLExportUseCase shaclExportUseCase;
     private final MigrationSessionStore migrationSessionStore;
+    private final GenerateMigrationReportUseCase generateMigrationReportUseCase;
 
     @Operation(
             summary = "generate migration script",
@@ -102,4 +105,55 @@ public ResponseEntity<byte[]> generateMigrationScript(
 
         return response;
     }
+
+    @Operation(
+            summary = "generate migration script",
+            description =
+                    "Generates a migration script based on the previously computed migration actions and the shacl shapes of the new schema.",
+            tags = {"migration"},
+            responses = {
+                @ApiResponse(
+                        responseCode = "200",
+                        content = @Content(mediaType = "application/zip"))
+            })
+    @GetMapping("/api/migrations/report")
+    public ResponseEntity<byte[]> generateMigrationReport(
+            @Parameter(description = "The name/url of the inquirer.")
+                    @RequestHeader(value = "origin", required = false, defaultValue = "unknown")
+                    String originURL,
+            @Parameter(
+                            description =
+                                    "Type of the migration report to generate. Can be either SUMMARY or DETAILED.")
+                    @RequestParam(value = "reportType", defaultValue = "SUMMARY")
+                    MigrationReportType reportType) {
+        logger.info("Received GET request: \"/api/migrations/report\" from \"{}\".", originURL);
+
+        var report =
+                switch (reportType) {
+                    case SUMMARY -> generateMigrationReportUseCase.generateSummaryMigrationReport();
+                    case DETAILED ->
+                            generateMigrationReportUseCase.generateDetailedMigrationReport();
+                };
+
+        var body = report.getBytes(StandardCharsets.UTF_8);
+        var headers = new HttpHeaders();
+        headers.setAccessControlExposeHeaders(List.of("Content-disposition"));
+        var response =
+                ResponseEntity.ok()
+                        .headers(headers)
+                        .header(HttpHeaders.CONTENT_DISPOSITION, "migration_report.md")
+                        .contentType(MediaType.APPLICATION_OCTET_STREAM)
+                        .body(body);
+
+        logger.info(
+                "Sending response to GET request: \"/api/migrations/report\" from \"{}\".",
+                originURL);
+
+        return response;
+    }
+
+    public enum MigrationReportType {
+        SUMMARY,
+        DETAILED
+    }
 }

backend/src/main/java/org/rdfarchitect/api/controller/datasets/graphs/migration/MigrationChangesRESTController.java

@@ -0,0 +1,106 @@
+/*
+ *    Copyright (c) 2024-2026 SOPTIM AG
+ *
+ *    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
+ *
+ *        http://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.
+ *
+ */
+
+package org.rdfarchitect.api.controller.datasets.graphs.migration;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+
+import lombok.RequiredArgsConstructor;
+
+import org.rdfarchitect.models.changes.semanticchanges.SemanticClassChange;
+import org.rdfarchitect.models.changes.semanticchanges.SemanticResourceChange;
+import org.rdfarchitect.services.schemamigration.MigrationChangesUseCase;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/migrations/changes")
+@RequiredArgsConstructor
+public class MigrationChangesRESTController {
+
+    private static final Logger logger =
+            LoggerFactory.getLogger(MigrationChangesRESTController.class);
+
+    private final MigrationChangesUseCase migrationChangesUseCase;
+
+    @Operation(
+            summary = "migration changes overview",
+            description = "returns final changes in migration to be displayed for review",
+            tags = {"migration"},
+            responses = {
+                @ApiResponse(
+                        responseCode = "200",
+                        content =
+                                @Content(
+                                        mediaType = "application/json",
+                                        array =
+                                                @ArraySchema(
+                                                        schema =
+                                                                @Schema(
+                                                                        implementation =
+                                                                                SemanticResourceChange
+                                                                                        .class))))
+            })
+    @GetMapping
+    public List<SemanticClassChange> getMigrationChanges(
+            @Parameter(description = "The name/url of the inquirer.")
+                    @RequestHeader(value = "origin", required = false, defaultValue = "unknown")
+                    String originURL) {
+        logger.info("Received GET request: \"/api/migrations/changes\" from \"{}\".", originURL);
+
+        var classes = migrationChangesUseCase.getMigrationChanges();
+
+        logger.info(
+                "Sending response to GET request: \"/api/migrations/changes\" from \"{}\".",
+                originURL);
+
+        return classes;
+    }
+
+    @Operation(
+            summary = "confirm migration changes",
+            description = "Confirms the migration changes including potentially added comments",
+            tags = {"migration"})
+    @PostMapping
+    public void confirmMigrationChanges(
+            @Parameter(description = "The name/url of the inquirer.")
+                    @RequestHeader(value = "origin", required = false, defaultValue = "unknown")
+                    String originURL,
+            @Parameter(description = "The updated class renamings") @RequestBody
+                    List<SemanticClassChange> changes) {
+        logger.info("Received POST request: \"/api/migrations/changes\" from \"{}\".", originURL);
+
+        migrationChangesUseCase.confirmMigrationChanges(changes);
+
+        logger.info(
+                "Sending response to POST request: \"/api/migrations/changes\" from \"{}\".",
+                originURL);
+    }
+}

backend/src/main/java/org/rdfarchitect/api/controller/datasets/graphs/migration/MigrationContextRESTController.java

@@ -89,32 +89,38 @@ public void computeMigrationContext(
                             description =
                                     "URI of graph B. Required together with dataset_b when not uploading graph B as a file.")
                     @RequestParam(required = false)
-                    String graphB) {
+                    String graphB,
+            @Parameter(
+                            description =
+                                    "Whether to ignore prefixes in the comparison and rename detection. Defaults to false.")
+                    @RequestParam(required = false, defaultValue = "false")
+                    boolean ignorePrefixes) {
         logger.info("Received POST request: \"/api/migrations/context\" from \"{}\".", originURL);
 
         // file to file
         if (fileA != null && fileB != null) {
-            setMigrationContextUseCase.setMigrationContext(fileA, fileB);
+            setMigrationContextUseCase.setMigrationContext(fileA, fileB, ignorePrefixes);
         }
         // stored to stored
         else if (datasetA != null && datasetB != null && graphA != null && graphB != null) {
             var extendedGraphURIA = expandURIUseCase.expandUri(datasetA, graphA);
             var extendedGraphURIB = expandURIUseCase.expandUri(datasetB, graphB);
             setMigrationContextUseCase.setMigrationContext(
                     new GraphIdentifier(datasetA, extendedGraphURIA),
-                    new GraphIdentifier(datasetB, extendedGraphURIB));
+                    new GraphIdentifier(datasetB, extendedGraphURIB),
+                    ignorePrefixes);
         }
         // file to stored
         else if (fileA != null && datasetB != null && graphB != null) {
             var extendedGraphURIB = expandURIUseCase.expandUri(datasetB, graphB);
             setMigrationContextUseCase.setMigrationContext(
-                    fileA, new GraphIdentifier(datasetB, extendedGraphURIB));
+                    fileA, new GraphIdentifier(datasetB, extendedGraphURIB), ignorePrefixes);
         }
         // stored to file
         else if (datasetA != null && graphA != null && fileA != null) {
             var extendedGraphURIA = expandURIUseCase.expandUri(datasetA, graphA);
             setMigrationContextUseCase.setMigrationContext(
-                    new GraphIdentifier(datasetA, extendedGraphURIA), fileA);
+                    new GraphIdentifier(datasetA, extendedGraphURIA), fileA, ignorePrefixes);
         } else {
             logger.warn(
                     "Invalid request to POST \"/api/migrations/context\" from \"{}\". Missing required parameters.",

backend/src/main/java/org/rdfarchitect/api/dto/migration/ResourceRenameOverview.java

@@ -17,7 +17,6 @@
 
 package org.rdfarchitect.api.dto.migration;
 
-import lombok.AllArgsConstructor;
 import lombok.Data;
 
 import org.rdfarchitect.models.changes.RenameCandidate;
@@ -29,13 +28,10 @@
 import java.util.stream.Collectors;
 
 @Data
-@AllArgsConstructor
 public class ResourceRenameOverview<T extends SemanticResourceChange> {
 
     private List<T> added;
 
-    private List<T> modified;
-
     private List<RenameCandidate<T>> deletedAndRenamed;
 
     public ResourceRenameOverview(List<T> changes, List<RenameCandidate<T>> renameCandidates) {
@@ -46,13 +42,6 @@ public ResourceRenameOverview(List<T> changes, List<RenameCandidate<T>> renameCa
                                         change.getSemanticResourceChangeType()
                                                 == SemanticResourceChangeType.ADD)
                         .toList();
-        this.modified =
-                changes.stream()
-                        .filter(
-                                change ->
-                                        change.getSemanticResourceChangeType()
-                                                == SemanticResourceChangeType.CHANGE)
-                        .toList();
         var deleted =
                 changes.stream()
                         .filter(

backend/src/main/java/org/rdfarchitect/context/SchemaMigrationContext.java

@@ -29,6 +29,9 @@
 @Data
 public class SchemaMigrationContext {
 
+    // whether the comparison ignores prefixes in comparison and rename detection
+    private boolean ignorePrefixes;
+
     // original graph of the schema
     private Graph originalSchema;
 

backend/src/main/java/org/rdfarchitect/models/changes/semanticchanges/SemanticFieldChangeType.java

@@ -22,6 +22,7 @@ public enum SemanticFieldChangeType {
     LABEL_CHANGE,
     COMMENT_CHANGE,
     SUPERCLASS_CHANGE,
+    SUPERCLASS_RENAME,
     BELONGS_TO_CATEGORY_CHANGE,
     DATATYPE_CHANGE,
     DATATYPE_RENAME,

backend/src/main/java/org/rdfarchitect/models/changes/semanticchanges/SemanticResourceChange.java

@@ -60,6 +60,8 @@ public sealed class SemanticResourceChange
 
     protected String label;
 
+    protected String comment = "";
+
     // only set in case of a rename
     protected String oldIRI;
 
@@ -84,6 +86,7 @@ public SemanticResourceChange(SemanticResourceChange other) {
         this.iri = other.getIri();
         this.semanticResourceChangeType = other.getSemanticResourceChangeType();
         this.changes = other.getChanges();
+        this.comment = other.getComment();
     }
 
     public SemanticResourceChange(Resource resource, SemanticResourceChangeType changeType) {