Merge pull request #17 from aether-framework/feature/schema-tooling

Improve schema validation and documentation

Author: Splatcrafter

CHANGELOG.md

@@ -6,10 +6,53 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
-## [0.3.0] - 2026-01-07
+## [0.3.0] - 2026-01-08
 
 ### Added
 
+#### Schema Tools Module (`aether-datafixers-schema-tools`)
+
+New module for schema analysis, validation, and migration coverage checking.
+
+**Schema Diffing (`schematools.diff`):**
+- `SchemaDiffer` — Fluent API for comparing two schemas
+- `SchemaDiff` — Immutable result with added/removed/common types
+- `TypeDiff` — Field-level changes for types present in both schemas
+- `FieldDiff` — Individual field change (ADDED, REMOVED, MODIFIED, UNCHANGED)
+- `DiffKind` — Enumeration of change types
+- Optional field-level diffing via `includeFieldLevel(true)`
+- Type filtering via `ignoreTypes(...)`
+
+**Migration Analysis (`schematools.analysis`):**
+- `MigrationAnalyzer` — Fluent API for analyzing migration paths
+- `MigrationPath` — Complete migration sequence with all steps
+- `MigrationStep` — Single version transition with optional DataFix and SchemaDiff
+- `FixCoverage` — Analysis result showing fix coverage for schema changes
+- `CoverageGap` — Represents a schema change without corresponding DataFix
+- Coverage gap reasons: TYPE_ADDED, TYPE_REMOVED, TYPE_MODIFIED, FIELD_ADDED, FIELD_REMOVED, FIELD_TYPE_CHANGED
+- Orphan fix detection (fixes without schema changes)
+
+**Schema Validation (`schematools.validation`):**
+- `SchemaValidator` — Fluent API for validating schemas
+- `ValidationResult` — Immutable collection of validation issues
+- `ValidationIssue` — Single issue with severity, code, message, location, context
+- `IssueSeverity` — ERROR, WARNING, INFO levels
+- `StructureValidator` — Validates schema structure (cycles, version ordering, parent chains)
+- `ConventionChecker` — Validates naming conventions for types, fields, classes
+- `ConventionRules` — Configurable naming rules (STRICT, RELAXED, NONE, or custom)
+- Schema class prefix/suffix validation (e.g., "Schema" prefix for Schema100, Schema200)
+- Fix class prefix/suffix validation (e.g., "Fix" suffix for PlayerNameFix)
+- Predefined patterns for snake_case, camelCase
+- Custom validators via `customTypeValidator()` and `customFieldValidator()`
+
+**Type Introspection (`schematools.introspection`):**
+- `TypeIntrospector` — Utility for analyzing type structures
+- `TypeStructure` — Normalized, comparable representation of a Type
+- `FieldInfo` — Field metadata (name, path, optionality, type)
+- `TypeKind` — Classification (PRIMITIVE, LIST, OPTIONAL, PRODUCT, SUM, FIELD, etc.)
+- Recursive field extraction with hierarchical paths
+- Structural equality comparison
+
 #### CLI Module (`aether-datafixers-cli`)
 
 New command-line interface for data migration without writing Java code.
@@ -47,6 +90,13 @@ New command-line interface for data migration without writing Java code.
 - `BootstrapLoadException` — Bootstrap class loading failures
 - `FormatParseException` — Input parsing failures
 
+### Documentation
+
+- Added comprehensive Schema Tools documentation (diffing, analysis, validation, introspection)
+- Added CLI module documentation (commands, format handlers, examples)
+- Updated glossary with Schema Tools terminology
+- Updated installation guide with new modules
+
 ---
 
 ## [0.2.0] - 2026-01-07

README.md

@@ -18,6 +18,8 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
 - ✅ **Codec System** — Bidirectional transformation between typed Java objects and dynamic representations
 - ✅ **Type Safety** — Strong typing with `TypeReference` identifiers for data routing
 - ✅ **Testkit** — Fluent test data builders, custom assertions, and test harnesses for DataFix testing
+- ✅ **CLI Tool** — Migrate and validate data files from the command line with batch processing
+- ✅ **Schema Tools** — Schema diffing, validation, migration analysis, and type introspection
 - ✅ **Migration Diagnostics** — Opt-in structured reports with timing, applied fixes, and snapshots
 - ✅ **Extended Rewrite Rules** — Batch operations, path-based transforms, conditional rules
 - ✅ **High-Performance APIs** — `Rules.batch()` for single-pass multi-operation transforms
@@ -31,6 +33,8 @@ inspired by Minecraft's DataFixer Upper (DFU), with a focus on **simplicity**, *
 - **aether-datafixers-core** — Default implementations of the API interfaces
 - **aether-datafixers-codec** — Codec implementations for serialization formats
 - **aether-datafixers-testkit** — Testing utilities for DataFix, Schema, and migration testing
+- **aether-datafixers-cli** — Command-line interface for data migration and validation
+- **aether-datafixers-schema-tools** — Schema analysis, validation, diffing, and introspection
 - **aether-datafixers-examples** — Practical examples demonstrating real-world usage
 - **aether-datafixers-bom** — Bill of Materials for coordinated dependency management
 
@@ -418,8 +422,10 @@ mvn test
   - **Performance optimizations** — Path caching, optimized fix registry, reduced allocations
 
 - **v0.3.0** (next)
-  - **CLI module** — Migrate files and print/export a migration report (batch-friendly)
-  - **Schema tooling** — Runtime schema validation + diff utilities between versions
+  - **CLI module** — Migrate files from the command line with batch processing and reports
+  - **Schema Tools module** — Schema diffing, migration analysis, validation, and introspection
+  - **Fix coverage analysis** — Detect schema changes without corresponding DataFixes
+  - **Convention checking** — Enforce naming conventions for types, fields, and classes
 
 - **v0.4.0**
   - **Spring Boot integration** — Auto-configuration for DataFixer in Spring apps

aether-datafixers-api/src/main/java/de/splatgames/aether/datafixers/api/schema/SchemaRegistry.java

@@ -28,6 +28,9 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.Set;
+import java.util.stream.Stream;
+
 /**
  * A registry for managing {@link Schema} instances across data versions.
  *
@@ -152,4 +155,29 @@ default void freeze() {
     default boolean isFrozen() {
         return false;
     }
+
+    /**
+     * Returns a stream of all registered schemas.
+     *
+     * <p>The returned stream provides access to all schemas in this registry.
+     * The order of schemas in the stream is implementation-dependent.</p>
+     *
+     * @return a stream of all schemas, never {@code null}
+     * @since 0.3.0
+     */
+    @NotNull
+    Stream<Schema> stream();
+
+    /**
+     * Returns the set of all registered versions.
+     *
+     * <p>The returned set is a snapshot of the registered versions at the time
+     * of the call. Modifications to the registry after this call will not be
+     * reflected in the returned set.</p>
+     *
+     * @return an unmodifiable set of all registered versions, never {@code null}
+     * @since 0.3.0
+     */
+    @NotNull
+    Set<DataVersion> versions();
 }

aether-datafixers-api/src/main/java/de/splatgames/aether/datafixers/api/type/TypeRegistry.java

@@ -89,6 +89,19 @@ public interface TypeRegistry {
      */
     boolean has(@NotNull final TypeReference ref);
 
+    /**
+     * Returns all registered type references.
+     *
+     * <p>The returned set is a snapshot of the registered references at the time
+     * of the call. Modifications to the registry after this call will not be
+     * reflected in the returned set.</p>
+     *
+     * @return an unmodifiable set of all registered type references, never {@code null}
+     * @since 0.3.0
+     */
+    @NotNull
+    java.util.Set<TypeReference> references();
+
     /**
      * Retrieves a type by its reference, throwing if not found.
      *

aether-datafixers-api/src/test/java/de/splatgames/aether/datafixers/api/schema/SchemaTest.java

@@ -345,6 +345,12 @@ public Type<?> get(@NotNull TypeReference ref) {
         public boolean has(@NotNull TypeReference ref) {
             return types.containsKey(ref);
         }
+
+        @NotNull
+        @Override
+        public java.util.Set<TypeReference> references() {
+            return java.util.Set.copyOf(types.keySet());
+        }
     }
 
     private static class TestSchema extends Schema {

aether-datafixers-bom/pom.xml

@@ -37,6 +37,11 @@
                 <artifactId>aether-datafixers-testkit</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>de.splatgames.aether.datafixers</groupId>
+                <artifactId>aether-datafixers-schema-tools</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>de.splatgames.aether.datafixers</groupId>
                 <artifactId>aether-datafixers-cli</artifactId>

aether-datafixers-core/src/main/java/de/splatgames/aether/datafixers/core/fix/DataFixerBuilder.java

@@ -202,4 +202,22 @@ public DataFixer build() {
         this.registry.freeze();
         return new DataFixerImpl(this.currentVersion, this.registry, this.defaultContext);
     }
+
+    /**
+     * Returns the internal fix registry.
+     *
+     * <p>This method provides access to the underlying {@link DataFixRegistry}
+     * for analysis and introspection purposes. The registry may be mutable
+     * if {@link #build()} has not been called yet.</p>
+     *
+     * <p><b>Warning:</b> Modifying the returned registry after build() has been
+     * called will have no effect, as build() creates an immutable copy.</p>
+     *
+     * @return the fix registry, never {@code null}
+     * @since 0.3.0
+     */
+    @NotNull
+    public DataFixRegistry getFixRegistry() {
+        return this.registry;
+    }
 }

aether-datafixers-core/src/main/java/de/splatgames/aether/datafixers/core/schema/SimpleSchemaRegistry.java

@@ -32,7 +32,9 @@
 import java.util.Collections;
 import java.util.Map;
 import java.util.NavigableMap;
+import java.util.Set;
 import java.util.TreeMap;
+import java.util.stream.Stream;
 
 /**
  * A simple {@link TreeMap}-based implementation of {@link SchemaRegistry}.
@@ -136,4 +138,16 @@ public void freeze() {
     public boolean isFrozen() {
         return this.frozen;
     }
+
+    @Override
+    @NotNull
+    public Stream<Schema> stream() {
+        return this.schemas.values().stream();
+    }
+
+    @Override
+    @NotNull
+    public Set<DataVersion> versions() {
+        return this.frozen ? this.schemas.keySet() : Set.copyOf(this.schemas.keySet());
+    }
 }

aether-datafixers-core/src/main/java/de/splatgames/aether/datafixers/core/type/SimpleTypeRegistry.java

@@ -31,6 +31,7 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Set;
 
 /**
  * A simple {@link HashMap}-based implementation of {@link TypeRegistry}.
@@ -85,6 +86,12 @@ public boolean has(@NotNull final TypeReference ref) {
         return this.types.containsKey(ref);
     }
 
+    @NotNull
+    @Override
+    public Set<TypeReference> references() {
+        return this.frozen ? this.types.keySet() : Set.copyOf(this.types.keySet());
+    }
+
     @Override
     public void freeze() {
         if (!this.frozen) {

aether-datafixers-schema-tools/pom.xml

@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>de.splatgames.aether.datafixers</groupId>
+        <artifactId>aether-datafixers</artifactId>
+        <version>0.3.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>aether-datafixers-schema-tools</artifactId>
+    <packaging>jar</packaging>
+
+    <name>Aether Datafixers :: Schema Tools</name>
+    <description>Schema analysis, validation, and migration path analysis tools for Aether Datafixers.</description>
+
+    <dependencies>
+        <!-- Aether Datafixers modules -->
+        <dependency>
+            <groupId>de.splatgames.aether.datafixers</groupId>
+            <artifactId>aether-datafixers-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>de.splatgames.aether.datafixers</groupId>
+            <artifactId>aether-datafixers-core</artifactId>
+        </dependency>
+
+        <!-- JetBrains annotations -->
+        <dependency>
+            <groupId>org.jetbrains</groupId>
+            <artifactId>annotations</artifactId>
+        </dependency>
+
+        <!-- Guava for utilities -->
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+        </dependency>
+
+        <!-- Testing -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>de.splatgames.aether.datafixers</groupId>
+            <artifactId>aether-datafixers-testkit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>de.splatgames.aether.datafixers</groupId>
+            <artifactId>aether-datafixers-codec</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-enforcer-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>