Add JDT AST sealed interface hierarchy and parser

Create JdtAst with three sealed node types:
- DirectiveNode: contains @jdt.rename/remove/merge/replace + children
- MergeNode: default object-to-object deep merge
- ReplacementNode: direct value replacement

JdtAstParser builds the AST from a JsonValue transform document.
Jdt.parseToAst() public API for codegen modules to access the AST.

4 new AST parser tests (22 total JDT unit tests).

To verify: mvn test -pl json-java21-jdt -am

Author: simbo1905

json-java21-jdt/src/main/java/json/java21/jdt/Jdt.java

@@ -59,6 +59,15 @@ private Jdt() {
         // Static utility class
     }
 
+    /// Parses a transform specification into a JDT AST for codegen or analysis.
+    ///
+    /// @param transform the transform specification document
+    /// @return the root AST node
+    public static JdtAst.JdtNode parseToAst(JsonValue transform) {
+        Objects.requireNonNull(transform, "transform must not be null");
+        return JdtAstParser.parse(transform);
+    }
+
     /// Default path resolver using the interpreter-based JsonPath.
     private static final Function<String, Function<JsonValue, List<JsonValue>>> DEFAULT_RESOLVER =
         expr -> JsonPath.parse(expr)::query;

json-java21-jdt/src/main/java/json/java21/jdt/JdtAst.java

@@ -0,0 +1,70 @@
+package json.java21.jdt;
+
+import jdk.sandbox.java.util.json.JsonValue;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/// AST representation for JSON Document Transform specifications.
+///
+/// A JDT transform document is parsed into an immutable tree of [JdtNode] records.
+/// Each node represents either a directive-bearing transform, a default merge,
+/// or a direct replacement. The AST can be walked with exhaustive switch expressions
+/// for bytecode codegen, ESM codegen, or interpretation.
+///
+/// ## Node Types
+/// - [DirectiveNode]: Contains `@jdt.*` directives (rename, remove, merge, replace)
+///   plus child transforms for non-directive keys
+/// - [MergeNode]: Default object-to-object deep merge (no directives)
+/// - [ReplacementNode]: Direct value replacement (primitive or array)
+///
+/// ## Parse Entry Point
+/// Use [JdtAstParser.parse] to convert a `JsonValue` transform into a [JdtNode].
+public interface JdtAst {
+
+    /// A node in the JDT transform AST.
+    sealed interface JdtNode permits DirectiveNode, MergeNode, ReplacementNode {}
+
+    /// A transform node containing `@jdt.*` directives.
+    ///
+    /// Directives execute in order: Rename -> Remove -> Merge -> Replace.
+    /// After directives, child transforms are applied as recursive merges.
+    ///
+    /// @param rename the rename directive spec (null if absent)
+    /// @param remove the remove directive spec (null if absent)
+    /// @param merge the merge directive spec (null if absent)
+    /// @param replace the replace directive spec (null if absent)
+    /// @param children non-directive key transforms to apply after directives
+    record DirectiveNode(
+        JsonValue rename,
+        JsonValue remove,
+        JsonValue merge,
+        JsonValue replace,
+        Map<String, JdtNode> children
+    ) implements JdtNode {
+        public DirectiveNode {
+            Objects.requireNonNull(children, "children must not be null");
+            children = Map.copyOf(children);
+        }
+    }
+
+    /// Default object merge: recursively merge transform keys into the source object.
+    ///
+    /// @param children the key-to-transform mapping for recursive merge
+    record MergeNode(Map<String, JdtNode> children) implements JdtNode {
+        public MergeNode {
+            Objects.requireNonNull(children, "children must not be null");
+            children = Map.copyOf(children);
+        }
+    }
+
+    /// Direct replacement: the transform value replaces the source wholesale.
+    ///
+    /// @param value the replacement value (primitive, array, or object without directives)
+    record ReplacementNode(JsonValue value) implements JdtNode {
+        public ReplacementNode {
+            Objects.requireNonNull(value, "value must not be null");
+        }
+    }
+}

json-java21-jdt/src/main/java/json/java21/jdt/JdtAstParser.java

@@ -0,0 +1,77 @@
+package json.java21.jdt;
+
+import jdk.sandbox.java.util.json.*;
+
+import java.util.LinkedHashMap;
+import java.util.logging.Logger;
+
+import json.java21.jdt.JdtAst.*;
+
+/// Parses a JSON transform document into a [JdtAst.JdtNode] tree.
+///
+/// The parser examines each object in the transform for `@jdt.*` directive
+/// keys and builds the appropriate AST node type.
+final class JdtAstParser {
+
+    private static final Logger LOG = Logger.getLogger(JdtAstParser.class.getName());
+
+    private JdtAstParser() {}
+
+    /// Parses a transform JsonValue into an AST node.
+    ///
+    /// @param transform the transform specification value
+    /// @return the root AST node
+    static JdtNode parse(JsonValue transform) {
+        if (!(transform instanceof JsonObject transformObj)) {
+            // Non-object transforms are direct replacements
+            return new ReplacementNode(transform);
+        }
+
+        final var members = transformObj.members();
+
+        // Check if this object has any JDT directives
+        final var hasDirectives = members.keySet().stream()
+                .anyMatch(k -> k.startsWith(Jdt.JDT_PREFIX));
+
+        if (hasDirectives) {
+            return parseDirectiveNode(transformObj);
+        }
+
+        // No directives: this is a default merge node
+        return parseMergeNode(transformObj);
+    }
+
+    private static DirectiveNode parseDirectiveNode(JsonObject transformObj) {
+        final var members = transformObj.members();
+
+        final var rename = members.get(Jdt.JDT_RENAME);
+        final var remove = members.get(Jdt.JDT_REMOVE);
+        final var merge = members.get(Jdt.JDT_MERGE);
+        final var replace = members.get(Jdt.JDT_REPLACE);
+
+        // Parse non-directive keys as child transforms
+        final var children = new LinkedHashMap<String, JdtNode>();
+        for (final var entry : members.entrySet()) {
+            if (!entry.getKey().startsWith(Jdt.JDT_PREFIX)) {
+                children.put(entry.getKey(), parse(entry.getValue()));
+            }
+        }
+
+        LOG.finer(() -> "Parsed DirectiveNode: rename=" + (rename != null) +
+                " remove=" + (remove != null) + " merge=" + (merge != null) +
+                " replace=" + (replace != null) + " children=" + children.size());
+
+        return new DirectiveNode(rename, remove, merge, replace, children);
+    }
+
+    private static MergeNode parseMergeNode(JsonObject transformObj) {
+        final var children = new LinkedHashMap<String, JdtNode>();
+        for (final var entry : transformObj.members().entrySet()) {
+            children.put(entry.getKey(), parse(entry.getValue()));
+        }
+
+        LOG.finer(() -> "Parsed MergeNode with " + children.size() + " children");
+
+        return new MergeNode(children);
+    }
+}

json-java21-jdt/src/test/java/json/java21/jdt/JdtTest.java

@@ -393,4 +393,74 @@ void primitiveTransform_replacesSource() {
 
         assertThat(result).isEqualTo(transform);
     }
+
+    // ========== AST Parser Tests ==========
+
+    @Test
+    void ast_primitiveTransformParsesToReplacement() {
+        LOG.info(() -> "TEST: ast_primitiveTransformParsesToReplacement");
+        
+        final var transform = Json.parse("42");
+        final var ast = Jdt.parseToAst(transform);
+        
+        assertThat(ast).isInstanceOf(JdtAst.ReplacementNode.class);
+        assertThat(((JdtAst.ReplacementNode) ast).value()).isEqualTo(transform);
+    }
+
+    @Test
+    void ast_objectWithoutDirectivesParsesToMergeNode() {
+        LOG.info(() -> "TEST: ast_objectWithoutDirectivesParsesToMergeNode");
+        
+        final var transform = Json.parse("""
+            {"A": 1, "B": {"C": 2}}
+            """);
+        final var ast = Jdt.parseToAst(transform);
+        
+        assertThat(ast).isInstanceOf(JdtAst.MergeNode.class);
+        final var merge = (JdtAst.MergeNode) ast;
+        assertThat(merge.children()).containsKeys("A", "B");
+        assertThat(merge.children().get("A")).isInstanceOf(JdtAst.ReplacementNode.class);
+        assertThat(merge.children().get("B")).isInstanceOf(JdtAst.MergeNode.class);
+    }
+
+    @Test
+    void ast_objectWithDirectivesParsesToDirectiveNode() {
+        LOG.info(() -> "TEST: ast_objectWithDirectivesParsesToDirectiveNode");
+        
+        final var transform = Json.parse("""
+            {
+                "@jdt.rename": {"old": "new"},
+                "@jdt.remove": "B",
+                "C": 3
+            }
+            """);
+        final var ast = Jdt.parseToAst(transform);
+        
+        assertThat(ast).isInstanceOf(JdtAst.DirectiveNode.class);
+        final var directive = (JdtAst.DirectiveNode) ast;
+        assertThat(directive.rename()).isNotNull();
+        assertThat(directive.remove()).isNotNull();
+        assertThat(directive.merge()).isNull();
+        assertThat(directive.replace()).isNull();
+        assertThat(directive.children()).containsKey("C");
+    }
+
+    @Test
+    void ast_nestedDirectivesParseCorrectly() {
+        LOG.info(() -> "TEST: ast_nestedDirectivesParseCorrectly");
+        
+        final var transform = Json.parse("""
+            {
+                "Settings": {
+                    "@jdt.merge": {"newKey": "value"},
+                    "existing": "updated"
+                }
+            }
+            """);
+        final var ast = Jdt.parseToAst(transform);
+        
+        assertThat(ast).isInstanceOf(JdtAst.MergeNode.class);
+        final var root = (JdtAst.MergeNode) ast;
+        assertThat(root.children().get("Settings")).isInstanceOf(JdtAst.DirectiveNode.class);
+    }
 }