tree_haver 3.0.0 → 3.1.1

data/README.md

@@ -54,20 +54,20 @@
 
 ## 🌻 Synopsis
 
-TreeHaver is a cross-Ruby adapter for the [tree-sitter](https://tree-sitter.github.io/tree-sitter/) parsing library that works seamlessly across MRI Ruby, JRuby, and TruffleRuby. It provides a unified API for parsing source code using tree-sitter grammars, regardless of your Ruby implementation.
+TreeHaver is a cross-Ruby adapter for the [tree-sitter](https://tree-sitter.github.io/tree-sitter/) and [Citrus](https://github.com/mjackson/citrus) parsing libraries and other dedicated parsing tools that works seamlessly across MRI Ruby, JRuby, and TruffleRuby. It provides a unified API for parsing source code using grammars, regardless of your Ruby implementation.
 
 ### The Adapter Pattern: Like Faraday, but for Parsing
 
 If you've used [Faraday](https://github.com/lostisland/faraday), [multi_json](https://github.com/intridea/multi_json), or [multi_xml](https://github.com/sferik/multi_xml), you'll feel right at home with TreeHaver. These gems share a common philosophy:
 
-| Gem            | Unified API for     | Backend Examples                                     |
-|----------------|---------------------|------------------------------------------------------|
-| **Faraday**    | HTTP requests       | Net::HTTP, Typhoeus, Patron, Excon                   |
-| **multi_json** | JSON parsing        | Oj, Yajl, JSON gem                                   |
-| **multi_xml**  | XML parsing         | Nokogiri, LibXML, Ox                                 |
-| **TreeHaver**  | tree-sitter parsing | ruby_tree_sitter, tree_stump, FFI, Java JARs, Citrus |
+| Gem            | Unified API for     | Backend Examples                                                         |
+|----------------|---------------------|--------------------------------------------------------------------------|
+| **Faraday**    | HTTP requests       | Net::HTTP, Typhoeus, Patron, Excon                                       |
+| **multi_json** | JSON parsing        | Oj, Yajl, JSON gem                                                       |
+| **multi_xml**  | XML parsing         | Nokogiri, LibXML, Ox                                                     |
+| **TreeHaver**  | Code parsing        | MRI, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus (& Co.) |
 
-**Write once, run anywhere.** 
+**Write once, run anywhere.**
 
 **Learn once, write anywhere.**
 
@@ -88,18 +88,26 @@ tree = parser.parse(source_code)
 ### Key Features
 
 - **Universal Ruby Support**: Works on MRI Ruby, JRuby, and TruffleRuby
-- **Multiple Backends**:
-  - **MRI Backend**: Leverages the excellent [`ruby_tree_sitter`](https://github.com/Faveod/ruby-tree-sitter) gem (C extension)
-  - **Rust Backend**: Uses [`tree_stump`](https://github.com/anthropics/tree_stump) gem (Rust extension with precompiled binaries)
-    - **Note**: Currently requires [pboling's fork](https://github.com/pboling/tree_stump/tree/tree_haver) until PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), and [#13 (inclusive of the others)](https://github.com/joker1007/tree_stump/pull/13) are merged
-  - **FFI Backend**: Pure Ruby FFI bindings to `libtree-sitter` (ideal for JRuby)
-  - **Java Backend**: Support for JRuby's native Java integration, and native java-tree-sitter grammar JARs
-  - **Citrus Backend**: Pure Ruby parser using [`citrus`](https://github.com/mjackson/citrus) gem (no native dependencies, portable)
+- **10 Parsing Backends** - Choose the right backend for your needs:
+  - **Tree-sitter Backends** (high-performance, incremental parsing):
+    - **MRI Backend**: Leverages [`ruby_tree_sitter`](https://github.com/Faveod/ruby-tree-sitter) gem (C extension, fastest on MRI)
+    - **Rust Backend**: Uses [`tree_stump`][tree_stump] gem (Rust with precompiled binaries)
+      - **Note**: `tree_stump` currently requires unreleased fixes in the `main` branch.
+    - **FFI Backend**: Pure Ruby FFI bindings to `libtree-sitter` (ideal for JRuby, TruffleRuby)
+    - **Java Backend**: Native Java integration for JRuby with [`java-tree-sitter`](https://github.com/tree-sitter/java-tree-sitter) / [`jtreesitter`](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter) grammar JARs
+  - **Language-Specific Backends** (native parser integration):
+    - **Prism Backend**: Ruby's official parser ([Prism][prism], stdlib in Ruby 3.4+)
+    - **Psych Backend**: Ruby's YAML parser ([Psych][psych], stdlib)
+    - **Commonmarker Backend**: Fast Markdown parser ([Commonmarker][commonmarker], comrak Rust)
+    - **Markly Backend**: GitHub Flavored Markdown ([Markly][markly], cmark-gfm C)
+  - **Pure Ruby Fallback**:
+    - **Citrus Backend**: Pure Ruby parsing via [`citrus`][citrus] (no native dependencies)
 - **Automatic Backend Selection**: Intelligently selects the best backend for your Ruby implementation
-- **Language Agnostic**: Load any tree-sitter grammar dynamically (TOML, JSON, Ruby, JavaScript, etc.)
+- **Language Agnostic**: Parse any language - Ruby, Markdown, YAML, JSON, Bash, TOML, JavaScript, etc.
 - **Grammar Discovery**: Built-in `GrammarFinder` utility for platform-aware grammar library discovery
+- **Unified Position API**: Consistent `start_line`, `end_line`, `source_position` across all backends
 - **Thread-Safe**: Built-in language registry with thread-safe caching
-- **Minimal API Surface**: Simple, focused API that covers the most common tree-sitter use cases
+- **Minimal API Surface**: Simple, focused API that covers the most common use cases
 
 ### Backend Requirements
 
@@ -128,11 +136,11 @@ gem "ruby_tree_sitter", "~> 2.0"
 
 #### Rust Backend (tree_stump)
 
-Currently requires [pboling's fork](https://github.com/pboling/tree_stump/tree/tree_haver) until upstream PRs are merged.
+NOTE: `tree_stump` currently requires unreleased fixes in the `main` branch.
 
 ```ruby
 # Add to your Gemfile for Rust backend
-gem "tree_stump", github: "pboling/tree_stump", branch: "tree_haver"
+gem "tree_stump", github: "joker1007/tree_stump", branch: "main"
 ```
 
 #### FFI Backend
@@ -167,7 +175,7 @@ gem "citrus", "~> 3.0"
 
 #### Java Backend (JRuby only)
 
-No additional dependencies required beyond grammar JARs built for java-tree-sitter.
+No additional dependencies required beyond grammar JARs built for java-tree-sitter / jtreesitter.
 
 ### Why TreeHaver?
 
@@ -179,6 +187,58 @@ tree-sitter is a powerful parser generator that creates incremental parsers for
 
 TreeHaver solves these problems by providing a unified API that automatically selects the appropriate backend for your Ruby implementation, allowing you to write code once and run it anywhere.
 
+### The `*-merge` Gem Family
+
+The `*-merge` gem family provides intelligent, AST-based merging for various file formats. At the foundation is [tree_haver][tree_haver], which provides a unified cross-Ruby parsing API that works seamlessly across MRI, JRuby, and TruffleRuby.
+
+| Gem                                      | Format   | Parser Backend(s)                                                                                   | Description                                                                      |
+|------------------------------------------|----------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
+| [tree_haver][tree_haver]                 | Multi    | MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus                                  | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
+| [ast-merge][ast-merge]                   | Text     | internal                                                                                            | **Infrastructure**: Shared base classes and merge logic for all `*-merge` gems   |
+| [prism-merge][prism-merge]               | Ruby     | [Prism][prism]                                                                                      | Smart merge for Ruby source files                                                |
+| [psych-merge][psych-merge]               | YAML     | [Psych][psych]                                                                                      | Smart merge for YAML files                                                       |
+| [json-merge][json-merge]                 | JSON     | [tree-sitter-json][ts-json] (via tree_haver)                                                        | Smart merge for JSON files                                                       |
+| [jsonc-merge][jsonc-merge]               | JSONC    | [tree-sitter-jsonc][ts-jsonc] (via tree_haver)                                                      | ⚠️ Proof of concept; Smart merge for JSON with Comments                          |
+| [bash-merge][bash-merge]                 | Bash     | [tree-sitter-bash][ts-bash] (via tree_haver)                                                        | Smart merge for Bash scripts                                                     |
+| [rbs-merge][rbs-merge]                   | RBS      | [RBS][rbs]                                                                                          | Smart merge for Ruby type signatures                                             |
+| [dotenv-merge][dotenv-merge]             | Dotenv   | internal                                                                                            | Smart merge for `.env` files                                                     |
+| [toml-merge][toml-merge]                 | TOML     | [Citrus + toml-rb][toml-rb] (default, via tree_haver), [tree-sitter-toml][ts-toml] (via tree_haver) | Smart merge for TOML files                                                       |
+| [markdown-merge][markdown-merge]         | Markdown | [Commonmarker][commonmarker] / [Markly][markly] (via tree_haver)                                    | **Foundation**: Shared base for Markdown mergers with inner code block merging   |
+| [markly-merge][markly-merge]             | Markdown | [Markly][markly] (via tree_haver)                                                                   | Smart merge for Markdown (CommonMark via cmark-gfm C)                            |
+| [commonmarker-merge][commonmarker-merge] | Markdown | [Commonmarker][commonmarker] (via tree_haver)                                                       | Smart merge for Markdown (CommonMark via comrak Rust)                            |
+
+**Example implementations** for the gem templating use case:
+
+| Gem | Purpose | Description |
+|-----|---------|-------------|
+| [kettle-dev][kettle-dev] | Gem Development | Gem templating tool using `*-merge` gems |
+| [kettle-jem][kettle-jem] | Gem Templating | Gem template library with smart merge support |
+
+[tree_haver]: https://github.com/kettle-rb/tree_haver
+[ast-merge]: https://github.com/kettle-rb/ast-merge
+[prism-merge]: https://github.com/kettle-rb/prism-merge
+[psych-merge]: https://github.com/kettle-rb/psych-merge
+[json-merge]: https://github.com/kettle-rb/json-merge
+[jsonc-merge]: https://github.com/kettle-rb/jsonc-merge
+[bash-merge]: https://github.com/kettle-rb/bash-merge
+[rbs-merge]: https://github.com/kettle-rb/rbs-merge
+[dotenv-merge]: https://github.com/kettle-rb/dotenv-merge
+[toml-merge]: https://github.com/kettle-rb/toml-merge
+[markdown-merge]: https://github.com/kettle-rb/markdown-merge
+[markly-merge]: https://github.com/kettle-rb/markly-merge
+[commonmarker-merge]: https://github.com/kettle-rb/commonmarker-merge
+[kettle-dev]: https://github.com/kettle-rb/kettle-dev
+[kettle-jem]: https://github.com/kettle-rb/kettle-jem
+[prism]: https://github.com/ruby/prism
+[psych]: https://github.com/ruby/psych
+[ts-json]: https://github.com/tree-sitter/tree-sitter-json
+[ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
+[ts-toml]: https://github.com/tree-sitter-grammars/tree-sitter-toml
+[rbs]: https://github.com/ruby/rbs
+[toml-rb]: https://github.com/emancu/toml-rb
+[markly]: https://github.com/ioquatix/markly
+[commonmarker]: https://github.com/gjtorikian/commonmarker
+
 ### Comparison with Other Ruby AST / Parser Bindings
 
 | Feature                   | [tree_haver] (this gem)                | [ruby_tree_sitter] | [tree_stump]   | [citrus]    |
@@ -198,15 +258,15 @@ TreeHaver solves these problems by providing a unified API that automatically se
 | **Minimum Ruby**          | 3.2+                                   | 3.0+               | 3.1+           | 0+          |
 
 [ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
-[tree_stump]: https://github.com/anthropics/tree_stump
+[tree_stump]: https://github.com/joker1007/tree_stump
 [citrus]: https://github.com/mjackson/citrus
 [tree_haver]: https://github.com/kettle-rb/tree_haver
 
-**Note:** Java backend works with grammar JARs built specifically for java-tree-sitter, or grammar .so files that statically link tree-sitter. This is why FFI is recommended for JRuby & TruffleRuby.
+**Note:** Java backend works with grammar JARs built specifically for `java-tree-sitter` / `jtreesitter`, or grammar .so files that statically link tree-sitter. This is why FFI is recommended for JRuby & TruffleRuby.
 
-**Note:** TreeHaver can use `ruby_tree_sitter` or `tree_stump` as backends, giving you TreeHaver's unified API, grammar discovery, and security features, plus full access to incremental parsing when using those backends.
+**Note:** TreeHaver can use `ruby_tree_sitter` (MRI) or `tree_stump` (MRI, JRuby?) as backends, or `java-tree-sitter` ([docs](https://tree-sitter.github.io/java-tree-sitter/), [maven](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter), [source](https://github.com/tree-sitter/java-tree-sitter), JRuby), or FFI on any backend, giving you TreeHaver's unified API, grammar discovery, and security features, plus full access to incremental parsing when using those backends.
 
-**Note:** `tree_stump` currently requires [pboling's fork (tree_haver branch)](https://github.com/pboling/tree_stump/tree/tree_haver) until upstream PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), and [#13](https://github.com/joker1007/tree_stump/pull/13) are merged.
+**Note:** `tree_stump` currently requires unreleased fixes in the `main` branch.
 
 #### When to Use Each
 
@@ -231,7 +291,7 @@ TreeHaver solves these problems by providing a unified API that automatically se
 - You prefer Rust-based native extensions
 - You want precompiled binaries without system dependencies
 - You don't need TreeHaver's grammar discovery
-- **Note:** Use [pboling's fork (tree_haver branch)](https://github.com/pboling/tree_stump/tree/tree_haver) until PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), [#13](https://github.com/joker1007/tree_stump/pull/13) are merged
+- **Note:** `tree_stump` currently requires unreleased fixes in the `main` branch.
 
 **Choose citrus directly when:**
 
@@ -355,18 +415,29 @@ NOTE: Be prepared to track down certs for signed gems and add them the same way
 
 ### Available Backends
 
-TreeHaver supports multiple parsing backends, each with different trade-offs. The `auto` backend automatically selects the best available option.
+TreeHaver supports 10 parsing backends, each with different trade-offs. The `auto` backend automatically selects the best available option.
+
+#### Tree-sitter Backends (Universal Parsing)
+
+| Backend | Description | Performance | Portability | Examples |
+|---------|-------------|-------------|-------------|----------|
+| **Auto** | Auto-selects best backend | Varies | ✅ Universal | [JSON](examples/auto_json.rb) · [JSONC](examples/auto_jsonc.rb) · [Bash](examples/auto_bash.rb) · [TOML](examples/auto_toml.rb) |
+| **MRI** | C extension via ruby_tree_sitter | ⚡ Fastest | MRI only | [JSON](examples/mri_json.rb) · [JSONC](examples/mri_jsonc.rb) · ~~Bash~~* · [TOML](examples/mri_toml.rb) |
+| **Rust** | Precompiled via tree_stump | ⚡ Very Fast | ✅ Good | [JSON](examples/rust_json.rb) · [JSONC](examples/rust_jsonc.rb) · ~~Bash~~* · [TOML](examples/rust_toml.rb) |
+| **FFI** | Dynamic linking via FFI | 🔵 Fast | ✅ Universal | [JSON](examples/ffi_json.rb) · [JSONC](examples/ffi_jsonc.rb) · [Bash](examples/ffi_bash.rb) · [TOML](examples/ffi_toml.rb) |
+| **Java** | JNI bindings | ⚡ Very Fast | JRuby only | [JSON](examples/java_json.rb) · [JSONC](examples/java_jsonc.rb) · [Bash](examples/java_bash.rb) · [TOML](examples/java_toml.rb) |
+
+#### Language-Specific Backends (Native Parser Integration)
 
 | Backend | Description | Performance | Portability | Examples |
 |---------|-------------|-------------|-------------|----------|
-| **Auto** | Auto-selects best backend | Varies | ✅ Universal | [JSON](examples/auto_json.rb) · [JSONC](examples/auto_jsonc.rb) · [Bash](examples/auto_bash.rb) |
-| **MRI** | C extension via ruby_tree_sitter | ⚡ Fastest | MRI only | [JSON](examples/mri_json.rb) · [JSONC](examples/mri_jsonc.rb) · ~~Bash~~* |
-| **Rust** | Precompiled via tree_stump | ⚡ Very Fast | ✅ Good | [JSON](examples/rust_json.rb) · [JSONC](examples/rust_jsonc.rb) · ~~Bash~~* |
-| **FFI** | Dynamic linking via FFI | 🔵 Fast | ✅ Universal | [JSON](examples/ffi_json.rb) · [JSONC](examples/ffi_jsonc.rb) · [Bash](examples/ffi_bash.rb) |
-| **Java** | JNI bindings | ⚡ Very Fast | JRuby only | [JSON](examples/java_json.rb) · [JSONC](examples/java_jsonc.rb) · [Bash](examples/java_bash.rb) |
+| **Prism** | Ruby's official parser | ⚡ Very Fast | ✅ Universal | [Ruby](examples/prism_ruby.rb) |
+| **Psych** | Ruby's YAML parser (stdlib) | ⚡ Very Fast | ✅ Universal | [YAML](examples/psych_yaml.rb) |
+| **Commonmarker** | Markdown via comrak (Rust) | ⚡ Very Fast | ✅ Good | [Markdown](examples/commonmarker_markdown.rb) · [Merge](examples/commonmarker_merge_example.rb) |
+| **Markly** | GFM via cmark-gfm (C) | ⚡ Very Fast | ✅ Good | [Markdown](examples/markly_markdown.rb) · [Merge](examples/markly_merge_example.rb) |
 | **Citrus** | Pure Ruby parsing | 🟡 Slower | ✅ Universal | [TOML](examples/citrus_toml.rb) · [Finitio](examples/citrus_finitio.rb) · [Dhall](examples/citrus_dhall.rb) |
 
-**Selection Priority (Auto mode):** MRI → Rust → FFI → Java → Citrus
+**Selection Priority (Auto mode):** MRI → Rust → FFI → Java → Prism → Psych → Commonmarker → Markly → Citrus
 
 **Known Issues:**
 - *MRI + Bash: ABI incompatibility (use FFI instead)
@@ -375,29 +446,43 @@ TreeHaver supports multiple parsing backends, each with different trade-offs. Th
 **Backend Requirements:**
 
 ```ruby
-# MRI Backend
-gem 'ruby_tree_sitter'
-
-# Rust Backend  
-gem 'tree_stump'
-
-# FFI Backend
-gem 'ffi'
-
-# Citrus Backend
-gem 'citrus'
+# Tree-sitter backends
+gem "ruby_tree_sitter", "~> 2.0"  # MRI backend
+gem "tree_stump"                   # Rust backend
+gem "ffi", ">= 1.15", "< 2.0"     # FFI backend
+# Java backend: no gem required (uses JRuby's built-in JNI)
+
+# Language-specific backends
+gem "prism", "~> 1.0"              # Ruby parsing (stdlib in Ruby 3.4+)
+# Psych: no gem required (Ruby stdlib)
+gem "commonmarker", ">= 0.23"      # Markdown parsing (comrak)
+gem "markly", "~> 0.11"            # GFM parsing (cmark-gfm)
+
+# Pure Ruby fallback
+gem "citrus", "~> 3.0"             # Citrus backend
 # Plus grammar gems: toml-rb, dhall, finitio, etc.
 ```
 
 **Force Specific Backend:**
 
 ```ruby
+# Tree-sitter backends
+TreeHaver.backend = :mri    # Force MRI backend (ruby_tree_sitter)
+TreeHaver.backend = :rust   # Force Rust backend (tree_stump)
 TreeHaver.backend = :ffi    # Force FFI backend
-TreeHaver.backend = :mri    # Force MRI backend
-TreeHaver.backend = :rust   # Force Rust backend
-TreeHaver.backend = :java   # Force Java backend (JRuby)
+TreeHaver.backend = :java   # Force Java backend (JRuby only)
+
+# Language-specific backends
+TreeHaver.backend = :prism        # Force Prism (Ruby parsing)
+TreeHaver.backend = :psych        # Force Psych (YAML parsing)
+TreeHaver.backend = :commonmarker # Force Commonmarker (Markdown)
+TreeHaver.backend = :markly       # Force Markly (GFM Markdown)
+
+# Pure Ruby fallback
 TreeHaver.backend = :citrus # Force Citrus backend
-TreeHaver.backend = :auto   # Auto-select (default)
+
+# Auto-selection (default)
+TreeHaver.backend = :auto   # Let TreeHaver choose
 ```
 
 **Block-based Backend Switching:**
@@ -453,7 +538,7 @@ TreeHaver.backend_module       # => TreeHaver::Backends::FFI
 TreeHaver.capabilities         # => { backend: :ffi, parse: true, query: false, ... }
 ```
 
-See [examples/](examples/) directory for 18 complete working examples demonstrating all backends and languages.
+See [examples/](examples/) directory for **26 complete working examples** demonstrating all 10 backends with multiple languages (JSON, JSONC, Bash, TOML, Ruby, YAML, Markdown) plus markdown-merge integration examples.
 
 ### Security Considerations
 
@@ -549,8 +634,8 @@ TreeHaver.backend = :auto
 # Force a specific backend
 TreeHaver.backend = :mri     # Use ruby_tree_sitter (MRI only, C extension)
 TreeHaver.backend = :rust    # Use tree_stump (MRI, Rust extension with precompiled binaries)
-                             # Note: Requires pboling's fork until PRs #5, #7, #11, #13 are merged
-                             # See: https://github.com/pboling/tree_stump/tree/tree_haver
+                             # Note: `tree_stump` currently requires unreleased fixes in the `main` branch.
+                             # See: https://github.com/joker1007/tree_stump
 TreeHaver.backend = :ffi     # Use FFI bindings (works on MRI and JRuby)
 TreeHaver.backend = :java    # Use Java bindings (JRuby only, coming soon)
 TreeHaver.backend = :citrus  # Use Citrus pure Ruby parser
@@ -627,6 +712,8 @@ For the Java backend on JRuby:
 export TREE_SITTER_JAVA_JARS_DIR=/path/to/java-tree-sitter/jars
 ```
 
+For more see [docs](https://tree-sitter.github.io/java-tree-sitter/), [maven](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter), and [source](https://github.com/tree-sitter/java-tree-sitter).
+
 ### Language Registration
 
 Register languages once at application startup for convenient access:
@@ -765,74 +852,141 @@ parser = TreeSitter::Parser.new  # Actually creates TreeHaver::Parser
 
 This is safe and idempotent—if the real `TreeSitter` module is already loaded, the shim does nothing.
 
-#### ⚠️ Critical: Exception Hierarchy Incompatibility
-
-**ruby_tree_sitter v2+ exceptions inherit from `Exception` (not `StandardError`).**  
-**TreeHaver exceptions follow Ruby best practices and inherit from `StandardError`.**
+#### ⚠️ Important: Exception Hierarchy
 
-This means exception handling behaves **differently** between the two:
+**Both ruby_tree_sitter v2+ and TreeHaver exceptions inherit from `Exception` (not `StandardError`).**
 
-| Scenario | ruby_tree_sitter v2+ | TreeHaver Compat Mode |
-|----------|---------------------|----------------------|
-| `rescue => e` | Does NOT catch TreeSitter errors | DOES catch TreeHaver errors |
-| Behavior | Errors propagate (inherit Exception) | Errors caught (inherit StandardError) |
+This design decision follows ruby_tree_sitter's lead for thread-safety and signal handling reasons. See [ruby_tree_sitter PR #83](https://github.com/Faveod/ruby-tree-sitter/pull/83) for the rationale.
 
-**Example showing the difference:**
+**What this means for exception handling:**
 
 ```ruby
-# With real ruby_tree_sitter v2+
+# ⚠️ This will NOT catch TreeHaver errors
 begin
-  TreeSitter::Language.load("missing", "/nonexistent.so")
+  TreeHaver::Language.from_library("/nonexistent.so")
 rescue => e
-  puts "Caught!"  # Never reached - TreeSitter errors inherit Exception
+  puts "Caught!"  # Never reached - TreeHaver::Error inherits Exception
 end
 
-# With TreeHaver compat mode
-require "tree_haver/compat"
+# ✅ Explicit rescue is required
 begin
-  TreeSitter::Language.load("missing", "/nonexistent.so")  # Actually TreeHaver
-rescue => e
-  puts "Caught!"  # WILL be reached - TreeHaver errors inherit StandardError
+  TreeHaver::Language.from_library("/nonexistent.so")
+rescue TreeHaver::Error => e
+  puts "Caught!"  # This works
+end
+
+# ✅ Or rescue specific exceptions
+begin
+  TreeHaver::Language.from_library("/nonexistent.so")
+rescue TreeHaver::NotAvailable => e
+  puts "Grammar not available: #{e.message}"
 end
 ```
 
-**To write compatible exception handling:**
+**TreeHaver Exception Hierarchy:**
+
+```
+Exception
+└── TreeHaver::Error              # Base error class
+    ├── TreeHaver::NotAvailable   # Backend/grammar not available
+    └── TreeHaver::BackendConflict # Backend incompatibility detected
+```
+
+**Compatibility Mode Behavior:**
+
+The compat mode (`require "tree_haver/compat"`) creates aliases but **does not change the exception hierarchy**:
 
 ```ruby
-# Option 1: Catch specific exception (works with both)
-begin
-  TreeSitter::Language.load(...)
-rescue TreeSitter::TreeSitterError => e  # Explicit rescue
-  # Works with both ruby_tree_sitter and TreeHaver compat mode
-end
+require "tree_haver/compat"
+
+# TreeSitter constants are now aliases to TreeHaver
+TreeSitter::Error       # => TreeHaver::Error (still inherits Exception)
+TreeSitter::Parser      # => TreeHaver::Parser
+TreeSitter::Language    # => TreeHaver::Language
 
-# Option 2: Use TreeHaver API directly (recommended)
+# Exception handling remains the same
 begin
-  TreeHaver::Language.from_library(...)
-rescue TreeHaver::NotAvailable => e  # TreeHaver's unified exception
-  # Clear and consistent when using TreeHaver
+  TreeSitter::Language.load("missing", "/nonexistent.so")
+rescue TreeSitter::Error => e  # Still requires explicit rescue
+  puts "Error: #{e.message}"
 end
 ```
 
-**Why TreeHaver uses StandardError:**
+**Best Practices:**
+
+1. **Always use explicit rescue** for TreeHaver errors:
+   ```ruby
+   begin
+     finder = TreeHaver::GrammarFinder.new(:toml)
+     finder.register! if finder.available?
+     language = TreeHaver::Language.toml
+   rescue TreeHaver::NotAvailable => e
+     warn("TOML grammar not available: #{e.message}")
+     # Fallback to another backend or fail gracefully
+   end
+   `````
+
+2. **Never rely on `rescue => e`** to catch TreeHaver errors (it won't work)
+
+**Why inherit from Exception?**
 
-1. **Ruby Best Practice**: The [Ruby style guide](https://rubystyle.guide/#exception-flow-control) recommends inheriting from `StandardError`
-2. **Safety**: Inheriting from `Exception` can catch system signals (`SIGTERM`, `SIGINT`) and `exit`, which is dangerous
-3. **Consistency**: Most Ruby libraries follow this convention
-4. **Testability**: StandardError exceptions are easier to test and mock
+Following ruby_tree_sitter's reasoning:
+- **Thread safety**: Prevents accidental catching in thread cleanup code
+- **Signal handling**: Ensures parsing errors don't interfere with SIGTERM/SIGINT
+- **Intentional handling**: Forces developers to explicitly handle parsing errors
 
-See `lib/tree_haver/compat.rb` for detailed documentation.
+See `lib/tree_haver/compat.rb` for compatibility layer documentation.
 
 ## 🔧 Basic Usage
 
 ### Quick Start
 
-Here's a complete example of parsing TOML with TreeHaver:
+The simplest way to parse code is with `TreeHaver.parser_for`, which handles all the complexity of language loading, grammar discovery, and backend selection:
 
 ```ruby
 require "tree_haver"
 
-# Load a language grammar
+# Parse TOML - auto-discovers grammar and falls back to Citrus if needed
+parser = TreeHaver.parser_for(:toml)
+tree = parser.parse("[package]\nname = \"my-app\"")
+
+# Parse JSON
+parser = TreeHaver.parser_for(:json)
+tree = parser.parse('{"key": "value"}')
+
+# Parse Bash
+parser = TreeHaver.parser_for(:bash)
+tree = parser.parse("#!/bin/bash\necho hello")
+
+# With explicit library path
+parser = TreeHaver.parser_for(:toml, library_path: "/custom/path/libtree-sitter-toml.so")
+
+# With Citrus fallback configuration
+parser = TreeHaver.parser_for(
+  :toml,
+  citrus_config: {gem_name: "toml-rb", grammar_const: "TomlRB::Document"},
+)
+```
+
+`TreeHaver.parser_for` handles:
+1. Checking if the language is already registered
+2. Auto-discovering tree-sitter grammar via `GrammarFinder`
+3. Falling back to Citrus grammar if tree-sitter is unavailable
+4. Creating and configuring the parser
+5. Raising `NotAvailable` with a helpful message if nothing works
+
+### Manual Parser Setup
+
+For more control, you can create parsers manually:
+
+TreeHaver works with any language through its 10 backends. Here are examples for different parsing needs:
+
+#### Parsing with Tree-sitter (Universal Languages)
+
+```ruby
+require "tree_haver"
+
+# Load a tree-sitter grammar (works with MRI, Rust, FFI, or Java backend)
 language = TreeHaver::Language.from_library(
   "/usr/local/lib/libtree-sitter-toml.so",
   symbol: "tree_sitter_toml",
@@ -842,7 +996,7 @@ language = TreeHaver::Language.from_library(
 parser = TreeHaver::Parser.new
 parser.language = language
 
-# Parse some source code
+# Parse source code
 source = <<~TOML
   [package]
   name = "my-app"
@@ -851,16 +1005,116 @@ TOML
 
 tree = parser.parse(source)
 
-# Access the root node
+# Access the unified Position API (works across all backends)
 root = tree.root_node
-puts "Root node type: #{root.type}"  # => "document"
+puts "Root type: #{root.type}"              # => "document"
+puts "Start line: #{root.start_line}"       # => 1 (1-based)
+puts "End line: #{root.end_line}"           # => 3
+puts "Position: #{root.source_position}"    # => {start_line: 1, end_line: 3, ...}
 
 # Traverse the tree
 root.each do |child|
-  puts "Child type: #{child.type}"
-  child.each do |grandchild|
-    puts "  Grandchild type: #{grandchild.type}"
+  puts "Child: #{child.type} at line #{child.start_line}"
+end
+```
+
+#### Parsing Ruby with Prism
+
+```ruby
+require "tree_haver"
+
+TreeHaver.backend = :prism
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Backends::Prism::Language.ruby
+
+source = <<~RUBY
+  class Example
+    def hello
+      puts "Hello, world!"
+    end
   end
+RUBY
+
+tree = parser.parse(source)
+root = tree.root_node
+
+# Find all method definitions
+def find_methods(node, results = [])
+  results << node if node.type == "def_node"
+  node.children.each { |child| find_methods(child, results) }
+  results
+end
+
+methods = find_methods(root)
+methods.each do |method_node|
+  pos = method_node.source_position
+  puts "Method at lines #{pos[:start_line]}-#{pos[:end_line]}"
+end
+```
+
+#### Parsing YAML with Psych
+
+```ruby
+require "tree_haver"
+
+TreeHaver.backend = :psych
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Backends::Psych::Language.yaml
+
+source = <<~YAML
+  database:
+    host: localhost
+    port: 5432
+YAML
+
+tree = parser.parse(source)
+root = tree.root_node
+
+# Navigate YAML structure
+def show_structure(node, indent = 0)
+  prefix = "  " * indent
+  puts "#{prefix}#{node.type} (line #{node.start_line})"
+  node.children.each { |child| show_structure(child, indent + 1) }
+end
+
+show_structure(root)
+```
+
+#### Parsing Markdown with Commonmarker or Markly
+
+```ruby
+require "tree_haver"
+
+# Choose your backend
+TreeHaver.backend = :commonmarker  # or :markly for GFM
+
+parser = TreeHaver::Parser.new
+parser.language = TreeHaver::Backends::Commonmarker::Language.markdown
+
+source = <<~MARKDOWN
+  # My Document
+
+  ## Section
+
+  - Item 1
+  - Item 2
+MARKDOWN
+
+tree = parser.parse(source)
+root = tree.root_node
+
+# Find all headings
+def find_headings(node, results = [])
+  results << node if node.type == "heading"
+  node.children.each { |child| find_headings(child, results) }
+  results
+end
+
+headings = find_headings(root)
+headings.each do |heading|
+  level = heading.header_level
+  text = heading.children.map(&:text).join
+  puts "H#{level}: #{text} (line #{heading.start_line})"
 end
 ```
 
@@ -989,9 +1243,9 @@ tree.edit(
 new_tree = parser.parse_string(tree, "x = 42")
 ```
 
-**Note:** Incremental parsing requires the MRI (`ruby_tree_sitter`), Rust (`tree_stump`), or Java (`java-tree-sitter`) backend. The FFI and Citrus backends do not currently support incremental parsing. You can check support with:
+**Note:** Incremental parsing requires the MRI (`ruby_tree_sitter`), Rust (`tree_stump`), or Java (`java-tree-sitter` / `jtreesitter`) backend. The FFI and Citrus backends do not currently support incremental parsing. You can check support with:
 
-**Note:** `tree_stump` requires [pboling's fork (tree_haver branch)](https://github.com/pboling/tree_stump/tree/tree_haver) until PRs [#5](https://github.com/joker1007/tree_stump/pull/5), [#7](https://github.com/joker1007/tree_stump/pull/7), [#11](https://github.com/joker1007/tree_stump/pull/11), [#13](https://github.com/joker1007/tree_stump/pull/13) are merged.
+**Note:** `tree_stump` currently requires unreleased fixes in the `main` branch.
 
 ```ruby
 tree.supports_editing?  # => true if edit() is available
@@ -1095,7 +1349,7 @@ The FFI backend uses Ruby's FFI gem which relies on the system's dynamic linker,
 
 The Java backend will work with:
 
-- Grammar JARs built specifically for java-tree-sitter (self-contained)
+- Grammar JARs built specifically for java-tree-sitter / jtreesitter (self-contained, [docs](https://tree-sitter.github.io/java-tree-sitter/), [maven](https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter), [source](https://github.com/tree-sitter/java-tree-sitter))
 - Grammar `.so` files that statically link tree-sitter
 
 **Option 3: Citrus Backend (pure Ruby, portable)**
@@ -1159,7 +1413,7 @@ RSpec.describe("MyParser") do
         TreeHaver.with_backend(backend_name) do
           parser = TreeHaver::Parser.new
           result = parser.parse("x = 42")
-          expect(result.root_node.type).to eq("document")
+          expect(result.root_node.type).to(eq("document"))
         end
         # Backend automatically restored after block
       end
@@ -1274,6 +1528,76 @@ TOML
 package_name = extract_package_name(toml)
 ```
 
+### 🧪 RSpec Integration
+
+TreeHaver provides shared RSpec helpers for conditional test execution based on dependency availability. This is useful for testing code that uses optional backends.
+
+```ruby
+# In your spec_helper.rb
+require "tree_haver/rspec"
+```
+
+This automatically configures RSpec with exclusion filters for all TreeHaver dependencies. Use tags to conditionally run tests:
+
+```ruby
+# Runs only when FFI backend is available
+it "parses with FFI", :ffi do
+  # ...
+end
+
+# Runs only when ruby_tree_sitter gem is available
+it "uses MRI backend", :mri_backend do
+  # ...
+end
+
+# Runs only when tree-sitter-toml grammar works
+it "parses TOML", :tree_sitter_toml do
+  # ...
+end
+
+# Runs only when any markdown backend is available
+it "parses markdown", :markdown_backend do
+  # ...
+end
+```
+
+**Available Tags:**
+
+| Tag | Description |
+|-----|-------------|
+| `:ffi` | FFI backend available (dynamic check) |
+| `:mri_backend` | ruby_tree_sitter gem available |
+| `:rust_backend` | tree_stump gem available |
+| `:java_backend` | Java backend available (JRuby) |
+| `:prism_backend` | Prism gem available |
+| `:psych_backend` | Psych available (stdlib) |
+| `:commonmarker` | commonmarker gem available |
+| `:markly` | markly gem available |
+| `:citrus_toml` | toml-rb with Citrus grammar available |
+| `:jruby` | Running on JRuby |
+| `:truffleruby` | Running on TruffleRuby |
+| `:mri` | Running on MRI (CRuby) |
+| `:tree_sitter_bash` | Bash grammar available and working |
+| `:tree_sitter_toml` | TOML grammar available and working |
+| `:tree_sitter_json` | JSON grammar available and working |
+| `:tree_sitter_jsonc` | JSONC grammar available and working |
+| `:toml_backend` | Any TOML backend available |
+| `:markdown_backend` | Any markdown backend available |
+| `:toml_merge` | toml-merge gem functional |
+| `:json_merge` | json-merge gem functional |
+| `:prism_merge` | prism-merge gem functional |
+| `:psych_merge` | psych-merge gem functional |
+
+All tags have negated versions (e.g., `:not_mri_backend`, `:not_jruby`) for testing fallback behavior.
+
+**Debug Output:**
+
+Set `TREE_HAVER_DEBUG=1` to print a dependency summary at the start of your test suite:
+
+```bash
+TREE_HAVER_DEBUG=1 bundle exec rspec
+```
+
 ## 🦷 FLOSS Funding
 
 While kettle-rb tools are free software and will always be, the project would benefit immensely from some funding.
@@ -1304,9 +1628,7 @@ Support us with a monthly donation and help us continue our activities. [[Become
 NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
 
 <!-- OPENCOLLECTIVE-INDIVIDUALS:START -->
-
 No backers yet. Be the first!
-
 <!-- OPENCOLLECTIVE-INDIVIDUALS:END -->
 
 ### Open Collective for Organizations
@@ -1316,9 +1638,7 @@ Become a sponsor and get your logo on our README on GitHub with a link to your s
 NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
 
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:START -->
-
 No sponsors yet. Be the first!
-
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:END -->
 
 [kettle-readme-backers]: https://github.com/kettle-rb/tree_haver/blob/main/exe/kettle-readme-backers
@@ -1623,7 +1943,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.067-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.461-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
@@ -1643,3 +1963,6 @@ Thanks for RTFM. ☺️
 [💎appraisal2]: https://github.com/appraisal-rb/appraisal2
 [💎appraisal2-img]: https://img.shields.io/badge/appraised_by-appraisal2-34495e.svg?plastic&logo=ruby&logoColor=white
 [💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/
+
+[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
+[dotenv]: https://github.com/bkeepers/dotenv