tree_haver 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f711d2013566d14c8ae9d5f3609de3c32f8621e04d573543841c88e04fb6b1fb
-  data.tar.gz: '09c5054535b0399848c728302631daf9fdebb6c9d6a1aa3fa7d5428e52875b36'
+  metadata.gz: ad698ec9d939142aa2fd735e356ee50e83be0b2bc9ac16358f15b48f18d11d13
+  data.tar.gz: 51d0e7f2cb6d39bd0e10ffca602e096e86d463ccc38cbce5e0997dce39ca1bb2
 SHA512:
-  metadata.gz: fd50cd072f0e37bd051e184eb4e8fb2f198f3645f403732d04e73d08990890c28cf30d678a40142b459ea361577cfa1c22a68e1b0050f71d5cc9fe631d1a4f0d
-  data.tar.gz: 46072b508a3a538750b202a948a8a9e14dcc0134e659bc481df66de28d334daee69e55cd4c3d7b66bf01fe193f3fed9a419c785eea0a79266680261186367c29
+  metadata.gz: 0c0c55b6be53012357cd638e8997f1bd201310e494750b90a82a3f9588fb505a059ead9f056ffc443c424ca2a3cf6370d27e0b508a30faa90a39403bb067cb85
+  data.tar.gz: 71d9577716ab0edb436fa784dbfc5d6c81360c745ed98ef156c57475b6cd1f11eccf0030f2565e12d7dcf5035fcdf8fdc2c1eca64f81623109b1318048f41db4

data/CHANGELOG.md

@@ -30,6 +30,286 @@ 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]
+- COVERAGE: 85.19% -- 909/1067 lines in 11 files
+- BRANCH COVERAGE: 67.47% -- 338/501 branches in 11 files
+- 92.93% documented
+
+### Added
+
+#### Backend Requirements
+
+- **MRI Backend**: Requires `ruby_tree_sitter` v2.0+ (exceptions inherit from `Exception` not `StandardError`)
+  - In ruby_tree_sitter v2.0, TreeSitter errors were changed to inherit from Exception for thread-safety
+  - TreeHaver now properly handles: `ParserNotFoundError`, `LanguageLoadError`, `SymbolNotFoundError`, etc.
+
+#### Thread-Safe Backend Selection (Hybrid Approach)
+
+- **NEW: Block-based backend API** - `TreeHaver.with_backend(:ffi) { ... }` for thread-safe backend selection
+  - Thread-local context with proper nesting support
+  - Exception-safe (context restored even on errors)
+  - Fully backward compatible with existing global backend setting
+- **NEW: Explicit backend parameters**
+  - `Parser.new(backend: :mri)` - specify backend when creating parser
+  - `Language.from_library(path, backend: :ffi)` - specify backend when loading language
+  - Backend parameters override thread context and global settings
+- **NEW: Backend introspection** - `parser.backend` returns the current backend name (`:ffi`, `:mri`, etc.)
+- **Backend precedence chain**: `explicit parameter > thread context > global setting > :auto`
+- **Backend-aware caching** - Language cache now includes backend in cache key to prevent cross-backend pollution
+- Added `TreeHaver.effective_backend` - returns the currently effective backend considering precedence
+- Added `TreeHaver.current_backend_context` - returns thread-local backend context
+- Added `TreeHaver.resolve_backend_module(explicit_backend)` - resolves backend module with precedence
+
+#### Examples and Discovery
+
+- Added 18 comprehensive examples demonstrating all backends and languages
+  - JSON examples (5): auto, MRI, Rust, FFI, Java
+  - JSONC examples (5): auto, MRI, Rust, FFI, Java
+  - Bash examples (5): auto, MRI, Rust, FFI, Java
+  - Citrus examples (3): TOML, Finitio, Dhall
+  - All examples use bundler inline (self-contained, no Gemfile needed)
+  - Added `examples/run_all.rb` - comprehensive test runner with colored output
+  - Updated `examples/README.md` - complete guide to all examples
+- Added `TreeHaver::CitrusGrammarFinder` for language-agnostic discovery and registration of Citrus-based grammar gems
+  - Automatically discovers Citrus grammar gems by gem name and grammar constant path
+  - Validates grammar modules respond to `.parse(source)` before registration
+  - Provides helpful error messages when grammars are not found
+- Added multi-backend language registry supporting multiple backends per language simultaneously
+  - Restructured `LanguageRegistry` to use nested hash: `{ language: { backend_type: config } }`
+  - Enables registering both tree-sitter and Citrus grammars for the same language without conflicts
+  - Supports runtime backend switching, benchmarking, and fallback scenarios
+- Added `LanguageRegistry.register(name, backend_type, **config)` with backend-specific configuration storage
+- Added `LanguageRegistry.registered(name, backend_type = nil)` to query by specific backend or get all backends
+- Added `TreeHaver::Backends::Citrus::Node#structural?` method to distinguish structural nodes from terminals
+  - Uses Citrus grammar's `terminal?` method to dynamically determine node classification
+  - Works with any Citrus grammar without language-specific knowledge
+
+### Changed
+
+- **BREAKING**: All errors now inherit from `TreeHaver::Error` which inherits from `Exception`
+  - see: https://github.com/Faveod/ruby-tree-sitter/pull/83 for reasoning
+- **BREAKING**: `LanguageRegistry.register` signature changed from `register(name, path:, symbol:)` to `register(name, backend_type, **config)`
+  - This enables proper separation of tree-sitter and Citrus configurations
+  - Users should update to use `TreeHaver.register_language` instead of calling `LanguageRegistry.register` directly
+- Updated `TreeHaver.register_language` to support both tree-sitter and Citrus grammars in single call or separate calls
+  - Can now register: `register_language(:toml, path: "...", symbol: "...", grammar_module: TomlRB::Document)`
+  - **INTENTIONAL DESIGN**: Uses separate `if` statements (not `elsif`) to allow registering both backends simultaneously
+  - Enables maximum flexibility: runtime backend switching, performance benchmarking, fallback scenarios
+  - Multiple registrations for same language now merge instead of overwrite
+
+### Improved
+
+#### Code Quality and Documentation
+
+- **Uniform backend API**: All backends now implement `reset!` method for consistent testing interface
+  - Eliminates need for tests to manipulate private instance variables
+  - Provides clean way to reset backend state between tests
+- **Documented design decisions** with inline rationale
+  - FFI Tree finalizer behavior and why Parser doesn't use finalizers
+  - `resolve_backend_module` early-return pattern with comprehensive comments
+  - `register_language` multi-backend registration capability extensively documented
+- **Enhanced YARD documentation**
+  - All Citrus examples now include `gem_name` parameter (matches actual usage patterns)
+  - Added complete examples showing both single-backend and multi-backend registration
+  - Documented backend precedence chain and thread-safety guarantees
+- **Comprehensive test coverage** for thread-safe backend selection
+  - Thread-local context tests
+  - Parser backend parameter tests
+  - Language backend parameter tests
+  - Concurrent parsing tests with multiple backends
+  - Backend-aware cache isolation tests
+  - Nested block behavior tests (inner blocks override outer blocks)
+  - Exception safety tests (context restored even on errors)
+  - Explicit parameter precedence tests
+- Updated `Language.method_missing` to automatically select appropriate grammar based on active backend
+  - tree-sitter backends (MRI, Rust, FFI, Java) query `:tree_sitter` registry key
+  - Citrus backend queries `:citrus` registry key
+  - Provides clear error messages when requested backend has no registered grammar
+- Improved `TreeHaver::Backends::Citrus::Node#type` to use dynamic Citrus grammar introspection
+  - Uses event `.name` method and Symbol events for accurate type extraction
+  - Works with any Citrus grammar without language-specific code
+  - Handles compound rules (Repeat, Choice, Optional) intelligently
+
+### Fixed
+
+#### Thread-Safety and Backend Selection
+
+- Fixed `resolve_backend_module` to properly handle mocked backends without `available?` method
+  - Assumes modules without `available?` are available (for test compatibility and backward compatibility)
+  - Only rejects if module explicitly has `available?` method and returns false
+  - Makes code more defensive and test-friendly
+- Fixed Language cache to include backend in cache key
+  - Prevents returning wrong backend's Language object when switching backends
+  - Essential for correctness with multiple backends in use
+  - Cache key now: `"#{path}:#{symbol}:#{backend}"` instead of just `"#{path}:#{symbol}"`
+- Fixed `TreeHaver.register_language` to properly support multi-backend registration
+  - Documented intentional design: uses `if` not `elsif` to allow both backends in one call
+  - Added comprehensive inline comments explaining why no early return
+  - Added extensive YARD documentation with examples
+
+#### Backend Bug Fixes
+
+- Fixed critical double-wrapping bug in ALL backends (MRI, Rust, FFI, Java, Citrus)
+  - Backend `Parser#parse` and `parse_string` methods now return raw backend trees
+  - TreeHaver::Parser wraps the raw tree in TreeHaver::Tree (single wrapping)
+  - Previously backends were returning TreeHaver::Tree, then TreeHaver::Parser wrapped it again (double wrapping)
+  - This caused `@inner_tree` to be a TreeHaver::Tree instead of raw backend tree, leading to nil errors
+- Fixed TreeHaver::Parser to pass source parameter when wrapping backend trees
+  - Enables `Node#text` to work correctly by providing source for text extraction
+  - Fixes all parse and parse_string methods to include `source: source` parameter
+- Fixed MRI backend to properly use ruby_tree_sitter API
+  - Fixed `require "tree_sitter"` (gem name is `ruby_tree_sitter` but requires `tree_sitter`)
+  - Fixed `Language.load` to use correct argument order: `(symbol_name, path)`
+  - Fixed `Parser#parse` to use `parse_string(nil, source)` instead of creating Input objects
+  - Fixed `Language.from_library` to implement the expected signature matching other backends
+- Fixed FFI backend missing essential node methods
+  - Added `ts_node_start_byte`, `ts_node_end_byte`, `ts_node_start_point`, `ts_node_end_point`
+  - Added `ts_node_is_null`, `ts_node_is_named`
+  - These methods are required for accessing node byte positions and metadata
+  - Fixes `NoMethodError` when using FFI backend to traverse AST nodes
+- Fixed GrammarFinder error messages for environment variable validation
+  - Detects leading/trailing whitespace in paths and provides correction suggestions
+  - 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 Citrus backend infinite recursion in `Node#extract_type_from_event`
+  - Added cycle detection to prevent stack overflow when traversing recursive grammar structures
+
+### Known Issues
+
+- **MRI backend + Bash grammar**: ABI/symbol loading incompatibility
+  - The ruby_tree_sitter gem cannot load tree-sitter-bash grammar (symbol not found)
+  - Workaround: Use FFI backend instead (works perfectly)
+  - This is documented in examples and test runner
+- **Rust backend + Bash grammar**: Version mismatch due to static linking
+  - tree_stump statically links tree-sitter at compile time
+  - System bash.so may be compiled with different tree-sitter version
+  - Workaround: Use FFI backend (dynamic linking avoids version conflicts)
+  - This is documented in examples with detailed explanations
+
+### Notes on Backward Compatibility
+
+Despite the major version bump to 3.0.0 (following semver due to the breaking `LanguageRegistry.register` signature change), **most users will experience NO BREAKING CHANGES**:
+
+#### Why 3.0.0?
+
+- `LanguageRegistry.register` signature changed to support multi-backend registration
+- However, most users should use `TreeHaver.register_language` (which remains backward compatible)
+- Direct calls to `LanguageRegistry.register` are rare in practice
+
+#### What Stays the Same?
+
+- **Global backend setting**: `TreeHaver.backend = :ffi` works unchanged
+- **Parser creation**: `Parser.new` without parameters works as before
+- **Language loading**: `Language.from_library(path)` works as before
+- **Auto-detection**: Backend auto-selection still works when backend is `:auto`
+- **All existing code** continues to work without modifications
+
+#### What's New (All Optional)?
+
+- Thread-safe block API: `TreeHaver.with_backend(:ffi) { ... }`
+- Explicit backend parameters: `Parser.new(backend: :mri)`
+- Backend introspection: `parser.backend`
+- Multi-backend language registration
+
+**Migration Path**: Existing codebases can upgrade to 3.0.0 and gain access to new thread-safe features without changing any existing code. The new features are purely additive and opt-in.
+
 ## [2.0.0] - 2025-12-15
 
 - TAG: [v2.0.0][2.0.0t]
@@ -85,7 +365,11 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v2.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
 [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

data/CONTRIBUTING.md

@@ -42,6 +42,138 @@ There are many Rake tasks available as well. You can see them by running:
 bin/rake -T
 ```
 
+## Backend Compatibility Testing
+
+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.
+
+### Basic Usage
+
+```shell
+# Test all backends with TOML grammar (default)
+bin/backend-matrix
+
+# 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
+
+Test all possible backend combinations by spawning fresh subprocesses for each:
+
+```shell
+# 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
+
+The most interesting test: can different backends coexist if they use *different* grammar files?
+
+```shell
+# Test: FFI+json then MRI+toml, MRI+json then FFI+toml, etc.
+bin/backend-matrix --cross-grammar --grammars=json,toml
+
+# Full cross-grammar matrix
+bin/backend-matrix --all-permutations --cross-grammar --grammars=json,toml
+```
+
+### Custom Source Files
+
+Provide your own source files for parsing:
+
+```shell
+bin/backend-matrix --toml-source=my_config.toml --json-source=data.json
+```
+
+### List Available Grammars
+
+Check which grammars are configured and available:
+
+```shell
+bin/backend-matrix --list-grammars
+```
+
+### Understanding the Output
+
+The script produces tables showing:
+
+1. **1-Backend Tests**: Each backend tested in isolation with all grammars
+2. **2-Backend Tests**: Pairs of backends tested in sequence (A → B)
+3. **3-Backend Tests**: Triples tested in sequence (A → B → C)
+4. **Backend Pair Compatibility**: Data-driven analysis of which backends can coexist
+5. **Statistics**: Success rates and combination counts
+
+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 │
+│ 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 for tree-sitter backends:
+
+```shell
+export TREE_SITTER_TOML_PATH=/path/to/libtree-sitter-toml.so
+export TREE_SITTER_JSON_PATH=/path/to/libtree-sitter-json.so
+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.