tree_haver 3.2.3 → 3.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02ffefe8f7a777c04ca0682c3bae06f92d383eacdf2e852755dd6e517cff68bf
-  data.tar.gz: a44f91a685d4736f7eac5a81cc04f43e274e18f8af8904eaa4e1247bf1779764
+  metadata.gz: 5491d352853baeea6501864dec4d703cfd57fea279d6e16edf104c2f1d533c90
+  data.tar.gz: 5c71898a5022f0459bc502bfeb977d7fc7e909ffb3fd0c30fe0b4e2055811fe9
 SHA512:
-  metadata.gz: e0d54671ac5cecea3e8496da4e5a9cf9f4ef4c3abd7bcb926f0d8830e230b2d850845e4a49e824e0144c79c35e7477abf6ee9f4a7284637c1fc0c0ff6ff15033
-  data.tar.gz: 8f7487bd3fba0f8d03128a32a485db360a1db5d97161f2885918992dd516140c37006d7bf2bc7d8f86867ad597fe5920683f126bd1d30c2257764aab19b37c88
+  metadata.gz: c3ebc956fca1d0e57925f3a152aa2465bb0b86c5fcb0fc1622fe0f038d00214d38c04cb2c52bdbb08250074d48bbd2096353bf14d5d70a0b3a7ae9b58997e79a
+  data.tar.gz: 53192de159ce84a508b9795a866ab01ea23af4de7f9b8c4f2be077a7dff1cc394959462926a948a89c84670668beb2a7c2b5eac9f735c39ffabc6f99c6fe9cbb

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,192 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.5] - 2026-01-05
+
+- TAG: [v3.2.5][3.2.5t]
+- COVERAGE: 92.07% -- 2230/2422 lines in 23 files
+- BRANCH COVERAGE: 74.69% -- 788/1055 branches in 23 files
+- 90.37% documented
+
+### Fixed
+
+- **Markly backend**: `Node#text` now correctly handles container nodes (headings, paragraphs, etc.)
+  - Previously returned empty string because `string_content` was checked first (responds but returns empty for containers)
+  - Now falls through to `to_plaintext` or children concatenation when `string_content` is empty
+- **Commonmarker backend**: `Node#text` now correctly handles container nodes
+  - Previously could return empty string in edge cases
+  - Now consistently falls through to children concatenation when `string_content` is empty or raises TypeError
+
+## [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 +901,11 @@ 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.5...HEAD
+[3.2.5]: https://github.com/kettle-rb/tree_haver/compare/v3.2.4...v3.2.5
+[3.2.5t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.5
+[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 +925,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**