tree_haver 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 141cf04a77bd50b8802a20eb098ddb03352b08fa6b1592b95180dcf336cc25e1
-  data.tar.gz: 134418492ecd86ef348221dfb7cef3f7c459acee00318c2669bdd666dc37d4ba
+  metadata.gz: 4086bd0349e2cfd205314110a7af3b8548530cc8d5f4328d84ecc38f840744f9
+  data.tar.gz: 01c27844a370a8235518002d6947226061931a127de6473b495d99ac4549cefd
 SHA512:
-  metadata.gz: bafe3a43549cecf6e38a3c8f68c4f072348050d2a3807c4ad8fa9ec2f1d073892abaf5b4300e750a2282849c1bdd081c9ef122b1f2dcb0c5044bddedb451c7b2
-  data.tar.gz: 62e7cd0947fdda50ea54f9e9a1b07a05c142388ef56a7a25a9ebb177f12804883cc3fc59dbfbbd3d5f08d062f59f89e850bb5d71733521344c53b5eec19ada78
+  metadata.gz: 1a77445cd016d4cf0d5cb0cf28aee79e6a664578ac2da92babc663e3df483f024f1c17c434ef19d4941cf25dd6674aea68177d71c096b75e3d83315d4d0e222a
+  data.tar.gz: a53b817c9a24181d7b2b17810977f0978085c0603ca07b41f9189a221d1e3a7cd0b2e7751e53f4440883ea02e22c262de6b965ca9dedb4bf7bc6282ff29d57c3

data/CHANGELOG.md

@@ -30,6 +30,167 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.0] - 2025-12-30
+
+- TAG: [v3.2.0][3.2.0t]
+- COVERAGE: 86.82% -- 2167/2496 lines in 22 files
+- BRANCH COVERAGE: 66.79% -- 734/1099 branches in 22 files
+- 90.03% documented
+
+### Added
+
+- `TreeHaver::CITRUS_DEFAULTS` constant with default Citrus configurations for known languages
+  - Enables automatic Citrus fallback for TOML without explicit `citrus_config` parameter
+  - Currently includes configuration for `:toml` (gem: `toml-rb`, const: `TomlRB::Document`)
+- Regression test suite for Citrus fallback (`spec/integration/citrus_fallback_spec.rb`)
+  - Tests `parser_for` with all tree-sitter backends stubbed as unavailable (simulating TruffleRuby)
+  - Tests `CitrusGrammarFinder` with nil `gem_name` and `require_path`
+  - Tests explicit Citrus backend usage on MRI via `with_backend(:citrus)`
+- Shared examples for TOML parsing tests (`spec/support/shared_examples/toml_parsing_examples.rb`)
+  - `"toml parsing basics"` - tests basic parsing, positions, children, text extraction
+  - `"toml node navigation"` - tests first_child, named_children navigation
+- Multi-backend TOML test suite (`spec/integration/multi_backend_toml_spec.rb`)
+  - Runs shared examples against both tree-sitter-toml and Citrus/toml-rb backends
+  - Tests backend equivalence for parsing results and positions
+  - Tagged appropriately so tests run on whichever backends are available
+- Backend Platform Compatibility section to README
+  - Complete compatibility matrix showing which backends work on MRI, JRuby, TruffleRuby
+  - Detailed explanations for TruffleRuby and JRuby limitations
+- `FFI.available?` method at module level for API consistency with other backends
+- `TreeHaver.resolve_native_backend_module` method for resolving only tree-sitter backends
+- `TreeHaver::NATIVE_BACKENDS` constant listing backends that support shared libraries
+- TruffleRuby short-circuit in `resolve_native_backend_module` for efficiency
+  - Avoids trying 3 backends that are all known to fail on TruffleRuby
+- `citrus_available?` method to check if Citrus backend is available
+
+### Fixed
+
+- **`TreeHaver::Node#child` now returns `nil` for out-of-bounds indices on all backends**
+  - MRI backend (ruby_tree_sitter) raises `IndexError` for invalid indices
+  - Other backends return `nil` for invalid indices
+  - Now consistently returns `nil` across all backends for API compatibility
+- **Citrus backend `calculate_point` returns negative column values**
+  - When `offset` was 0, `@source.rindex("\n", -1)` searched from end of string
+  - This caused `column = 0 - (position_of_last_newline) - 1` to be negative (e.g., -34)
+  - Fix: Early return `{row: 0, column: 0}` for `offset <= 0`
+  - This bug affected both MRI and TruffleRuby when using Citrus backend
+- **Citrus fallback fails on TruffleRuby when no explicit `citrus_config` provided**
+  - `parser_for(:toml)` would fail with `TypeError: no implicit conversion of nil into String`
+  - Root cause: `citrus_config` defaulted to `{}`, so `citrus_config[:gem_name]` was `nil`
+  - `CitrusGrammarFinder` was instantiated with `gem_name: nil`, causing `require nil`
+  - On TruffleRuby, this triggered a bug in `bundled_gems.rb` calling `File.path` on nil
+  - Fix: Added `CITRUS_DEFAULTS` with known Citrus configurations (TOML currently)
+  - Fix: `parser_for` now uses `CITRUS_DEFAULTS[name]` when no explicit config provided
+  - Fix: Added guard in `CitrusGrammarFinder#available?` to return false when `require_path` is nil
+  - Fix: Added `TypeError` to rescue clause for TruffleRuby-specific edge cases
+- **`from_library` no longer falls back to pure-Ruby backends**
+  - Previously, calling `Language.from_library(path)` on TruffleRuby would fall back to Citrus
+    backend which then raised a confusing error about not supporting shared libraries
+  - Now `from_library` only considers native tree-sitter backends (MRI, Rust, FFI, Java)
+  - Clear error message when no native backend is available explaining the situation
+- **Integration specs now use `parser_for` instead of explicit paths**
+  - `tree_edge_cases_spec.rb` and `node_edge_cases_spec.rb` now use `TreeHaver.parser_for(:toml)`
+    which auto-discovers the best available backend (tree-sitter or Citrus fallback)
+  - Tests now work correctly on all platforms (MRI, JRuby, TruffleRuby)
+  - Tagged with `:toml_parsing` which passes if ANY toml parser is available
+- **Core specs now use `parser_for` instead of explicit paths**
+  - `tree_spec.rb`, `node_spec.rb`, `parser_spec.rb` converted to use `TreeHaver.parser_for(:toml)`
+  - All `:toml_grammar` tags changed to `:toml_parsing` for cross-platform compatibility
+  - Tests now run on JRuby and TruffleRuby via Citrus/toml-rb fallback
+- FFI backend now properly reports as unavailable on TruffleRuby
+  - `ffi_gem_available?` returns `false` on TruffleRuby since tree-sitter uses STRUCT_BY_VALUE return types
+  - `FFI.available?` added at module level (was only in Native submodule)
+  - Prevents confusing runtime errors (Polyglot::ForeignException) by detecting incompatibility upfront
+  - Dependency tags now check `truffleruby?` before attempting FFI backend tests
+- MRI backend now properly reports as unavailable on JRuby and TruffleRuby
+  - `available?` returns `false` on non-MRI platforms (C extension only works on MRI)
+- Rust backend now properly reports as unavailable on JRuby and TruffleRuby
+  - `available?` returns `false` on non-MRI platforms (magnus requires MRI's C API)
+- Backend compatibility matrix spec now properly skips tests for platform-incompatible backends
+  - MRI and Rust backends skip on JRuby/TruffleRuby with clear skip messages
+  - FFI backend skips on TruffleRuby with clear skip message
+
+### Changed
+
+- **BREAKING: RSpec Dependency Tag Naming Convention Overhaul**
+  - All dependency tags now follow consistent naming conventions with suffixes
+  - Backend tags now use `*_backend` suffix (e.g., `:commonmarker_backend`, `:markly_backend`)
+  - Engine tags now use `*_engine` suffix (e.g., `:mri_engine`, `:jruby_engine`, `:truffleruby_engine`)
+  - Grammar tags now use `*_grammar` suffix (e.g., `:bash_grammar`, `:toml_grammar`, `:json_grammar`)
+  - Parsing capability tags now use `*_parsing` suffix (e.g., `:toml_parsing`, `:markdown_parsing`)
+  - **Migration required**: Update specs using legacy tags:
+    - `:commonmarker` → `:commonmarker_backend`
+    - `:markly` → `:markly_backend`
+    - `:mri` → `:mri_engine`
+    - `:jruby` → `:jruby_engine`
+    - `:truffleruby` → `:truffleruby_engine`
+    - `:tree_sitter_bash` → `:bash_grammar`
+    - `:tree_sitter_toml` → `:toml_grammar`
+    - `:tree_sitter_json` → `:json_grammar`
+    - `:tree_sitter_jsonc` → `:jsonc_grammar`
+    - `:toml_backend` → `:toml_parsing`
+    - `:markdown_backend` → `:markdown_parsing`
+- **Removed inner-merge dependency tags from tree_haver**
+  - Tags `:toml_merge`, `:json_merge`, `:prism_merge`, `:psych_merge` removed
+  - These belong in ast-merge gem, not tree_haver
+  - Use `require "ast/merge/rspec/dependency_tags"` for merge gem tags
+- **API Consistency**: All backends now have uniform `available?` API at module level:
+  - `TreeHaver::Backends::FFI.available?` - checks ffi gem + not TruffleRuby + MRI not loaded
+  - `TreeHaver::Backends::MRI.available?` - checks MRI platform + ruby_tree_sitter gem
+  - `TreeHaver::Backends::Rust.available?` - checks MRI platform + tree_stump gem
+  - `TreeHaver::Backends::Java.available?` - checks JRuby platform + jtreesitter JAR
+  - `TreeHaver::Backends::Prism.available?` - checks prism gem (all platforms)
+  - `TreeHaver::Backends::Psych.available?` - checks psych stdlib (all platforms)
+  - `TreeHaver::Backends::Commonmarker.available?` - checks commonmarker gem (all platforms)
+  - `TreeHaver::Backends::Markly.available?` - checks markly gem (all platforms)
+  - `TreeHaver::Backends::Citrus.available?` - checks citrus gem (all platforms)
+- README now accurately documents TruffleRuby backend support
+  - FFI backend doesn't work on TruffleRuby due to `STRUCT_BY_VALUE` limitation in TruffleRuby's FFI
+  - Rust backend (tree_stump) doesn't work due to magnus/rb-sys incompatibility with TruffleRuby's C API
+  - TruffleRuby users should use Prism, Psych, Commonmarker, Markly, or Citrus backends
+- Documented confirmed tree-sitter backend limitations:
+  - **TruffleRuby**: No tree-sitter backend works (FFI, MRI, Rust all fail)
+  - **JRuby**: Only Java and FFI backends work; Rust/MRI don't
+- Updated Rust Backend section with platform compatibility notes
+- Updated FFI Backend section with TruffleRuby limitation details
+- Use kettle-rb/ts-grammar-setup GHA in CI workflows
+
+### Fixed
+
+- Rakefile now properly overrides `test` task after `require "kettle/dev"`
+  - Works around a bug in kettle-dev where test task runs minitest loader in CI
+  - Ensures `rake test` runs RSpec specs instead of empty minitest suite
+- `TreeHaver::RSpec::DependencyTags` now catches TruffleRuby FFI exceptions
+  - TruffleRuby's FFI raises `Polyglot::ForeignException` for unsupported types like `STRUCT_BY_VALUE`
+  - `ffi_available?` and `libtree_sitter_available?` now return `false` instead of crashing
+  - Fixes spec loading errors on TruffleRuby
+- `TreeHaver::Backends::FFI::Language.from_library` now catches `RuntimeError` from TruffleRuby
+  - TruffleRuby raises `RuntimeError` instead of `LoadError` when a shared library cannot be opened
+  - Now properly converts to `TreeHaver::NotAvailable` with descriptive message
+- `TreeHaver::Backends::FFI::Native.try_load!` now only sets `@loaded = true` after all `attach_function` calls succeed
+  - Previously, `loaded?` returned `true` even when `attach_function` failed (e.g., on TruffleRuby)
+  - Now `loaded?` correctly returns `false` when FFI functions couldn't be attached
+  - Ensures FFI tests are properly skipped on TruffleRuby
+
+## [3.1.2] - 2025-12-29
+
+- TAG: [v3.1.2][3.1.2t]
+- COVERAGE: 87.40% -- 2171/2484 lines in 22 files
+- BRANCH COVERAGE: 67.04% -- 726/1083 branches in 22 files
+- 90.03% documented
+
+### Added
+
+- Enhanced `TreeHaver::RSpec::DependencyTags` debugging
+  - `env_summary` method returns relevant environment variables for diagnosis
+  - `grammar_works?` now logs detailed trace when `TREE_HAVER_DEBUG=1`
+  - `before(:suite)` prints both env vars and dependency status when debugging
+  - Helps diagnose differences between local and CI environments
+- Many new specs for:
+  - TreeHaver::GrammarFinder
+  - TreeHaver::Node
+  - TreeHaver::Tree
+
 ## [3.1.1] - 2025-12-28
 
 - TAG: [v3.1.1][3.1.1t]
@@ -321,7 +482,7 @@ Please file a bug if you notice a violation of semantic versioning.
   - Shows when TREE_SITTER_*_PATH is set but points to nonexistent file
   - Provides helpful guidance for setting environment variables correctly
 - Fixed registry conflicts when registering multiple backend types for the same language
-- Fixed `CitrusGrammarFinder` to properly handle gems with non-standard require paths (e.g., `toml-rb.rb` vs `toml/rb.rb`)
+- Fixed `CitrusGrammarFinder` to use gem name as-is for require path (e.g., `require "toml-rb"` not `require "toml/rb"`)
 - Fixed Citrus backend infinite recursion in `Node#extract_type_from_event`
   - Added cycle detection to prevent stack overflow when traversing recursive grammar structures
 
@@ -419,7 +580,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.1.1...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/kettle-rb/tree_haver/compare/v3.1.2...v3.2.0
+[3.2.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.0
+[3.1.2]: https://github.com/kettle-rb/tree_haver/compare/v3.1.1...v3.1.2
+[3.1.2t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.1.2
 [3.1.1]: https://github.com/kettle-rb/tree_haver/compare/v3.1.0...v3.1.1
 [3.1.1t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.1.1
 [3.1.0]: https://github.com/kettle-rb/tree_haver/compare/v3.0.0...v3.1.0