Enable field-level diagnostics in migration CLI and expose in reports

Add support for detailed field-level diagnostics during migrations. Extend CLI command options, enhance diagnostic report generation (text/JSON formats), and integrate diagnostics into the actuator endpoint.

Signed-off-by: Erik Pförtner <splatcrafter@splatgames.de>

Author: Splatcrafter

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/command/MigrateCommand.java

@@ -28,6 +28,9 @@
 import de.splatgames.aether.datafixers.api.bootstrap.DataFixerBootstrap;
 import de.splatgames.aether.datafixers.api.dynamic.Dynamic;
 import de.splatgames.aether.datafixers.api.dynamic.TaggedDynamic;
+import de.splatgames.aether.datafixers.api.diagnostic.DiagnosticContext;
+import de.splatgames.aether.datafixers.api.diagnostic.DiagnosticOptions;
+import de.splatgames.aether.datafixers.api.diagnostic.MigrationReport;
 import de.splatgames.aether.datafixers.cli.bootstrap.BootstrapLoader;
 import de.splatgames.aether.datafixers.cli.format.FormatHandler;
 import de.splatgames.aether.datafixers.cli.format.FormatRegistry;
@@ -36,6 +39,7 @@
 import de.splatgames.aether.datafixers.core.AetherDataFixer;
 import de.splatgames.aether.datafixers.core.bootstrap.DataFixerRuntimeFactory;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Option;
 import picocli.CommandLine.Parameters;
@@ -396,6 +400,32 @@ public class MigrateCommand implements Callable<Integer> {
     )
     private boolean verbose;
 
+    /**
+     * Whether to enable field-level diagnostics output.
+     *
+     * <p>When {@code true}, a detailed diagnostic report is generated for each
+     * migrated file, including information about every fix execution, rule
+     * application, and field-level operation (renames, removals, additions,
+     * transforms, etc.).</p>
+     *
+     * <p>Diagnostics output is written alongside the migration report: to
+     * {@link #reportFile} if specified, or to stderr otherwise. The output
+     * format follows the selected {@link #reportFormat}.</p>
+     *
+     * <p>Default value: {@code false}</p>
+     *
+     * <p>CLI usage: {@code --diagnostics}</p>
+     *
+     * @see DiagnosticContext
+     * @see de.splatgames.aether.datafixers.api.diagnostic.FieldOperation
+     * @since 1.0.0
+     */
+    @Option(
+            names = {"--diagnostics"},
+            description = "Enable field-level diagnostics output showing detailed fix and field operation information."
+    )
+    private boolean diagnostics;
+
     /**
      * Whether to pretty-print the output JSON.
      *
@@ -474,6 +504,8 @@ public Integer call() {
             int errorCount = 0;
             final StringBuilder reportBuilder = new StringBuilder();
 
+            final StringBuilder diagnosticBuilder = new StringBuilder();
+
             for (final File inputFile : this.inputFiles) {
                 try {
                     final MigrationResult result = processFile(
@@ -483,6 +515,9 @@ public Integer call() {
                     if (this.generateReport) {
                         reportBuilder.append(result.report).append("\n");
                     }
+                    if (this.diagnostics && !result.diagnosticOutput.isEmpty()) {
+                        diagnosticBuilder.append(result.diagnosticOutput).append("\n");
+                    }
                 } catch (final Exception e) {
                     errorCount++;
                     System.err.println("Error processing " + inputFile + ": " + e.getMessage());
@@ -505,6 +540,19 @@ public Integer call() {
                 }
             }
 
+            // Write diagnostic output
+            if (this.diagnostics && !diagnosticBuilder.isEmpty()) {
+                final String diagnosticContent = diagnosticBuilder.toString();
+                if (this.reportFile != null) {
+                    Files.writeString(this.reportFile.toPath(), diagnosticContent,
+                            StandardCharsets.UTF_8,
+                            java.nio.file.StandardOpenOption.CREATE,
+                            java.nio.file.StandardOpenOption.APPEND);
+                } else {
+                    System.err.println(diagnosticContent);
+                }
+            }
+
             // Summary
             if (this.inputFiles.size() > 1 || this.verbose) {
                 System.err.println("Completed: " + successCount + " migrated, " + errorCount + " errors");
@@ -590,15 +638,24 @@ private <T> MigrationResult processFile(
                 System.err.println("Skipping " + inputFile + " (already at v"
                         + sourceVersion.getVersion() + ")");
             }
-            return new MigrationResult("", Duration.ZERO);
+            return new MigrationResult("", Duration.ZERO, "");
         }
 
         // Create dynamic and migrate
         final Dynamic<T> dynamic = new Dynamic<>(handler.ops(), data);
         final TaggedDynamic tagged = new TaggedDynamic(typeRef, dynamic);
 
-        // Perform migration
-        final TaggedDynamic migrated = fixer.update(tagged, sourceVersion, targetVersion);
+        // Perform migration (with diagnostics if enabled)
+        final DiagnosticContext diagCtx = this.diagnostics
+                ? DiagnosticContext.create(DiagnosticOptions.builder()
+                        .captureSnapshots(false)
+                        .captureRuleDetails(true)
+                        .captureFieldDetails(true)
+                        .build())
+                : null;
+        final TaggedDynamic migrated = diagCtx != null
+                ? fixer.update(tagged, sourceVersion, targetVersion, diagCtx)
+                : fixer.update(tagged, sourceVersion, targetVersion);
 
         // Extract result
         @SuppressWarnings("unchecked")
@@ -631,7 +688,19 @@ private <T> MigrationResult processFile(
             );
         }
 
-        return new MigrationResult(report, duration);
+        // Generate diagnostic report
+        final MigrationReport diagnosticReport = diagCtx != null ? diagCtx.getReport() : null;
+        String diagnosticOutput = "";
+        if (diagnosticReport != null) {
+            final ReportFormatter formatter = ReportFormatter.forFormat(this.reportFormat);
+            diagnosticOutput = formatter.formatDiagnostic(
+                    inputFile.getName(),
+                    typeRef.getId(),
+                    diagnosticReport
+            );
+        }
+
+        return new MigrationResult(report, duration, diagnosticOutput);
     }
 
     /**
@@ -719,6 +788,21 @@ private void writeOutput(@NotNull final File inputFile, @NotNull final String co
      * @see #processFile(File, AetherDataFixer, FormatHandler, TypeReference, DataVersion)
      * @see ReportFormatter
      */
-    private record MigrationResult(String report, Duration duration) {
+    /**
+     * Holds the result of a single file migration operation.
+     *
+     * <p>This record captures the outcome of migrating one file, including
+     * the formatted report string (if reporting is enabled), the time
+     * taken for the migration, and the optional diagnostic output (if
+     * {@code --diagnostics} was enabled).</p>
+     *
+     * @param report           the formatted migration report string, empty if reporting is disabled
+     *                         or if the file was skipped (already at target version)
+     * @param duration         the time elapsed during the migration process, including file I/O
+     * @param diagnosticOutput the formatted diagnostic report string, empty if diagnostics are disabled
+     * @see #processFile(File, AetherDataFixer, FormatHandler, TypeReference, DataVersion)
+     * @see ReportFormatter
+     */
+    private record MigrationResult(String report, Duration duration, String diagnosticOutput) {
     }
 }

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/report/JsonReportFormatter.java

@@ -25,7 +25,12 @@
 import com.google.common.base.Preconditions;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
+import com.google.gson.JsonArray;
 import com.google.gson.JsonObject;
+import de.splatgames.aether.datafixers.api.diagnostic.FieldOperation;
+import de.splatgames.aether.datafixers.api.diagnostic.FixExecution;
+import de.splatgames.aether.datafixers.api.diagnostic.MigrationReport;
+import de.splatgames.aether.datafixers.api.diagnostic.RuleApplication;
 import org.jetbrains.annotations.NotNull;
 
 import java.time.Duration;
@@ -122,4 +127,113 @@ public String formatSimple(
 
         return GSON.toJson(json);
     }
+
+    /**
+     * Formats a diagnostic migration report as a JSON object.
+     *
+     * <p>The output is a pretty-printed JSON object with the following structure:</p>
+     * <pre>{@code
+     * {
+     *   "file": "player.json",
+     *   "type": "player",
+     *   "fromVersion": 100,
+     *   "toVersion": 200,
+     *   "durationMs": 42,
+     *   "fixCount": 2,
+     *   "ruleCount": 3,
+     *   "fieldOperationCount": 5,
+     *   "fixes": [
+     *     {
+     *       "name": "PlayerV1ToV2Fix",
+     *       "fromVersion": 100,
+     *       "toVersion": 150,
+     *       "durationMs": 20,
+     *       "rules": [
+     *         {
+     *           "name": "renameField",
+     *           "matched": true,
+     *           "durationMs": 5,
+     *           "fieldOperations": [
+     *             {
+     *               "type": "RENAME",
+     *               "field": "oldName",
+     *               "target": "newName"
+     *             }
+     *           ]
+     *         }
+     *       ]
+     *     }
+     *   ],
+     *   "warnings": []
+     * }
+     * }</pre>
+     *
+     * @param fileName the name of the migrated file
+     * @param type     the type reference ID (e.g., "player", "world")
+     * @param report   the diagnostic migration report containing fix and field operation details
+     * @return a pretty-printed JSON string representing the diagnostic report
+     */
+    @Override
+    @NotNull
+    public String formatDiagnostic(
+            @NotNull final String fileName,
+            @NotNull final String type,
+            @NotNull final MigrationReport report
+    ) {
+        Preconditions.checkNotNull(fileName, "fileName must not be null");
+        Preconditions.checkNotNull(type, "type must not be null");
+        Preconditions.checkNotNull(report, "report must not be null");
+
+        final JsonObject json = new JsonObject();
+        json.addProperty("file", fileName);
+        json.addProperty("type", type);
+        json.addProperty("fromVersion", report.fromVersion().getVersion());
+        json.addProperty("toVersion", report.toVersion().getVersion());
+        json.addProperty("durationMs", report.totalDuration().toMillis());
+        json.addProperty("fixCount", report.fixCount());
+        json.addProperty("ruleCount", report.ruleApplicationCount());
+        json.addProperty("fieldOperationCount", report.totalFieldOperationCount());
+
+        final JsonArray fixes = new JsonArray();
+        for (final FixExecution fix : report.fixExecutions()) {
+            final JsonObject fixObj = new JsonObject();
+            fixObj.addProperty("name", fix.fixName());
+            fixObj.addProperty("fromVersion", fix.fromVersion().getVersion());
+            fixObj.addProperty("toVersion", fix.toVersion().getVersion());
+            fixObj.addProperty("durationMs", fix.durationMillis());
+
+            final JsonArray rules = new JsonArray();
+            for (final RuleApplication rule : fix.ruleApplications()) {
+                final JsonObject ruleObj = new JsonObject();
+                ruleObj.addProperty("name", rule.ruleName());
+                ruleObj.addProperty("matched", rule.matched());
+                ruleObj.addProperty("durationMs", rule.durationMillis());
+
+                final JsonArray fieldOps = new JsonArray();
+                for (final FieldOperation fieldOp : rule.fieldOperations()) {
+                    final JsonObject opObj = new JsonObject();
+                    opObj.addProperty("type", fieldOp.operationType().name());
+                    opObj.addProperty("field", fieldOp.fieldPathString());
+                    fieldOp.targetFieldNameOpt()
+                            .ifPresent(target -> opObj.addProperty("target", target));
+                    fieldOp.descriptionOpt()
+                            .ifPresent(desc -> opObj.addProperty("description", desc));
+                    fieldOps.add(opObj);
+                }
+                ruleObj.add("fieldOperations", fieldOps);
+                rules.add(ruleObj);
+            }
+            fixObj.add("rules", rules);
+            fixes.add(fixObj);
+        }
+        json.add("fixes", fixes);
+
+        final JsonArray warnings = new JsonArray();
+        for (final String warning : report.warnings()) {
+            warnings.add(warning);
+        }
+        json.add("warnings", warnings);
+
+        return GSON.toJson(json);
+    }
 }

aether-datafixers-cli/src/main/java/de/splatgames/aether/datafixers/cli/report/ReportFormatter.java

@@ -23,6 +23,7 @@
 package de.splatgames.aether.datafixers.cli.report;
 
 import com.google.common.base.Preconditions;
+import de.splatgames.aether.datafixers.api.diagnostic.MigrationReport;
 import org.jetbrains.annotations.NotNull;
 
 import java.time.Duration;
@@ -72,6 +73,25 @@ String formatSimple(
             @NotNull Duration duration
     );
 
+    /**
+     * Formats a diagnostic migration report including field-level operation details.
+     *
+     * <p>When diagnostics are enabled, the report includes comprehensive information
+     * about each fix execution and its field-level operations (renames, removals,
+     * additions, transforms, etc.).</p>
+     *
+     * @param fileName the name of the migrated file
+     * @param type     the type reference ID
+     * @param report   the diagnostic migration report
+     * @return the formatted diagnostic report string
+     */
+    @NotNull
+    String formatDiagnostic(
+            @NotNull String fileName,
+            @NotNull String type,
+            @NotNull MigrationReport report
+    );
+
     /**
      * Gets a formatter by format name.
      *