tree_haver 3.2.3 → 3.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02ffefe8f7a777c04ca0682c3bae06f92d383eacdf2e852755dd6e517cff68bf
-  data.tar.gz: a44f91a685d4736f7eac5a81cc04f43e274e18f8af8904eaa4e1247bf1779764
+  metadata.gz: 1cea4c9eec7fee0afdffcb4f6b66a7dce698af731cc23028a77f70bc71dc207e
+  data.tar.gz: 68ac3a9c026204a9f0cd42f0afc01f00478405f0be07b74c32c1a85488c7275e
 SHA512:
-  metadata.gz: e0d54671ac5cecea3e8496da4e5a9cf9f4ef4c3abd7bcb926f0d8830e230b2d850845e4a49e824e0144c79c35e7477abf6ee9f4a7284637c1fc0c0ff6ff15033
-  data.tar.gz: 8f7487bd3fba0f8d03128a32a485db360a1db5d97161f2885918992dd516140c37006d7bf2bc7d8f86867ad597fe5920683f126bd1d30c2257764aab19b37c88
+  metadata.gz: 4f48fad6061b7d14cc8cd0b0a7c98e0457f1e65613ef8f4ea469f5cdb36e6137512b42a329f846752e9016a43a2fe6cd24e73cbcce2ecb83b17f4cc9eb3653b6
+  data.tar.gz: 68949852113d833c6d40d8bde278d08c9b4b68b6d90299af99036683b070a3eeac97a92723de435be2c9e7025f718627d9b100a5fbcbcad554e5e3c6e3b141e3

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog
+**# Changelog
 
 [![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog]
 
@@ -30,6 +30,176 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.4] - 2026-01-04
+
+- TAG: [v3.2.4][3.2.4t]
+- COVERAGE: 92.07% -- 2229/2421 lines in 23 files
+- BRANCH COVERAGE: 74.79% -- 786/1051 branches in 23 files
+- 90.37% documented
+
+### Added
+
+- **External backend registration via `backend_module`** - External gems can now register
+  their own pure Ruby backends using the same API as built-in backends. This enables gems
+  like rbs-merge to integrate with `TreeHaver.parser_for` without modifying tree_haver:
+```ruby
+TreeHaver.register_language(
+  :rbs,
+  backend_module: Rbs::Merge::Backends::RbsBackend,
+  backend_type: :rbs,
+  gem_name: "rbs",
+)
+# Now TreeHaver.parser_for(:rbs) works!
+```
+- **`Backends::PURE_RUBY_BACKENDS` constant** - Maps pure Ruby backend names to their
+  language and module info. Used for auto-registration of built-in backends.
+- **`TreeHaver.register_builtin_backends!`** - Registers built-in pure Ruby backends
+  (Prism, Psych, Commonmarker, Markly) in the LanguageRegistry using the same API that
+  external backends use. Called automatically by `parser_for` on first use.
+- **`TreeHaver.ensure_builtin_backends_registered!`** - Idempotent helper that ensures
+  built-in backends are registered exactly once.
+- **`parser_for` now supports registered `backend_module` backends** - When a language
+  has a registered `backend_module`, `parser_for` will use it. This enables external
+  gems to provide language support without tree-sitter grammars:
+  - Checks LanguageRegistry for registered `backend_module` entries
+  - Creates parser from the backend module's `Parser` and `Language` classes
+  - Falls back to tree-sitter and Citrus if no backend_module matches
+- **RBS dependency tags in `DependencyTags`** - New RSpec tags for RBS parsing:
+  - `:rbs_grammar` - tree-sitter-rbs grammar is available and parsing works
+  - `:rbs_parsing` - at least one RBS parser (rbs gem OR tree-sitter-rbs) is available
+  - `:rbs_gem` - the official rbs gem is available (MRI only)
+  - Negated versions: `:not_rbs_grammar`, `:not_rbs_parsing`, `:not_rbs_gem`
+  - New availability methods: `tree_sitter_rbs_available?`, `rbs_gem_available?`, `any_rbs_backend_available?`
+- **Support for tree-sitter 0.26.x ABI** - TreeHaver now fully supports grammars built
+  against tree-sitter 0.26.x (LANGUAGE_VERSION 15). This required updates to vendored
+  dependencies:
+  - **ruby-tree-sitter**: Updated to support tree-sitter 0.26.3 C library API changes
+    including new `ts_language_abi_version()` function, UTF-16 encoding split, and
+    removal of deprecated parser timeout/cancellation APIs
+  - **tree_stump (Rust backend)**: Updated to tree-sitter Rust crate 0.26.3 with new
+    `abi_version()` method, `u32` child indices, and streaming iterator-based query matches
+- **MRI backend now loads grammars with LANGUAGE_VERSION 15** - Previously, MRI backend
+  using ruby_tree_sitter could only load grammars with LANGUAGE_VERSION ≤ 14. Now supports
+  grammars built against tree-sitter 0.26.x.
+- **Rust backend now loads grammars with LANGUAGE_VERSION 15** - Previously, the tree_stump
+  Rust backend reported "Incompatible language version 15. Expected minimum 13, maximum 14".
+  Now supports the latest grammar format.
+- **BackendAPI validation module** - New `TreeHaver::BackendAPI` module for validating
+  backend API compliance:
+  - `BackendAPI.validate(backend_module)` - Returns validation results hash
+  - `BackendAPI.validate!(backend_module)` - Raises on validation failure
+  - `BackendAPI.validate_node_instance(node)` - Validates a node instance
+  - Defines required and optional methods for Language, Parser, Tree, and Node classes
+  - Documents API contract for wrapper vs raw backends
+  - New `examples/validate_backends.rb` script to validate all backends
+- **Java backend Node class now implements full API** - Added missing methods to ensure
+  API consistency with other backends:
+  - `parent` - Get parent node
+  - `next_sibling` - Get next sibling node
+  - `prev_sibling` - Get previous sibling node
+  - `named?` - Check if node is named
+  - `child_by_field_name` - Get child by field name
+  - All methods properly handle jtreesitter 0.26.0's `Optional<Node>` return types
+- **Three environment variables for backend control** - Fine-grained control over which
+  backends are available:
+  - `TREE_HAVER_BACKEND` - Single backend selection (auto, mri, ffi, rust, java, citrus, etc.)
+  - `TREE_HAVER_NATIVE_BACKEND` - Allow list for native backends (auto, none, or comma-separated
+    list like `mri,ffi`). Use `none` for pure-Ruby-only mode.
+  - `TREE_HAVER_RUBY_BACKEND` - Allow list for pure Ruby backends (auto, none, or comma-separated
+    list like `citrus,prism`). Use `none` for native-only mode.
+- **Backend availability now respects allow lists** - When `TREE_HAVER_NATIVE_BACKEND` is set
+  to specific backends (e.g., `mri,ffi`), all other native backends are treated as unavailable.
+  This applies to ALL backend selection mechanisms:
+  - Auto-selection in `backend_module`
+  - Explicit selection via `with_backend(:rust)` - returns nil/unavailable
+  - Explicit selection via `resolve_backend_module(:rust)` - returns nil
+  - RSpec dependency tags (`ffi_available?`, etc.)
+
+  This makes the environment variables a **hard restriction**, not just a hint for auto-selection.
+  Use `TREE_HAVER_NATIVE_BACKEND=none` for pure-Ruby-only mode, or specify exactly which
+  native backends are permitted (e.g., `mri,ffi`).
+- **Java backend updated for jtreesitter 0.26.0** - Full compatibility with jtreesitter 0.26.0:
+  - Updated `Parser#parse` and `Parser#parse_string` to handle `Optional<Tree>` return type
+  - Updated `Tree#root_node` to handle `Optional<Node>` return type
+  - Fixed `parse_string` argument order to match jtreesitter 0.26.0 API: `parse(String, Tree)`
+  - Updated `Language.load_by_name` to use `SymbolLookup` API (single-arg `load(name)` removed)
+  - Added `bin/setup-jtreesitter` script to download jtreesitter JAR from Maven Central
+  - Added `bin/build-grammar` script to build tree-sitter grammars from source
+  - Older versions of jtreesitter are NOT supported
+- **`TREE_HAVER_BACKEND_PROTECT` environment variable** - Explicit control over backend
+  conflict protection. Set to `false` to disable protection that prevents mixing
+  incompatible native backends (e.g., FFI after MRI). Useful for testing scenarios
+  where you understand the risks. Default behavior (protection enabled) unchanged.
+
+### Changed
+
+- **API normalized: `from_library` is now universal** - All language-specific backends
+  (Psych, Prism, Commonmarker, Markly) now implement `Language.from_library` for API
+  consistency. This allows `TreeHaver.parser_for(:yaml)` to work uniformly regardless
+  of which backend is active:
+  - **Psych**: `from_library` accepts (and ignores) path/symbol, returns YAML language
+  - **Prism**: `from_library` accepts (and ignores) path/symbol, returns Ruby language
+  - **Commonmarker**: `from_library` accepts (and ignores) path/symbol, returns Markdown language
+  - **Markly**: `from_library` accepts (and ignores) path/symbol, returns Markdown language
+  - All raise `TreeHaver::NotAvailable` if a different language is requested
+- **Citrus backend `from_library` now looks up registered grammars** - Instead of always
+  raising an error, `Backends::Citrus::Language.from_library` now looks up registered
+  Citrus grammars by name via `LanguageRegistry`. This enables `TreeHaver.parser_for(:toml)`
+  to work seamlessly when a Citrus grammar has been registered with
+  `TreeHaver.register_language(:toml, grammar_module: TomlRB::Document)`.
+- **Java backend requires jtreesitter >= 0.26.0** - Due to API changes in jtreesitter,
+  older versions are no longer supported. The tree-sitter runtime library must also be
+  version 0.26.x to match.
+  by the RSpec dependency tags. This ensures tests tagged with `:mri_backend` only run when
+  MRI is in the allow list. Same for `TREE_HAVER_RUBY_BACKEND` and pure Ruby backends.
+- New `TreeHaver.allowed_native_backends` method returns the allow list for native backends.
+- New `TreeHaver.allowed_ruby_backends` method returns the allow list for pure Ruby backends.
+- New `TreeHaver.backend_allowed?(backend)` method checks if a specific backend is allowed
+  based on the current environment variable settings.
+- New `DependencyTags.allowed_native_backends` and `DependencyTags.allowed_ruby_backends` methods.
+- Updated `examples/test_backend_selection.rb` script to test all three environment variables.
+- **`LanguageRegistry` now supports any backend type** - Previously only `:tree_sitter` and
+  `:citrus` were documented. Now supports arbitrary backend types including `:prism`, `:psych`,
+  `:commonmarker`, `:markly`, `:rbs`, or any custom type. External gems can register their
+  own backend types using the same API.
+- **`register_language` accepts `backend_module` parameter** - New parameter for registering
+  pure Ruby backends. The module must provide `Language` and `Parser` classes with the
+  standard TreeHaver API (`available?`, `capabilities`, `from_library`, etc.).
+
+### Fixed
+
+- **`TreeHaver::Node#text` now handles backends with different `text` method signatures** -
+  Previously, `Node#text` would call `@inner_node.text` directly, but `TreeStump::Node#text`
+  (Rust backend) requires the source as an argument (`text(source)`). This caused
+  `ArgumentError: wrong number of arguments (given 0, expected 1)` when using the Rust
+  backend. Now `Node#text` checks the method arity and passes the source when required:
+  - Arity 0 or -1: calls `@inner_node.text` without arguments
+  - Arity >= 1: calls `@inner_node.text(@source)` with source
+  - Falls back to byte-based extraction if source is available
+
+- **AUTO mode now gracefully falls back when explicitly requested backend is blocked** -
+  Previously, if `TREE_HAVER_BACKEND=ffi` was set in the environment but FFI was blocked
+  due to MRI being used first (backend conflict protection), `parser_for` would raise a
+  `BackendConflict` error. Now, when the explicitly requested backend is blocked by a
+  **backend conflict** (e.g., FFI after MRI causes segfaults):
+  - `backend_module` detects the conflict and falls back to auto-selection
+  - `resolve_native_backend_module` rescues `BackendConflict` and continues to the next
+    backend in the priority list
+  - This enables seamless multi-backend usage in test suites where different tests use
+    different backends, but one backend has already "poisoned" the process for another.
+
+  Note: This fallback only applies to **backend conflicts** (runtime incompatibility).
+  If a backend is disallowed by `TREE_HAVER_NATIVE_BACKEND` or `TREE_HAVER_RUBY_BACKEND`,
+  it will simply be unavailable—no error is raised, but no fallback occurs either.
+
+- **`java_backend_available?` now verifies grammar loading works** - Previously, the
+  `DependencyTags.java_backend_available?` method only checked if java-tree-sitter
+  classes could be loaded, but didn't verify that grammars could actually be used.
+  This caused tests tagged with `:java_backend` to run on JRuby even when the grammar
+  `.so` files (built for MRI) were incompatible with java-tree-sitter's Foreign Function
+  Memory API. Now the check does a live test by attempting to load a grammar, ensuring
+  the tag accurately reflects whether the Java backend is fully functional.
+
 ## [3.2.3] - 2026-01-02
 
 - TAG: [v3.2.3][3.2.3t]
@@ -715,7 +885,9 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.3...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.4...HEAD
+[3.2.4]: https://github.com/kettle-rb/tree_haver/compare/v3.2.3...v3.2.4
+[3.2.4t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.4
 [3.2.3]: https://github.com/kettle-rb/tree_haver/compare/v3.2.2...v3.2.3
 [3.2.3t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.3
 [3.2.2]: https://github.com/kettle-rb/tree_haver/compare/v3.2.1...v3.2.2
@@ -735,4 +907,4 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 [2.0.0]: https://github.com/kettle-rb/tree_haver/compare/v1.0.0...v2.0.0
 [2.0.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v2.0.0
 [1.0.0]: https://github.com/kettle-rb/tree_haver/compare/a89211bff10f4440b96758a8ac9d7d539001b0c8...v1.0.0
-[1.0.0t]: https://github.com/kettle-rb/tree_haver/tags/v1.0.0
+[1.0.0t]: https://github.com/kettle-rb/tree_haver/tags/v1.0.0**

data/README.md

@@ -185,25 +185,120 @@ gem "citrus", "~> 3.0"
 
 #### Java Backend (JRuby only)
 
-No additional dependencies required beyond grammar JARs built for java-tree-sitter / jtreesitter.
+**Requires jtreesitter >= 0.26.0** from Maven Central. Older versions are not supported due to breaking API changes.
+
+```ruby
+# No gem dependency - uses JRuby's built-in Java integration
+# Download the JAR:
+# curl -L -o jtreesitter-0.26.0.jar \
+#   "https://repo1.maven.org/maven2/io/github/tree-sitter/jtreesitter/0.26.0/jtreesitter-0.26.0.jar"
+
+# Set environment variable:
+# export TREE_SITTER_JAVA_JARS_DIR=/path/to/jars
+```
+
+**Also requires**:
+- Tree-sitter runtime library (`libtree-sitter.so`) version 0.26+ (must match jtreesitter version)
+- Grammar `.so` files built against tree-sitter 0.26+ (or rebuilt with `tree-sitter generate`)
 
 ### Backend Platform Compatibility
 
 Not all backends work on all Ruby platforms. Here's a complete compatibility matrix:
 
-| Backend | MRI | JRuby | TruffleRuby | Notes |
-| --- | :-: | :-: | :-: | --- |
-| **MRI** ([ruby\_tree\_sitter](https://github.com/Faveod/ruby-tree-sitter)) | ✅ | ❌ | ❌ | C extension, MRI only |
-| **Rust** ([tree\_stump](https://github.com/joker1007/tree_stump)) | ✅ | ❌ | ❌ | magnus/rb-sys incompatible with non-MRI |
-| **FFI** | ✅ | ✅ | ❌ | TruffleRuby FFI doesn't support `STRUCT_BY_VALUE` |
-| **Java** ([jtreesitter](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter)) | ❌ | ✅ | ❌ | JRuby only, requires grammar JARs |
-| **Prism** | ✅ | ✅ | ✅ | Ruby parsing, stdlib in Ruby 3.4+ |
-| **Psych** | ✅ | ✅ | ✅ | YAML parsing, stdlib |
-| **Citrus** | ✅ | ✅ | ✅ | Pure Ruby, no native dependencies |
-| **Commonmarker** | ✅ | ❌ | ❓ | Rust extension for Markdown |
-| **Markly** | ✅ | ❌ | ❓ | C extension for Markdown |
+| Backend | MRI | JRuby | TruffleRuby | API Complete | Notes |
+| --- | :-: | :-: | :-: | :-: | --- |
+| **MRI** ([ruby\_tree\_sitter](https://github.com/Faveod/ruby-tree-sitter)) | ✅ | ❌ | ❌ | ✅ | C extension, MRI only |
+| **Rust** ([tree\_stump](https://github.com/joker1007/tree_stump)) | ✅ | ❌ | ❌ | ✅ | magnus/rb-sys incompatible with non-MRI |
+| **FFI** | ✅ | ✅ | ❌ | ⚠️ | TruffleRuby FFI doesn't support `STRUCT_BY_VALUE` |
+| **Java** ([jtreesitter](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter)) | ❌ | ✅ | ❌ | ✅ | JRuby only, requires jtreesitter >= 0.26.0 |
+| **Prism** | ✅ | ✅ | ✅ | ✅ | Ruby parsing, stdlib in Ruby 3.4+ |
+| **Psych** | ✅ | ✅ | ✅ | ✅ | YAML parsing, stdlib |
+| **Citrus** | ✅ | ✅ | ✅ | ⚠️ | Pure Ruby, no native dependencies |
+| **Commonmarker** | ✅ | ❌ | ❓ | ✅ | Rust extension for Markdown |
+| **Markly** | ✅ | ❌ | ❓ | ✅ | C extension for Markdown |
+
+**Legend**: ✅ = Works / Complete, ❌ = Does not work, ❓ = Untested, ⚠️ = Partial (some optional methods missing)
+
+**API Complete** indicates whether the backend implements all optional Node methods (`parent`, `next_sibling`, `prev_sibling`, `named?`, `missing?`, `text`, `child_by_field_name`). Backends marked ⚠️ work but may be missing some advanced traversal methods. Use `TreeHaver::BackendAPI.validate(backend_module)` to check specific backends.
+
+### Version Requirements for Tree-Sitter Backends
+
+#### tree-sitter Runtime Library
+
+All tree-sitter backends (MRI, Rust, FFI, Java) require the tree-sitter runtime library. **Version 0.26+ is required** for the Java backend (to match jtreesitter 0.26.0). Other backends may work with 0.24+, but 0.26+ is recommended for consistency.
+
+```bash
+# Check your tree-sitter version
+tree-sitter --version  # Should be 0.26.0 or newer for Java backend
+
+# macOS
+brew install tree-sitter
+
+# Ubuntu/Debian
+apt-get install libtree-sitter0 libtree-sitter-dev
+
+# Fedora
+dnf install tree-sitter tree-sitter-devel
+```
+
+#### jtreesitter (Java Backend)
+
+**The Java backend requires jtreesitter >= 0.26.0.** This version introduced breaking API changes:
+
+- `Parser.parse()` returns `Optional<Tree>` instead of `Tree`
+- `Tree.getRootNode()` returns `Node` directly (not `Optional<Node>`)
+- `Node.getChild()`, `getParent()`, `getNextSibling()`, `getPrevSibling()` return `Optional<Node>`
+- `Language.load(name)` was removed; use `SymbolLookup` API instead
+
+Older versions of jtreesitter are **NOT supported**.
+
+```bash
+# Download jtreesitter 0.26.0 from Maven Central
+curl -L -o jtreesitter-0.26.0.jar \
+  "https://repo1.maven.org/maven2/io/github/tree-sitter/jtreesitter/0.26.0/jtreesitter-0.26.0.jar"
 
-**Legend**: ✅ = Works, ❌ = Does not work, ❓ = Untested
+# Or use the provided setup script
+bin/setup-jtreesitter
+```
+
+Set the environment variable to point to your JAR directory:
+
+```bash
+export TREE_SITTER_JAVA_JARS_DIR=/path/to/jars
+```
+
+#### Grammar ABI Compatibility
+
+**CRITICAL**: Grammars must be built against a compatible tree-sitter version.
+
+Tree-sitter 0.24+ changed how language ABI versions are reported (from `ts_language_version()` to `ts_language_abi_version()`). For the Java backend with jtreesitter 0.26.0, grammars must be built against tree-sitter 0.26+. If you get errors like:
+
+```
+Failed to load tree_sitter_toml
+Version mismatch detected: The grammar was built against tree-sitter < 0.26
+```
+
+You need to rebuild the grammar from source:
+
+```bash
+# Use the provided build script
+bin/build-grammar toml
+
+# Or manually:
+git clone https://github.com/tree-sitter-grammars/tree-sitter-toml
+cd tree-sitter-toml
+tree-sitter generate  # Regenerates parser.c for your tree-sitter version
+cc -shared -fPIC -o libtree-sitter-toml.so src/parser.c src/scanner.c -I src
+```
+
+**Grammar sources for common languages:**
+
+| Language | Repository |
+| --- | --- |
+| TOML | [tree-sitter-grammars/tree-sitter-toml](https://github.com/tree-sitter-grammars/tree-sitter-toml) |
+| JSON | [tree-sitter/tree-sitter-json](https://github.com/tree-sitter/tree-sitter-json) |
+| JSONC | [WhyNotHugo/tree-sitter-jsonc](https://gitlab.com/WhyNotHugo/tree-sitter-jsonc) |
+| Bash | [tree-sitter/tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) |
 
 #### TruffleRuby Limitations
 
@@ -215,11 +310,12 @@ TruffleRuby users should use: **Prism** (Ruby), **Psych** (YAML), **Citrus** (TO
 
 #### JRuby Limitations
 
-JRuby runs on the JVM and **cannot load native `.so` extensions**:
+JRuby runs on the JVM and **cannot load native `.so` extensions via Ruby's C API**:
 
   - **MRI/Rust**: C and Rust extensions simply cannot be loaded
   - **FFI**: Works\! JRuby has excellent FFI support
-JRuby users should use: **FFI backend** or **Java backend** for tree-sitter, plus **Prism**, **Psych**, **Citrus** for other formats.
+  - **Java**: Works\! The Java backend uses jtreesitter (requires >= 0.26.0)
+JRuby users should use: **Java backend** (best performance, full API) or **FFI backend** for tree-sitter, plus **Prism**, **Psych**, **Citrus** for other formats.
 
 [ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
 [tree_stump]: https://github.com/joker1007/tree_stump
@@ -314,9 +410,9 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 [citrus]: https://github.com/mjackson/citrus
 [tree_haver]: https://github.com/kettle-rb/tree_haver
 
-**Note:** Java backend works with grammar JARs built specifically for `java-tree-sitter` / `jtreesitter`, or grammar .so files that statically link tree-sitter. This is why FFI is recommended for JRuby & TruffleRuby.
+**Note:** Java backend works with grammar `.so` files built against tree-sitter 0.24+. The grammars must be rebuilt with `tree-sitter generate` if they were compiled against older tree-sitter versions. FFI is recommended for JRuby as it's easier to set up.
 
-**Note:** TreeHaver can use `ruby_tree_sitter` (MRI) or `tree_stump` (MRI, JRuby?) as backends, or `java-tree-sitter` ([docs](https://tree-sitter.github.io/java-tree-sitter/), [maven](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter), [source](https://github.com/tree-sitter/java-tree-sitter), JRuby), or FFI on any backend, giving you TreeHaver's unified API, grammar discovery, and security features, plus full access to incremental parsing when using those backends.
+**Note:** TreeHaver can use `ruby_tree_sitter` (MRI) or `tree_stump` (MRI) as backends, or `java-tree-sitter` / `jtreesitter` >= 0.26.0 ([docs](https://tree-sitter.github.io/java-tree-sitter/), [maven](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter), [source](https://github.com/tree-sitter/java-tree-sitter), JRuby), or FFI on any backend, giving you TreeHaver's unified API, grammar discovery, and security features, plus full access to incremental parsing when using those backends.
 
 **Note:** `tree_stump` currently requires unreleased fixes in the `main` branch.
 
@@ -471,7 +567,7 @@ TreeHaver supports 10 parsing backends, each with different trade-offs. The `aut
 | **MRI** | C extension via ruby\_tree\_sitter | ⚡ Fastest | MRI only | [JSON](examples/mri_json.rb) · [JSONC](examples/mri_jsonc.rb) · \~\~Bash\~\~\* · [TOML](examples/mri_toml.rb) |
 | **Rust** | Precompiled via tree\_stump | ⚡ Very Fast | ✅ Good | [JSON](examples/rust_json.rb) · [JSONC](examples/rust_jsonc.rb) · \~\~Bash\~\~\* · [TOML](examples/rust_toml.rb) |
 | **FFI** | Dynamic linking via FFI | 🔵 Fast | ✅ Universal | [JSON](examples/ffi_json.rb) · [JSONC](examples/ffi_jsonc.rb) · [Bash](examples/ffi_bash.rb) · [TOML](examples/ffi_toml.rb) |
-| **Java** | JNI bindings | ⚡ Very Fast | JRuby only | [JSON](examples/java_json.rb) · [JSONC](examples/java_jsonc.rb) · [Bash](examples/java_bash.rb) · [TOML](examples/java_toml.rb) |
+| **Java** | JNI bindings (jtreesitter >= 0.26.0) | ⚡ Very Fast | JRuby only | [JSON](examples/java_json.rb) · [JSONC](examples/java_jsonc.rb) · [Bash](examples/java_bash.rb) · [TOML](examples/java_toml.rb) |
 
 #### Language-Specific Backends (Native Parser Integration)
 
@@ -745,12 +841,34 @@ export TREE_SITTER_TOML_PATH=/usr/local/lib/libtree-sitter-toml.so
 export TREE_SITTER_JSON_PATH=/usr/local/lib/libtree-sitter-json.so
 ```
 
-#### JRuby-Specific: Java Backend JARs
+#### JRuby-Specific: Java Backend Configuration
+
+For the Java backend on JRuby, you need:
 
-For the Java backend on JRuby:
+1. **jtreesitter >= 0.26.0** JAR from Maven Central
+2. **Tree-sitter runtime library** (`libtree-sitter.so`) version 0.26+
+3. **Grammar `.so` files** built against tree-sitter 0.26+
 
 ``` bash
+# Download jtreesitter JAR (or use bin/setup-jtreesitter)
 export TREE_SITTER_JAVA_JARS_DIR=/path/to/java-tree-sitter/jars
+
+# Point to tree-sitter runtime (must be 0.26+)
+export TREE_SITTER_RUNTIME_LIB=/usr/local/lib/libtree-sitter.so
+
+# Point to grammar libraries (must be built for tree-sitter 0.26+)
+export TREE_SITTER_TOML_PATH=/path/to/libtree-sitter-toml.so
+```
+
+**Building grammars for Java backend:**
+
+If you get "version mismatch" errors, rebuild the grammar:
+
+```bash
+# Use the provided build script
+bin/build-grammar toml
+
+# This regenerates parser.c for your tree-sitter version and compiles it
 ```
 
 For more see [docs](https://tree-sitter.github.io/java-tree-sitter/), [maven](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter), and [source](https://github.com/tree-sitter/java-tree-sitter).
@@ -1977,7 +2095,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.200-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.421-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year