Enhance field-level diagnostics and documentation

aether-datafixers-api/src/main/java/de/splatgames/aether/datafixers/api/DataVersion.java

@@ -27,6 +27,7 @@
 import de.splatgames.aether.datafixers.api.fix.DataFixer;
 import de.splatgames.aether.datafixers.api.schema.Schema;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Objects;
 
@@ -171,7 +172,7 @@ public int compareTo(@NotNull final DataVersion o) {
      * @see #hashCode()
      */
     @Override
-    public boolean equals(final Object obj) {
+    public boolean equals(@Nullable final Object obj) {
         if (this == obj) {
             return true;
         }
@@ -222,6 +223,7 @@ public int hashCode() {
      * @return a string representation of this data version in the format {@code "DataVersion{version=N}"}
      */
     @Override
+    @NotNull
     public String toString() {
         return "DataVersion{" + "version=" + this.version + '}';
     }

aether-datafixers-api/src/main/java/de/splatgames/aether/datafixers/api/TypeReference.java

@@ -28,6 +28,7 @@
 import de.splatgames.aether.datafixers.api.type.Type;
 import de.splatgames.aether.datafixers.api.type.TypeRegistry;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * A unique identifier for a data type in the data fixing system.
@@ -183,7 +184,7 @@ public int hashCode() {
      * @see #hashCode()
      */
     @Override
-    public boolean equals(final Object obj) {
+    public boolean equals(@Nullable final Object obj) {
         if (this == obj) {
             return true;
         }
@@ -217,6 +218,7 @@ public boolean equals(final Object obj) {
      * @see #getId()
      */
     @Override
+    @NotNull
     public String toString() {
         return "TypeReference{" + "id='" + this.id + '\'' + '}';
     }

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
             );
         }
     }