Issue #121 Scaffold JsonPath module with initial AST and tests

Co-authored-by: simbo1905 <simbo1905@60hertz.com>

Author: cursoragent

PLAN_121.md

@@ -0,0 +1,116 @@
+## Issue #121: Add JsonPath module with AST parser and evaluator
+
+### Goal
+
+Add a new Maven module that implements **JsonPath** as described by Stefan Goessner:
+`https://goessner.net/articles/JsonPath/index.html`.
+
+This module must:
+
+- Parse a JsonPath string into a **custom AST**
+- Evaluate that AST against a JSON document already parsed by this repo’s
+  `jdk.sandbox.java.util.json` API
+- Have **no runtime dependencies** outside `java.base` (and the existing `json-java21` module)
+- Target **Java 21** and follow functional / data-oriented style (records + sealed interfaces)
+
+### Non-goals
+
+- Parsing JSON documents from strings (the core `Json.parse(...)` already does that)
+- Adding non-trivial external dependencies (no regex engines beyond JDK, no parser generators)
+- Supporting every JsonPath dialect ever published; the baseline is the article examples
+
+### Public API shape (module `json-java21-jsonpath`)
+
+Package: `json.java21.jsonpath`
+
+- `JsonPathExpression JsonPath.parse(String path)`
+  - Parses a JsonPath string into an AST-backed compiled expression.
+- `List<JsonValue> JsonPathExpression.select(JsonValue document)`
+  - Evaluates the expression against a parsed JSON document and returns matched nodes in traversal order.
+
+Notes:
+- The return type is a `List<JsonValue>` to avoid introducing a JSON encoding of “result sets”.
+  Callers can wrap it into `JsonArray.of(...)` if desired.
+
+### AST plan
+
+Use a sealed interface with records (no inheritance trees with stateful objects):
+
+- `sealed interface PathNode permits Root, StepChain`
+- `record Root() implements PathNode`
+- `record StepChain(PathNode base, Step step) implements PathNode`
+
+Steps are a separate sealed protocol:
+
+- `sealed interface Step permits Child, RecursiveDescent, Wildcard, ArrayIndex, ArraySlice, Union, Filter`
+- `record Child(Name name)` where `Name` is either identifier or quoted key
+- `record RecursiveDescent(Step selector)` where selector is `Child` or `Wildcard`
+- `record Wildcard()`
+- `record ArrayIndex(int index)` supports negative indices per examples
+- `record ArraySlice(Integer start, Integer end, Integer step)` to cover `[:2]`, `[-1:]`, etc.
+- `record Union(List<Step> selectors)` for `[0,1]`, `['a','b']`
+- `record Filter(PredicateExpr expr)` for `[?(...)]`
+
+Filter expressions:
+
+- Keep a minimal expression AST that supports the article examples:
+  - `@.field` access
+  - `@.length` pseudo-property for array length
+  - numeric literals
+  - string literals
+  - comparison operators: `<`, `<=`, `>`, `>=`, `==`, `!=`
+  - arithmetic: `+`, `-` (only what’s needed for `(@.length-1)`)
+
+### Parser plan
+
+Hand-rolled scanner + recursive descent parser:
+
+- Lex JsonPath into tokens (`$`, `.`, `..`, `[`, `]`, `*`, `,`, `:`, `?(`, `)`, identifiers, quoted strings, numbers, operators).
+- Parse according to the article grammar:
+  - Root `$` must appear first
+  - Dot-notation steps: `.name`, `.*`, `..name`, `..*`
+  - Bracket steps:
+    - `['name']`
+    - `[0]`, `[-1]`
+    - `[0,1]`, `['a','b']`
+    - `[:2]`, `[2:]`, `[-1:]`
+    - `[?(...)]`
+    - `[(...)]` for script expressions used as array index in examples (limited support)
+
+### Evaluator plan
+
+Evaluator is a pure function over immutable inputs, implemented as static methods:
+
+- Maintain a worklist of “current nodes” (starting with the document root).
+- For each step:
+  - **Child**: for objects, pick member by key; for arrays, apply to each element if they’re objects (per example behavior).
+  - **RecursiveDescent**: walk the subtree of each current node (object members + array elements) and apply the selector to every node encountered.
+  - **Wildcard**: for objects select all member values; for arrays select all elements.
+  - **ArrayIndex / Slice / Union**: apply only when the current node is an array.
+  - **Filter**: apply only when current node is an array; keep elements where predicate is true.
+
+Ordering:
+- Preserve traversal order implied by iterating object members (`JsonObject.members()` is order-preserving) and array elements order.
+
+### Tests (TDD baseline)
+
+Add tests that correspond 1:1 with every example on the article page:
+
+- Use the article’s sample document (embedded as a Java text block) and parse with `Json.parse(...)`.
+- Assertions check matched values by rendering to JSON (`JsonValue.toString()`) and comparing to expected fragments.
+- Every test method logs an INFO banner at start (common base class).
+
+### Verification
+
+Run focused module tests with logging:
+
+```bash
+$(command -v mvnd || command -v mvn || command -v ./mvnw) -pl json-java21-jsonpath test -Djava.util.logging.ConsoleHandler.level=FINE
+```
+
+Run full suite once stable:
+
+```bash
+$(command -v mvnd || command -v mvn || command -v ./mvnw) test -Djava.util.logging.ConsoleHandler.level=INFO
+```
+

README.md

@@ -328,6 +328,29 @@ This repo contains an incubating JTD validator that has the core JSON API as its
 
 A complete JSON Type Definition validator is included (module: json-java21-jtd).
 
+## JsonPath (AST + evaluator over `java.util.json`)
+
+This repo also includes (in progress) a **JsonPath** module based on Stefan Goessner’s article:
+`https://goessner.net/articles/JsonPath/index.html`.
+
+Design goals:
+- **No runtime deps beyond `java.base`** (and the core `json-java21` module)
+- **Parse JsonPath strings to a custom AST**
+- **Evaluate against already-parsed JSON** (`JsonValue`), not against JSON text
+- Pure Java 21, functional/data-oriented style (records + sealed interfaces)
+- Unit tests mirror the article examples
+
+Planned public API (module: `json-java21-jsonpath`):
+
+```java
+import jdk.sandbox.java.util.json.JsonValue;
+import json.java21.jsonpath.JsonPath;
+
+JsonValue doc = /* Json.parse(...) from json-java21 */;
+var expr = JsonPath.parse("$.store.book[*].author");
+var matches = expr.select(doc); // List<JsonValue>
+```
+
 ### Empty Schema `{}` Semantics (RFC 8927)
 
 Per **RFC 8927 (JSON Typedef)**, the empty schema `{}` is the **empty form** and

json-java21-jsonpath/README.md

@@ -0,0 +1,22 @@
+# JsonPath (Goessner) for `java.util.json` (Java 21)
+
+This module implements **JsonPath** as described by Stefan Goessner:
+`https://goessner.net/articles/JsonPath/index.html`.
+
+Design constraints:
+- Evaluates over already-parsed JSON (`jdk.sandbox.java.util.json.JsonValue`)
+- Parses JsonPath strings into a custom AST
+- No runtime dependencies outside `java.base` (and the core `java.util.json` backport)
+
+## Usage (planned API)
+
+```java
+import jdk.sandbox.java.util.json.Json;
+import jdk.sandbox.java.util.json.JsonValue;
+import json.java21.jsonpath.JsonPath;
+
+JsonValue doc = Json.parse("{\"a\": {\"b\": [1,2,3]}}");
+var expr = JsonPath.parse("$.a.b[0]");
+var matches = expr.select(doc);
+```
+

json-java21-jsonpath/pom.xml

@@ -0,0 +1,80 @@
+<?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>io.github.simbo1905.json</groupId>
+        <artifactId>parent</artifactId>
+        <version>0.1.9</version>
+    </parent>
+
+    <artifactId>java.util.json.jsonpath</artifactId>
+    <packaging>jar</packaging>
+    <name>java.util.json Java21 Backport JsonPath</name>
+    <url>https://simbo1905.github.io/java.util.json.Java21/</url>
+    <scm>
+        <connection>scm:git:https://github.com/simbo1905/java.util.json.Java21.git</connection>
+        <developerConnection>scm:git:git@github.com:simbo1905/java.util.json.Java21.git</developerConnection>
+        <url>https://github.com/simbo1905/java.util.json.Java21</url>
+        <tag>HEAD</tag>
+    </scm>
+    <description>Experimental JsonPath (Goessner) parser to AST and evaluator over the java.util.json Java 21 backport.</description>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.compiler.release>21</maven.compiler.release>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.github.simbo1905.json</groupId>
+            <artifactId>java.util.json</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!-- Treat all warnings as errors, enable all lint warnings -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+                <configuration>
+                    <release>21</release>
+                    <compilerArgs>
+                        <arg>-Xlint:all</arg>
+                        <arg>-Werror</arg>
+                        <arg>-Xdiags:verbose</arg>
+                    </compilerArgs>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPath.java

@@ -0,0 +1,15 @@
+package json.java21.jsonpath;
+
+import java.util.Objects;
+
+/// JsonPath entry point: parse to an AST-backed expression.
+public final class JsonPath {
+
+    public static JsonPathExpression parse(String path) {
+        Objects.requireNonNull(path, "path must not be null");
+        return new JsonPathExpression(JsonPathParser.parse(path));
+    }
+
+    private JsonPath() {}
+}
+

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathAst.java

@@ -0,0 +1,22 @@
+package json.java21.jsonpath;
+
+import java.util.List;
+import java.util.Objects;
+
+record JsonPathAst(List<Segment> segments) {
+    JsonPathAst {
+        Objects.requireNonNull(segments, "segments must not be null");
+        segments.forEach(s -> Objects.requireNonNull(s, "segment must not be null"));
+    }
+
+    sealed interface Segment permits Segment.Child, Segment.Wildcard {
+        record Child(String name) implements Segment {
+            Child {
+                Objects.requireNonNull(name, "name must not be null");
+            }
+        }
+
+        record Wildcard() implements Segment {}
+    }
+}
+

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathEvaluator.java

@@ -0,0 +1,69 @@
+package json.java21.jsonpath;
+
+import jdk.sandbox.java.util.json.JsonArray;
+import jdk.sandbox.java.util.json.JsonObject;
+import jdk.sandbox.java.util.json.JsonValue;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static json.java21.jsonpath.JsonPathAst.Segment;
+
+sealed interface JsonPathEvaluator permits JsonPathEvaluator.Impl {
+
+    static List<JsonValue> select(JsonPathAst ast, JsonValue document) {
+        return Impl.select(ast, document);
+    }
+
+    final class Impl implements JsonPathEvaluator {
+        static List<JsonValue> select(JsonPathAst ast, JsonValue document) {
+            var current = List.of(document);
+            for (final var seg : ast.segments()) {
+                current = apply(seg, current);
+            }
+            return current;
+        }
+
+        private static List<JsonValue> apply(Segment seg, List<JsonValue> current) {
+            return switch (seg) {
+                case Segment.Child child -> selectChild(current, child.name());
+                case Segment.Wildcard ignored -> selectWildcard(current);
+            };
+        }
+
+        private static List<JsonValue> selectChild(List<JsonValue> current, String name) {
+            final var out = new ArrayList<JsonValue>();
+            for (final var node : current) {
+                switch (node) {
+                    case JsonObject obj -> {
+                        final var val = obj.members().get(name);
+                        if (val != null) out.add(val);
+                    }
+                    case JsonArray arr -> arr.elements().forEach(v -> {
+                        if (v instanceof JsonObject o) {
+                            final var val = o.members().get(name);
+                            if (val != null) out.add(val);
+                        }
+                    });
+                    default -> {
+                    }
+                }
+            }
+            return List.copyOf(out);
+        }
+
+        private static List<JsonValue> selectWildcard(List<JsonValue> current) {
+            final var out = new ArrayList<JsonValue>();
+            for (final var node : current) {
+                switch (node) {
+                    case JsonObject obj -> out.addAll(obj.members().values());
+                    case JsonArray arr -> out.addAll(arr.elements());
+                    default -> {
+                    }
+                }
+            }
+            return List.copyOf(out);
+        }
+    }
+}
+

json-java21-jsonpath/src/main/java/json/java21/jsonpath/JsonPathExpression.java

@@ -0,0 +1,20 @@
+package json.java21.jsonpath;
+
+import jdk.sandbox.java.util.json.JsonValue;
+
+import java.util.List;
+import java.util.Objects;
+
+/// A compiled JsonPath expression (AST + evaluator).
+public record JsonPathExpression(JsonPathAst ast) {
+
+    public JsonPathExpression {
+        Objects.requireNonNull(ast, "ast must not be null");
+    }
+
+    public List<JsonValue> select(JsonValue document) {
+        Objects.requireNonNull(document, "document must not be null");
+        return JsonPathEvaluator.select(ast, document);
+    }
+}
+