JsonPath runtime compilation

[simbo1905]

This pull request contains changes generated by a Cursor Cloud Agent

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[gemini-code-assist]

Summary of Changes

Hello @simbo1905, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the json-java21-jsonpath library by introducing an optional runtime compilation feature for JsonPath expressions. Previously, all JsonPath evaluations relied on an Abstract Syntax Tree (AST) interpreter. With this change, users can now compile their JsonPath expressions into optimized Java bytecode at runtime, which is particularly beneficial for "hot paths" requiring high performance. The JsonPath class has been refactored into an interface to accommodate both the original AST-backed implementation and the new compiled version, providing a flexible and extensible architecture.

Highlights

• Runtime Compilation Feature: Introduced an optional runtime compilation mechanism for JsonPath expressions, allowing for performance improvements on frequently used paths.
• JsonPath Interface Refactoring: The JsonPath class has been refactored into an interface, enabling different implementations (AST-backed and compiled).
• New compile() Method: A compile() method was added to the JsonPath interface, which returns a potentially runtime-compiled version of the JsonPath.
• Modularized Evaluation Logic: The original AST-walking evaluation logic was extracted into a new JsonPathAstInterpreter class, promoting cleaner separation of concerns.
• Dynamic Code Generation: New internal classes (JsonPathCompiler, JsonPathRuntime) were added to handle dynamic Java source code generation, in-memory compilation, and loading of optimized JsonPath evaluators.
• Documentation Update: The README.md was updated to inform users about the new runtime compilation option and its usage.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4530a3c6cd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Handle recursive-descent array indices in compiled paths

The compiler’s recursive-descent emitter only handles property names and wildcards, and falls through to Stream.empty() for everything else. That means expressions like ..[0] (which the parser allows and the AST interpreter currently supports in JsonPathAstInterpreter.evaluateTargetSegment) will return no results once compile() is used. This is a behavior regression specific to compiled paths: the AST-backed evaluator still resolves recursive array indices. Consider emitting a recursive-index selector (mirroring the interpreter’s ArrayIndex handling) instead of dropping to empty.

Useful? React with 👍 / 👎.

[gemini-code-assist]

Code Review

This pull request introduces a major new feature: runtime compilation of JsonPath expressions for improved performance on hot paths. The implementation is well-structured, refactoring the original JsonPath class into a clean interface and several new classes with distinct responsibilities: an AST-based interpreter, a runtime compiler, and a runtime library for the compiled code. The code is of high quality, with good fallback mechanisms and thorough tests.

My main feedback is a minor inconsistency in logging behavior between the AST-based and the new compiled implementations. I've added a specific comment with a suggestion to align them for better diagnostics.

[gemini-code-assist]

The compiled path's query method just delegates, but this misses the FINE-level logging that the AST-based implementation has. To ensure consistent behavior for diagnostics, logging should be added here. This wrapper is the ideal place for such cross-cutting concerns.

final class JsonPathCompiledPath implements JsonPathCompiled {

    private static final java.util.logging.Logger LOG = java.util.logging.Logger.getLogger(JsonPathCompiledPath.class.getName());

    private final String expression;
    private final String generatedClassName;
    private final String javaSource;
    private final JsonPath delegate;

    JsonPathCompiledPath(String expression, String generatedClassName, String javaSource, JsonPath delegate) {
        this.expression = Objects.requireNonNull(expression, "expression must not be null");
        this.generatedClassName = Objects.requireNonNull(generatedClassName, "generatedClassName must not be null");
        this.javaSource = Objects.requireNonNull(javaSource, "javaSource must not be null");
        this.delegate = Objects.requireNonNull(delegate, "delegate must not be null");
    }

    @Override
    public List<JsonValue> query(JsonValue json) {
        // The delegate also performs this check, but we log before calling.
        Objects.requireNonNull(json, "json must not be null");
        LOG.fine(() -> "Querying document with compiled path: " + this);
        return delegate.query(json);
    }