JsonPath AST and matching

json-java21-jsonpath/AGENTS.md

@@ -0,0 +1,77 @@
+# json-java21-jsonpath Module AGENTS.md
+
+## Purpose
+This module implements a JsonPath query engine for the java.util.json Java 21 backport. It parses JsonPath expressions into an AST and evaluates them against JSON documents.
+
+## Specification
+Based on Stefan Goessner's JSONPath specification:
+https://goessner.net/articles/JsonPath/
+
+## Module Structure
+
+### Main Classes
+- `JsonPath`: Public API facade with `query()` method
+- `JsonPathAst`: Sealed interface hierarchy defining the AST
+- `JsonPathParser`: Recursive descent parser
+- `JsonPathParseException`: Parse error exception
+
+### Test Classes
+- `JsonPathLoggingConfig`: JUL test configuration base class
+- `JsonPathAstTest`: Unit tests for AST records
+- `JsonPathParserTest`: Unit tests for parser
+- `JsonPathGoessnerTest`: Integration tests based on Goessner article examples
+
+## Development Guidelines
+
+### Adding New Operators
+1. Add new record type to `JsonPathAst.Segment` sealed interface
+2. Update `JsonPathParser` to parse the new syntax
+3. Add parser tests in `JsonPathParserTest`
+4. Implement evaluation in `JsonPath.evaluateSegments()`
+5. Add integration tests in `JsonPathGoessnerTest`
+
+### Testing
+```bash
+# Run all tests
+$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Djava.util.logging.ConsoleHandler.level=INFO
+
+# Run specific test class with debug logging
+$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Dtest=JsonPathGoessnerTest -Djava.util.logging.ConsoleHandler.level=FINE
+
+# Run single test method
+$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Dtest=JsonPathGoessnerTest#testAuthorsOfAllBooks -Djava.util.logging.ConsoleHandler.level=FINEST
+```
+
+## Design Principles
+
+1. **No external dependencies**: Only java.base is allowed
+2. **Pure TDD**: Tests first, then implementation
+3. **Functional style**: Immutable records, pure evaluation functions
+4. **Java 21 features**: Records, sealed interfaces, pattern matching with switch
+5. **Defensive copies**: All collections in records are copied for immutability
+
+## Known Limitations
+
+1. **Script expressions**: Only `@.length-1` pattern is supported
+2. **No general expression evaluation**: Complex scripts are not supported
+3. **Stack-based recursion**: May overflow on very deep documents
+
+## API Usage
+
+```java
+import jdk.sandbox.java.util.json.*;
+import json.java21.jsonpath.JsonPath;
+
+JsonValue json = Json.parse(jsonString);
+
+// Preferred: parse once (cache) and reuse
+JsonPath path = JsonPath.parse("$.store.book[*].author");
+List<JsonValue> results = path.query(json);
+
+// If you want a static call site, pass the compiled JsonPath
+List<JsonValue> sameResults = JsonPath.query(path, json);
+```
+
+Notes:
+- Parsing a JsonPath expression is relatively expensive compared to evaluation; cache compiled `JsonPath` instances in hot code paths.
+- `JsonPath.query(String, JsonValue)` is intended for one-off usage only.

json-java21-jsonpath/ARCHITECTURE.md

@@ -0,0 +1,207 @@
+# JsonPath Module Architecture
+
+## Overview
+
+This module implements a JsonPath query engine for the java.util.json Java 21 backport. It parses JsonPath expressions into an AST (Abstract Syntax Tree) and evaluates them against JSON documents parsed by the core library.
+
+**Key Design Principles:**
+- **No external dependencies**: Only uses java.base
+- **Pure TDD development**: Tests define expected behavior before implementation
+- **Functional programming style**: Immutable data structures, pure functions
+- **Java 21 features**: Records, sealed interfaces, pattern matching
+
+## JsonPath Specification
+
+Based on the original JSONPath specification by Stefan Goessner:
+https://goessner.net/articles/JsonPath/
+
+### Supported Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$` | Root element | `$` |
+| `.property` | Child property access | `$.store` |
+| `['property']` | Bracket notation property | `$['store']` |
+| `[n]` | Array index (supports negative) | `$.book[0]`, `$.book[-1]` |
+| `[start:end:step]` | Array slice | `$.book[:2]`, `$.book[::2]` |
+| `[*]` or `.*` | Wildcard (all children) | `$.store.*`, `$.book[*]` |
+| `..` | Recursive descent | `$..author` |
+| `[n,m]` | Union of indices | `$.book[0,1]` |
+| `['a','b']` | Union of properties | `$.store['book','bicycle']` |
+| `[?(@.prop)]` | Filter by existence | `$..book[?(@.isbn)]` |
+| `[?(@.prop op value)]` | Filter by comparison | `$..book[?(@.price<10)]` |
+| `[(@.length-1)]` | Script expression | `$..book[(@.length-1)]` |
+
+### Comparison Operators
+
+| Operator | Description |
+|----------|-------------|
+| `==` | Equal |
+| `!=` | Not equal |
+| `<` | Less than |
+| `<=` | Less than or equal |
+| `>` | Greater than |
+| `>=` | Greater than or equal |
+
+## Module Structure
+
+```
+json-java21-jsonpath/
+├── src/main/java/json/java21/jsonpath/
+│   ├── JsonPath.java           # Public API facade
+│   ├── JsonPathAst.java        # AST definition (sealed interface + records)
+│   ├── JsonPathParser.java     # Recursive descent parser
+│   └── JsonPathParseException.java  # Parse error exception
+└── src/test/java/json/java21/jsonpath/
+    ├── JsonPathLoggingConfig.java   # JUL test configuration
+    ├── JsonPathAstTest.java         # AST unit tests
+    ├── JsonPathParserTest.java      # Parser unit tests
+    └── JsonPathGoessnerTest.java    # Goessner article examples
+```
+
+## AST Design
+
+The AST uses a sealed interface hierarchy with record implementations:
+
+```mermaid
+classDiagram
+    class JsonPathAst {
+        <<sealed interface>>
+    }
+    class Root {
+        <<record>>
+        +segments: List~Segment~
+    }
+    class Segment {
+        <<sealed interface>>
+    }
+    class PropertyAccess {
+        <<record>>
+        +name: String
+    }
+    class ArrayIndex {
+        <<record>>
+        +index: int
+    }
+    class ArraySlice {
+        <<record>>
+        +start: Integer
+        +end: Integer
+        +step: Integer
+    }
+    class Wildcard {
+        <<record>>
+    }
+    class RecursiveDescent {
+        <<record>>
+        +target: Segment
+    }
+    class Filter {
+        <<record>>
+        +expression: FilterExpression
+    }
+    class Union {
+        <<record>>
+        +selectors: List~Segment~
+    }
+    class ScriptExpression {
+        <<record>>
+        +script: String
+    }
+
+    JsonPathAst <|-- Root
+    Segment <|-- PropertyAccess
+    Segment <|-- ArrayIndex
+    Segment <|-- ArraySlice
+    Segment <|-- Wildcard
+    Segment <|-- RecursiveDescent
+    Segment <|-- Filter
+    Segment <|-- Union
+    Segment <|-- ScriptExpression
+```
+
+## Evaluation Flow
+
+```mermaid
+flowchart TD
+    A[JsonPath.query] --> B[JsonPathParser.parse]
+    B --> C[AST Root]
+    C --> D[JsonPath.evaluate]
+    D --> E[evaluateSegments]
+    E --> F{Segment Type}
+    F -->|PropertyAccess| G[evaluatePropertyAccess]
+    F -->|ArrayIndex| H[evaluateArrayIndex]
+    F -->|Wildcard| I[evaluateWildcard]
+    F -->|RecursiveDescent| J[evaluateRecursiveDescent]
+    F -->|Filter| K[evaluateFilter]
+    F -->|ArraySlice| L[evaluateArraySlice]
+    F -->|Union| M[evaluateUnion]
+    F -->|ScriptExpression| N[evaluateScriptExpression]
+    G --> O[Recurse with next segment]
+    H --> O
+    I --> O
+    J --> O
+    K --> O
+    L --> O
+    M --> O
+    N --> O
+    O --> P{More segments?}
+    P -->|Yes| E
+    P -->|No| Q[Add to results]
+```
+
+## Usage Example
+
+```java
+import jdk.sandbox.java.util.json.*;
+import json.java21.jsonpath.JsonPath;
+
+// Parse JSON
+JsonValue json = Json.parse("""
+    {
+      "store": {
+        "book": [
+          {"title": "Book 1", "price": 8.95},
+          {"title": "Book 2", "price": 12.99}
+        ]
+      }
+    }
+    """);
+
+// Query authors of all books
+List<JsonValue> titles = JsonPath.query("$.store.book[*].title", json);
+
+// Query books cheaper than 10
+List<JsonValue> cheapBooks = JsonPath.query("$.store.book[?(@.price<10)]", json);
+
+// Query all prices recursively
+List<JsonValue> prices = JsonPath.query("$..price", json);
+```
+
+## Testing
+
+Run all JsonPath tests:
+
+```bash
+$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Djava.util.logging.ConsoleHandler.level=INFO
+```
+
+Run specific test with debug logging:
+
+```bash
+$(command -v mvnd || command -v mvn || command -v ./mvnw) test -pl json-java21-jsonpath -Dtest=JsonPathGoessnerTest -Djava.util.logging.ConsoleHandler.level=FINE
+```
+
+## Limitations
+
+1. **Script expressions**: Limited support - only `@.length-1` pattern
+2. **Logical operators in filters**: `&&`, `||`, `!` - implemented but not extensively tested
+3. **Deep nesting**: May cause stack overflow on extremely deep documents
+4. **Complex scripts**: No general JavaScript/expression evaluation
+
+## Performance Considerations
+
+1. **Recursive evaluation**: Uses Java call stack for segment traversal
+2. **Result collection**: Results collected in ArrayList during traversal
+3. **No caching**: Each query parses the path fresh
+4. **Defensive copies**: AST records create defensive copies for immutability

json-java21-jsonpath/pom.xml

@@ -0,0 +1,86 @@
+<?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>JsonPath implementation for the java.util.json Java 21 backport; parses JsonPath expressions to AST and matches against JSON documents.</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>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <argLine>-ea</argLine>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>