tree_haver 3.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ddc5d837509119a581acd92a33fc7819b6e6dd40a727d1eb0b074d1e944c22f
-  data.tar.gz: f7b329ee2245068b3bc05e9e6c250e565bbb3b617a50840617f389c2f18dc679
+  metadata.gz: 141cf04a77bd50b8802a20eb098ddb03352b08fa6b1592b95180dcf336cc25e1
+  data.tar.gz: 134418492ecd86ef348221dfb7cef3f7c459acee00318c2669bdd666dc37d4ba
 SHA512:
-  metadata.gz: 66e9dda1e2638d5340ad99a48959d63002293225a3fc636ea776f5718e0ed388628a4a9fe87c1b0150ae265ec812dd763b1cecfe434044148a1fffc16a9e78b1
-  data.tar.gz: 9545f9a6b25e6f5944c60b1c7e1a3ecc278cea04c5274b3c34a3d3a0d9d83f14324bda96820286e21ae627c380200866ee47cf6161a12f9bffc9ff72064c3aec
+  metadata.gz: bafe3a43549cecf6e38a3c8f68c4f072348050d2a3807c4ad8fa9ec2f1d073892abaf5b4300e750a2282849c1bdd081c9ef122b1f2dcb0c5044bddedb451c7b2
+  data.tar.gz: 62e7cd0947fdda50ea54f9e9a1b07a05c142388ef56a7a25a9ebb177f12804883cc3fc59dbfbbd3d5f08d062f59f89e850bb5d71733521344c53b5eec19ada78

data/CHANGELOG.md

@@ -30,6 +30,153 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.1.1] - 2025-12-28
+
+- TAG: [v3.1.1][3.1.1t]
+- COVERAGE: 87.44% -- 2152/2461 lines in 22 files
+- BRANCH COVERAGE: 66.67% -- 710/1065 branches in 22 files
+- 90.02% documented
+
+### Added
+
+- **`TreeHaver::RSpec::DependencyTags`**: Shared RSpec dependency detection for the entire gem family
+  - New `lib/tree_haver/rspec.rb` entry point - other gems can simply `require "tree_haver/rspec"`
+  - Detects all TreeHaver backends: FFI, MRI, Rust, Java, Prism, Psych, Commonmarker, Markly, Citrus
+  - Ruby engine detection: `jruby?`, `truffleruby?`, `mri?`
+  - Language grammar detection: `tree_sitter_bash_available?`, `tree_sitter_toml_available?`, `tree_sitter_json_available?`, `tree_sitter_jsonc_available?`
+  - Inner-merge dependency detection: `toml_merge_available?`, `json_merge_available?`, `prism_merge_available?`, `psych_merge_available?`
+  - Composite checks: `any_toml_backend_available?`, `any_markdown_backend_available?`
+  - Records MRI backend usage when checking availability (critical for FFI conflict detection)
+  - Configures RSpec exclusion filters for all dependency tags automatically
+  - Supports debug output via `TREE_HAVER_DEBUG=1` environment variable
+  - Comprehensive documentation with usage examples
+
+- **`TreeHaver.parser_for`**: New high-level factory method for creating configured parsers
+  - Handles all language loading complexity in one call
+  - Auto-discovers tree-sitter grammar via `GrammarFinder`
+  - Falls back to Citrus grammar if tree-sitter unavailable
+  - Accepts `library_path` for explicit grammar location
+  - Accepts `citrus_config` for Citrus fallback configuration
+  - Raises `NotAvailable` with helpful message if no backend works
+  - Example: `parser = TreeHaver.parser_for(:toml)`
+  - Raises `NotAvailable` if the specified path doesn't exist (Principle of Least Surprise)
+  - Does not back to auto-discovery when an explicit path is provided
+  - Re-raises with context-rich error message if loading from explicit path fails
+  - Auto-discovery still works normally when no `library_path` is provided
+
+### Changed
+
+- **Backend sibling navigation**: Backends that don't support sibling/parent navigation now raise `NotImplementedError` instead of returning `nil`
+  - This distinguishes "not implemented" from "no sibling exists"
+  - Affected backends: Prism, Psych
+  - Affected methods: `next_sibling`, `prev_sibling`, `parent`
+
+- **Canonical sibling method name**: All backends now use `prev_sibling` as the canonical method name (not `previous_sibling`)
+  - Matches the universal `TreeHaver::Node` API
+
+### Fixed
+
+- **Backend conflict detection**: Fixed bug where MRI backend usage wasn't being recorded during availability checks
+  - `mri_backend_available?` now calls `TreeHaver.record_backend_usage(:mri)` after successfully loading ruby_tree_sitter
+  - This ensures FFI conflict detection works correctly even when MRI is loaded indirectly
+
+- **GrammarFinder#not_found_message**: Improved error message when grammar file exists but no tree-sitter runtime is available
+  - Now suggests adding `ruby_tree_sitter`, `ffi`, or `tree_stump` gem to Gemfile
+  - Clearer guidance for users who have grammar files but are missing the Ruby tree-sitter bindings
+
+## [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 +419,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.0.0...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.1.1...HEAD
+[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
+[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.