tree_haver 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ddc5d837509119a581acd92a33fc7819b6e6dd40a727d1eb0b074d1e944c22f
-  data.tar.gz: f7b329ee2245068b3bc05e9e6c250e565bbb3b617a50840617f389c2f18dc679
+  metadata.gz: ad698ec9d939142aa2fd735e356ee50e83be0b2bc9ac16358f15b48f18d11d13
+  data.tar.gz: 51d0e7f2cb6d39bd0e10ffca602e096e86d463ccc38cbce5e0997dce39ca1bb2
 SHA512:
-  metadata.gz: 66e9dda1e2638d5340ad99a48959d63002293225a3fc636ea776f5718e0ed388628a4a9fe87c1b0150ae265ec812dd763b1cecfe434044148a1fffc16a9e78b1
-  data.tar.gz: 9545f9a6b25e6f5944c60b1c7e1a3ecc278cea04c5274b3c34a3d3a0d9d83f14324bda96820286e21ae627c380200866ee47cf6161a12f9bffc9ff72064c3aec
+  metadata.gz: 0c0c55b6be53012357cd638e8997f1bd201310e494750b90a82a3f9588fb505a059ead9f056ffc443c424ca2a3cf6370d27e0b508a30faa90a39403bb067cb85
+  data.tar.gz: 71d9577716ab0edb436fa784dbfc5d6c81360c745ed98ef156c57475b6cd1f11eccf0030f2565e12d7dcf5035fcdf8fdc2c1eca64f81623109b1318048f41db4

checksums.yaml.gz.sig

@@ -1,3 +1,3 @@
-�S�����z�'�w�wu|�,�Ƴ�y�Ҥlj�{���xԝ��.��
-��+m�b@}Aޞ�����VvD����6@C�~��<��q�^�{@)�Z<|pء2���G��S��?��&ᔵS*��)z��Հ�-?m9�ҕ�c���*:|z�v�\�a<o�Λ%b��#��u�͞�
-��o�>(>�Uj�BQ����N���P8%���@z�؀	��!�ԋ�����l\�n#癝�t��(�E�jw�][8��4�o�B^�*�eqh��1�w]/"J�_�<REi����ˉ��P痛��Z�����u�L��b!P>�����٤��c��s��Vlu<�X�����0�gF�6!5z��8q��n�\(�@���d��n�3�@���} Q�
+
+�†' ��w|n`5�vi�/��n�@bF��0ZLr�vη�lg�+��W2��S�V��;����H�0�����RD��A�Md ��D^M�
}��ŋ"�~,x�兪���W)
�UDF�`�͕a�WN֚�G����

 
+�c�>�

data/CHANGELOG.md

@@ -30,6 +30,99 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.1.0] - 2025-12-18
+
+- TAG: [v3.1.0][3.1.0t]
+- COVERAGE: 82.65% -- 943/1141 lines in 11 files
+- BRANCH COVERAGE: 63.80% -- 349/547 branches in 11 files
+- 88.97% documented
+
+### Added
+
+- **Position API Enhancements** – Added consistent position methods to all backend Node classes for compatibility with `*-merge` gems
+  - `start_line` - Returns 1-based line number where node starts (converts 0-based `start_point.row` to 1-based)
+  - `end_line` - Returns 1-based line number where node ends (converts 0-based `end_point.row` to 1-based)
+  - `source_position` - Returns hash `{start_line:, end_line:, start_column:, end_column:}` with 1-based lines and 0-based columns
+  - `first_child` - Convenience method that returns `children.first` for iteration compatibility
+  - **Fixed:** `TreeHaver::Node#start_point` and `#end_point` now handle both Point objects and hashes from backends (Prism, Citrus return hashes)
+  - **Fixed:** Added Psych, Commonmarker, and Markly backends to `resolve_backend_module` and `backend_module` case statements so they can be explicitly selected with `TreeHaver.backend = :psych` etc.
+  - **Fixed:** Added Prism, Psych, Commonmarker, and Markly backends to `unwrap_language` method so language objects are properly passed to backend parsers
+  - **Fixed:** Commonmarker backend's `text` method now safely handles container nodes that don't have string_content (wraps in rescue TypeError)
+  - **Added to:**
+    - Main `TreeHaver::Node` wrapper (used by tree-sitter backends: MRI, FFI, Java, Rust)
+    - `Backends::Commonmarker::Node` - uses Commonmarker's `sourcepos` (already 1-based)
+    - `Backends::Markly::Node` - uses Markly's `source_position` (already 1-based)
+    - `Backends::Prism::Node` - uses Prism's `location` (already 1-based)
+    - `Backends::Psych::Node` - calculates from `start_point`/`end_point` (0-based)
+    - `Backends::Citrus::Node` - calculates from `start_point`/`end_point` (0-based)
+  - **Backward Compatible:** Existing `start_point`/`end_point` methods continue to work unchanged
+  - **Purpose:** Enables all `*-merge` gems to use consistent position API without backend-specific workarounds
+
+- **Prism Backend** – New backend wrapping Ruby's official Prism parser (stdlib in Ruby 3.4+, gem for 3.2+)
+  - `TreeHaver::Backends::Prism::Language` - Language wrapper (Ruby-only)
+  - `TreeHaver::Backends::Prism::Parser` - Parser with `parse` and `parse_string` methods
+  - `TreeHaver::Backends::Prism::Tree` - Tree wrapper with `root_node`, `errors`, `warnings`, `comments`
+  - `TreeHaver::Backends::Prism::Node` - Node wrapper implementing full TreeHaver::Node protocol
+  - Registered with `:prism` backend name, no conflicts with other backends
+
+- **Psych Backend** – New backend wrapping Ruby's standard library YAML parser
+  - `TreeHaver::Backends::Psych::Language` - Language wrapper (YAML-only)
+  - `TreeHaver::Backends::Psych::Parser` - Parser with `parse` and `parse_string` methods
+  - `TreeHaver::Backends::Psych::Tree` - Tree wrapper with `root_node`, `errors`
+  - `TreeHaver::Backends::Psych::Node` - Node wrapper implementing TreeHaver::Node protocol
+  - Psych-specific methods: `mapping?`, `sequence?`, `scalar?`, `alias?`, `mapping_entries`, `anchor`, `tag`, `value`
+  - Registered with `:psych` backend name, no conflicts with other backends
+
+- **Commonmarker Backend** – New backend wrapping the Commonmarker gem (comrak Rust parser)
+  - `TreeHaver::Backends::Commonmarker::Language` - Language wrapper with parse options passthrough
+  - `TreeHaver::Backends::Commonmarker::Parser` - Parser with `parse` and `parse_string` methods
+  - `TreeHaver::Backends::Commonmarker::Tree` - Tree wrapper with `root_node`
+  - `TreeHaver::Backends::Commonmarker::Node` - Node wrapper implementing TreeHaver::Node protocol
+  - Commonmarker-specific methods: `header_level`, `fence_info`, `url`, `title`, `next_sibling`, `previous_sibling`, `parent`
+  - Registered with `:commonmarker` backend name, no conflicts with other backends
+
+- **Markly Backend** – New backend wrapping the Markly gem (cmark-gfm C library)
+  - `TreeHaver::Backends::Markly::Language` - Language wrapper with flags and extensions passthrough
+  - `TreeHaver::Backends::Markly::Parser` - Parser with `parse` and `parse_string` methods
+  - `TreeHaver::Backends::Markly::Tree` - Tree wrapper with `root_node`
+  - `TreeHaver::Backends::Markly::Node` - Node wrapper implementing TreeHaver::Node protocol
+  - Type normalization: `:header` → `"heading"`, `:hrule` → `"thematic_break"`, `:html` → `"html_block"`
+  - Markly-specific methods: `header_level`, `fence_info`, `url`, `title`, `next_sibling`, `previous_sibling`, `parent`, `raw_type`
+  - Registered with `:markly` backend name, no conflicts with other backends
+
+- **Automatic Citrus Fallback** – When tree-sitter fails, automatically fall back to Citrus backend
+  - `TreeHaver::Language.method_missing` now catches tree-sitter loading errors (`NotAvailable`, `ArgumentError`, `LoadError`, `FFI::NotFoundError`) and falls back to registered Citrus grammar
+  - `TreeHaver::Parser#initialize` now catches parser creation errors and falls back to Citrus parser when backend is `:auto`
+  - `TreeHaver::Parser#language=` automatically switches to Citrus parser when a Citrus language is assigned
+  - Enables seamless use of pure-Ruby parsers (like toml-rb) when tree-sitter runtime is unavailable
+
+- **GrammarFinder Runtime Check** – `GrammarFinder#available?` now verifies tree-sitter runtime is actually usable
+  - New `GrammarFinder.tree_sitter_runtime_usable?` class method tests if parser can be created
+  - `TREE_SITTER_BACKENDS` constant defines which backends use tree-sitter (MRI, FFI, Rust, Java)
+  - Prevents registration of grammars when tree-sitter runtime isn't functional
+  - `GrammarFinder.reset_runtime_check!` for testing
+
+- **Empty ENV Variable as Explicit Skip** – Setting `TREE_SITTER_<LANG>_PATH=''` explicitly disables that grammar
+  - Previously, empty string was treated same as unset (would search paths)
+  - Now, empty string means "do not use tree-sitter for this language"
+  - Allows explicit opt-out to force fallback to alternative backends like Citrus
+  - Useful for testing and environments where tree-sitter isn't desired
+
+- **TOML Examples** – New example scripts demonstrating TOML parsing with various backends
+  - `examples/auto_toml.rb` - Auto backend selection with Citrus fallback demonstration
+  - `examples/ffi_toml.rb` - FFI backend with TOML
+  - `examples/mri_toml.rb` - MRI backend with TOML
+  - `examples/rust_toml.rb` - Rust backend with TOML
+  - `examples/java_toml.rb` - Java backend with TOML (JRuby only)
+
+### Fixed
+
+- **BREAKING**: `TreeHaver::Language.method_missing` no longer raises `ArgumentError` when only Citrus grammar is registered and tree-sitter backend is active – it now falls back to Citrus instead
+  - Previously: Would raise "No grammar registered for :lang compatible with tree_sitter backend"
+  - Now: Returns `TreeHaver::Backends::Citrus::Language` if Citrus grammar is registered
+  - Migration: If you were catching this error, update your code to handle the fallback behavior
+  - This is a bug fix, but would be a breaking change for some users who were relying on the old behavior
+
 ## [3.0.0] - 2025-12-16
 
 - TAG: [v3.0.0][3.0.0t]
@@ -272,7 +365,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.0.0...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/kettle-rb/tree_haver/compare/v3.0.0...v3.1.0
+[3.1.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.1.0
 [3.0.0]: https://github.com/kettle-rb/tree_haver/compare/v2.0.0...v3.0.0
 [3.0.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.0.0
 [2.0.0]: https://github.com/kettle-rb/tree_haver/compare/v1.0.0...v2.0.0

data/CONTRIBUTING.md

@@ -44,9 +44,21 @@ bin/rake -T
 
 ## Backend Compatibility Testing
 
-TreeHaver supports multiple backends (MRI, FFI, Rust, Citrus), but not all backends can coexist
-in the same Ruby process. Notably, **FFI and MRI backends conflict** at the libtree-sitter runtime
-level—using both in the same process will cause segfaults.
+TreeHaver supports multiple backends with different characteristics:
+
+- **MRI**: ruby_tree_sitter (C extension, tree-sitter grammars)
+- **FFI**: Pure Ruby FFI bindings (tree-sitter grammars)
+- **Rust**: tree_stump (Rust extension, tree-sitter grammars)
+- **Citrus**: Pure Ruby parser (TOML only via toml-rb grammar)
+
+Not all backends can coexist in the same Ruby process. Notably, **FFI and MRI backends conflict**
+at the libtree-sitter runtime level—using both in the same process will cause segfaults.
+
+The **Citrus backend** works differently:
+- Uses pure Ruby parsing (no .so files)
+- Currently only supports TOML via toml-rb grammar
+- Can coexist with tree-sitter backends
+- Useful for testing multi-backend scenarios
 
 The `bin/backend-matrix` script helps test and document backend compatibility by running tests
 in isolated subprocesses.
@@ -57,14 +69,21 @@ in isolated subprocesses.
 # Test all backends with TOML grammar (default)
 bin/backend-matrix
 
-# Test specific backend order
-bin/backend-matrix ffi mri rust
+# Test specific backend order (including Citrus)
+bin/backend-matrix ffi mri rust citrus
+
+# Test Citrus with tree-sitter backends
+bin/backend-matrix citrus mri ffi    # Citrus before tree-sitter
+bin/backend-matrix mri citrus ffi    # Citrus between tree-sitter
 
 # Test with a different grammar
 bin/backend-matrix --grammar=json
 
 # Test multiple grammars
 bin/backend-matrix --grammars=json,toml,bash
+
+# Citrus only supports TOML
+bin/backend-matrix --grammar=toml citrus
 ```
 
 ### All Permutations Mode
@@ -72,11 +91,13 @@ bin/backend-matrix --grammars=json,toml,bash
 Test all possible backend combinations by spawning fresh subprocesses for each:
 
 ```shell
-# Test all 15 backend combinations (1-backend, 2-backend, 3-backend)
+# Test all 64 backend combinations (4 backends: 4 1-backend + 12 2-backend + 24 3-backend + 24 4-backend)
 bin/backend-matrix --all-permutations
 
 # With multiple grammars
 bin/backend-matrix --all-permutations --grammars=json,toml
+
+# Note: Citrus only supports TOML, so JSON/Bash tests will skip for Citrus
 ```
 
 ### Cross-Grammar Testing
@@ -121,18 +142,23 @@ Example findings:
 
 ```
 Backend Pair Compatibility:
-╭──────────────┬────────────────────┬─────────┬────────╮
-│ Backend Pair │ Compatibility      │ Working │ Failed │
-├──────────────┼────────────────────┼─────────┼────────┤
-│ ffi+mri      │ ✗ Incompatible     │       0 │      8 │
-│ mri+rust     │ ✓ Fully compatible │       8 │      0 │
-│ ffi+rust     │ ✓ Fully compatible │       8 │      0 │
-╰──────────────┴────────────────────┴─────────┴────────╯
+╭───────────────┬────────────────────┬─────────┬────────╮
+│ Backend Pair  │ Compatibility      │ Working │ Failed │
+├───────────────┼────────────────────┼─────────┼────────┤
+│ ffi+mri       │ ✗ Incompatible     │       0 │      8 │
+│ mri+rust      │ ✓ Fully compatible │       8 │      0 │
+│ ffi+rust      │ ✓ Fully compatible │       8 │      0 │
+│ citrus+mri    │ ✓ Fully compatible │       2 │      0 │
+│ citrus+ffi    │ ✓ Fully compatible │       2 │      0 │
+│ citrus+rust   │ ✓ Fully compatible │       2 │      0 │
+╰───────────────┴────────────────────┴─────────┴────────╯
+
+Note: Citrus only supports TOML, so it has fewer total combinations.
 ```
 
 ### Required Environment Variables
 
-The script requires grammar paths to be set:
+The script requires grammar paths to be set for tree-sitter backends:
 
 ```shell
 export TREE_SITTER_TOML_PATH=/path/to/libtree-sitter-toml.so
@@ -142,6 +168,12 @@ export TREE_SITTER_BASH_PATH=/path/to/libtree-sitter-bash.so
 
 See `.envrc` for examples of how these are typically configured.
 
+**For Citrus backend:**
+- Requires the `toml-rb` gem (pure Ruby TOML parser)
+  - **Auto-installs**: Script uses bundler inline to install `toml-rb` automatically if missing
+- No environment variables needed (doesn't use .so files)
+- Only supports TOML grammar
+
 ## Environment Variables for Local Development
 
 Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.