Introduce field-level diagnostics for rewrite rules

Enable field-aware metadata aggregation and diagnostics for rewrite rules, enhancing visibility of affected fields in composed and standalone operations. Refactor combinators and wrappers to support this functionality.

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

Author: Splatcrafter

aether-datafixers-api/src/main/java/de/splatgames/aether/datafixers/api/diagnostic/DiagnosticOptions.java

@@ -53,6 +53,10 @@
  * @param captureRuleDetails   whether to capture individual rule application details
  * @param maxSnapshotLength    maximum length for snapshot strings (0 for unlimited)
  * @param prettyPrintSnapshots whether to format snapshots for readability
+ * @param captureFieldDetails  whether to capture field-level operation metadata from
+ *                             {@link de.splatgames.aether.datafixers.api.rewrite.FieldAwareRule}
+ *                             implementations; requires {@code captureRuleDetails} to be
+ *                             {@code true} to have any effect (since 1.0.0)
  * @author Erik Pförtner
  * @see DiagnosticContext
  * @see MigrationReport
@@ -62,7 +66,8 @@ public record DiagnosticOptions(
         boolean captureSnapshots,
         boolean captureRuleDetails,
         int maxSnapshotLength,
-        boolean prettyPrintSnapshots
+        boolean prettyPrintSnapshots,
+        boolean captureFieldDetails
 ) {
 
     /**
@@ -79,13 +84,14 @@ public record DiagnosticOptions(
      *   <li>{@code captureRuleDetails} = {@code true}</li>
      *   <li>{@code maxSnapshotLength} = {@code 10000}</li>
      *   <li>{@code prettyPrintSnapshots} = {@code true}</li>
+     *   <li>{@code captureFieldDetails} = {@code true}</li>
      * </ul>
      *
      * @return default diagnostic options
      */
     @NotNull
     public static DiagnosticOptions defaults() {
-        return new DiagnosticOptions(true, true, DEFAULT_MAX_SNAPSHOT_LENGTH, true);
+        return new DiagnosticOptions(true, true, DEFAULT_MAX_SNAPSHOT_LENGTH, true, true);
     }
 
     /**
@@ -97,13 +103,14 @@ public static DiagnosticOptions defaults() {
      *   <li>{@code captureRuleDetails} = {@code false}</li>
      *   <li>{@code maxSnapshotLength} = {@code 0}</li>
      *   <li>{@code prettyPrintSnapshots} = {@code false}</li>
+     *   <li>{@code captureFieldDetails} = {@code false}</li>
      * </ul>
      *
      * @return minimal diagnostic options
      */
     @NotNull
     public static DiagnosticOptions minimal() {
-        return new DiagnosticOptions(false, false, 0, false);
+        return new DiagnosticOptions(false, false, 0, false, false);
     }
 
     /**
@@ -127,6 +134,7 @@ public static final class Builder {
         private boolean captureRuleDetails = true;
         private int maxSnapshotLength = DEFAULT_MAX_SNAPSHOT_LENGTH;
         private boolean prettyPrintSnapshots = true;
+        private boolean captureFieldDetails = true;
 
         private Builder() {
         }
@@ -197,6 +205,24 @@ public Builder prettyPrintSnapshots(final boolean prettyPrintSnapshots) {
             return this;
         }
 
+        /**
+         * Sets whether to capture field-level operation metadata.
+         *
+         * <p>When enabled and {@code captureRuleDetails} is also enabled, the migration
+         * report will include structured metadata about which fields each rule affects.
+         * This information is extracted from rules that implement
+         * {@link de.splatgames.aether.datafixers.api.rewrite.FieldAwareRule}.</p>
+         *
+         * @param captureFieldDetails {@code true} to capture field-level details
+         * @return this builder
+         * @since 1.0.0
+         */
+        @NotNull
+        public Builder captureFieldDetails(final boolean captureFieldDetails) {
+            this.captureFieldDetails = captureFieldDetails;
+            return this;
+        }
+
         /**
          * Builds the diagnostic options.
          *
@@ -208,7 +234,8 @@ public DiagnosticOptions build() {
                     this.captureSnapshots,
                     this.captureRuleDetails,
                     this.maxSnapshotLength,
-                    this.prettyPrintSnapshots
+                    this.prettyPrintSnapshots,
+                    this.captureFieldDetails
             );
         }
     }